📝 add more API documentation

doc/docset/docSet.sql

@@ -80,6 +80,14 @@ INSERT INTO searchIndex(name, type, path) VALUES ('type', 'Method', 'api/basic_j
 INSERT INTO searchIndex(name, type, path) VALUES ('type_name', 'Method', 'api/basic_json/type_name/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('unflatten', 'Method', 'api/basic_json/unflatten/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('update', 'Method', 'api/basic_json/update/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('from_bson', 'Function', 'api/basic_json/from_bson/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('from_cbor', 'Function', 'api/basic_json/from_cbor/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('from_msgpack', 'Function', 'api/basic_json/from_msgpack/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('from_ubjson', 'Function', 'api/basic_json/from_ubjson/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('to_bson', 'Function', 'api/basic_json/to_bson/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('to_cbor', 'Function', 'api/basic_json/to_cbor/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('to_msgpack', 'Function', 'api/basic_json/to_msgpack/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('to_ubjson', 'Function', 'api/basic_json/to_ubjson/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('value', 'Method', 'api/basic_json/value/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('value_t', 'Enum', 'api/basic_json/value_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('~basic_json', 'Method', 'api/basic_json/~basic_json/index.html');

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

@@ -7,9 +7,8 @@ static bool accept(InputType&& i,
                    const bool ignore_comments = false);
 
 // (2)
-static bool accept(iterator first, iterator last,
-                   const bool ignore_comments = false);
-static bool accept(const_iterator first, const_iterator last,
+template<typename IteratorType>
+static bool accept(IteratorType first, IteratorType last,
                    const bool ignore_comments = false);
 ```
 
@@ -35,6 +34,9 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti
     - 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)

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`.
+
+## 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)
+
+## 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`.
+
+## 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`.
+
+## 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`.
+
+## 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/index.md

@@ -204,9 +204,9 @@ Access to the JSON value
 
 ### Deserialization
 
-- [**parse**](parse.md) - deserialize from a compatible input
-- [**accept**](accept.md) - check if the input is valid JSON
-- [**sax_parse**](sax_parse.md) - generate SAX events
+- [**parse**](parse.md) (static) - deserialize from a compatible input
+- [**accept**](accept.md) (static) - check if the input is valid JSON
+- [**sax_parse**](sax_parse.md) (static) - generate SAX events
 
 ### JSON Pointer functions
 
@@ -229,14 +229,14 @@ Access to the JSON value
 
 ### Binary formats
 
-- to_cbor - create a CBOR serialization of a given JSON value
-- to_msgpack - create a MessagePack serialization of a given JSON value
-- to_ubjson - create a UBJSON serialization of a given JSON value
-- to_bson - create a BSON serialization of a given JSON value
-- from_cbor - create a JSON value from an input in CBOR format
-- from_msgpack - create a JSON value from an input in MessagePack format
-- from_ubjson - create a JSON value from an input in UBJSON format
-- from_bson - create a JSON value from an input in BSON format
+- [**from_bson**](from_bson.md) (static) - create a JSON value from an input in BSON format
+- [**from_cbor**](from_cbor.md) (static) - create a JSON value from an input in CBOR format
+- [**from_msgpack**](from_msgpack.md) (static) - create a JSON value from an input in MessagePack format
+- [**from_ubjson**](from_ubjson.md) (static) - create a JSON value from an input in UBJSON format
+- [**to_bson**](to_bson.md) (static) - create a BSON serialization of a given JSON value
+- [**to_cbor**](to_cbor.md) (static) - create a CBOR serialization of a given JSON value
+- [**to_msgpack**](to_msgpack.md) (static) - create a MessagePack serialization of a given JSON value
+- [**to_ubjson**](to_ubjson.md) (static) - create a UBJSON serialization of a given JSON value
 
 ## Non-member functions
 

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

@@ -9,11 +9,8 @@ static basic_json parse(InputType&& i,
                         const bool ignore_comments = false);
 
 // (2)
-static basic_json parse(iterator first, iterator last,
-                        const parser_callback_t cb = nullptr,
-                        const bool allow_exceptions = true,
-                        const bool ignore_comments = false);
-static basic_json parse(const_iterator first, const_iterator last,
+template<typename IteratorType>
+static basic_json parse(IteratorType first, IteratorType last,
                         const parser_callback_t cb = nullptr,
                         const bool allow_exceptions = true,
                         const bool ignore_comments = false);
@@ -36,6 +33,9 @@ static basic_json parse(const_iterator first, const_iterator last,
     - 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)

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

+# basic_json::to_bson
+
+```cpp
+// (1)
+static std::vector<std::uint8_t> to_bson(const basic_json& j);
+
+// (2)
+static void to_bson(const basic_json& j, detail::output_adapter<std::uint8_t> o);
+static void to_bson(const basic_json& j, detail::output_adapter<char> o);
+```
+
+BSON (Binary JSON) is a binary format in which zero or more ordered key/value pairs are stored as a single entity (a
+so-called document).
+
+1. Returns a byte vector containing the BSON serialization.
+2. Writes the BSON serialization to an output adapter.
+
+## Parameters
+
+`j` (in)
+:   JSON value to serialize
+
+`o` (in)
+:   output adapter to write serialization to
+
+## Return value
+
+1. BSON serialization as byte vector
+2. /
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of the JSON value `j`.
+
+## Example
+
+??? example
+
+    The example shows the serialization of a JSON value to a byte vector in BSON format.
+     
+    ```cpp
+    --8<-- "examples/to_bson.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_bson.output"
+    ```
+
+## Version history
+
+- Added in version 3.4.0.

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

+# basic_json::to_cbor
+
+```cpp
+// (1)
+static std::vector<std::uint8_t> to_cbor(const basic_json& j);
+
+// (2)
+static void to_cbor(const basic_json& j, detail::output_adapter<std::uint8_t> o);
+static void to_cbor(const basic_json& j, detail::output_adapter<char> o);
+```
+
+Serializes a given JSON value `j` to a byte vector using the CBOR (Concise Binary Object Representation) serialization
+format. CBOR is a binary serialization format which aims to be more compact than JSON itself, yet more efficient to
+parse.
+
+1. Returns a byte vector containing the CBOR serialization.
+2. Writes the CBOR serialization to an output adapter.
+
+## Parameters
+
+`j` (in)
+:   JSON value to serialize
+
+`o` (in)
+:   output adapter to write serialization to
+
+## Return value
+
+1. CBOR serialization as byte vector
+2. /
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of the JSON value `j`.
+
+## Example
+
+??? example
+
+    The example shows the serialization of a JSON value to a byte vector in CBOR format.
+     
+    ```cpp
+    --8<-- "examples/to_cbor.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_cbor.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.9.
+- Compact representation of floating-point numbers added in version 3.8.0.

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

+# basic_json::to_msgpack
+
+```cpp
+// (1)
+static std::vector<std::uint8_t> to_msgpack(const basic_json& j);
+
+// (2)
+static void to_msgpack(const basic_json& j, detail::output_adapter<std::uint8_t> o);
+static void to_msgpack(const basic_json& j, detail::output_adapter<char> o);
+```
+
+Serializes a given JSON value `j` to a byte vector using the MessagePack serialization format. MessagePack is a binary
+serialization format which aims to be more compact than JSON itself, yet more efficient to parse.
+
+1. Returns a byte vector containing the MessagePack serialization.
+2. Writes the MessagePack serialization to an output adapter.
+
+## Parameters
+
+`j` (in)
+:   JSON value to serialize
+
+`o` (in)
+:   output adapter to write serialization to
+
+## Return value
+
+1. MessagePack serialization as byte vector
+2. /
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of the JSON value `j`.
+
+## Example
+
+??? example
+
+    The example shows the serialization of a JSON value to a byte vector in MessagePack format.
+     
+    ```cpp
+    --8<-- "examples/to_msgpack.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_msgpack.output"
+    ```
+
+## Version history
+
+- Added in version 2.0.9.

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

+# basic_json::to_ubjson
+
+```cpp
+// (1)
+static std::vector<std::uint8_t> to_ubjson(const basic_json& j,
+                                           const bool use_size = false,
+                                           const bool use_type = false);
+
+// (2)
+static void to_ubjson(const basic_json& j, detail::output_adapter<std::uint8_t> o,
+                      const bool use_size = false, const bool use_type = false);
+static void to_ubjson(const basic_json& j, detail::output_adapter<char> o,
+                      const bool use_size = false, const bool use_type = false);
+```
+
+Serializes a given JSON value `j` to a byte vector using the UBJSON (Universal Binary JSON) serialization format. UBJSON
+aims to be more compact than JSON itself, yet more efficient to parse.
+
+1. Returns a byte vector containing the UBJSON serialization.
+2. Writes the UBJSON serialization to an output adapter.
+
+## Parameters
+
+`j` (in)
+:   JSON value to serialize
+
+`o` (in)
+:   output adapter to write serialization to
+
+`use_size` (in)
+:   whether to add size annotations to container types; optional, `#!cpp false` by default.
+
+`use_type` (in)
+:   whether to add type annotations to container types (must be combined with `#!cpp use_size = true`); optional,
+    `#!cpp false` by default.
+
+## Return value
+
+1. UBJSON serialization as byte vector
+2. /
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
+## Complexity
+
+Linear in the size of the JSON value `j`.
+
+## Example
+
+??? example
+
+    The example shows the serialization of a JSON value to a byte vector in UBJSON format.
+     
+    ```cpp
+    --8<-- "examples/to_ubjson.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_ubjson.output"
+    ```
+
+## Version history
+
+- Added in version 3.1.0.

doc/mkdocs/mkdocs.yml

@@ -99,6 +99,10 @@ nav:
         - api/basic_json/error_handler_t.md
         - api/basic_json/find.md
         - api/basic_json/flatten.md
+        - api/basic_json/from_bson.md
+        - api/basic_json/from_cbor.md
+        - api/basic_json/from_msgpack.md
+        - api/basic_json/from_ubjson.md
         - api/basic_json/front.md
         - api/basic_json/insert.md
         - api/basic_json/is_array.md
@@ -141,6 +145,10 @@ nav:
         - api/basic_json/sax_parse.md
         - api/basic_json/size.md
         - api/basic_json/string_t.md
+        - api/basic_json/to_bson.md
+        - api/basic_json/to_cbor.md
+        - api/basic_json/to_msgpack.md
+        - api/basic_json/to_ubjson.md
         - api/basic_json/type.md
         - api/basic_json/type_name.md
         - api/basic_json/unflatten.md