amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-10-12 09:27:13 +00:00

Files

T

Niels Lohmann 11ef352511 Point users to update(…, true), JSON Pointer defaults, and built-in std::optional (#5804 )

A code search of client code found many hand-written versions of
functionality the library already has: recursive object merges
(update(j, true) since 3.10.5), dotted-path getters (value() and
contains() with a JSON Pointer), get_or helpers (value() throws for a
member that is present but null), and adl_serializer specializations
for std::optional (supported since 3.12.0).

- modifying_values.md: describe both modes of update(), add a
  defaults + user settings recipe, and stop recommending Merge Patch
  for recursive merges.
- merge_patch.md: note that null deletes keys, so a merge patch is not
  a general deep merge; link update().
- default_value.md: add "Nested values" (value/contains with a JSON
  Pointer, building a pointer from a dotted path with operator/=) and
  a warning that null and mistyped members are not missing.
- value.md: note that a null member is converted, not replaced by the
  default.
- json_pointer.md: link value/contains/at with JSON Pointers.
- arbitrary_types.md: note that std::optional needs no serializer.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-10-11 08:22:10 +02:00

3.8 KiB

Raw Blame History

Modifying values

Once a JSON value exists, its content can be changed: elements can be added, replaced, merged, and removed. This page gives an overview of the available operations. For read access, see element access.

Adding to arrays

New elements are appended to an array with push_back or constructed in place with emplace_back. If the value is #!json null, it is converted to an array first, so these functions can also be used to build an array from scratch.

json j;                 // null
j.push_back(1);         // [1]
j.push_back(2);         // [1,2]
j.emplace_back(3);      // [1,2,3]

// operator+= is a shorthand for push_back
j += 4;                 // [1,2,3,4]

Adding to objects

The most common way to add or replace a member is operator[], which inserts the key if it does not exist yet:

json j;
j["name"] = "Mary";     // {"name":"Mary"}
j["name"] = "John";     // {"name":"John"}  (replaced)

emplace inserts a member only if the key is not already present, and reports whether the insertion happened — useful for "add if absent" semantics.

Merging objects

To merge one object into another, update copies all members from another object (similar to Python's dict.update). This is the idiomatic way to combine two objects. It has two modes:

By default, the merge is shallow: existing keys are overwritten, even if both values are objects.
With merge_objects = #!cpp true, keys whose values are objects in both JSON values are merged recursively. Everything else is overwritten. In particular, arrays are replaced, not concatenated.

??? example

```cpp
--8<-- "examples/update.cpp"
```

Output:

```json
--8<-- "examples/update.output"
```

A common use of the recursive mode is combining defaults with user settings. Nested defaults that the user did not set are kept:

json defaults = {{"log", {{"level", "info"}, {"file", "app.log"}}}, {"retries", 3}};
json user_settings = {{"log", {{"level", "debug"}}}};

json config = defaults;
config.update(user_settings, true);
// {"log":{"file":"app.log","level":"debug"},"retries":3}

JSON Merge Patch (RFC 7386) also merges objects recursively, but it is a different tool: a #!json null in the patch means "remove this key". It is meant for applying merge patch documents (e.g., received via HTTP PATCH). To merge configuration-like objects, use #!cpp update(..., true). To apply a sequence of well-defined edit operations, see JSON Patch.

Removing elements

Elements are removed with erase, which accepts an object key, an array index, or an iterator. clear empties a value while keeping its type, and operator[] combined with assignment can overwrite a value entirely.

json j = {{"a", 1}, {"b", 2}, {"c", 3}};
j.erase("b");           // {"a":1,"c":3}

json a = {1, 2, 3, 4};
a.erase(1);             // [1,3,4]  (erase by index)

3.8 KiB Raw Blame History