Skip to content

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

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

## Parameters

`j` (in)
  JSON object to read values from
`merge_objects` (in)
  when `true`, existing keys are not overwritten, but contents of objects are merged recursively (default: `false`)
`first` (in)
  begin of the range of elements to insert
`last` (in)
  end of the range of elements to insert

## 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.202` if called on an iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
   - 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 usecase for this function is the handling of user settings. Assume your application can 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"}
    }

## Version history

- Added in version 3.0.0.
- Added `merge_objects` parameter in 3.10.4.

Last update: May 1, 2022
Back to top