nlohmann::basic_json::update

// (1)
void update(const_reference j, bool merge_objects = false);

// (2)
void update(const_iterator first, const_iterator last, bool merge_objects = false);
  1. Inserts all values from JSON object j.
  2. Inserts all values from range [first, last)

When merge_objects is false (default), existing keys are overwritten. When merge_objects is true, recursively merges objects with common keys.

If the JSON value is null, it is implicitly converted to an empty object before the values are inserted.

The function is motivated by Python's dict.update function.

Iterator invalidation

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.

Parameters

j (in) : JSON object to read values from

merge_objects (in) : when 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: false)

first (in) : the beginning of the range of elements to insert

last (in) : the end of the range of elements to insert

Exception safety

Basic guarantee: if an exception is thrown during the operation, the JSON value may be partially modified.

Exceptions

  1. The function can throw the following exceptions:
    • Throws type_error.312 if called on JSON values other than objects; example: "cannot use update() with string"
  2. The function can throw the following exceptions:
    • Throws type_error.312 if called on JSON values other than objects; example: "cannot use update() with string"
    • Throws invalid_iterator.210 if first and last do not belong to the same JSON value; example: "iterators do not fit"

Complexity

  1. O(N*log(size() + N)), where N is the number of elements to insert.
  2. O(N*log(size() + N)), where N is the number of elements to insert.

Examples

Example

The example shows how update() is used.

#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:

{
  "color": "blue",
  "names": {
    "en": "plane"
  },
  "price": 17.99,
  "speed": 100
}
{
  "color": "blue",
  "names": {
    "de": "Flugzeug",
    "en": "plane"
  },
  "price": 17.99,
  "speed": 100
}

Example

The example shows how update() is used.

#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:

{
  "color": "blue",
  "names": {
    "en": "plane"
  },
  "price": 17.99,
  "speed": 100
}
{
  "color": "blue",
  "names": {
    "de": "Flugzeug",
    "en": "plane"
  },
  "price": 17.99,
  "speed": 100
}

Example

One common use case for this function is the handling of user settings. Assume your application can be configured in some aspects:

{
    "color": "red",
    "active": true,
    "name": {"de": "Maus", "en": "mouse"}
}

The user may override the default settings selectively:

{
    "color": "blue",
    "name": {"es": "ratón"},
}

Then update manages the merging of default settings and user settings:

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:

{
    "color": "blue",
    "active": true,
    "name": {"es": "ratón"}
}

Note existing keys were just overwritten. To merge objects, merge_objects setting should be set to true:

auto user_settings = json::parse("config.json");
auto effective_settings = get_default_settings();
effective_settings.update(user_settings, true);

{
    "color": "blue",
    "active": true,
    "name": {"de": "Maus", "en": "mouse", "es": "ratón"}
}

See also

Version history

  • Added in version 3.0.0.
  • Added merge_objects parameter in 3.10.5.