Niels Lohmann
ccc005c012
- Discarded values: the legacy macro only changes <= and >=; != is true by default - Out-of-range numbers are rejected while parsing, not stored as NaN - merge_diff round trip: point to the ordered_json caveat - ensure_ascii example shows the escaped output - out_of_range.405 is thrown for "remove"/"move" on the root, not "add" - CBOR stores binary subtypes as tags - Integer/float comparison uses exact values, not conversion - diff, flatten, and the binary writers are depth-bounded - FAQ: max_digits10 for serialization, trailing commas are supported - out_of_range.407 is still thrown by to_bon8 - FetchContent_MakeAvailable needs CMake 3.14 - json_fwd.hpp contents, operator< link, RFC 7396 for merge patch - README: dump() wording, merge_diff, MSYS2/build2, patch comment typos, operator[] link, embedded CMake example aligned with the docs Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.8 KiB
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 7396) 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)
See also
push_back/emplace_back- append to an arrayemplace- insert into an object if the key is absentupdate- merge objects (shallow, or recursive withmerge_objects)merge_patch- apply an RFC 7396 merge patcherase/clear- remove elements- JSON Patch and Diff and JSON Merge Patch - structured modifications