// (1) void update(const_reference j, bool merge_objects = false); // (2) void update(const_iterator first, const_iterator last, bool merge_objects = false);
j.[first, last)When merge_objects is #!c false (default), existing keys are overwritten. When merge_objects is #!c true, recursively merges objects with common keys.
If the JSON value is #!json null, it is implicitly converted to an empty object before the values are inserted.
The function is motivated by Python's dict.update function.
For ordered_json, adding a value to an object can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.
j (in) : JSON object to read values from
merge_objects (in) : when #!c true, keys that exist in both objects and whose value in the source is itself an object are merged recursively; all other values are overwritten as usual (default: #!c false)
first (in) : the beginning of the range of elements to insert
last (in) : the end of the range of elements to insert
Basic guarantee: if an exception is thrown during the operation, the JSON value may be partially modified.
type_error.312 if called on JSON values other than objects; example: "cannot use update() with string"type_error.312 if called on JSON values other than objects; example: "cannot use update() with string"invalid_iterator.210 if first and last do not belong to the same JSON value; example: "iterators do not fit"The argument j (or, for overload (2), the range [first, last)) may be #!cpp *this itself or refer to a value contained in #!cpp *this (for example, a subobject returned by #!cpp (*this)[key]); it is read as it was when update() was called, before any modification of #!cpp *this.
??? example “Example: (1) update with another object”
The example shows how `update()` is used.
```cpp
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create two JSON objects
json o1 = R"( {"color": "red", "price": 17.99, "names": {"de": "Flugzeug"}} )"_json;
json o2 = R"( {"color": "blue", "speed": 100, "names": {"en": "plane"}} )"_json;
json o3 = o1;
// add all keys from o2 to o1 (updating "color", replacing "names")
o1.update(o2);
// add all keys from o2 to o1 (updating "color", merging "names")
o3.update(o2, true);
// output updated object o1 and o3
std::cout << std::setw(2) << o1 << '\n';
std::cout << std::setw(2) << o3 << '\n';
}
```
Output:
```json
{
"color": "blue",
"names": {
"en": "plane"
},
"price": 17.99,
"speed": 100
}
{
"color": "blue",
"names": {
"de": "Flugzeug",
"en": "plane"
},
"price": 17.99,
"speed": 100
}
```
??? example “Example: (2) update with an iterator range”
The example shows how `update()` is used.
```cpp
#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create two JSON objects
json o1 = R"( {"color": "red", "price": 17.99, "names": {"de": "Flugzeug"}} )"_json;
json o2 = R"( {"color": "blue", "speed": 100, "names": {"en": "plane"}} )"_json;
json o3 = o1;
// add all keys from o2 to o1 (updating "color", replacing "names")
o1.update(o2.begin(), o2.end());
// add all keys from o2 to o1 (updating "color", merging "names")
o3.update(o2.begin(), o2.end(), true);
// output updated object o1 and o3
std::cout << std::setw(2) << o1 << '\n';
std::cout << std::setw(2) << o3 << '\n';
}
```
Output:
```json
{
"color": "blue",
"names": {
"en": "plane"
},
"price": 17.99,
"speed": 100
}
{
"color": "blue",
"names": {
"de": "Flugzeug",
"en": "plane"
},
"price": 17.99,
"speed": 100
}
```
??? example “Example: (1) merge user settings into default settings”
One common use case for this function is the handling of user settings. Assume your application can be configured in
some aspects:
```json
{
"color": "red",
"active": true,
"name": {"de": "Maus", "en": "mouse"}
}
```
The user may override the default settings selectively:
```json
{
"color": "blue",
"name": {"es": "ratón"},
}
```
Then `update` manages the merging of default settings and user settings:
```cpp
auto user_settings = json::parse("config.json");
auto effective_settings = get_default_settings();
effective_settings.update(user_settings);
```
Now `effective_settings` contains the default settings, but those keys set by the user are overwritten:
```json
{
"color": "blue",
"active": true,
"name": {"es": "ratón"}
}
```
Note existing keys were just overwritten. To merge objects, `merge_objects` setting should be set to `#!c true`:
```cpp
auto user_settings = json::parse("config.json");
auto effective_settings = get_default_settings();
effective_settings.update(user_settings, true);
```
```json
{
"color": "blue",
"active": true,
"name": {"de": "Maus", "en": "mouse", "es": "ratón"}
}
```
merge_objects parameter in 3.10.5.#!cpp *this or refers to a value contained in #!cpp *this, in version 3.13.0.