Complete documentation for 3.11.0 (#3464)

* 👥 update contributor and sponsor list

* 🚧 document BJData format

* 🚧 document BJData format

* 📝 clarified documentation of [json.exception.parse_error.112]

* ✏️ adjust titles

* 📝 add more examples

* 🚨 adjust warnings for index.md files

* 📝 add more examples

* 🔥 remove example for deprecated code

* 📝 add missing enum entry

* 📝 overwork table for binary formats

* ✅ add test to create table for binary formats

* 📝 fix wording in example

* 📝 add more examples

* Update iterators.md (#3481)

* ✨ add check for overloads to linter #3455

* 👥 update contributor list

* 📝 add more examples

* 📝 fix documentation

* 📝 add more examples

* 🎨 fix indentation

* 🔥 remove example for destructor

* 📝 overwork documentation

* Updated BJData documentation, #3464 (#3493)

* update bjdata.md for #3464

* Minor edit

* Fix URL typo

* Add info on demoting ND array to a 1-D optimized array when singleton dimension

Co-authored-by: Chaoqi Zhang <prncoprs@163.com>
Co-authored-by: Qianqian Fang <fangqq@gmail.com>

docs/mkdocs/docs/api/basic_json/at.md

@@ -184,6 +184,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## See also
 
+- documentation on [checked access](../../features/element_access/checked_access.md)
 - see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
 - see [`value`](value.md) for access with default value
 

docs/mkdocs/docs/api/basic_json/basic_json.md

@@ -241,7 +241,7 @@ basic_json(basic_json&& other) noexcept;
 
 - Overload 5:
 
-    !!! note
+    !!! note "Empty initializer list"
 
         When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
         function, yielding the JSON `#!json null` value.

docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md

@@ -20,6 +20,23 @@ ignore
 store
 :   store tagged values as binary container with subtype (for bytes 0xd8..0xdb)
 
+## Examples
+
+??? example
+
+    The example below shows how the different values of the `cbor_tag_handler_t` influence the behavior of
+    [`from_cbor`](from_cbor.md) when reading a tagged byte string.
+
+    ```cpp
+    --8<-- "examples/cbor_tag_handler_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/cbor_tag_handler_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.9.0. Added value `store` in 3.10.0.

docs/mkdocs/docs/api/basic_json/contains.md

@@ -60,8 +60,8 @@ Logarithmic in the size of the JSON object.
 
 ## Notes
 
-1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
-2. This method can be executed on any JSON value type.
+- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+- This method can be executed on any JSON value type.
 
 !!! info "Postconditions"
 

docs/mkdocs/docs/api/basic_json/default_object_comparator_t.md

@@ -14,6 +14,22 @@ when looking up a key in an object.
 The actual comparator used depends on [`object_t`](object_t.md) and can be obtained via
 [`object_comparator_t`](object_comparator_t.md).
 
+## Examples
+
+??? example
+
+    The example below demonstrates the default comparator.
+
+    ```cpp
+    --8<-- "examples/default_object_comparator_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/default_object_comparator_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/error_handler_t.md

@@ -20,6 +20,23 @@ replace
 ignore
 :   ignore invalid UTF-8 sequences; all bytes are copied to the output unchanged
 
+## Examples
+
+??? example
+
+    The example below shows how the different values of the `error_handler_t` influence the behavior of
+    [`dump`](dump.md) when reading serializing an invalid UTF-8 sequence.
+
+    ```cpp
+    --8<-- "examples/error_handler_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/error_handler_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.4.0.

docs/mkdocs/docs/api/basic_json/from_bjdata.md

@@ -0,0 +1,93 @@
+# <small>nlohmann::basic_json::</small>from_bjdata
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_bjdata(InputType&& i,
+                              const bool strict = true,
+                              const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType>
+static basic_json from_bjdata(IteratorType first, IteratorType last,
+                              const bool strict = true,
+                              const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the BJData (Binary JData) serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range.
+
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
+
+## Template parameters
+
+`InputType`
+:   A compatible input, for instance:
+
+    - an `std::istream` object
+    - a `FILE` pointer
+    - a C-style array of characters
+    - a pointer to a null-terminated string of single byte characters
+    - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
+
+`IteratorType`
+:   a compatible iterator type
+
+## Parameters
+
+`i` (in)
+:   an input in BJData format convertible to an input adapter
+
+`first` (in)
+:   iterator to start of the input
+
+`last` (in)
+:   iterator to end of the input
+
+`strict` (in)
+:   whether to expect the input to be consumed until EOF (`#!cpp true` by default)
+
+`allow_exceptions` (in)
+:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+## Return value
+
+deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
+`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
+  successfully
+
+## Complexity
+
+Linear in the size of the input.
+
+## Examples
+
+??? example
+
+    The example shows the deserialization of a byte vector in BJData format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_bjdata.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_bjdata.output"
+    ```
+
+## Version history
+
+- Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/get_allocator.md

@@ -10,10 +10,22 @@ Returns the allocator associated with the container.
 
 associated allocator
 
+## Examples
+
+??? example
+
+    The example shows how `get_allocator()` is used to created `json` values.
+    
+    ```cpp
+    --8<-- "examples/get_allocator.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_allocator.output"
+    ```
+
 ## Version history
 
-- Unknown.
-
-!!! note
-
-    This documentation page is a stub.
+- Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/index.md

@@ -268,10 +268,12 @@ Access to the JSON value
 
 ### Binary formats
 
+- [**from_bjdata**](from_bjdata.md) (_static_) - create a JSON value from an input in BJData format
 - [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
 - [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
 - [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
 - [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
+- [**to_bjdata**](to_bjdata.md) (_static_) - create a BJData serialization of a given JSON value
 - [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
 - [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
 - [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value

docs/mkdocs/docs/api/basic_json/input_format_t.md

@@ -6,7 +6,8 @@ enum class input_format_t {
     cbor,
     msgpack,
     ubjson,
-    bson
+    bson,
+    bjdata
 };
 ```
 
@@ -27,6 +28,25 @@ ubjson
 bson
 :   BSON (Binary JSON)
 
+bjdata
+:   BJData (Binary JData)
+
+## Examples
+
+??? example
+
+    The example below shows how an `input_format_t` enum value is passed to `sax_parse` to set the input format to CBOR.
+
+    ```cpp
+    --8<-- "examples/sax_parse__binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/sax_parse__binary.output"
+    ```
+
 ## Version history
 
 - Added in version 3.2.0.

docs/mkdocs/docs/api/basic_json/object_comparator_t.md

@@ -1,6 +1,5 @@
 # <small>nlohmann::basic_json::</small>object_comparator_t
 
-
 ```cpp
 using object_comparator_t = typename object_t::key_compare;
 // or
@@ -10,6 +9,22 @@ using object_comparator_t = default_object_comparator_t;
 The comparator used by [`object_t`](object_t.md). Defined as `#!cpp typename object_t::key_compare` if available,
 and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
 
+## Examples
+
+??? example
+
+    The example below demonstrates the used object comparator.
+
+    ```cpp
+    --8<-- "examples/object_comparator_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/object_comparator_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.0.0.

docs/mkdocs/docs/api/basic_json/operator+=.md

@@ -41,12 +41,9 @@ reference operator+=(initializer_list_t init);
 
 ## Exceptions
 
-1. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON array or null; example: `"cannot use operator+=() with number"`
-2. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON object or null; example: `"cannot use operator+=() with number"`
+All functions can throw the following exception:
+  - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
+    JSON array or null; example: `"cannot use operator+=() with number"`
 
 ## Complexity
 

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -198,6 +198,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## See also
 
+- documentation on [unchecked access](../../features/element_access/unchecked_access.md)
+- documentation on [runtime assertions](../../features/assertions.md)
 - see [`at`](at.md) for access by reference with range checking
 - see [`value`](value.md) for access with default value
 

docs/mkdocs/docs/api/basic_json/operator_ValueType.md

@@ -56,7 +56,6 @@ Linear in the size of the JSON value.
     [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0` and replace any implicit
     conversions with calls to [`get`](../basic_json/get.md).
 
-
 ## Examples
 
 ??? example

docs/mkdocs/docs/api/basic_json/operator_eq.md

@@ -44,13 +44,13 @@ Linear.
 
 ## Notes
 
-!!! note
+!!! note "Comparing special values"
 
     - NaN values never compare equal to themselves or to other NaN values.
     - JSON `#!cpp null` values are all equal.
     - Discarded values never compare equal to themselves.
 
-!!! note
+!!! note "Comparing floating-point numbers"
 
     Floating-point numbers inside JSON values numbers are compared with `json::number_float_t::operator==` which is
     `double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative

docs/mkdocs/docs/api/basic_json/push_back.md

@@ -37,12 +37,9 @@ void push_back(initializer_list_t init);
 
 ## Exceptions
 
-1. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON array or null; example: `"cannot use push_back() with number"`
-2. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      JSON object or null; example: `"cannot use push_back() with number"`
+All functions can throw the following exception:
+  - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
+    JSON array or null; example: `"cannot use push_back() with number"`
 
 ## Complexity
 

docs/mkdocs/docs/api/basic_json/to_bjdata.md

@@ -0,0 +1,70 @@
+# <small>nlohmann::basic_json::</small>to_bjdata
+
+```cpp
+// (1)
+static std::vector<std::uint8_t> to_bjdata(const basic_json& j,
+                                           const bool use_size = false,
+                                           const bool use_type = false);
+
+// (2)
+static void to_bjdata(const basic_json& j, detail::output_adapter<std::uint8_t> o,
+                      const bool use_size = false, const bool use_type = false);
+static void to_bjdata(const basic_json& j, detail::output_adapter<char> o,
+                      const bool use_size = false, const bool use_type = false);
+```
+
+Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData
+aims to be more compact than JSON itself, yet more efficient to parse.
+
+1. Returns a byte vector containing the BJData serialization.
+2. Writes the BJData serialization to an output adapter.
+
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
+
+## Parameters
+
+`j` (in)
+:   JSON value to serialize
+
+`o` (in)
+:   output adapter to write serialization to
+
+`use_size` (in)
+:   whether to add size annotations to container types; optional, `#!cpp false` by default.
+
+`use_type` (in)
+:   whether to add type annotations to container types (must be combined with `#!cpp use_size = true`); optional,
+`#!cpp false` by default.
+
+## Return value
+
+1. BJData serialization as byte vector
+2. (none)
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of the JSON value `j`.
+
+## Examples
+
+??? example
+
+    The example shows the serialization of a JSON value to a byte vector in BJData format.
+     
+    ```cpp
+    --8<-- "examples/to_bjdata.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_bjdata.output"
+    ```
+
+## Version history
+
+- Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/value_t.md

@@ -29,6 +29,22 @@ distinguishes these three types for numbers: [`number_unsigned_t`](number_unsign
 [`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
 for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
 
+## Examples
+
+??? example
+
+    The following code how `type()` queries the `value_t` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/type.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.