Point users to update(…, true), JSON Pointer defaults, and built-in std::optional (#5804)

A code search of client code found many hand-written versions of
functionality the library already has: recursive object merges
(update(j, true) since 3.10.5), dotted-path getters (value() and
contains() with a JSON Pointer), get_or helpers (value() throws for a
member that is present but null), and adl_serializer specializations
for std::optional (supported since 3.12.0).

- modifying_values.md: describe both modes of update(), add a
  defaults + user settings recipe, and stop recommending Merge Patch
  for recursive merges.
- merge_patch.md: note that null deletes keys, so a merge patch is not
  a general deep merge; link update().
- default_value.md: add "Nested values" (value/contains with a JSON
  Pointer, building a pointer from a dotted path with operator/=) and
  a warning that null and mistyped members are not missing.
- value.md: note that a null member is converted, not replaced by the
  default.
- json_pointer.md: link value/contains/at with JSON Pointers.
- arbitrary_types.md: note that std::optional needs no serializer.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/features/element_access/default_value.md

@@ -30,6 +30,47 @@ you want to access and a default value in case there is no value stored with tha
     | `#!cpp j.value("append", false)`            | `#!json true`                                        |
     | `#!cpp j.value("logLevel", "verbose")`      | `#!json "verbose"`                                   |
 
+## Nested values
+
+To read a value deep inside a document, pass a [JSON Pointer](../json_pointer.md) instead of a key. The default value is
+returned if the value at the pointer does not exist, including the case that an intermediate key is missing. There is
+no need to check each level with [`contains`](../../api/basic_json/contains.md) first.
+
+```cpp
+json j = {{"server", {{"port", 8080}}}, {"list", {10, 20}}};
+
+int port = j.value("/server/port"_json_pointer, 80);        // 8080
+int timeout = j.value("/server/limits/timeout"_json_pointer, 30); // 30 (missing intermediate key)
+int second = j.value("/list/1"_json_pointer, 0);            // 20 (numeric tokens index arrays)
+int third = j.value("/list/5"_json_pointer, 0);             // 0 (index out of range)
+
+bool has_port = j.contains("/server/port"_json_pointer);    // true
+bool has_host = j.contains("/server/host/name"_json_pointer); // false
+```
+
+If the path is only available as a dotted string such as `#!cpp "server.port"`, do not build the pointer by
+concatenating `#!cpp "/"` and the parts: keys containing `/` or `~` would be misinterpreted. Append each part as a
+reference token with [`operator/=`](../../api/json_pointer/operator_slasheq.md) instead. It escapes the token for you.
+
+```cpp
+json::json_pointer to_pointer(const std::string& dotted)
+{
+    json::json_pointer ptr;
+    std::istringstream in(dotted);
+    for (std::string token; std::getline(in, token, '.');)
+    {
+        ptr /= token;
+    }
+    return ptr;
+}
+
+int port = j.value(to_pointer("server.port"), 80);          // 8080
+int first = j.value(to_pointer("list.0"), 0);               // 10
+```
+
+The key `#!cpp "a/b"` yields the pointer `#!cpp "/a~1b"`; the dot-splitting itself is up to the caller, so keys
+containing `.` need a different separator.
+
 ## Notes
 
 !!! failure "Exceptions"
@@ -37,6 +78,31 @@ you want to access and a default value in case there is no value stored with tha
     - With string keys, `value` can only be used with objects. For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error306) is thrown.
     - With JSON Pointers, `value` can be used with both objects and arrays. For other types (null, boolean, number, string), a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error306) is thrown.
 
+!!! warning "`null` and mistyped members are not missing"
+
+    `value` returns the default value only if the key is **absent**. If the member exists, it is converted to the type
+    of the default value, even if it is `#!json null`. For `#!json {"k": null}`, the call `#!cpp j.value("k", 0)` throws
+    a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error302), and so does a member of another
+    type such as a string where a number is expected. The same holds for JSON Pointers.
+
+    To treat `#!json null` like a missing value, check for it explicitly:
+
+    ```cpp
+    int n = (j.contains("k") && !j["k"].is_null()) ? j["k"].get<int>() : 0;
+    ```
+
+    With C++17, [`get<std::optional<T>>()`](../../api/basic_json/get.md) maps `#!json null` to an empty optional. As
+    [`at`](../../api/basic_json/at.md) throws [`out_of_range`](../../home/exceptions.md#jsonexceptionout_of_range403)
+    for an absent key, use [`find`](../../api/basic_json/find.md) to cover both cases:
+
+    ```cpp
+    std::optional<int> n;                        // empty if "k" is absent or null
+    if (const auto it = j.find("k"); it != j.end())
+    {
+        n = it->get<std::optional<int>>();       // still throws for a non-number such as "text"
+    }
+    ```
+
 !!! warning "Return type"
 
     The value function is a template, and the return type of the function is determined by the type of the provided
@@ -63,3 +129,6 @@ you want to access and a default value in case there is no value stored with tha
 
 - [`value`](../../api/basic_json/value.md) for access with default value
 - documentation on [checked access](checked_access.md)
+- documentation on [JSON Pointer](../json_pointer.md)
+- [`contains`](../../api/basic_json/contains.md) to check whether a key or JSON Pointer exists
+- [`json_pointer::operator/=`](../../api/json_pointer/operator_slasheq.md) to build a pointer token by token