Add recursive update function (#3069)

* ✨ add recursive update function

doc/mkdocs/docs/api/basic_json/update.md

@@ -2,14 +2,17 @@
 
 ```cpp
 // (1)
-void update(const_reference j);
+void update(const_reference j, bool merge_objects = false);
 
 // (2)
-void update(const_iterator first, const_iterator last);
+void update(const_iterator first, const_iterator last, bool merge_objects = false);
 ```
 
-1. Inserts all values from JSON object `j` and overwrites existing keys.
-2. Inserts all values from from range `[first, last)` and overwrites existing keys.
+1. Inserts all values from JSON object `j`.
+2. Inserts all values from from range `[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](https://docs.python.org/3.6/library/stdtypes.html#dict.update)
 function.
@@ -19,6 +22,10 @@ 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
 
@@ -73,6 +80,63 @@ function.
     --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"}
+    }
+    ```
+
 ## Version history
 
 - Added in version 3.0.0.
+- Added `merge_objects` parameter in 3.10.4.