deploy: 63c10a51fc

features/element_access/checked_access.md

@@ -6,7 +6,7 @@ The [`at`](../../api/basic_json/at.md) member function performs checked access;
 desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range)
 otherwise.
 
-??? example "Read access"
+??? example "Example: read access"
 
     Consider the following JSON value:
     
@@ -31,7 +31,7 @@ otherwise.
 
 The return value is a reference, so it can be used to modify the original value.
 
-??? example "Write access"
+??? example "Example: write access"
 
     ```cpp
     j.at("name") = "John Smith";
@@ -50,7 +50,7 @@ The return value is a reference, so it can be used to modify the original value.
 When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is
 non-existing, an exception is thrown.
 
-??? example "Accessing via invalid index or missing key"
+??? example "Example: access via invalid index or missing key"
 
     ```cpp
     j.at("hobbies").at(3) = "cooking";

features/element_access/checked_access/index.md

@@ -4,7 +4,7 @@
 
 The [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a [`basic_json::out_of_range` exception](https://json.nlohmann.me/home/exceptions/#out-of-range) otherwise.
 
-Read access
+Example: read access
 
 Consider the following JSON value:
 
@@ -29,7 +29,7 @@ Assume the value is parsed to a `json` variable `j`.
 
 The return value is a reference, so it can be used to modify the original value.
 
-Write access
+Example: write access
 
 ```
 j.at("name") = "John Smith";
@@ -47,7 +47,7 @@ This code produces the following JSON value:
 
 When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.
 
-Accessing via invalid index or missing key
+Example: access via invalid index or missing key
 
 ```
 j.at("hobbies").at(3) = "cooking";

features/element_access/default_value.md

@@ -41,9 +41,9 @@ you want to access and a default value in case there is no value stored with tha
 
     The value function is a template, and the return type of the function is determined by the type of the provided
     default value unless otherwise specified. This can have unexpected effects. In the example below, we store a 64-bit
-    unsigned integer. We get exactly that value when using [`operator[]`](../../api/basic_json/operator[].md). However,
-    when we call `value` and provide `#!c 0` as default value, then `#!c -1` is returned. This occurs, because `#!c 0`
-    has type `#!c int` which overflows when handling the value `#!c 18446744073709551615`.
+    unsigned integer. We get exactly that value when using [`operator[]`](../../api/basic_json/operator%5B%5D.md).
+    However, when we call `value` and provide `#!c 0` as default value, then `#!c -1` is returned. This occurs,
+    because `#!c 0` has type `#!c int` which overflows when handling the value `#!c 18446744073709551615`.
 
     To address this issue, either provide a correctly typed default value or use the template parameter to specify the
     desired return type. Note that this issue occurs even when a value is stored at the provided key, and the default

features/element_access/index.md

@@ -5,5 +5,17 @@ There are many ways elements in a JSON value can be accessed:
 - unchecked access via [`operator[]`](https://json.nlohmann.me/features/element_access/unchecked_access/index.md)
 - checked access via [`at`](https://json.nlohmann.me/features/element_access/checked_access/index.md)
 - access with default value via [`value`](https://json.nlohmann.me/features/element_access/default_value/index.md)
-- iterators
-- JSON pointers
+- [iterators](https://json.nlohmann.me/features/iterators/index.md)
+- [JSON pointers](https://json.nlohmann.me/features/json_pointer/index.md)
+
+Testing whether a key or index exists before accessing it is also possible, with [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md) or [`find`](https://json.nlohmann.me/api/basic_json/find/index.md) (which returns an iterator to the value, or `end()` if it is not found).
+
+```
+flowchart TD
+    A["accessing a value"] --> B{"must it exist?"}
+    B -->|"yes, missing is an error"| C["at() -- throws"]
+    B -->|"yes, but checking is my job"| D["operator[] -- unchecked"]
+    B -->|"no, a fallback is fine"| E["value() -- default value"]
+    A --> F{"just testing first?"}
+    F -->|"yes"| G["contains() / find()"]
+```

features/element_access/unchecked_access.md

@@ -5,7 +5,7 @@
 Elements in a JSON object and a JSON array can be accessed via [`operator[]`](../../api/basic_json/operator%5B%5D.md)
 similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
 
-??? example "Read access"
+??? example "Example: read access"
 
     Consider the following JSON value:
     
@@ -31,7 +31,7 @@ similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
 The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a
 `#!json null` value is inserted which can immediately be overwritten.
 
-??? example "Write access"
+??? example "Example: write access"
 
     ```cpp
     j["name"] = "John Smith";
@@ -52,7 +52,7 @@ The return value is a reference, so it can modify the original value. In case th
 When accessing an invalid index (i.e., an index greater than or equal to the array size), the JSON array is resized such
 that the passed index is the new maximal index. Intermediate values are filled with `#!json null`.
 
-??? example "Filling up arrays with `#!json null` values"
+??? example "Example: filling up arrays with `#!json null` values"
 
     ```cpp
     j["hobbies"][0] = "running";
@@ -94,8 +94,8 @@ that the passed index is the new maximal index. Intermediate values are filled w
     - It is **undefined behavior** to access a const object with a non-existing key.
     - It is **undefined behavior** to access a const array with an invalid index.
     - In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor
-      symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../macros.md#json_assertx). See the documentation
-      on [runtime assertions](../assertions.md) for more information.
+      symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../../api/macros/json_assert.md). See the
+      documentation on [runtime assertions](../assertions.md) for more information.
 
 !!! failure "Exceptions"
 
@@ -105,8 +105,9 @@ that the passed index is the new maximal index. Intermediate values are filled w
 ## Performance: reserving array capacity
 
 There is no public `reserve(count)` member on `basic_json` for pre-allocating array capacity. If you are building
-a large array incrementally (e.g., via repeated `push_back()`) and know its final size ahead of time, you can
-reserve capacity via `get_ref()` to access the underlying `array_t` directly:
+a large array incrementally (e.g., via repeated [`push_back()`](../../api/basic_json/push_back.md)) and know its final
+size ahead of time, you can reserve capacity via [`get_ref()`](../../api/basic_json/get_ref.md) to access the
+underlying `array_t` directly:
 
 ```cpp
 json j = json::array();

features/element_access/unchecked_access/index.md

@@ -4,7 +4,7 @@
 
 Elements in a JSON object and a JSON array can be accessed via [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) similar to a `std::map` and a `std::vector`, respectively.
 
-Read access
+Example: read access
 
 Consider the following JSON value:
 
@@ -29,7 +29,7 @@ Assume the value is parsed to a `json` variable `j`.
 
 The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a `null` value is inserted which can immediately be overwritten.
 
-Write access
+Example: write access
 
 ```
 j["name"] = "John Smith";
@@ -49,7 +49,7 @@ This code produces the following JSON value:
 
 When accessing an invalid index (i.e., an index greater than or equal to the array size), the JSON array is resized such that the passed index is the new maximal index. Intermediate values are filled with `null`.
 
-Filling up arrays with `null` values
+Example: filling up arrays with `null` values
 
 ```
 j["hobbies"][0] = "running";
@@ -86,7 +86,7 @@ Danger
 
 - It is **undefined behavior** to access a const object with a non-existing key.
 - It is **undefined behavior** to access a const array with an invalid index.
-- In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor symbol `NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](https://json.nlohmann.me/features/macros/#json_assertx). See the documentation on [runtime assertions](https://json.nlohmann.me/features/assertions/index.md) for more information.
+- In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor symbol `NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](https://json.nlohmann.me/api/macros/json_assert/index.md). See the documentation on [runtime assertions](https://json.nlohmann.me/features/assertions/index.md) for more information.
 
 Exceptions
 
@@ -94,7 +94,7 @@ Exceptions
 
 ## Performance: reserving array capacity
 
-There is no public `reserve(count)` member on `basic_json` for pre-allocating array capacity. If you are building a large array incrementally (e.g., via repeated `push_back()`) and know its final size ahead of time, you can reserve capacity via `get_ref()` to access the underlying `array_t` directly:
+There is no public `reserve(count)` member on `basic_json` for pre-allocating array capacity. If you are building a large array incrementally (e.g., via repeated [`push_back()`](https://json.nlohmann.me/api/basic_json/push_back/index.md)) and know its final size ahead of time, you can reserve capacity via [`get_ref()`](https://json.nlohmann.me/api/basic_json/get_ref/index.md) to access the underlying `array_t` directly:
 
 ```
 json j = json::array();