Merge branch 'develop' of https://github.com/nlohmann/json into hedley14

.circleci/config.yml

@@ -44,5 +44,13 @@ workflows:
   version: 2
   build_and_test_all:
     jobs:
-      - build_stable
-      - build_bleeding_edge
+      - build_stable:
+          filters:
+            branches:
+              ignore:
+                gh-pages
+      - build_bleeding_edge:
+          filters:
+            branches:
+              ignore:
+                gh-pages

.gitignore

@@ -33,3 +33,4 @@ doc/mkdocs/docs/examples
 doc/mkdocs/site
 doc/mkdocs/docs/__pycache__/
 doc/xml
+/doc/docset/nlohmann_json.docset/

Makefile

@@ -81,7 +81,6 @@ doctest:
 # -Wno-documentation-unknown-command: code uses user-defined commands like @complexity
 # -Wno-exit-time-destructors: warning in json code triggered by NLOHMANN_JSON_SERIALIZE_ENUM
 # -Wno-float-equal: not all comparisons in the tests can be replaced by Approx
-# -Wno-keyword-macro: unit-tests use "#define private public"
 # -Wno-missing-prototypes: for NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE
 # -Wno-padded: padding is nothing to warn about
 # -Wno-range-loop-analysis: items tests "for(const auto i...)"
@@ -98,7 +97,6 @@ pedantic_clang:
 		-Wno-documentation-unknown-command \
 		-Wno-exit-time-destructors \
 		-Wno-float-equal \
-		-Wno-keyword-macro \
 		-Wno-missing-prototypes \
 		-Wno-padded \
 		-Wno-range-loop-analysis \
@@ -629,7 +627,7 @@ clean:
 	rm -fr json_unit json_benchmarks fuzz fuzz-testing *.dSYM test/*.dSYM oclint_report.html
 	rm -fr benchmarks/files/numbers/*.json
 	rm -fr cmake-3.1.0-Darwin64.tar.gz cmake-3.1.0-Darwin64
-	rm -fr cmake-build-coverage cmake-build-benchmarks fuzz-testing cmake-build-clang-analyze cmake-build-pvs-studio cmake-build-infer cmake-build-clang-sanitize cmake_build
+	rm -fr cmake-build-coverage cmake-build-benchmarks cmake-build-pedantic fuzz-testing cmake-build-clang-analyze cmake-build-pvs-studio cmake-build-infer cmake-build-clang-sanitize cmake_build
 	$(MAKE) clean -Cdoc
 
 ##########################################################################

doc/Makefile

@@ -44,6 +44,8 @@ check_output: $(EXAMPLES:.cpp=.test)
 
 clean:
 	rm -fr me.nlohmann.json.docset html xml $(EXAMPLES:.cpp=)
+	$(MAKE) clean -C docset
+	$(MAKE) clean -C mkdocs
 
 
 ##########################################################################

doc/docset/Info.plist

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleIdentifier</key>
+	<string>nlohmann_json</string>
+	<key>CFBundleName</key>
+	<string>JSON for Modern C++</string>
+	<key>DocSetPlatformFamily</key>
+	<string>json</string>
+	<key>isDashDocset</key>
+	<true/>
+    <key>dashIndexFilePath</key>
+    <string>index.html</string>
+    <key>DashDocSetFallbackURL</key>
+    <string>https://nlohmann.github.io/json/</string>
+    <key>isJavaScriptEnabled</key>
+    <true/>
+</dict>
+</plist>

doc/docset/Makefile

+nlohmann_json.docset: Info.plist docSet.sql
+	$(MAKE) clean
+	mkdir -p nlohmann_json.docset/Contents/Resources/Documents/
+	cp info.plist nlohmann_json.docset/Contents
+	# build and copy documentation
+	$(MAKE) build -C ../mkdocs
+	cp -r ../mkdocs/site/* nlohmann_json.docset/Contents/Resources/Documents
+	# patch CSS to hide navigation items
+	echo "\n\nheader, footer, navi, div.md-sidebar--primary, nav.md-tabs--active, a.md-content__button { display: none; }" >> nlohmann_json.docset/Contents/Resources/Documents/assets/stylesheets/main.b5d04df8.min.css
+	# fix spacing
+	echo "\n\ndiv.md-sidebar div.md-sidebar--secondary, div.md-main__inner { top: 0; margin-top: 0 }" >> nlohmann_json.docset/Contents/Resources/Documents/assets/stylesheets/main.b5d04df8.min.css
+	# remove "JSON for Modern C++" from page titles
+	find nlohmann_json.docset/Contents/Resources/Documents -type f -exec gsed -i 's| - JSON for Modern C++</title>|</title>|' {} +
+	# clean up
+	rm nlohmann_json.docset/Contents/Resources/Documents/hooks.py
+	rm nlohmann_json.docset/Contents/Resources/Documents/sitemap.*
+	# generate index
+	sqlite3 nlohmann_json.docset/Contents/Resources/docSet.dsidx < docSet.sql
+
+clean:
+	rm -fr nlohmann_json.docset

doc/docset/README.md

+# docset
+
+The folder contains the required files to create a [docset](https://kapeli.com/docsets) which can be used in
+documentation browsers like [Dash](https://kapeli.com/dash), [Velocity](https://velocity.silverlakesoftware.com), or
+[Zeal](https://zealdocs.org).
+
+The docset can be created with
+
+```sh
+make nlohmann_json.docset
+```
+
+The generated folder `nlohmann_json.docset` can then be opened in the documentation browser.

doc/examples/parse__allow_exceptions.cpp

+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // an invalid JSON text
+    std::string text = R"(
+    {
+        "key": "value without closing quotes
+    }
+    )";
+
+    // parse with exceptions
+    try
+    {
+        json j = json::parse(text);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    // parse without exceptions
+    json j = json::parse(text, nullptr, false);
+
+    if (j.is_discarded())
+    {
+        std::cout << "the input is invalid JSON" << std::endl;
+    }
+    else
+    {
+        std::cout << "the input is valid JSON: " << j << std::endl;
+    }
+}

doc/examples/parse__allow_exceptions.link

+<a target="_blank" href="https://wandbox.org/permlink/2TsG4VSg87HsRQC9"><b>online</b></a>
\ No newline at end of file

doc/examples/parse__allow_exceptions.output

+[json.exception.parse_error.101] parse error at line 4, column 0: syntax error while parsing value - invalid string: control character U+000A (LF) must be escaped to \u000A or \n; last read: '"value without closing quotes<U+000A>'
+the input is invalid JSON

doc/mkdocs/Makefile

@@ -2,6 +2,9 @@
 serve: prepare_files
 	venv/bin/mkdocs serve
 
+build: prepare_files
+	venv/bin/mkdocs build
+
 # create files that are not versioned inside the mkdocs folder
 prepare_files: clean
 	# build Doxygen
@@ -9,7 +12,7 @@ prepare_files: clean
 	# create subfolders
 	mkdir docs/images docs/examples
 	# copy images
-	cp -vr ../json.gif ../images/range-begin-end.svg ../images/range-rbegin-rend.svg docs/images
+	cp -vr ../json.gif ../images/range-begin-end.svg ../images/range-rbegin-rend.svg ../images/callback_events.png docs/images
 	# copy examples
 	cp -vr ../examples/*.cpp ../examples/*.output docs/examples
 

doc/mkdocs/docs/api/adl_serializer.md

+# adl_serializer
+
+```cpp
+template<typename, typename>
+struct adl_serializer;
+```
+
+Serializer that uses ADL ([Argument-Dependent Lookup](https://en.cppreference.com/w/cpp/language/adl)) to choose
+`to_json`/`from_json` functions from the types' namespaces.
+
+It is implemented similar to
+
+```cpp
+template<typename ValueType>
+struct adl_serializer {
+    template<typename BasicJsonType>
+    static void to_json(BasicJsonType& j, const T& value) {
+        // calls the "to_json" method in T's namespace
+    }
+
+    template<typename BasicJsonType>
+    static void from_json(const BasicJsonType& j, T& value) {
+        // same thing, but with the "from_json" method
+    }
+};
+```
+
+## Member functions
+
+- **from_json** - convert a JSON value to any value type
+- **to_json** - convert any value type to a JSON value

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

+# basic_json::accept
+
+```cpp
+// (1)
+template<typename InputType>
+static bool accept(InputType&& i,
+                   const bool ignore_comments = false);
+
+// (2)
+template<typename IteratorType>
+static bool accept(IteratorType first, IteratorType last,
+                   const bool ignore_comments = false);
+```
+
+Checks whether the input is valid JSON.
+
+1. Reads from a compatible input.
+2. Reads from a pair of character iterators
+    
+    The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
+    respectively as UTF-8, UTF-16 and UTF-32.
+    
+Unlike the [`parse`](parse.md) function, this function neither throws an exception in case of invalid JSON input
+(i.e., a parse error) nor creates diagnostic information.
+
+## 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)
+:   Input to parse from.
+
+`ignore_comments` (in)
+:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
+`first` (in)
+:   iterator to start of character range
+
+`last` (in)
+:   iterator to end of character range
+
+## Return value
+
+Whether the input is valid JSON.
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the length of the input. The parser is a predictive LL(1) parser.
+
+## Notes
+
+(1) A UTF-8 byte order mark is silently ignored.
+
+## Examples
+
+??? example
+
+    The example below demonstrates the `accept()` function reading from a string.
+
+    ```cpp
+    --8<-- "examples/accept__string.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/accept__string.output"
+    ```
+
+## Version history
+
+- Added in version 3.0.0.
+- Ignoring comments via `ignore_comments` added in version 3.9.0.

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

+# basic_json::array
+
+```cpp
+static basic_json array(initializer_list_t init = {});
+```
+
+Creates a JSON array value from a given initializer list. That is, given a list of values `a, b, c`, creates the JSON
+value `#!json [a, b, c]`. If the initializer list is empty, the empty array `#!json []` is created.
+
+## Parameters
+
+`init` (in)
+:   initializer list with JSON values to create an array from (optional)
+
+## Return value
+
+JSON array value
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of `init`.
+
+## Notes
+
+This function is only needed to express two edge cases that cannot be realized with the initializer list constructor
+([`basic_json(initializer_list_t, bool, value_t)`](basic_json.md)). These cases are:
+
+1. creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list
+   constructor would create an object, taking the first elements as keys
+2. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty
+   object
+
+## Examples
+
+??? example
+
+    The following code shows an example for the `array` function.
+
+    ```cpp
+    --8<-- "examples/array.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/array.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::array_t
+
+```cpp
+using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
+```
+
+The type used to store JSON arrays.
+
+[RFC 7159](http://rfc7159.net/rfc7159) describes JSON arrays as follows:
+> An array is an ordered sequence of zero or more values.
+
+To store objects in C++, a type is defined by the template parameters explained below.
+
+## Template parameters
+
+`ArrayType`
+:   container type to store arrays (e.g., `std::vector` or `std::list`)
+
+`AllocatorType`
+:   the allocator to use for objects (e.g., `std::allocator`)
+
+## Notes
+
+#### Default type
+
+With the default values for `ArrayType` (`std::vector`) and `AllocatorType` (`std::allocator`), the default value for
+`array_t` is:
+
+```cpp
+std::vector<
+  basic_json, // value_type
+  std::allocator<basic_json> // allocator_type
+>
+```
+
+#### Limits
+
+[RFC 7159](http://rfc7159.net/rfc7159) specifies:
+> An implementation may set limits on the maximum depth of nesting.
+
+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`](max_size.md) function of a JSON array.
+
+#### 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.
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::at
+
+```cpp
+// (1)
+reference at(size_type idx);
+const_reference at(size_type idx) const;
+
+// (2)
+reference at(const typename object_t::key_type& key);
+const_reference at(const typename object_t::key_type& key) const;
+
+// (3)
+reference at(const json_pointer& ptr);
+const_reference at(const json_pointer& ptr) const;
+```
+
+1. Returns a reference to the element at specified location `idx`, with bounds checking.
+2. Returns a reference to the element at with specified key `key`, with bounds checking.
+3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking.
+
+## Parameters
+
+`idx` (in)
+:   index of the element to access
+
+`key` (in)
+:   object key of the elements to remove
+    
+`ptr` (in)
+:   JSON pointer to the desired element
+    
+## Return value
+
+1. reference to the element at index `idx`
+2. reference to the element at key `key`
+3. reference to the element pointed to by `ptr`
+
+## Exceptions
+
+1. The function can throw the following exceptions:
+    - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an array;
+      in this case, calling `at` with an index makes no sense. See example below.
+    - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if the index `idx` is out of
+      range of the array; that is, `idx >= size()`. See example below.
+2. The function can throw the following exceptions:
+    - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
+      in this case, calling `at` with a key makes no sense. See example below.
+    - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is is not
+      stored in the object; that is, `find(key) == end()`. See example below.
+3. The function can throw the following exceptions:
+    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
+      JSON pointer `ptr` begins with '0'. See example below.
+    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
+      JSON pointer `ptr` is not a number. See example below.
+    - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index in the passed
+      JSON pointer `ptr` is out of range. See example below.
+    - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
+      in the passed JSON pointer `ptr`. As `at` provides checked access (and no elements are implicitly inserted), the
+      index '-' is always invalid. See example below.
+    - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the JSON pointer describes a
+      key of an object which cannot be found. See example below.
+    - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
+      not be resolved. See example below.
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+1. Constant
+2. Logarithmic in the size of the container.
+3. Constant
+
+## Example
+
+??? example
+
+    The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
+    exceptions that can be thrown.
+    
+    ```cpp
+    --8<-- "examples/at__size_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__size_type.output"
+    ```
+
+??? example
+
+    The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
+    that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at__size_type_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__size_type_const.output"
+    ```
+
+??? example
+
+    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
+    exceptions that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at__object_t_key_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__object_t_key_type.output"
+    ```
+
+??? example
+
+    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
+    that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at__object_t_key_type_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__object_t_key_type_const.output"
+    ```
+
+??? example
+
+    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
+    exceptions that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at_json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at_json_pointer.output"
+    ```
+
+??? example
+
+    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
+    that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at_json_pointer_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at_json_pointer_const.output"
+    ```
+
+## Version history
+
+1. Added in version 1.0.0.
+2. Added in version 1.0.0.
+3. Added in version 2.0.0.

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

+# basic_json::back
+
+```cpp
+reference back();
+
+const_reference back() const;
+```
+
+Returns a reference to the last element in the container. For a JSON container `c`, the expression `c.back()` is
+equivalent to
+
+```cpp
+auto tmp = c.end();
+--tmp;
+return *tmp;
+```
+    
+## Return value
+
+In case of a structured type (array or object), a reference to the last element is returned. In case of number, string,
+boolean, or binary values, a reference to the value is returned.
+
+## Exceptions
+
+If the JSON value is `#!json null`, exception
+[`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Constant.
+
+## Note
+
+!!! danger
+
+    Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**!
+
+## Example
+
+??? example
+
+    The following code shows an example for `back()`.
+     
+    ```cpp
+    --8<-- "examples/back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/back.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Adjusted code to return reference to binary values in version 3.8.0.

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

+# basic_json::begin
+
+```cpp
+iterator begin() noexcept;
+const_iterator begin() const noexcept;
+```
+
+Returns an iterator to the first element.
+
+![Illustration from cppreference.com](../../images/range-begin-end.svg)
+
+## Return value
+
+iterator to the first element
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code shows an example for `begin()`.
+    
+    ```cpp
+    --8<-- "examples/begin.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/begin.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::binary
+
+```cpp
+// (1)
+static basic_json binary(const typename binary_t::container_type& init);
+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);
+static basic_json binary(typename binary_t::container_type&& init,
+                         std::uint8_t subtype);
+```
+
+1. Creates a JSON binary array value from a given binary container.
+2. Creates a JSON binary array value from a given binary container with subtype.
+ 
+Binary values are part of various binary formats, such as CBOR, MessagePack, and BSON. This constructor is used to
+create a value for serialization to those formats.
+
+## Parameters
+
+`init` (in)
+:   container containing bytes to use as binary type
+
+`subtype` (in)
+:   subtype to use in CBOR, MessagePack, and BSON
+
+## Return value
+
+JSON binary array value
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of `init`; constant for `typename binary_t::container_type&& init` versions.
+
+## Notes
+
+Note, this function exists because of the difficulty in correctly specifying the correct template overload in the
+standard value ctor, as both JSON arrays and JSON binary arrays are backed with some form of a `std::vector`. Because
+JSON binary arrays are a non-standard extension it was decided that it would be best to prevent automatic initialization
+of a binary array type, for backwards compatibility and so it does not happen on accident.
+
+## Version history
+
+- Added in version 3.8.0.

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

+# basic_json::binary_t
+
+```cpp
+using binary_t = byte_container_with_subtype<BinaryType>;
+```
+
+This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type
+2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for
+compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
+
+Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint8_t`, which
+is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is
+incompatible with each other, and it is up to the user to translate between them).
+
+[CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
+> Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
+> (major type 0).
+
+[MessagePack's documentation on the bin type
+family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:
+> Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
+
+[BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to
+represent the generic binary type which has the description:
+> Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and
+> tools.
+
+None of these impose any limitations on the internal representation other than the basic unit of storage be some type of
+array whose parts are decomposable into bytes.
+
+The default representation of this binary format is a `#!cpp std::vector<std::uint8_t>`, which is a very common way to
+represent a byte array in modern C++.
+
+## Template parameters
+
+`BinaryType`
+:   container type to store arrays
+
+## Notes
+
+#### Default type
+
+The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.
+
+#### 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
+
+- CBOR
+    - Binary values are represented as byte strings. Subtypes are written as tags.
+
+- MessagePack
+    - If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
+      fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
+      then added as singed 8-bit integer.
+    - If no subtype is given, the bin family (bin8, bin16, bin32) is used.
+
+- BSON
+    - If a subtype is given, it is used and added as unsigned 8-bit integer.
+    - If no subtype is given, the generic binary subtype 0x00 is used.
+
+## Version history
+
+- Added in version 3.8.0.

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

+# basic_json::boolean_t
+
+```cpp
+using boolean_t = BooleanType;
+```
+
+The type used to store JSON booleans.
+
+[RFC 7159](http://rfc7159.net/rfc7159) implicitly describes a boolean as a type which differentiates the two literals
+`#!json true` and `#!json false`.
+
+To store objects in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.
+
+## Notes
+
+#### Default type
+
+With the default values for `BooleanType` (`#!cpp bool`), the default value for `boolean_t` is `#!cpp bool`.
+
+#### Storage
+
+Boolean values are stored directly inside a `basic_json` type.
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::cbegin
+
+```cpp
+const_iterator cbegin() const noexcept;
+```
+
+Returns an iterator to the first element.
+
+![Illustration from cppreference.com](../../images/range-begin-end.svg)
+
+## Return value
+
+iterator to the first element
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code shows an example for `cbegin()`.
+    
+    ```cpp
+    --8<-- "examples/cbegin.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/cbegin.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::cbor_tag_handler_t
+
+```cpp
+enum class cbor_tag_handler_t
+{
+    error,
+    ignore
+};
+```
+
+This enumeration is used in the [`from_cbor`](from_cbor.md) function to choose how to treat tags:
+
+error
+:   throw a `parse_error` exception in case of a tag
+
+ignore
+:   ignore tags
+
+## Version history
+
+- Added in version 3.9.0.

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

+# basic_json::cend
+
+```cpp
+const_iterator cend() const noexcept;
+```
+
+Returns an iterator to one past the last element.
+
+![Illustration from cppreference.com](../../images/range-begin-end.svg)
+
+## Return value
+
+iterator one past the last element
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code shows an example for `cend()`.
+    
+    ```cpp
+    --8<-- "examples/cend.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/cend.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::clear
+
+```cpp
+void clear() noexcept;
+```
+
+Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](basic_json.md) would
+have been called with the current value type from [`type()`](type.md):
+
+Value type  | initial value
+----------- | -------------
+null        | `null`
+boolean     | `false`
+string      | `""`
+number      | `0`
+binary      | An empty byte vector
+object      | `{}`
+array       | `[]`
+
+Has the same effect as calling
+
+```.cpp
+*this = basic_json(type());
+```
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Linear in the size of the JSON value.
+
+## Notes
+
+All iterators, pointers and references related to this container are invalidated.
+
+## Example
+
+??? example
+
+    The example below shows the effect of `clear()` to different
+    JSON types.
+    
+    ```cpp
+    --8<-- "examples/clear.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/clear.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Added support for binary types in version 3.8.0.

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

+# basic_json::contains
+
+```cpp
+template<typename KeyT>
+bool contains(KeyT && key) const;
+```
+
+Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the JSON
+value is not an object, `#!cpp false` is returned.
+
+## Template parameters
+
+`KeyT`
+:   A type for an object key other than `basic_json::json_pointer`.
+
+## Parameters
+
+`key` (in)
+:   key value to check its existence.
+    
+## Return value
+
+`#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value is
+not an object, `#!cpp false` is returned.
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+Logarithmic in the size of the JSON object.
+
+## Notes
+
+This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+
+## Example
+
+??? example
+
+    The example shows how `contains()` is used.
+    
+    ```cpp
+    --8<-- "examples/contains.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/contains.output"
+    ```
+
+## Version history
+
+- Added in version 3.6.0.

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

+# basic_json::count
+
+```cpp
+template<typename KeyT>
+size_type count(KeyT&& key) const;
+```
+
+Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will
+always be `0` (`key` was not found) or `1` (`key` was found).
+
+## Template parameters
+
+`KeyT`
+:   A type for an object key.
+
+## Parameters
+
+`key` (in)
+:   key value of the element to count.
+    
+## Return value
+
+Number of elements with key `key`. If the JSON value is not an object, the return value will be `0`.
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+Logarithmic in the size of the JSON object.
+
+## Notes
+
+This method always returns `0` when executed on a JSON type that is not an object.
+
+## Example
+
+??? example
+
+    The example shows how `count()` is used.
+    
+    ```cpp
+    --8<-- "examples/count.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/count.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::crbegin
+
+```cpp
+const_reverse_iterator crbegin() const noexcept;
+```
+
+Returns an iterator to the reverse-beginning; that is, the last element.
+
+![Illustration from cppreference.com](../../images/range-rbegin-rend.svg)
+
+## Return value
+
+reverse iterator to the first element
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code shows an example for `crbegin()`.
+    
+    ```cpp
+    --8<-- "examples/crbegin.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/crbegin.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::rend
+
+```cpp
+const_reverse_iterator crend() const noexcept;
+```
+
+Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder,
+attempting to access it results in undefined behavior.
+
+![Illustration from cppreference.com](../../images/range-rbegin-rend.svg)
+
+## Return value
+
+reverse iterator to the element following the last element
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code shows an example for `eend()`.
+    
+    ```cpp
+    --8<-- "examples/crend.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/crend.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::diff
+
+```cpp
+static basic_json diff(const basic_json& source,
+                       const basic_json& target);
+```
+
+Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling
+[`patch`](patch.md) function.
+
+For two JSON values `source` and `target`, the following code yields always `#!cpp true`:
+```cpp
+source.patch(diff(source, target)) == target;
+```
+
+## Parameters
+
+`source` (in)
+:   JSON value to compare from
+
+`target` (in)
+:   JSON value to compare against
+
+## Return value
+
+a JSON patch to convert the `source` to `target`
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the lengths of `source` and `target`.
+
+## Note
+
+Currently, only `remove`, `add`, and `replace` operations are generated.
+          
+## Example
+
+??? example
+
+    The following code shows how a JSON patch is created as a diff for two JSON values.
+     
+    ```cpp
+    --8<-- "examples/diff.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/diff.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.0.

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

@@ -4,36 +4,30 @@
 string_t dump(const int indent = -1,
               const char indent_char = ' ',
               const bool ensure_ascii = false,
-              const error_handler_t error_handler = error_handler_t::strict) const
+              const error_handler_t error_handler = error_handler_t::strict) const;
 ```
 
-Serialization function for JSON values. The function tries to mimic
-Python's `json.dumps()` function, and currently supports its `indent`
-and `ensure_ascii` parameters.
+Serialization function for JSON values. The function tries to mimic Python's `json.dumps()` function, and currently
+supports its `indent` and `ensure_ascii` parameters.
     
 ## Parameters
 
 `indent` (in)
-:   If `indent` is nonnegative, then array elements and object
-    members will be pretty-printed with that indent level. An indent level of
-    `0` will only insert newlines. `-1` (the default) selects the most compact
-    representation.
+:   If `indent` is nonnegative, then array elements and object members will be pretty-printed with that indent level. An
+    indent level of `0` will only insert newlines. `-1` (the default) selects the most compact representation.
 
 `indent_char` (in)
-:   The character to use for indentation if `indent` is
-    greater than `0`. The default is ` ` (space).
+:   The character to use for indentation if `indent` is greater than `0`. The default is ` ` (space).
 
 `ensure_ascii` (in)
-:   If `ensure_ascii` is true, all non-ASCII characters
-    in the output are escaped with `\uXXXX` sequences, and the result consists
-    of ASCII characters only.
+:   If `ensure_ascii` is true, all non-ASCII characters in the output are escaped with `\uXXXX` sequences, and the
+    result consists of ASCII characters only.
 
 `error_handler` (in)
-:   how to react on decoding errors; there are three
-    possible values: `strict` (throws and exception in case a decoding error
-    occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD),
-    and `ignore` (ignore invalid UTF-8 sequences during serialization; all
-    bytes are copied to the output unchanged).
+:   how to react on decoding errors; there are three possible values (see [`error_handler_t`](error_handler_t.md):
+    `strict` (throws and exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
+    with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all bytes are copied to the output
+    unchanged).
     
 ## Return value
 
@@ -41,8 +35,7 @@ string containing the serialization of the JSON value
 
 ## 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.
 
 ## Complexity
 
@@ -59,9 +52,8 @@ Binary values are serialized as object containing two keys:
 
 ??? example
 
-    The following example shows the effect of different `indent`,
-    `indent_char`, and `ensure_ascii` parameters to the result of the
-    serialization.
+    The following example shows the effect of different `indent`, `indent_char`, and `ensure_ascii` parameters to the
+    result of the serialization.
 
     ```cpp
     --8<-- "examples/dump.cpp"

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

+# basic_json::emplace
+
+```cpp
+template<class... Args>
+std::pair<iterator, bool> emplace(Args&& ... args);
+```
+
+Inserts a new element into a JSON object constructed in-place with the given `args` if there is no element with the key
+in the container. If the function is called on a JSON null value, an empty object is created before appending the value
+created from `args`.
+
+## Template parameters
+
+`Args`
+:   compatible types to create a `basic_json` object
+
+## Parameters
+
+`args` (in)
+:   arguments to forward to a constructor of `basic_json`
+
+## Return value
+
+a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and
+a `#!cpp bool` denoting whether the insertion took place.
+
+## Exceptions
+
+Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON
+object or `#!json null`; example: `"cannot use emplace() with number"`
+
+## Complexity
+
+Logarithmic in the size of the container, O(log(`size()`)).
+
+## Examples
+
+??? example
+
+    The example shows how `emplace()` can be used to add elements to a JSON object. Note how the `#!json null` value was
+    silently converted to a JSON object. Further note how no value is added if there was already one value stored with
+    the same key.
+            
+    ```cpp
+    --8<-- "examples/emplace.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/emplace.output"
+    ```
+
+## Version history
+
+- Since version 2.0.8.

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

+# basic_json::emplace_back
+
+```cpp
+template<class... Args>
+reference emplace_back(Args&& ... args);
+```
+
+Creates a JSON value from the passed parameters `args` to the end of the JSON value. If the function is called on a JSON
+`#!json null` value, an empty array is created before appending the value created from `args`.
+
+## Template parameters
+
+`Args`
+:   compatible types to create a `basic_json` object
+
+## Parameters
+
+`args` (in)
+:   arguments to forward to a constructor of `basic_json`
+
+## Return value
+
+reference to the inserted element
+
+## Exceptions
+
+Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON
+array or `#!json null`; example: `"cannot use emplace_back() with number"`
+
+## Complexity
+
+Amortized constant.
+
+## Examples
+
+??? example
+
+    The example shows how `emplace_back()` can be used to add elements to a JSON array. Note how the `null` value was
+    silently converted to a JSON array.
+        
+    ```cpp
+    --8<-- "examples/emplace_back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/emplace_back.output"
+    ```
+
+## Version history
+
+- Since version 2.0.8.
+- Returns reference since 3.7.0.

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

+# basic_json::empty
+
+```cpp
+bool empty() const noexcept;
+```
+
+Checks if a JSON value has no elements (i.e. whether its [`size()`](size.md) is `0`).
+    
+## Return value
+
+The return value depends on the different types and is defined as follows:
+
+Value type  | return value
+----------- | -------------
+null        | `#!cpp true`
+boolean     | `#!cpp false`
+string      | `#!cpp false`
+number      | `#!cpp false`
+binary      | `#!cpp false`
+object      | result of function `object_t::empty()`
+array       | result of function `array_t::empty()`
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy the
+[Container](https://en.cppreference.com/w/cpp/named_req/Container) concept; that is, their `empty()` functions have
+constant complexity.
+
+## Possible implementation
+
+```cpp
+bool empty() const noexcept
+{
+    return size() == 0;
+}
+```
+
+## Notes
+
+This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container
+itself is empty which is `#!cpp false` in the case of a string.
+
+## Example
+
+??? example
+
+    The following code uses `empty()` to check if a JSON object contains any elements.
+    
+    ```cpp
+    --8<-- "examples/empty.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/empty.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to return `#!cpp false` for binary types in version 3.8.0.

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

+# basic_json::end
+
+```cpp
+iterator end() noexcept;
+const_iterator end() const noexcept;
+```
+
+Returns an iterator to one past the last element.
+
+![Illustration from cppreference.com](../../images/range-begin-end.svg)
+
+## Return value
+
+iterator one past the last element
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code shows an example for `end()`.
+    
+    ```cpp
+    --8<-- "examples/end.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/end.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::erase
+
+```cpp
+// (1)
+iterator erase(iterator pos);
+const_iterator erase(const_iterator pos);
+
+// (2)
+iterator erase(iterator first, iterator last);
+const_iterator erase(const_iterator first, const_iterator last);
+
+// (3)
+size_type erase(const typename object_t::key_type& key);
+
+// (4)
+void erase(const size_type idx);
+```
+
+1. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and
+   dereferenceable. Thus the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
+   `pos`.
+   
+    If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
+
+2. Remove an element range specified by `[first; last)` from a JSON value. The iterator `first` does not need to be
+   dereferenceable if `first == last`: erasing an empty range is a no-op.
+   
+    If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
+
+3. Removes an element from a JSON object by key.
+
+4. Removes an element from a JSON array by index.
+
+## Parameters
+
+`pos` (in)
+:   iterator to the element to remove
+
+`first` (in)
+:   iterator to the beginning of the range to remove
+
+`last` (in)
+:   iterator past the end of the range to remove
+
+`key` (in)
+:   object key of the elements to remove
+    
+`idx` (in)
+:   array index of the element to remove
+    
+## Return value
+
+1. Iterator following the last removed element. If the iterator `pos` refers to the last element, the `end()` iterator
+   is returned.
+2. Iterator following the last removed element. If the iterator `last` refers to the last element, the `end()` iterator
+   is returned.
+3. Number of elements removed. If `ObjectType` is the default `std::map` type, the return value will always be `0`
+   (`key` was not found) or `1` (`key` was found).
+4. /
+
+## Exceptions
+
+1. The function can throw the following exceptions:
+    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
+      example: `"cannot use erase() with null"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+    - Throws [`invalid_iterator.205`](../../home/exceptions.md#jsonexceptioninvalid_iterator205) if called on a
+      primitive type with invalid iterator (i.e., any iterator which is not `begin()`); example: `"iterator out of
+      range"`
+2. The function can throw thw following exceptions:
+    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if called on a `null` value;
+      example: `"cannot use erase() with null"`
+    - Throws [`invalid_iterator.203`](../../home/exceptions.md#jsonexceptioninvalid_iterator203) if called on iterators
+      which does not belong to the current JSON value; example: `"iterators do not fit current value"`
+    - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if called on a
+      primitive type with invalid iterators (i.e., if `first != begin()` and `last != end()`); example: `"iterators out
+      of range"`
+3. The function can throw thw following exceptions:
+    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
+      JSON object; example: `"cannot use erase() with null"`
+4. The function can throw thw following exceptions:
+    - Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
+      JSON object; example: `"cannot use erase() with null"`
+    - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
+      `"array index 17 is out of range"`
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+1. The complexity depends on the type:
+       - objects: amortized constant
+       - arrays: linear in distance between `pos` and the end of the container
+       - strings and binary: linear in the length of the member
+       - other types: constant
+2. The complexity depends on the type:
+       - objects: `log(size()) + std::distance(first, last)`
+       - arrays: linear in the distance between `first` and `last`, plus linear
+         in the distance between `last` and end of the container
+       - strings and binary: linear in the length of the member
+       - other types: constant
+3. `log(size()) + count(key)`
+4. Linear in distance between `idx` and the end of the container.
+
+## Notes
+
+1. Invalidates iterators and references at or after the point of the
+   erase, including the `end()` iterator.
+2. /
+3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
+4. /
+
+## Example
+
+??? example
+
+    The example shows the effect of `erase()` for different JSON types using an iterator.
+    
+    ```cpp
+    --8<-- "examples/erase__IteratorType.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/erase__IteratorType.output"
+    ```
+
+??? example
+
+    The example shows the effect of `erase()` for different JSON types using an iterator range.
+    
+    ```cpp
+    --8<-- "examples/erase__IteratorType_IteratorType.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/erase__IteratorType_IteratorType.output"
+    ```
+
+??? example
+
+    The example shows the effect of `erase()` for different JSON types using an object key.
+    
+    ```cpp
+    --8<-- "examples/erase__key_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/erase__key_type.output"
+    ```
+
+??? example
+
+    The example shows the effect of `erase()` using an array index.
+    
+    ```cpp
+    --8<-- "examples/erase__size_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/erase__size_type.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Added support for binary types in version 3.8.0.

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

+# basic_json::error_handler_t
+
+```cpp
+enum class error_handler_t {
+    strict,
+    replace,
+    ignore
+};
+```
+
+This enumeration is used in the [`dump`](dump.md) function to choose how to treat decoding errors while serializing a
+`basic_json` value. Three values are differentiated:
+
+strict
+:   throw a `type_error` exception in case of invalid UTF-8
+
+replace
+:   replace invalid UTF-8 sequences with U+FFFD (� REPLACEMENT CHARACTER)
+
+ignore
+:   ignore invalid UTF-8 sequences; all bytes are copied to the output unchanged
+
+## Version history
+
+- Added in version 3.4.0.

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

+# basic_json::exception
+
+```cpp
+class exception : public std::exception;
+```
+
+This class is an extension of [`std::exception`](https://en.cppreference.com/w/cpp/error/exception) objects with a
+member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This
+class can hence be used as "wildcard" to catch exceptions, see example below.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception #FFFF00 {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error {
+    + const std::size_t byte
+}
+```
+
+Subclasses:
+
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how arbitrary library exceptions can be caught.
+    
+    ```cpp
+    --8<-- "examples/exception.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/exception.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

+# basic_json::find
+
+```cpp
+template<typename KeyT>
+iterator find(KeyT&& key);
+
+template<typename KeyT>
+const_iterator find(KeyT&& key) const
+```
+
+Finds an element in a JSON object with key equivalent to `key`. If the element is not found or the JSON value is not an
+object, `end()` is returned.
+
+## Template parameters
+
+`KeyT`
+:   A type for an object key.
+
+## Parameters
+
+`key` (in)
+:   key value of the element to search for.
+    
+## Return value
+
+Iterator to an element with key equivalent to `key`. If no such element is found or the JSON value is not an object,
+past-the-end (see `end()`) iterator is returned.
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+Logarithmic in the size of the JSON object.
+
+## Notes
+
+This method always returns `end()` when executed on a JSON type that is not an object.
+
+## Example
+
+??? example
+
+    The example shows how `find()` is used.
+    
+    ```cpp
+    --8<-- "examples/find__key_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/find__key_type.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::flatten
+
+```cpp
+basic_json flatten() const;
+```
+
+The function creates a JSON object whose keys are JSON pointers (see [RFC 6901](https://tools.ietf.org/html/rfc6901))
+and whose values are all primitive (see [`is_primitive()`](is_primitive.md) for more information). The original JSON
+value can be restored using the [`unflatten()`](unflatten.md) function.
+    
+## Return value
+
+an object that maps JSON pointers to primitive values
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+Linear in the size the JSON value.
+
+## Notes
+
+Empty objects and arrays are flattened to `#!json null` and will not be reconstructed correctly by the
+[`unflatten()`](unflatten.md) function.
+
+## Example
+
+??? example
+
+    The following code shows how a JSON object is flattened to an object whose keys consist of JSON pointers.
+    
+    ```cpp
+    --8<-- "examples/flatten.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/flatten.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.0.

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

+# basic_json::from_bson
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_bson(InputType&& i,
+                            const bool strict = true,
+                            const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType>
+static basic_json from_bson(IteratorType first, IteratorType last,
+                            const bool strict = true,
+                            const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the BSON (Binary JSON) serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range.
+
+## 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 BSON 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.
+
+## Complexity
+
+Linear in the size of the input.
+
+## Example
+
+??? example
+
+    The example shows the deserialization of a byte vector in BSON format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_bson.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_bson.output"
+    ```
+
+## Version history
+
+- Added in version 3.4.0.

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

+# basic_json::from_cbor
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_cbor(InputType&& i,
+                            const bool strict = true,
+                            const bool allow_exceptions = true,
+                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
+
+// (2)
+template<typename IteratorType>
+static basic_json from_cbor(IteratorType first, IteratorType last,
+                            const bool strict = true,
+                            const bool allow_exceptions = true,
+                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
+```
+
+Deserializes a given input to a JSON value using the CBOR (Concise Binary Object Representation) serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range.
+
+## 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 CBOR 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)
+
+`tag_handler` (in)
+:   how to treat CBOR tags (optional, `error` by default); see [`cbor_tag_handler_t`](cbor_tag_handler_t.md) for more
+    information
+
+## 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.
+
+## Complexity
+
+Linear in the size of the input.
+
+## Example
+
+??? example
+
+    The example shows the deserialization of a byte vector in CBOR format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_cbor.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_cbor.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.9.
+- 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.
+- Added `tag_handler` parameter in version 3.9.0.

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

+# basic_json::from_msgpack
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_msgpack(InputType&& i,
+                               const bool strict = true,
+                               const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType>
+static basic_json from_msgpack(IteratorType first, IteratorType last,
+                               const bool strict = true,
+                               const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the MessagePack serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range.
+
+## 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 MessagePack 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.
+
+## Complexity
+
+Linear in the size of the input.
+
+## Example
+
+??? example
+
+    The example shows the deserialization of a byte vector in MessagePack format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_msgpack.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_msgpack.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.9.
+- 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.

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

+# basic_json::from_ubjson
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json from_ubjson(InputType&& i,
+                              const bool strict = true,
+                              const bool allow_exceptions = true);
+// (2)
+template<typename IteratorType>
+static basic_json from_ubjson(IteratorType first, IteratorType last,
+                              const bool strict = true,
+                              const bool allow_exceptions = true);
+```
+
+Deserializes a given input to a JSON value using the UBJSON (Universal Binary JSON) serialization format.
+
+1. Reads from a compatible input.
+2. Reads from an iterator range.
+
+## 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 UBJSON 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.
+
+## Complexity
+
+Linear in the size of the input.
+
+## Example
+
+??? example
+
+    The example shows the deserialization of a byte vector in UBJSON format to a JSON value.
+     
+    ```cpp
+    --8<-- "examples/from_ubjson.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_ubjson.output"
+    ```
+
+## Version history
+
+- Added in version 3.1.0.
+- Added `allow_exceptions` parameter in version 3.2.0.

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

+# basic_json::front
+
+```cpp
+reference front();
+const_reference front() const;
+```
+
+Returns a reference to the first element in the container. For a JSON container `#!cpp c`, the expression
+`#!cpp c.front()` is equivalent to `#!cpp *c.begin()`.
+    
+## Return value
+
+In case of a structured type (array or object), a reference to the first element is returned. In case of number, string,
+boolean, or binary values, a reference to the value is returned.
+
+## Exceptions
+
+If the JSON value is `#!json null`, exception
+[`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Constant.
+
+## Note
+
+!!! danger
+
+    Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**!
+
+## Example
+
+??? example
+
+    The following code shows an example for `front()`.
+     
+    ```cpp
+    --8<-- "examples/front.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/front.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Adjusted code to return reference to binary values in version 3.8.0.

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

+# basic_json::get
+
+```cpp
+// (1)
+template<typename ValueType>
+ValueType get() const noexcept(
+    noexcept(JSONSerializer<ValueType>::from_json(
+        std::declval<const basic_json_t&>(), std::declval<ValueType&>())));
+
+// (2)
+template<typename BasicJsonType>
+BasicJsonType get() const;
+
+// (3)
+template<typename PointerType>
+PointerType get_ptr();
+
+template<typename PointerType>
+constexpr const PointerType get_ptr() const noexcept;
+```
+
+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.
+   
+    The function is equivalent to executing
+    ```cpp
+    ValueType ret;
+    JSONSerializer<ValueType>::from_json(*this, ret);
+    return ret;
+    ```
+
+    This overloads is chosen if:
+    
+    - `ValueType` is not `basic_json`,
+    - `json_serializer<ValueType>` has a `from_json()` method of the form
+      `void from_json(const basic_json&, ValueType&)`, and
+    - `json_serializer<ValueType>` does not have a `from_json()` method of the form
+      `ValueType from_json(const basic_json&)`
+
+    If the type is **not** [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and
+    **not** [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible), the value is
+    converted by calling the `json_serializer<ValueType>` `from_json()` method.
+   
+    The function is then equivalent to executing
+    ```cpp
+    return JSONSerializer<ValueTypeCV>::from_json(*this);
+    ``` 
+   
+    This overloads is chosen if:
+    
+    - `ValueType` is not `basic_json` and
+    - `json_serializer<ValueType>` has a `from_json()` method of the form
+     `ValueType from_json(const basic_json&)`
+
+    If `json_serializer<ValueType>` has both overloads of `from_json()`, the latter one is chosen.
+
+2. Overload for `basic_json` specializations. The function is equivalent to executing
+    ```cpp
+    return *this;
+    ```
+
+3. Explicit pointer access to the internally stored JSON value. No copies are made.
+
+## Template parameters
+
+`ValueType`
+:   the value type to return
+
+`BasicJsonType`
+:   a specialization of `basic_json`
+
+`PointerType`
+:   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
+    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
+    [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    Other types will not compile.
+
+## Return value
+
+1. copy of the JSON value, converted to `ValueType`
+2. a copy of `#!cpp *this`, converted into `BasicJsonType`
+3. pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
+   otherwise
+
+## Exceptions
+
+Depends on what `json_serializer<ValueType>` `from_json()` method throws
+
+## Notes
+
+!!! warning
+
+    Writing data to the pointee (overload 3) of the result yields an undefined state.
+
+## Example
+
+??? example
+
+    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>`.
+        
+    ```cpp
+    --8<-- "examples/get__ValueType_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get__ValueType_const.output"
+    ```
+
+??? example
+
+    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.
+        
+    ```cpp
+    --8<-- "examples/get__PointerType.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get__PointerType.output"
+    ```
+
+## Version history
+
+1. Since version 2.1.0.
+2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0.
+3. Since version 1.0.0.

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

+# basic_json::get_allocator
+
+```cpp
+static allocator_type get_allocator();
+```
+
+Returns the allocator associated with the container.
+    
+## Return value
+
+associated allocator
+
+## Version history
+
+- Unknown.

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

+# basic_json::get_binary
+
+```cpp
+binary_t& get_binary();
+
+const binary_t& get_binary() const;
+```
+
+Returns a reference to the stored binary value.
+
+## Return value
+
+Reference to binary value.
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Exceptions
+
+Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value is not binary
+
+## Complexity
+
+Constant.
+
+## Version history
+
+- Added in version 3.8.0.

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

+# basic_json::get_ptr
+
+```cpp
+template<typename PointerType>
+PointerType get_ptr();
+
+template<typename PointerType>
+constexpr const PointerType get_ptr() const noexcept;
+```
+
+Implicit pointer access to the internally stored JSON value. No copies are made.
+
+## Template arguments
+
+`PointerType`
+:   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
+    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
+    [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    Other types will not compile.
+
+## Return value
+
+pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
+otherwise
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+!!! warning
+
+    Writing data to the pointee of the result yields an undefined state.
+
+## Example
+
+??? example
+
+    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.
+    
+    ```cpp
+    --8<-- "examples/get_ptr.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_ptr.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to binary types in version 3.8.0.

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

+# basic_json::get_ref
+
+```cpp
+template<typename ReferenceType>
+ReferenceType get_ref();
+
+template<typename ReferenceType>
+const ReferenceType get_ref() const;
+```
+
+Implicit reference access to the internally stored JSON value. No copies are made.
+
+## Template arguments
+
+`ReferenceType`
+:   reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
+    [`string_t`](string_t.md), [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
+    [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    Enforced by static assertion.
+
+## Return value
+
+reference to the internally stored JSON value if the requested reference type fits to the JSON value; throws
+[`type_error.303`](../../home/exceptions.md#jsonexceptiontype_error303) otherwise
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Exceptions
+
+Throws [`type_error.303`](../../home/exceptions.md#jsonexceptiontype_error303) if the requested reference type does not
+match the stored JSON value type; example: `"incompatible ReferenceType for get_ref, actual type is binary"`.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+!!! warning
+
+    Writing data to the referee of the result yields an undefined state.
+
+## Example
+
+??? example
+
+    The example shows several calls to `get_ref()`.
+    
+    ```cpp
+    --8<-- "examples/get_ref.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_ref.output"
+    ```
+
+## Version history
+
+- Added in version 1.1.0.
+- Extended to binary types in version 3.8.0.

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

+# basic_json::get_to
+
+```cpp
+template<typename ValueType>
+ValueType& get_to(ValueType& v) const noexcept(
+    noexcept(JSONSerializer<ValueType>::from_json(
+        std::declval<const basic_json_t&>(), v)))
+```
+
+Explicit type conversion between the JSON value and a compatible value. The value is filled into the input parameter by
+calling the `json_serializer<ValueType>` `from_json()` method.
+
+The function is equivalent to executing
+```cpp
+ValueType v;
+JSONSerializer<ValueType>::from_json(*this, v);
+```
+
+This overloads is chosen if:
+
+- `ValueType` is not `basic_json`,
+- `json_serializer<ValueType>` has a `from_json()` method of the form `void from_json(const basic_json&, ValueType&)`
+
+## Template parameters
+
+`ValueType`
+:   the value type to return
+
+## Return value
+
+the input parameter, allowing chaining calls
+
+## Exceptions
+
+Depends on what `json_serializer<ValueType>` `from_json()` method throws
+
+## Example
+
+??? example
+
+    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
+    `#!cpp std::vector<short>`, (3) A JSON object can be converted to C++ associative containers such as
+    `#cpp std::unordered_map<std::string, json>`.
+        
+    ```cpp
+    --8<-- "examples/get_to.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_to.output"
+    ```
+
+## Version history
+
+- Since version 3.3.0.

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

+# basic_json::input_format_t
+
+```cpp
+enum class input_format_t {
+    json,
+    cbor,
+    msgpack,
+    ubjson,
+    bson
+};
+```
+
+This enumeration is used in the [`sax_parse`](sax_parse.md) function to choose the input format to parse:
+
+json
+:   JSON (JavaScript Object Notation)
+
+cbor
+:   CBOR (Concise Binary Object Representation)
+
+msgpack
+:   MessagePack
+
+ubjson
+:   UBJSON (Universal Binary JSON)
+
+bson
+:   BSON (Bin­ary JSON)
+
+## Version history
+
+- Added in version 3.2.0.

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

+# basic_json::insert
+
+```cpp
+// (1)
+iterator insert(const_iterator pos, const basic_json& val);
+iterator insert(const_iterator pos, basic_json&& val);
+
+// (2)
+iterator insert(const_iterator pos, size_type cnt, const basic_json& val);
+
+// (3)
+iterator insert(const_iterator pos, const_iterator first, const_iterator last);
+
+// (4)
+iterator insert(const_iterator pos, initializer_list_t ilist);
+
+// (5)
+void insert(const_iterator first, const_iterator last);
+```
+
+1. Inserts element `val` to array before iterator `pos`.
+2. Inserts `cnt` copies of `val` to array before iterator `pos`.
+3. Inserts elements from range `[first, last)` to array before iterator `pos`.
+4. Inserts elements from initializer list `ilist` to array before iterator `pos`.
+5. Inserts elements from range `[first, last)` to object.
+
+## Parameters
+
+`pos` (in)
+:   iterator before which the content will be inserted; may be the `end()` iterator
+
+`val` (in)
+:   value to insert
+
+`cnt` (in)
+:   number of copies of `val` to insert
+
+`first` (in)
+:   begin of the range of elements to insert
+
+`last` (in)
+:   end of the range of elements to insert
+
+`ilist` (in)
+:   initializer list to insert the values from
+    
+## Return value
+
+1. iterator pointing to the inserted `val`.
+2. iterator pointing to the first element inserted, or `pos` if `#!cpp cnt==0`
+3. iterator pointing to the first element inserted, or `pos` if `#!cpp first==last`
+4. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
+5. /
+
+## Exceptions
+
+1. The function can throw the following exceptions:
+    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
+      arrays; example: `"cannot use insert() with string"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+2. The function can throw thw following exceptions:
+    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
+      arrays; example: `"cannot use insert() with string"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+3. The function can throw thw following exceptions:
+    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
+      arrays; example: `"cannot use insert() with string"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+    - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
+      do not belong to the same JSON value; example: `"iterators do not fit"`
+    - Throws [`invalid_iterator.211`](../../home/exceptions.md#jsonexceptioninvalid_iterator211) if `first` or `last`
+      are iterators into container for which insert is called; example: `"passed iterators may not belong to container"`
+4. The function can throw thw following exceptions:
+    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
+      arrays; example: `"cannot use insert() with string"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+5. The function can throw thw following exceptions:
+    - Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
+      objects; example: `"cannot use insert() with string"`
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
+    - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
+      do not belong to the same JSON value; example: `"iterators do not fit"`
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Complexity
+
+1. Constant plus linear in the distance between `pos` and end of the container.
+2. Linear in `cnt` plus linear in the distance between `pos` and end of the container.
+3. Linear in `#!cpp std::distance(first, last)` plus linear in the distance between `pos` and end of the container.
+4. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container.
+5. Logarithmic: `O(N*log(size() + N))`, where `N` is the number of elements to insert.
+
+## Example
+
+??? example
+
+    The example shows how `insert()` is used.
+    
+    ```cpp
+    --8<-- "examples/insert.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/insert.output"
+    ```
+
+??? example
+
+    The example shows how `insert()` is used.
+    
+    ```cpp
+    --8<-- "examples/insert__count.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/insert__count.output"
+    ```
+
+??? example
+
+    The example shows how `insert()` is used.
+    
+    ```cpp
+    --8<-- "examples/insert__range.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/insert__range.output"
+    ```
+
+??? example
+
+    The example shows how `insert()` is used.
+    
+    ```cpp
+    --8<-- "examples/insert__ilist.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/insert__ilist.output"
+    ```
+
+??? example
+
+    The example shows how `insert()` is used.
+    
+    ```cpp
+    --8<-- "examples/insert__range_object.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/insert__range_object.output"
+    ```
+
+## Version history
+
+1. Added in version 1.0.0.
+2. Added in version 1.0.0.
+3. Added in version 1.0.0.
+4. Added in version 1.0.0.
+5. Added in version 3.0.0.

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

+# basic_json::invalid_iterator
+
+```cpp
+class invalid_iterator : public exception;
+```
+
+This exception is thrown if iterators passed to a library function do not match the expected semantics.
+
+Exceptions have ids 2xx.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error {
+    + const std::size_t byte
+}
+
+class basic_json::invalid_iterator #FFFF00 {}
+```
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how a `invalid_iterator` exception can be caught.
+    
+    ```cpp
+    --8<-- "examples/invalid_iterator.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/invalid_iterator.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

+# basic_json::is_array
+
+```cpp
+constexpr bool is_array() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is an array.
+    
+## Return value
+
+`#!cpp true` if type is an array, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_array()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_array.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_array.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_binary
+
+```cpp
+constexpr bool is_binary() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is binary array.
+    
+## Return value
+
+`#!cpp true` if type is binary, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_binary()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_binary.output"
+    ```
+
+## Version history
+
+- Added in version 3.8.0.

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

+# basic_json::is_boolean
+
+```cpp
+constexpr bool is_boolean() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is `#!json true` or `#!json false`.
+    
+## Return value
+
+`#!cpp true` if type is boolean, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_boolean()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_boolean.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_boolean.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_discarded
+
+```cpp
+constexpr bool is_discarded() const noexcept;
+```
+
+This function returns `#!cpp true` for a JSON value if either:
+
+- the value was discarded during parsing with a callback function (see [`parser_callback_t`](parser_callback_t.md)), or
+- the value is the result of parsing invalid JSON with parameter `allow_exceptions` set to `#!cpp false`; see
+  [`parse`](parse.md) for more information.
+
+## Return value
+
+`#!cpp true` if type is discarded, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+!!! note
+
+    Discarded values are never compared equal with [`operator==`](operator_eq.md). That is, checking whether a JSON
+    value `j` is discarded will only work via:
+    
+    ```cpp
+    j.is_discarded()
+    ```
+    
+    because
+    
+    ```cpp
+    j == json::value_t::discarded
+    ```
+    
+    will always be `#!cpp false`.
+
+!!! note
+
+    When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
+    then it is removed when it is part of a structured value. For instance, if the second value of an array is discared,
+    instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level
+    value is discarded, the return value of the `parse` call is discarded.
+
+This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
+during parsing, but will be removed when inside a structured value or replaced by null in other cases.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_discarded()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_discarded.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_discarded.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_null
+
+```cpp
+constexpr bool is_null() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is `#!json null`.
+    
+## Return value
+
+`#!cpp true` if type is `#!json null`, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_null()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_null.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_null.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_number
+
+```cpp
+constexpr bool is_number() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is a number. This includes both integer (signed and
+unsigned) and floating-point values.
+    
+## Return value
+
+`#!cpp true` if type is number (regardless whether integer, unsigned integer or floating-type), `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Possible implementation
+
+```cpp
+constexpr bool is_number() const noexcept
+{
+    return is_number_integer() || is_number_float();
+}
+```
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_number()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_number.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_number.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to also return `#!cpp true` for unsigned integers in 2.0.0.

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

+# basic_json::is_number_float
+
+```cpp
+constexpr bool is_number_float() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is a floating-point number. This excludes signed and
+unsigned integer values.
+    
+## Return value
+
+`#!cpp true` if type is a floating-point number, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_number_float()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_number_float.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_number_float.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_number_integer
+
+```cpp
+constexpr bool is_number_integer() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is a signed or unsigned integer number. This excludes
+floating-point values.
+    
+## Return value
+
+`#!cpp true` if type is an integer or unsigned integer number, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_number_integer()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_number_integer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_number_integer.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to also return `#!cpp true` for unsigned integers in 2.0.0.

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

+# basic_json::is_number_unsigned
+
+```cpp
+constexpr bool is_number_unsigned() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is an unsigned integer number. This excludes
+floating-point and signed integer values.
+    
+## Return value
+
+`#!cpp true` if type is an unsigned integer number, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_number_unsigned()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_number_unsigned.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_number_unsigned.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.0.

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

+# basic_json::is_object
+
+```cpp
+constexpr bool is_object() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is an object.
+    
+## Return value
+
+`#!cpp true` if type is an object, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_object()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_object.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_object.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_primitive
+
+```cpp
+constexpr bool is_primitive() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON type is primitive (string, number, boolean, `#!json null`,
+binary).
+    
+## Return value
+
+`#!cpp true` if type is primitive (string, number, boolean, `#!json null`, or binary), `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Possible implementation
+
+```cpp
+constexpr bool is_primitive() const noexcept
+{
+    return is_null() || is_string() || is_boolean() || is_number() || is_binary();
+}
+```
+
+## Notes
+
+The term *primitive* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
+
+> JSON can represent four primitive types (strings, numbers, booleans, and null) and two structured types (objects and
+> arrays).
+
+This library extends primitive types to binary types, because binary types are  roughly comparable to strings. Hence,
+`is_primitive()` returns `#!cpp true` for binary values.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_primitive()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_primitive.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_primitive.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to return `#!cpp true` for binary types in version 3.8.0.

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

+# basic_json::is_string
+
+```cpp
+constexpr bool is_string() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON value is a string.
+    
+## Return value
+
+`#!cpp true` if type is a string, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_string()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_string.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_string.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::is_structured
+
+```cpp
+constexpr bool is_structured() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the JSON type is structured (array or object).
+    
+## Return value
+
+`#!cpp true` if type is structured (array or object), `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this member function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
+
+> JSON can represent four primitive types (strings, numbers, booleans, and null) and two structured types (objects and
+> arrays).
+
+Note that though strings are containers in C++, they are treated as primitive values in JSON.
+
+## Example
+
+??? example
+
+    The following code exemplifies `is_structured()` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/is_structured.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/is_structured.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::items
+
+```cpp
+iteration_proxy<iterator> items() noexcept;
+iteration_proxy<const_iterator> items() const noexcept;
+```
+
+This function allows to access `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
+reference to the JSON values is returned, so there is no access to the underlying iterator.
+
+For loop without `items()` function:
+
+```cpp
+for (auto it = j_object.begin(); it != j_object.end(); ++it)
+{
+    std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
+}
+```
+
+Range-based for loop without `items()` function:
+
+```cpp
+for (auto it : j_object)
+{
+    // "it" is of type json::reference and has no key() member
+    std::cout << "value: " << it << '\n';
+}
+```
+
+Range-based for loop with `items()` function:
+
+```cpp
+for (auto& el : j_object.items())
+{
+    std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
+}
+```
+
+The `items()` function also allows to use
+[structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding) (C++17):
+
+```cpp
+for (auto& [key, val] : j_object.items())
+{
+    std::cout << "key: " << key << ", value:" << val << '\n';
+}
+```
+
+## Return value
+
+iteration proxy object wrapping the current value with an interface to use in range-based for loops
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+When iterating over an array, `key()` will return the index of the element as string (see example). For primitive types
+(e.g., numbers), `key()` returns an empty string.
+
+!!! warning
+
+    Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exeeds the iteration. See
+    <https://github.com/nlohmann/json/issues/2040> for more information.
+
+## Example
+
+??? example
+
+    The following code shows an example for `items()`.
+    
+    ```cpp
+    --8<-- "examples/items.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/items.output"
+    ```
+
+## Version history
+
+- Added in version 3.0.0.
+- Added structured binding support in version 3.5.0.
+
+!!! note
+
+    This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been
+    deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all
+    occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`.

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

+# basic_json::json_serializer
+
+```cpp
+template<typename T, typename SFINAE>
+using json_serializer = JSONSerializer<T, SFINAE>;
+```
+
+## Template parameters
+
+`T`
+:   type to convert; will be used in the `to_json`/`from_json` functions
+
+`SFINAE`
+:   type to add compile type checks via SFINAE; usually `#!cpp void`
+
+## Notes
+
+#### Default type
+
+The default values for `json_serializer` is [`adl_serializer`](../adl_serializer.md).
+
+## Version history
+
+- Since version 2.0.0.

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

+# basic_json::max_size
+
+```cpp
+size_type max_size() const noexcept;
+```
+
+Returns the maximum number of elements a JSON value is able to hold due to system or library implementation limitations,
+i.e. `std::distance(begin(), end())` for the JSON value.
+    
+## Return value
+
+The return value depends on the different types and is defined as follows:
+
+Value type  | return value
+----------- | -------------
+null        | `0` (same as [`size()`](size.md))
+boolean     | `1` (same as [`size()`](size.md))
+string      | `1` (same as [`size()`](size.md))
+number      | `1` (same as [`size()`](size.md))
+binary      | `1` (same as [`size()`](size.md))
+object      | result of function `object_t::max_size()`
+array       | result of function `array_t::max_size()`
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy the
+[Container](https://en.cppreference.com/w/cpp/named_req/Container) concept; that is, their `max_size()` functions have
+constant complexity.
+
+## Notes
+
+This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of
+string elements the JSON value can store which is `1`.
+
+## Example
+
+??? example
+
+    The following code calls `max_size()` on the different value types. Note the output is implementation specific.
+        
+    ```cpp
+    --8<-- "examples/max_size.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/max_size.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended to return `1` for binary types in version 3.8.0.

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

+# basic_json::merge_patch
+
+```cpp
+void merge_patch(const basic_json& apply_patch);
+```
+
+The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of
+modifications to a target resource's content. This function applies a merge patch to the current JSON value.
+
+The function implements the following algorithm from Section 2 of
+[RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396):
+
+```python
+define MergePatch(Target, Patch):
+  if Patch is an Object:
+    if Target is not an Object:
+      Target = {} // Ignore the contents and set it to an empty Object
+    for each Name/Value pair in Patch:
+      if Value is null:
+        if Name exists in Target:
+          remove the Name/Value pair from Target
+      else:
+        Target[Name] = MergePatch(Target[Name], Value)
+    return Target
+  else:
+    return Patch
+```
+
+Thereby, `Target` is the current object; that is, the patch is applied to the current value.
+
+## Parameters
+
+`apply_patch` (in)
+:   the patch to apply
+
+## Complexity
+
+Linear in the lengths of `apply_patch`.
+
+## Example
+
+??? example
+
+    The following code shows how a JSON Merge Patch is applied to a JSON document.
+     
+    ```cpp
+    --8<-- "examples/merge_patch.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/merge_patch.output"
+    ```
+
+## Version history
+
+- Added in version 3.0.0.

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

@@ -4,8 +4,8 @@
 static basic_json meta();
 ```
 
-This function returns a JSON object with information about the library,
-including the version number and information on the platform and compiler.
+This function returns a JSON object with information about the library, including the version number and information on
+the platform and compiler.
     
 ## Return value
 
@@ -22,8 +22,7 @@ key         | description
 
 ## 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.
 
 ## Complexity
 
@@ -43,3 +42,7 @@ Output:
 ```json
 --8<-- "examples/meta.output"
 ```
+
+## Version history
+
+- Added in version 2.1.0.

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

+# basic_json::number_float_t
+
+```cpp
+using number_float_t = NumberFloatType;
+```
+
+The type used to store JSON numbers (floating-point).
+
+[RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+> The representation of numbers is similar to that used in most programming languages. A number is represented in base
+> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
+> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
+> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
+
+This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
+known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
+types, [`number_integer_t`](number_integer_t.md), [`number_unsigned_t`](number_unsigned_t.md) and `number_float_t` are
+used.
+
+To store floating-point numbers in C++, a type is defined by the template parameter `NumberFloatType` which chooses the
+type to use.
+
+## Notes
+
+#### Default type
+
+With the default values for `NumberFloatType` (`double`), the default value for `number_float_t` is `#!cpp double`.
+
+#### Default behavior
+
+- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in floating-point literals will be
+  ignored. Internally, the value will be stored as decimal number. For instance, the C++ floating-point literal `01.2`
+  will be serialized to `1.2`. During deserialization, leading zeros yield an error.
+- Not-a-number (NaN) values will be serialized to `null`.
+
+#### Limits
+
+[RFC 7159](http://rfc7159.net/rfc7159) states:
+> This specification allows implementations to set limits on the range and precision of numbers accepted. Since software
+> that implements IEEE 754-2008 binary64 (double precision) numbers is generally available and widely used, good
+> interoperability can be achieved by implementations that expect no more precision or range than these provide, in the
+> sense that implementations will approximate JSON numbers within the expected precision.
+
+This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values
+smaller than `-1.79769313486232e+308` and values greater than `1.79769313486232e+308` will be stored as NaN internally
+and be serialized to `null`.
+
+#### Storage
+
+Floating-point number values are stored directly inside a `basic_json` type.
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::number_integer_t
+
+```cpp
+using number_integer_t = NumberIntegerType;
+```
+
+The type used to store JSON numbers (integers).
+
+[RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+> The representation of numbers is similar to that used in most programming languages. A number is represented in base
+> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
+> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
+> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
+
+This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
+known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
+types, `number_integer_t`,  [`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are
+used.
+
+To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type
+to use.
+
+## Notes
+
+#### Default type
+
+With the default values for `NumberIntegerType` (`std::int64_t`), the default value for `number_integer_t` is
+`#!cpp std::int64_t`.
+
+#### Default behavior
+
+- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an
+  interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer
+  literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
+- Not-a-number (NaN) values will be serialized to `null`.
+
+#### Limits
+
+[RFC 7159](http://rfc7159.net/rfc7159) specifies:
+> An implementation may set limits on the range and precision of numbers.
+
+When the default type is used, the maximal integer number that can be stored is `9223372036854775807` (INT64_MAX) and
+the minimal integer number that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers that are out of
+range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers
+will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
+
+[RFC 7159](http://rfc7159.net/rfc7159) further states:
+> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
+> interoperable in the sense that implementations will agree exactly on their numeric values.
+
+As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
+interoperable.
+
+#### Storage
+
+Integer number values are stored directly inside a `basic_json` type.
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::number_unsigned_t
+
+```cpp
+using number_unsigned_t = NumberUnsignedType;
+```
+
+The type used to store JSON numbers (unsigned).
+
+[RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
+> The representation of numbers is similar to that used in most programming languages. A number is represented in base
+> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
+> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
+> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
+
+This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
+known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
+types, [`number_integer_t`](number_integer_t.md), `number_unsigned_t` and [`number_float_t`](number_float_t.md) are
+used.
+
+To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses
+the type to use.
+
+## Notes
+
+#### Default type
+
+With the default values for `NumberUnsignedType` (`std::uint64_t`), the default value for `number_unsigned_t` is
+`#!cpp std::uint64_t`.
+
+#### Default behavior
+
+- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an
+  interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer 
+  literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
+- Not-a-number (NaN) values will be serialized to `null`.
+
+#### Limits
+
+[RFC 7159](http://rfc7159.net/rfc7159) specifies:
+> An implementation may set limits on the range and precision of numbers.
+
+When the default type is used, the maximal integer number that can be stored is `18446744073709551615` (UINT64_MAX) and
+the minimal integer number that can be stored is `0`. Integer numbers that are out of range will yield over/underflow
+when used in a constructor. During deserialization, too large or small integer numbers will be automatically be stored
+as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
+
+[RFC 7159](http://rfc7159.net/rfc7159) further states:
+> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
+> interoperable in the sense that implementations will agree exactly on their numeric values.
+
+As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported
+range [0, UINT64_MAX], this class's integer type is interoperable.
+
+#### Storage
+
+Integer number values are stored directly inside a `basic_json` type.
+
+## Version history
+
+- Added in version 2.0.0.

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

+# basic_json::object
+
+```cpp
+static basic_json object(initializer_list_t init = {});
+```
+
+Creates a JSON object value from a given initializer list. The initializer lists elements must be pairs, and their first
+elements must be strings. If the initializer list is empty, the empty object `#!json {}` is created.
+
+## Parameters
+
+`init` (in)
+:   initializer list with JSON values to create an object from (optional)
+
+## Return value
+
+JSON object value
+
+## Exceptions
+
+Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose
+first elements are strings. In this case, no object can be created. When such a value is passed to
+`basic_json(initializer_list_t, bool, value_t)`, an array would have been created from the passed initializer list
+`init`. See example below.
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of `init`.
+
+## Notes
+
+This function is only added for symmetry reasons. In contrast to the related function `array(initializer_list_t)`, there
+are no cases which can only be expressed by this function. That is, any initializer list `init` can also be passed to
+the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`.
+    
+## Examples
+
+??? example
+
+    The following code shows an example for the `object` function.
+
+    ```cpp
+    --8<-- "examples/object.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/object.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.

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

+# basic_json::object_comparator_t
+
+```cpp
+// until C++14
+using object_comparator_t = std::less<StringType>;
+
+// since C++14
+using object_comparator_t = std::less<>;
+```
+
+The comparator used in [`object_t`](object_t.md).
+
+When C++14 is detected, a transparent com parator is used which, when combined with perfect forwarding on find() and
+count() calls, prevents unnecessary string construction.
+
+## Version history
+
+- Unknown.

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

+# basic_json::operator=
+
+```cpp
+basic_json& operator=(basic_json other) noexcept (
+    std::is_nothrow_move_constructible<value_t>::value &&
+    std::is_nothrow_move_assignable<value_t>::value &&
+    std::is_nothrow_move_constructible<json_value>::value &&
+    std::is_nothrow_move_assignable<json_value>::value
+);
+```
+
+Copy assignment operator. Copies a JSON value via the "copy and swap" strategy: It is expressed in terms of the copy
+constructor, destructor, and the `swap()` member function.
+
+## Parameters
+
+`other` (in)
+:   value to copy from
+
+## Complexity
+
+Linear.
+
+## Example
+
+??? example
+
+    The code below shows and example for the copy assignment. It creates a copy of value `a` which is then swapped with
+    `b`. Finally, the copy of `a` (which is the null value after the swap) is destroyed.
+     
+    ```cpp
+    --8<-- "examples/basic_json__copyassignment.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/basic_json__copyassignment.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.