// (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.
The function is motivated by Python's dict.update function.
j
(in) : JSON object to read values from
merge_objects
(in) : when #!c true
, existing keys are not overwritten, but contents of objects are merged recursively (default: #!c false
)
first
(in) : begin of the range of elements to insert
last
(in) : end of the range of elements to insert
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.202
if called on an iterator which does not belong to the current JSON value; example: "iterator does not fit current value"
invalid_iterator.210
if first
and last
do not belong to the same JSON value; example: "iterators do not fit"
??? example
The example shows how `update()` is used. ```cpp --8<-- "examples/update.cpp" ``` Output: ```json --8<-- "examples/update.output" ```
??? example
The example shows how `update()` is used. ```cpp --8<-- "examples/update__range.cpp" ``` Output: ```json --8<-- "examples/update__range.output" ```
??? example
One common usecase for this function is the handling of user settings. Assume your application can 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.4.