deploy: 63c10a51fc

api/basic_json/accept.md

@@ -96,7 +96,7 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
 
 ## Examples
 
-??? example
+??? example "Example: (1) reading from a string"
 
     The example below demonstrates the `accept()` function reading from a string.
 
@@ -110,6 +110,21 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
     --8<-- "examples/accept__string.output"
     ```
 
+??? example "Example: (2) reading from an iterator pair"
+
+    The example below demonstrates the `accept()` function reading from an iterator pair. Only the first call covers
+    exactly the JSON text; the second one also covers the trailing bytes and is therefore rejected.
+
+    ```cpp
+    --8<-- "examples/accept__iterator_pair.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/accept__iterator_pair.output"
+    ```
+
 ## See also
 
 - [parse](parse.md) - deserialize from a compatible input
@@ -137,3 +152,5 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
 
     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
     function.
+
+    See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.

api/basic_json/accept/index.md

@@ -88,7 +88,7 @@ By default, a `'\0'` (NUL) byte anywhere in the input is treated as end of input
 
 ## Examples
 
-Example
+Example: (1) reading from a string
 
 The example below demonstrates the `accept()` function reading from a string.
 
@@ -127,6 +127,34 @@ Output:
 true false
 ```
 
+Example: (2) reading from an iterator pair
+
+The example below demonstrates the `accept()` function reading from an iterator pair. Only the first call covers exactly the JSON text; the second one also covers the trailing bytes and is therefore rejected.
+
+```
+#include <iostream>
+#include <vector>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // a buffer containing a JSON text followed by more data
+    std::vector<std::uint8_t> input = {'[', '1', ',', '2', ',', '3', ']', 'o', 't', 'h', 'e', 'r'};
+
+    std::cout << std::boolalpha
+              << json::accept(input.begin(), input.begin() + 7) << ' '
+              << json::accept(input.begin(), input.end()) << '\n';
+}
+```
+
+Output:
+
+```
+true false
+```
+
 ## See also
 
 - [parse](https://json.nlohmann.me/api/basic_json/parse/index.md) - deserialize from a compatible input
@@ -139,13 +167,15 @@ true false
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](https://json.nlohmann.me/features/assertions/index.md) in case of `FILE*` null pointers to exception in version 3.12.0.
-- Added `ignore_trailing_commas` in version 3.13.0.
-- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
-- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
-- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 to optionally reject a NUL byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.
+- Added `ignore_trailing_commas` in version 3.13.0 unreleased.
+- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
+- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
+- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 unreleased to optionally reject a NUL byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.
 
 Deprecation
 
 Overload (2) replaces calls to `accept` with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like `accept({ptr, ptr+len}, ...);` with `accept(ptr, ptr+len, ...);`.
 
 You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#parsing) for how to update existing code.

api/basic_json/array_t.md

@@ -25,7 +25,7 @@ To store objects in C++, a type is defined by the template parameters explained
 
 ## Notes
 
-#### Default type
+### Default type
 
 With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default value for
 `array_t` is:
@@ -37,7 +37,7 @@ std::vector<
 >
 ```
 
-#### Limits
+### Limits
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
 > An implementation may set limits on the maximum depth of nesting.
@@ -46,7 +46,7 @@ In this class, the array's limit of nesting is not explicitly constrained. Howev
 introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the
 [`max_size`](max_size.md) function of a JSON array.
 
-#### Storage
+### Storage
 
 Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type
 `#!cpp array_t*` must be dereferenced.
@@ -67,6 +67,13 @@ Arrays are stored as pointers in a `basic_json` type. That is, for any access to
     --8<-- "examples/array_t.output"
     ```
 
+## See also
+
+- [object_t](object_t.md) the type used to store JSON objects
+- [binary_t](binary_t.md) the type used to store binary values
+- [is_array](is_array.md) checks whether the JSON value is an array
+- [max_size](max_size.md) returns the maximum possible number of elements
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/array_t/index.md

@@ -20,7 +20,7 @@ To store objects in C++, a type is defined by the template parameters explained
 
 ## Notes
 
-#### Default type
+### Default type
 
 With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default value for `array_t` is:
 
@@ -31,7 +31,7 @@ std::vector<
 >
 ```
 
-#### Limits
+### Limits
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) specifies:
 
@@ -39,7 +39,7 @@ std::vector<
 
 In this class, the array's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the [`max_size`](https://json.nlohmann.me/api/basic_json/max_size/index.md) function of a JSON array.
 
-#### Storage
+### Storage
 
 Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type `array_t*` must be dereferenced.
 
@@ -68,7 +68,14 @@ Output:
 true
 ```
 
+## See also
+
+- [object_t](https://json.nlohmann.me/api/basic_json/object_t/index.md) the type used to store JSON objects
+- [binary_t](https://json.nlohmann.me/api/basic_json/binary_t/index.md) the type used to store binary values
+- [is_array](https://json.nlohmann.me/api/basic_json/is_array/index.md) checks whether the JSON value is an array
+- [max_size](https://json.nlohmann.me/api/basic_json/max_size/index.md) returns the maximum possible number of elements
+
 ## Version history
 
 - Added in version 1.0.0.
-- Made `capacity()` optional, so that array types such as `std::deque` can be used, in version 3.13.0.
+- Made `capacity()` optional, so that array types such as `std::deque` can be used, in version 3.13.0 unreleased.

api/basic_json/at.md

@@ -92,6 +92,20 @@ Strong exception safety: if an exception occurs, the original value stays intact
 3. Logarithmic in the size of the container.
 4. Logarithmic in the size of the container.
 
+## Notes
+
+!!! warning "Deprecation"
+
+    Overload (4) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json`
+    specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since
+    version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`,
+    `nlohmann::json_pointer<std::string>`) instead.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.
+
+    See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
+
 ## Examples
 
 ??? example "Example: (1) access specified array element with bounds checking"

api/basic_json/at/index.md

@@ -73,6 +73,16 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Logarithmic in the size of the container.
 1. Logarithmic in the size of the container.
 
+## Notes
+
+Deprecation
+
+Overload (4) also accepts a [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) whose template argument is a `basic_json` specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`, `nlohmann::json_pointer<std::string>`) instead.
+
+You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#json-pointers) for how to update existing code.
+
 ## Examples
 
 Example: (1) access specified array element with bounds checking

api/basic_json/basic_json.md

@@ -99,6 +99,25 @@ basic_json(basic_json&& other) noexcept;
       elements of the pairs are treated as keys and the second elements are as values.
     3. In all other cases, an array is created.
     
+    The following flowchart also takes into account what happens when `type_deduction` is `#!cpp false`, in which case
+    `manual_type` decides between object and array, and an object can only be forced if `init` actually matches rule 2
+    (or is empty):
+
+    ```mermaid
+    flowchart TD
+        A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
+        B -->|"yes"| C{"type_deduction"}
+        B -->|"no"| D{"type_deduction"}
+        C -->|"true"| OBJ["create object"]
+        C -->|"false"| E{"manual_type"}
+        E -->|"object"| OBJ
+        E -->|"array"| ARR["create array"]
+        D -->|"true"| ARR
+        D -->|"false"| F{"manual_type"}
+        F -->|"array"| ARR
+        F -->|"object"| ERR["throw type_error.301"]
+    ```
+
     The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
     
     1. The empty initializer list is written as `#!cpp {}` which is exactly an empty JSON object.
@@ -171,8 +190,8 @@ basic_json(basic_json&& other) noexcept;
     - `BasicJsonType` has different template arguments than `basic_json_t`.
     
     **Note:** For cross-`basic_json` conversions to produce correct results, the target `basic_json`'s
-    `object_t::key_type` and `string_t` must be directly constructible from the source `basic_json`'s
-    corresponding types. See the description of overload (4) above for details on what happens when
+    [`object_t`](object_t.md)`::key_type` and [`string_t`](string_t.md) must be directly constructible from the source
+    `basic_json`'s corresponding types. See the description of overload (4) above for details on what happens when
     this requirement is not met.
 
 `U`:
@@ -347,6 +366,22 @@ basic_json(basic_json&& other) noexcept;
 
     Note the output is platform-dependent.
 
+??? example "Example: (4) create a JSON value from another `basic_json` specialization"
+
+    The example below shows how a `json` value is converted to an `ordered_json` value and back using the converting
+    constructor. Note how the original insertion order of `oj` is not restored, because it was already given up when
+    converting to `json`, whose `object_t` sorts by key.
+
+    ```cpp
+    --8<-- "examples/basic_json__BasicJsonType.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json__BasicJsonType.output"
+    ```
+
 ??? example "Example: (5) create a container (array or object) from an initializer list"
 
     The example below shows how JSON values are created from initializer lists.
@@ -417,6 +452,15 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__moveconstructor.output"
     ```
 
+## See also
+
+- [array](array.md) create a JSON array value, forcing array creation from an initializer list even when it looks like
+  an object
+- [object](object.md) create a JSON object value, forcing object creation from an initializer list
+- [binary](binary.md) create a JSON binary array value
+- [operator=](operator=.md) copy assignment operator
+- [Creating JSON values](../../features/creating_values.md) - the article on creating JSON values
+
 ## Version history
 
 1. Since version 1.0.0.

api/basic_json/basic_json/index.md

@@ -75,6 +75,23 @@ basic_json(basic_json&& other) noexcept;
    1. If the list consists of pairs whose first element is a string, a JSON object value is created where the first elements of the pairs are treated as keys and the second elements are as values.
    1. In all other cases, an array is created.
 
+   The following flowchart also takes into account what happens when `type_deduction` is `false`, in which case `manual_type` decides between object and array, and an object can only be forced if `init` actually matches rule 2 (or is empty):
+
+   ```
+   flowchart TD
+       A(["initializer_list init"]) --> B{"empty, or every element is a 2-element<br/>array whose first element is a string?"}
+       B -->|"yes"| C{"type_deduction"}
+       B -->|"no"| D{"type_deduction"}
+       C -->|"true"| OBJ["create object"]
+       C -->|"false"| E{"manual_type"}
+       E -->|"object"| OBJ
+       E -->|"array"| ARR["create array"]
+       D -->|"true"| ARR
+       D -->|"false"| F{"manual_type"}
+       F -->|"array"| ARR
+       F -->|"object"| ERR["throw type_error.301"]
+   ```
+
    The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:
 
    1. The empty initializer list is written as `{}` which is exactly an empty JSON object.
@@ -134,8 +151,8 @@ basic_json(basic_json&& other) noexcept;
 - `BasicJsonType` has different template arguments than `basic_json_t`.
 
 **Note:** For cross-`basic_json` conversions to produce correct results, the target `basic_json`'s
-`object_t::key_type` and `string_t` must be directly constructible from the source `basic_json`'s
-corresponding types. See the description of overload (4) above for details on what happens when
+[`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md)`::key_type` and [`string_t`](https://json.nlohmann.me/api/basic_json/string_t/index.md) must be directly constructible from the source
+`basic_json`'s corresponding types. See the description of overload (4) above for details on what happens when
 this requirement is not met.
 ```
 
@@ -360,7 +377,7 @@ int main()
     // create an object from std::unordered_multimap
     std::unordered_multimap<std::string, bool> c_ummap
     {
-        {"one", true}, {"two", true}, {"three", false}, {"three", true}
+        {"one", true}, {"two", true}, {"three", false}, {"three", false}
     };
     json j_ummap(c_ummap); // only one entry for key "three" is used
 
@@ -408,7 +425,7 @@ int main()
     json j_set(c_set); // only one entry for "one" is used
 
     // create an array from std::unordered_set
-    std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
+    std::unordered_set<std::string> c_uset {"one", "one"};
     json j_uset(c_uset); // only one entry for "one" is used
 
     // create an array from std::multiset
@@ -416,7 +433,7 @@ int main()
     json j_mset(c_mset); // both entries for "one" are used
 
     // create an array from std::unordered_multiset
-    std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
+    std::unordered_multiset<std::string> c_umset {"one", "one"};
     json j_umset(c_umset); // both entries for "one" are used
 
     // serialize the JSON arrays
@@ -547,9 +564,9 @@ Output:
 [12345678909876,23456789098765,34567890987654,45678909876543]
 [1,2,3,4]
 ["four","one","three","two"]
-["four","three","two","one"]
+["one"]
 ["four","one","one","two"]
-["four","two","one","one"]
+["one","one"]
 
 "The quick brown fox jumps over the lazy dog."
 "The quick brown fox jumps over the lazy dog."
@@ -576,6 +593,43 @@ false
 
 Note the output is platform-dependent.
 
+Example: (4) create a JSON value from another `basic_json` specialization
+
+The example below shows how a `json` value is converted to an `ordered_json` value and back using the converting constructor. Note how the original insertion order of `oj` is not restored, because it was already given up when converting to `json`, whose `object_t` sorts by key.
+
+```
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+using ordered_json = nlohmann::ordered_json;
+
+int main()
+{
+    // create an ordered_json value; insertion order is preserved
+    ordered_json oj = {{"c", 3}, {"a", 1}, {"b", 2}};
+
+    // convert to json -- overload (4) is used; keys end up sorted
+    json j(oj);
+
+    // convert back to ordered_json -- the original insertion order is lost,
+    // because it was already given up when converting to json
+    ordered_json oj2(j);
+
+    std::cout << oj << '\n';
+    std::cout << j << '\n';
+    std::cout << oj2 << '\n';
+}
+```
+
+Output:
+
+```
+{"c":3,"a":1,"b":2}
+{"a":1,"b":2,"c":3}
+{"a":1,"b":2,"c":3}
+```
+
 Example: (5) create a container (array or object) from an initializer list
 
 The example below shows how JSON values are created from initializer lists.
@@ -757,6 +811,14 @@ null
 23
 ```
 
+## See also
+
+- [array](https://json.nlohmann.me/api/basic_json/array/index.md) create a JSON array value, forcing array creation from an initializer list even when it looks like an object
+- [object](https://json.nlohmann.me/api/basic_json/object/index.md) create a JSON object value, forcing object creation from an initializer list
+- [binary](https://json.nlohmann.me/api/basic_json/binary/index.md) create a JSON binary array value
+- [operator=](https://json.nlohmann.me/api/basic_json/operator%3D/index.md) copy assignment operator
+- [Creating JSON values](https://json.nlohmann.me/features/creating_values/index.md) - the article on creating JSON values
+
 ## Version history
 
 1. Since version 1.0.0.
@@ -765,6 +827,6 @@ null
 1. Since version 3.2.0.
 1. Since version 1.0.0.
 1. Since version 1.0.0.
-1. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied, unlike the other primitive types.
+1. Since version 1.0.0. Fixed in version 3.13.0 unreleased to also check the iterator range for binary values; before, a range that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied, unlike the other primitive types.
 1. Since version 1.0.0.
 1. Since version 1.0.0.

api/basic_json/begin.md

@@ -37,6 +37,14 @@ Constant.
     --8<-- "examples/begin.output"
     ```
 
+## See also
+
+- [end](end.md) returns an iterator to one past the last element
+- [cbegin](cbegin.md) returns a const iterator to the first element
+- [rbegin](rbegin.md) returns a reverse iterator to the last element
+- [items](items.md) returns an iteration proxy to access keys and values during range-based for loops
+- [Iterators](../../features/iterators.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/begin/index.md

@@ -50,6 +50,14 @@ Output:
 1
 ```
 
+## See also
+
+- [end](https://json.nlohmann.me/api/basic_json/end/index.md) returns an iterator to one past the last element
+- [cbegin](https://json.nlohmann.me/api/basic_json/cbegin/index.md) returns a const iterator to the first element
+- [rbegin](https://json.nlohmann.me/api/basic_json/rbegin/index.md) returns a reverse iterator to the last element
+- [items](https://json.nlohmann.me/api/basic_json/items/index.md) returns an iteration proxy to access keys and values during range-based for loops
+- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/binary.md

@@ -7,9 +7,9 @@ static basic_json binary(typename binary_t::container_type&& init);
 
 // (2)
 static basic_json binary(const typename binary_t::container_type& init,
-                         std::uint8_t subtype);
+                         typename binary_t::subtype_type subtype);
 static basic_json binary(typename binary_t::container_type&& init,
-                         std::uint8_t subtype);
+                         typename binary_t::subtype_type subtype);
 ```
 
 1. Creates a JSON binary array value from a given binary container.
@@ -61,6 +61,15 @@ initialization of a binary array type, for backwards compatibility and so it doe
     --8<-- "examples/binary.output"
     ```
 
+## See also
+
+- [binary_t](binary_t.md) type for binary values
+- [get_binary](get_binary.md) get a reference to the stored binary value
+- [is_binary](is_binary.md) return whether the value is binary
+- [byte_container_with_subtype](../byte_container_with_subtype/index.md) container for binary values with subtype
+- [Binary Values](../../features/binary_values.md) - the article on binary values
+
 ## Version history
 
 - Added in version 3.8.0.
+- Changed the type of `subtype` from `std::uint8_t` to `binary_t::subtype_type` (`std::uint64_t`) in version 3.10.0.

api/basic_json/binary/index.md

@@ -7,9 +7,9 @@ static basic_json binary(typename binary_t::container_type&& init);
 
 // (2)
 static basic_json binary(const typename binary_t::container_type& init,
-                         std::uint8_t subtype);
+                         typename binary_t::subtype_type subtype);
 static basic_json binary(typename binary_t::container_type&& init,
-                         std::uint8_t subtype);
+                         typename binary_t::subtype_type subtype);
 ```
 
 1. Creates a JSON binary array value from a given binary container.
@@ -70,6 +70,15 @@ Output:
 type: binary, subtype: 42
 ```
 
+## See also
+
+- [binary_t](https://json.nlohmann.me/api/basic_json/binary_t/index.md) type for binary values
+- [get_binary](https://json.nlohmann.me/api/basic_json/get_binary/index.md) get a reference to the stored binary value
+- [is_binary](https://json.nlohmann.me/api/basic_json/is_binary/index.md) return whether the value is binary
+- [byte_container_with_subtype](https://json.nlohmann.me/api/byte_container_with_subtype/index.md) container for binary values with subtype
+- [Binary Values](https://json.nlohmann.me/features/binary_values/index.md) - the article on binary values
+
 ## Version history
 
 - Added in version 3.8.0.
+- Changed the type of `subtype` from `std::uint8_t` to `binary_t::subtype_type` (`std::uint64_t`) in version 3.10.0.

api/basic_json/binary_t.md

@@ -48,16 +48,16 @@ represent a byte array in modern C++.
 
 ## Notes
 
-#### Default type
+### Default type
 
 The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.
 
-#### Supported byte types
+### Supported byte types
 
 `#!cpp std::vector<std::uint8_t>`, `#!cpp std::vector<char>`, and `#!cpp std::vector<std::byte>` are supported.
 Regardless of which of them is configured, [`dump`](dump.md) writes the bytes as the numbers 0..255.
 
-#### Custom BinaryType behavior
+### Custom BinaryType behavior
 
 When a custom `BinaryType` is configured (other than the default `#!cpp std::vector<std::uint8_t>`), you can assign
 values of that type directly to a `basic_json` instance, and they will automatically be recognized as binary values
@@ -89,12 +89,12 @@ assert(extracted == data);
 This automatic type detection is a convenience feature that only applies to custom (non-default) `BinaryType` configurations.
 The default `nlohmann::json` continues to treat `#!cpp std::vector<std::uint8_t>` as arrays for backward compatibility.
 
-#### Storage
+### Storage
 
 Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the
 type `#!cpp binary_t*` must be dereferenced.
 
-#### Notes on subtypes
+### Notes on subtypes
 
 - CBOR
     - Binary values are represented as byte strings. Subtypes are written as tags.

api/basic_json/binary_t/index.md

@@ -42,15 +42,15 @@ the binary readers additionally require `resize()` and `operator[]`. See
 
 ## Notes
 
-#### Default type
+### Default type
 
 The default values for `BinaryType` is `std::vector<std::uint8_t>`.
 
-#### Supported byte types
+### Supported byte types
 
 `std::vector<std::uint8_t>`, `std::vector<char>`, and `std::vector<std::byte>` are supported. Regardless of which of them is configured, [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) writes the bytes as the numbers 0..255.
 
-#### Custom BinaryType behavior
+### Custom BinaryType behavior
 
 When a custom `BinaryType` is configured (other than the default `std::vector<std::uint8_t>`), you can assign values of that type directly to a `basic_json` instance, and they will automatically be recognized as binary values rather than arrays:
 
@@ -79,11 +79,11 @@ assert(extracted == data);
 
 This automatic type detection is a convenience feature that only applies to custom (non-default) `BinaryType` configurations. The default `nlohmann::json` continues to treat `std::vector<std::uint8_t>` as arrays for backward compatibility.
 
-#### Storage
+### Storage
 
 Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the type `binary_t*` must be dereferenced.
 
-#### Notes on subtypes
+### Notes on subtypes
 
 - CBOR
 
@@ -131,4 +131,4 @@ true
 ## Version history
 
 - Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0.
-- Fixed [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md), [`std::hash`](https://json.nlohmann.me/api/basic_json/std_hash/index.md), and [`to_ubjson`](https://json.nlohmann.me/api/basic_json/to_ubjson/index.md) for byte types that are not integers (e.g., `std::byte`) in version 3.13.0. `dump` now writes the bytes of a signed byte type (e.g., `char`) as 0..255 rather than as negative numbers.
+- Fixed [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md), [`std::hash`](https://json.nlohmann.me/api/basic_json/std_hash/index.md), and [`to_ubjson`](https://json.nlohmann.me/api/basic_json/to_ubjson/index.md) for byte types that are not integers (e.g., `std::byte`) in version 3.13.0 unreleased. `dump` now writes the bytes of a signed byte type (e.g., `char`) as 0..255 rather than as negative numbers.

api/basic_json/boolean_t.md

@@ -21,11 +21,11 @@ To store boolean values in C++, a type is defined by the template parameter  `Bo
 
 ## Notes
 
-#### Default type
+### Default type
 
 With the default values for `BooleanType` (`#!cpp bool`), the default value for `boolean_t` is `#!cpp bool`.
 
-#### Storage
+### Storage
 
 Boolean values are stored directly inside a `basic_json` type.
 
@@ -45,6 +45,10 @@ Boolean values are stored directly inside a `basic_json` type.
     --8<-- "examples/boolean_t.output"
     ```
 
+## See also
+
+- [is_boolean](is_boolean.md) checks whether the JSON value is a boolean
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/boolean_t/index.md

@@ -16,11 +16,11 @@ To store boolean values in C++, a type is defined by the template parameter `Boo
 
 ## Notes
 
-#### Default type
+### Default type
 
 With the default values for `BooleanType` (`bool`), the default value for `boolean_t` is `bool`.
 
-#### Storage
+### Storage
 
 Boolean values are stored directly inside a `basic_json` type.
 
@@ -49,6 +49,10 @@ Output:
 true
 ```
 
+## See also
+
+- [is_boolean](https://json.nlohmann.me/api/basic_json/is_boolean/index.md) checks whether the JSON value is a boolean
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/cbegin.md

@@ -36,6 +36,13 @@ Constant.
     --8<-- "examples/cbegin.output"
     ```
 
+## See also
+
+- [begin](begin.md) returns an iterator to the first element
+- [cend](cend.md) returns a const iterator to one past the last element
+- [crbegin](crbegin.md) returns a const reverse iterator to the last element
+- [Iterators](../../features/iterators.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/cbegin/index.md

@@ -49,6 +49,13 @@ Output:
 1
 ```
 
+## See also
+
+- [begin](https://json.nlohmann.me/api/basic_json/begin/index.md) returns an iterator to the first element
+- [cend](https://json.nlohmann.me/api/basic_json/cend/index.md) returns a const iterator to one past the last element
+- [crbegin](https://json.nlohmann.me/api/basic_json/crbegin/index.md) returns a const reverse iterator to the last element
+- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/cbor_tag_handler_t.md

@@ -38,6 +38,12 @@ store
     --8<-- "examples/cbor_tag_handler_t.output"
     ```
 
+## See also
+
+- [from_cbor](from_cbor.md) deserializes a JSON value from CBOR
+- [input_format_t](input_format_t.md) the enumeration of supported input formats
+- [CBOR](../../features/binary_formats/cbor.md) - the article on the CBOR format
+
 ## Version history
 
 - Added in version 3.9.0. Added value `store` in 3.10.0.

api/basic_json/cbor_tag_handler_t/index.md

@@ -62,6 +62,12 @@ Output:
 {"bytes":[202,254,186,190],"subtype":66}
 ```
 
+## See also
+
+- [from_cbor](https://json.nlohmann.me/api/basic_json/from_cbor/index.md) deserializes a JSON value from CBOR
+- [input_format_t](https://json.nlohmann.me/api/basic_json/input_format_t/index.md) the enumeration of supported input formats
+- [CBOR](https://json.nlohmann.me/features/binary_formats/cbor/index.md) - the article on the CBOR format
+
 ## Version history
 
 - Added in version 3.9.0. Added value `store` in 3.10.0.

api/basic_json/cend.md

@@ -36,6 +36,13 @@ Constant.
     --8<-- "examples/cend.output"
     ```
 
+## See also
+
+- [end](end.md) returns an iterator to one past the last element
+- [cbegin](cbegin.md) returns a const iterator to the first element
+- [crend](crend.md) returns a const reverse iterator to one before the first element
+- [Iterators](../../features/iterators.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/cend/index.md

@@ -52,6 +52,13 @@ Output:
 5
 ```
 
+## See also
+
+- [end](https://json.nlohmann.me/api/basic_json/end/index.md) returns an iterator to one past the last element
+- [cbegin](https://json.nlohmann.me/api/basic_json/cbegin/index.md) returns a const iterator to the first element
+- [crend](https://json.nlohmann.me/api/basic_json/crend/index.md) returns a const reverse iterator to one before the first element
+- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/clear.md

@@ -52,6 +52,11 @@ All iterators, pointers, and references related to this container are invalidate
     --8<-- "examples/clear.output"
     ```
 
+## See also
+
+- [erase](erase.md) removes elements from a JSON value
+- [empty](empty.md) checks whether the JSON value has no elements
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/clear/index.md

@@ -89,8 +89,13 @@ false
 ""
 ```
 
+## See also
+
+- [erase](https://json.nlohmann.me/api/basic_json/erase/index.md) removes elements from a JSON value
+- [empty](https://json.nlohmann.me/api/basic_json/empty/index.md) checks whether the JSON value has no elements
+
 ## Version history
 
 - Added in version 1.0.0.
 - Added support for binary types in version 3.8.0.
-- Fixed in version 3.13.0 to also clear the subtype of a binary value; before, the subtype was left unchanged.
+- Fixed in version 3.13.0 unreleased to also clear the subtype of a binary value; before, the subtype was left unchanged.

api/basic_json/contains.md

@@ -67,6 +67,18 @@ Logarithmic in the size of the JSON object.
 
     If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
 
+!!! warning "Deprecation"
+
+    Overload (3) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json`
+    specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since
+    version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`,
+    `nlohmann::json_pointer<std::string>`) instead.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.
+
+    See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
+
 ## Examples
 
 ??? example "Example: (1) check with key"

api/basic_json/contains/index.md

@@ -56,6 +56,14 @@ Postconditions
 
 If `j.contains(x)` returns `true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
 
+Deprecation
+
+Overload (3) also accepts a [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) whose template argument is a `basic_json` specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`, `nlohmann::json_pointer<std::string>`) instead.
+
+You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#json-pointers) for how to update existing code.
+
 ## Examples
 
 Example: (1) check with key
@@ -198,4 +206,4 @@ false
 1. Added in version 3.11.0.
 1. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0.
 1. Added in version 3.7.0.
-1. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.
+1. Deleted overloads for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.

api/basic_json/count/index.md

@@ -114,4 +114,4 @@ number of elements with key "three": 0
 
 1. Added in version 3.11.0.
 1. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0.
-1. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.
+1. Deleted overload for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.

api/basic_json/crbegin.md

@@ -36,6 +36,13 @@ Constant.
     --8<-- "examples/crbegin.output"
     ```
 
+## See also
+
+- [crend](crend.md) returns a const reverse iterator to one before the first element
+- [rbegin](rbegin.md) returns a reverse iterator to the last element
+- [cbegin](cbegin.md) returns a const iterator to the first element
+- [Iterators](../../features/iterators.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/crbegin/index.md

@@ -49,6 +49,13 @@ Output:
 5
 ```
 
+## See also
+
+- [crend](https://json.nlohmann.me/api/basic_json/crend/index.md) returns a const reverse iterator to one before the first element
+- [rbegin](https://json.nlohmann.me/api/basic_json/rbegin/index.md) returns a reverse iterator to the last element
+- [cbegin](https://json.nlohmann.me/api/basic_json/cbegin/index.md) returns a const iterator to the first element
+- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/crend.md

@@ -37,6 +37,13 @@ Constant.
     --8<-- "examples/crend.output"
     ```
 
+## See also
+
+- [crbegin](crbegin.md) returns a const reverse iterator to the last element
+- [rend](rend.md) returns a reverse iterator to one before the first element
+- [cend](cend.md) returns a const iterator to one past the last element
+- [Iterators](../../features/iterators.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/crend/index.md

@@ -52,6 +52,13 @@ Output:
 1
 ```
 
+## See also
+
+- [crbegin](https://json.nlohmann.me/api/basic_json/crbegin/index.md) returns a const reverse iterator to the last element
+- [rend](https://json.nlohmann.me/api/basic_json/rend/index.md) returns a reverse iterator to one before the first element
+- [cend](https://json.nlohmann.me/api/basic_json/cend/index.md) returns a const iterator to one past the last element
+- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/default_object_comparator_t.md

@@ -30,6 +30,11 @@ The actual comparator used depends on [`object_t`](object_t.md) and can be obtai
     --8<-- "examples/default_object_comparator_t.output"
     ```
 
+## See also
+
+- [object_comparator_t](object_comparator_t.md) the comparator actually used by `object_t`
+- [object_t](object_t.md) the type used to store JSON objects
+
 ## Version history
 
 - Added in version 3.11.0.

api/basic_json/default_object_comparator_t/index.md

@@ -39,6 +39,11 @@ one < two : true
 three < four : false
 ```
 
+## See also
+
+- [object_comparator_t](https://json.nlohmann.me/api/basic_json/object_comparator_t/index.md) the comparator actually used by `object_t`
+- [object_t](https://json.nlohmann.me/api/basic_json/object_t/index.md) the type used to store JSON objects
+
 ## Version history
 
 - Added in version 3.11.0.

api/basic_json/emplace.md

@@ -31,7 +31,8 @@ a `#!cpp bool` denoting whether the insertion took place.
 
 ## Exception safety
 
-Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value. As an exception, a `#!json null`
+value is converted to an empty object before the element is added and keeps that type if adding the element throws.
 
 ## Exceptions
 

api/basic_json/emplace/index.md

@@ -25,7 +25,7 @@ a pair consisting of an iterator to the inserted element, or the already-existin
 
 ## Exception safety
 
-Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value. As an exception, a `null` value is converted to an empty object before the element is added and keeps that type if adding the element throws.
 
 ## Exceptions
 

api/basic_json/emplace_back.md

@@ -28,6 +28,11 @@ iterator is invalidated.
 
 reference to the inserted element
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value. As an exception, a `#!json null`
+value is converted to an empty array before the element is added and keeps that type if adding the element throws.
+
 ## Exceptions
 
 Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON

api/basic_json/emplace_back/index.md

@@ -23,6 +23,10 @@ By adding an element to the end of the array, a reallocation can happen, in whic
 
 reference to the inserted element
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value. As an exception, a `null` value is converted to an empty array before the element is added and keeps that type if adding the element throws.
+
 ## Exceptions
 
 Throws [`type_error.311`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error311) when called on a type other than JSON array or `null`; example: `"cannot use emplace_back() with number"`

api/basic_json/empty.md

@@ -60,6 +60,11 @@ itself is empty which is `#!cpp false` in the case of a string.
     --8<-- "examples/empty.output"
     ```
 
+## See also
+
+- [size](size.md) returns the number of elements
+- [clear](clear.md) clears the content and resets the value to the default value
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/empty/index.md

@@ -94,6 +94,11 @@ true
 false
 ```
 
+## See also
+
+- [size](https://json.nlohmann.me/api/basic_json/size/index.md) returns the number of elements
+- [clear](https://json.nlohmann.me/api/basic_json/clear/index.md) clears the content and resets the value to the default value
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/end.md

@@ -37,6 +37,13 @@ Constant.
     --8<-- "examples/end.output"
     ```
 
+## See also
+
+- [begin](begin.md) returns an iterator to the first element
+- [cend](cend.md) returns a const iterator to one past the last element
+- [rend](rend.md) returns a reverse iterator to one before the first element
+- [Iterators](../../features/iterators.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/end/index.md

@@ -53,6 +53,13 @@ Output:
 5
 ```
 
+## See also
+
+- [begin](https://json.nlohmann.me/api/basic_json/begin/index.md) returns an iterator to the first element
+- [cend](https://json.nlohmann.me/api/basic_json/cend/index.md) returns a const iterator to one past the last element
+- [rend](https://json.nlohmann.me/api/basic_json/rend/index.md) returns a reverse iterator to one before the first element
+- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - the article on iterators
+
 ## Version history
 
 - Added in version 1.0.0.

api/basic_json/error_handler_t.md

@@ -37,6 +37,11 @@ ignore
     --8<-- "examples/error_handler_t.output"
     ```
 
+## See also
+
+- [dump](dump.md) serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
+- [Handling invalid UTF-8](../../features/serialization.md#handling-invalid-utf-8) - the article on handling invalid UTF-8
+
 ## Version history
 
 - Added in version 3.4.0.

api/basic_json/error_handler_t/index.md

@@ -57,6 +57,11 @@ string with replaced invalid characters: "ä�ü"
 string with ignored invalid characters: "äü"
 ```
 
+## See also
+
+- [dump](https://json.nlohmann.me/api/basic_json/dump/index.md) serializes a JSON value, with an `error_handler_t` parameter to configure invalid UTF-8 handling
+- [Handling invalid UTF-8](https://json.nlohmann.me/features/serialization/#handling-invalid-utf-8) - the article on handling invalid UTF-8
+
 ## Version history
 
 - Added in version 3.4.0.

api/basic_json/find/index.md

@@ -123,4 +123,4 @@ value at key "two": 2
 
 1. Added in version 3.11.0.
 1. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
-1. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of causing undefined behavior at runtime.
+1. Deleted overloads for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.

api/basic_json/flatten.md

@@ -27,7 +27,7 @@ Empty objects and arrays are flattened to `#!json null` and will not be reconstr
 
 ## Examples
 
-??? example
+??? example "Example: flatten a JSON object"
 
     The following code shows how a JSON object is flattened to an object whose keys consist of JSON pointers.
     
@@ -41,6 +41,21 @@ Empty objects and arrays are flattened to `#!json null` and will not be reconstr
     --8<-- "examples/flatten.output"
     ```
 
+??? example "Example: empty objects and arrays are flattened to `#!json null`"
+
+    The following code shows that an empty object and an empty array are both flattened to `#!json null`, and that
+    `unflatten()` restores them as `#!json null` rather than as empty containers.
+
+    ```cpp
+    --8<-- "examples/flatten__empty.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/flatten__empty.output"
+    ```
+
 ## See also
 
 - [unflatten](unflatten.md) the reverse function

api/basic_json/flatten/index.md

@@ -24,7 +24,7 @@ Empty objects and arrays are flattened to `null` and will not be reconstructed c
 
 ## Examples
 
-Example
+Example: flatten a JSON object
 
 The following code shows how a JSON object is flattened to an object whose keys consist of JSON pointers.
 
@@ -80,6 +80,52 @@ Output:
 }
 ```
 
+Example: empty objects and arrays are flattened to `null`
+
+The following code shows that an empty object and an empty array are both flattened to `null`, and that `unflatten()` restores them as `null` rather than as empty containers.
+
+```
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON value with an empty object and an empty array
+    json j =
+    {
+        {"empty_object", json::object()},
+        {"empty_array", json::array()},
+        {"name", "Niels"}
+    };
+
+    // call flatten()
+    json flattened = j.flatten();
+    std::cout << std::setw(4) << flattened << "\n\n";
+
+    // the empty containers cannot be restored by unflatten()
+    std::cout << std::setw(4) << flattened.unflatten() << '\n';
+}
+```
+
+Output:
+
+```
+{
+    "/empty_array": null,
+    "/empty_object": null,
+    "/name": "Niels"
+}
+
+{
+    "empty_array": null,
+    "empty_object": null,
+    "name": "Niels"
+}
+```
+
 ## See also
 
 - [unflatten](https://json.nlohmann.me/api/basic_json/unflatten/index.md) the reverse function

api/basic_json/format_as/index.md

@@ -151,4 +151,4 @@ Output:
 
 ## Version history
 
-- Added in version 3.13.0.
+- Added in version 3.13.0 unreleased.

api/basic_json/from_bjdata/index.md

@@ -123,5 +123,5 @@ Output:
 ## Version history
 
 - Added in version 3.11.0.
-- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
-- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
+- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.

api/basic_json/from_bon8/index.md

@@ -122,4 +122,4 @@ Output:
 
 ## Version history
 
-- Added in version 3.13.0.
+- Added in version 3.13.0 unreleased.

api/basic_json/from_bson.md

@@ -123,3 +123,5 @@ Linear in the size of the input.
 
     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
     function.
+
+    See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.

api/basic_json/from_bson/index.md

@@ -124,8 +124,8 @@ Output:
 ## Version history
 
 - Added in version 3.4.0.
-- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
-- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
+- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
 
 Deprecation
 
@@ -133,3 +133,5 @@ Deprecation
 - Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like `from_bson({ptr, ptr+len}, ...);` with `from_bson(ptr, ptr+len, ...);`.
 
 You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#parsing) for how to update existing code.

api/basic_json/from_cbor.md

@@ -133,3 +133,5 @@ Linear in the size of the input.
 
     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
     function.
+
+    See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.

api/basic_json/from_cbor/index.md

@@ -131,8 +131,8 @@ Output:
 - Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
 - Added `allow_exceptions` parameter in version 3.2.0.
 - Added `tag_handler` parameter in version 3.9.0.
-- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
-- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
+- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
 
 Deprecation
 
@@ -140,3 +140,5 @@ Deprecation
 - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like `from_cbor({ptr, ptr+len}, ...);` with `from_cbor(ptr, ptr+len, ...);`.
 
 You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#parsing) for how to update existing code.

api/basic_json/from_msgpack.md

@@ -125,3 +125,5 @@ Linear in the size of the input.
 
     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
     function.
+
+    See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.

api/basic_json/from_msgpack/index.md

@@ -125,8 +125,8 @@ Output:
 - Parameter `start_index` since version 2.1.1.
 - Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
 - Added `allow_exceptions` parameter in version 3.2.0.
-- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
-- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
+- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
 
 Deprecation
 
@@ -134,3 +134,5 @@ Deprecation
 - Overload (2) replaces calls to `from_msgpack` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like `from_msgpack({ptr, ptr+len}, ...);` with `from_msgpack(ptr, ptr+len, ...);`.
 
 You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#parsing) for how to update existing code.

api/basic_json/from_ubjson.md

@@ -124,3 +124,5 @@ Linear in the size of the input.
 
     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
     function.
+
+    See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.

api/basic_json/from_ubjson/index.md

@@ -124,8 +124,8 @@ Output:
 
 - Added in version 3.1.0.
 - Added `allow_exceptions` parameter in version 3.2.0.
-- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
-- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
+- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
 
 Deprecation
 
@@ -133,3 +133,5 @@ Deprecation
 - Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like `from_ubjson({ptr, ptr+len}, ...);` with `from_ubjson(ptr, ptr+len, ...);`.
 
 You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function.
+
+See the [migration guide](https://json.nlohmann.me/integration/migration_guide/#parsing) for how to update existing code.

api/basic_json/get.md

@@ -13,16 +13,16 @@ BasicJsonType get() const;
 
 // (3)
 template<typename PointerType>
-PointerType get_ptr();
+PointerType get() noexcept;
 
 template<typename PointerType>
-constexpr const PointerType get_ptr() const noexcept;
+const PointerType get() const noexcept;  // constexpr since C++14
 ```
 
 1. Explicit type conversion between the JSON value and a compatible value which is
    [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and
    [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). The value is converted by
-   calling the `json_serializer<ValueType>` `from_json()` method.
+   calling the [`json_serializer<ValueType>`](json_serializer.md) `from_json()` method.
    
     The function is equivalent to executing
     ```cpp
@@ -84,6 +84,12 @@ constexpr const PointerType get_ptr() const noexcept;
 3. pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
    otherwise
 
+## Exception safety
+
+Depends on what `json_serializer<ValueType>` `from_json()` method throws for overloads (1) and (2); the JSON value
+itself is never modified, since `get()` is a `#!cpp const` member function. No-throw guarantee for overload (3): this
+function never throws exceptions.
+
 ## Exceptions
 
 Depends on what `json_serializer<ValueType>` `from_json()` method throws
@@ -123,13 +129,13 @@ overload (3).
 
 ## Examples
 
-??? example
+??? example "Example: (1) explicit conversion to compatible types"
 
     The example below shows several conversions from JSON values
     to other types. There a few things to note: (1) Floating-point numbers can
     be converted to integers, (2) A JSON array can be converted to a standard
     `std::vector<short>`, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string, json>`.
+    associative containers such as `std::map<std::string, json>`.
         
     ```cpp
     --8<-- "examples/get__ValueType_const.cpp"
@@ -141,7 +147,21 @@ overload (3).
     --8<-- "examples/get__ValueType_const.output"
     ```
 
-??? example
+??? example "Example: (2) explicit conversion to another `basic_json` specialization"
+
+    The example below shows how a `json` value is converted to an `ordered_json` value using `get<BasicJsonType>()`.
+
+    ```cpp
+    --8<-- "examples/get__BasicJsonType.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/get__BasicJsonType.output"
+    ```
+
+??? example "Example: (3) explicit pointer access to the stored value"
 
     The example below shows how pointers to internal values of a JSON value can be requested. Note that no type
     conversions are made and a `#cpp nullptr` is returned if the value and the requested pointer type does not match.

api/basic_json/get/index.md

@@ -13,13 +13,13 @@ BasicJsonType get() const;
 
 // (3)
 template<typename PointerType>
-PointerType get_ptr();
+PointerType get() noexcept;
 
 template<typename PointerType>
-constexpr const PointerType get_ptr() const noexcept;
+const PointerType get() const noexcept;  // constexpr since C++14
 ```
 
-1. Explicit type conversion between the JSON value and a compatible value which is [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). The value is converted by calling the `json_serializer<ValueType>` `from_json()` method.
+1. Explicit type conversion between the JSON value and a compatible value which is [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). The value is converted by calling the [`json_serializer<ValueType>`](https://json.nlohmann.me/api/basic_json/json_serializer/index.md) `from_json()` method.
 
    The function is equivalent to executing
 
@@ -72,6 +72,10 @@ constexpr const PointerType get_ptr() const noexcept;
 1. a copy of `*this`, converted into `BasicJsonType`
 1. pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `nullptr` otherwise
 
+## Exception safety
+
+Depends on what `json_serializer<ValueType>` `from_json()` method throws for overloads (1) and (2); the JSON value itself is never modified, since `get()` is a `const` member function. No-throw guarantee for overload (3): this function never throws exceptions.
+
 ## Exceptions
 
 Depends on what `json_serializer<ValueType>` `from_json()` method throws
@@ -96,17 +100,17 @@ See [Number conversion](https://json.nlohmann.me/features/types/number_handling/
 
 `std::optional` conversions
 
-Prior to version 3.13.0, `get<std::optional<T>>()` (and other conversions to `std::optional<T>`) failed to compile in every configuration, due to an internal implementation bug that made the `from_json` overload for `std::optional` unreachable regardless of the [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) setting. This has been fixed.
+Prior to version 3.13.0 unreleased, `get<std::optional<T>>()` (and other conversions to `std::optional<T>`) failed to compile in every configuration, due to an internal implementation bug that made the `from_json` overload for `std::optional` unreachable regardless of the [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) setting. This has been fixed.
 
 ## Examples
 
-Example
+Example: (1) explicit conversion to compatible types
 
-The example below shows several conversions from JSON values to other types. There a few things to note: (1) Floating-point numbers can be converted to integers, (2) A JSON array can be converted to a standard `std::vector<short>`, (3) A JSON object can be converted to C++ associative containers such as `std::unordered_map<std::string, json>`.
+The example below shows several conversions from JSON values to other types. There a few things to note: (1) Floating-point numbers can be converted to integers, (2) A JSON array can be converted to a standard `std::vector<short>`, (3) A JSON object can be converted to C++ associative containers such as `std::map<std::string, json>`.
 
 ```
 #include <iostream>
-#include <unordered_map>
+#include <map>
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
@@ -136,7 +140,7 @@ int main()
     auto v5 = json_types["number"]["floating-point"].get<int>();
     auto v6 = json_types["string"].get<std::string>();
     auto v7 = json_types["array"].get<std::vector<short>>();
-    auto v8 = json_types.get<std::unordered_map<std::string, json>>();
+    auto v8 = json_types.get<std::map<std::string, json>>();
 
     // print the conversion results
     std::cout << v1 << '\n';
@@ -166,14 +170,45 @@ Output:
 Hello, world!
 1 2 3 4 5 
 
-number: {"floating-point":17.23,"integer":42}
-null: null
-string: "Hello, world!"
-boolean: true
 array: [1,2,3,4,5]
+boolean: true
+null: null
+number: {"floating-point":17.23,"integer":42}
+string: "Hello, world!"
 ```
 
-Example
+Example: (2) explicit conversion to another `basic_json` specialization
+
+The example below shows how a `json` value is converted to an `ordered_json` value using `get<BasicJsonType>()`.
+
+```
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+using ordered_json = nlohmann::ordered_json;
+
+int main()
+{
+    // create a JSON value
+    json j = {{"one", 1}, {"two", 2}, {"three", 3}};
+
+    // convert to a different basic_json specialization
+    ordered_json oj = j.get<ordered_json>();
+
+    std::cout << j << '\n';
+    std::cout << oj << '\n';
+}
+```
+
+Output:
+
+```
+{"one":1,"three":3,"two":2}
+{"one":1,"three":3,"two":2}
+```
+
+Example: (3) explicit pointer access to the stored value
 
 The example below shows how pointers to internal values of a JSON value can be requested. Note that no type conversions are made and a `#cpp nullptr` is returned if the value and the requested pointer type does not match.
 

api/basic_json/get_allocator.md

@@ -10,6 +10,14 @@ Returns the allocator associated with the container.
 
 associated allocator
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+
+## Complexity
+
+Constant.
+
 ## Examples
 
 ??? example
@@ -26,6 +34,11 @@ associated allocator
     --8<-- "examples/get_allocator.output"
     ```
 
+## See also
+
+- [basic_json](index.md#template-parameters) the class template, with `AllocatorType` as one of its template parameters
+- [Template Parameter Requirements](../../features/types/template_parameters.md#allocatortype) - the requirements for `AllocatorType`
+
 ## Version history
 
 - Added in version 1.0.0.