diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index 4ac547a0b..e3dae4e43 100644 --- a/doc/docset/docSet.sql +++ b/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'); diff --git a/doc/mkdocs/docs/api/basic_json/accept.md b/doc/mkdocs/docs/api/basic_json/accept.md index e90a3bb17..b18c5391a 100644 --- a/doc/mkdocs/docs/api/basic_json/accept.md +++ b/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 +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) diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md new file mode 100644 index 000000000..bf218cd91 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/from_bson.md @@ -0,0 +1,83 @@ +# basic_json::from_bson + +```cpp +// (1) +template +static basic_json from_bson(InputType&& i, + const bool strict = true, + const bool allow_exceptions = true); +// (2) +template +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. diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md new file mode 100644 index 000000000..afe91a1ca --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md @@ -0,0 +1,93 @@ +# basic_json::from_cbor + +```cpp +// (1) +template +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 +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. diff --git a/doc/mkdocs/docs/api/basic_json/from_msgpack.md b/doc/mkdocs/docs/api/basic_json/from_msgpack.md new file mode 100644 index 000000000..18649c14a --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/from_msgpack.md @@ -0,0 +1,86 @@ +# basic_json::from_msgpack + +```cpp +// (1) +template +static basic_json from_msgpack(InputType&& i, + const bool strict = true, + const bool allow_exceptions = true); +// (2) +template +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. diff --git a/doc/mkdocs/docs/api/basic_json/from_ubjson.md b/doc/mkdocs/docs/api/basic_json/from_ubjson.md new file mode 100644 index 000000000..91c22f058 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/from_ubjson.md @@ -0,0 +1,84 @@ +# basic_json::from_ubjson + +```cpp +// (1) +template +static basic_json from_ubjson(InputType&& i, + const bool strict = true, + const bool allow_exceptions = true); +// (2) +template +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. diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 145b04836..806289399 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/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 diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md index 1c2c050fb..11e420d41 100644 --- a/doc/mkdocs/docs/api/basic_json/parse.md +++ b/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 +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) diff --git a/doc/mkdocs/docs/api/basic_json/to_bson.md b/doc/mkdocs/docs/api/basic_json/to_bson.md new file mode 100644 index 000000000..747a4aa31 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/to_bson.md @@ -0,0 +1,57 @@ +# basic_json::to_bson + +```cpp +// (1) +static std::vector to_bson(const basic_json& j); + +// (2) +static void to_bson(const basic_json& j, detail::output_adapter o); +static void to_bson(const basic_json& j, detail::output_adapter 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. diff --git a/doc/mkdocs/docs/api/basic_json/to_cbor.md b/doc/mkdocs/docs/api/basic_json/to_cbor.md new file mode 100644 index 000000000..fd0eaa1fe --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/to_cbor.md @@ -0,0 +1,59 @@ +# basic_json::to_cbor + +```cpp +// (1) +static std::vector to_cbor(const basic_json& j); + +// (2) +static void to_cbor(const basic_json& j, detail::output_adapter o); +static void to_cbor(const basic_json& j, detail::output_adapter 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. diff --git a/doc/mkdocs/docs/api/basic_json/to_msgpack.md b/doc/mkdocs/docs/api/basic_json/to_msgpack.md new file mode 100644 index 000000000..1d438d7cd --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/to_msgpack.md @@ -0,0 +1,57 @@ +# basic_json::to_msgpack + +```cpp +// (1) +static std::vector to_msgpack(const basic_json& j); + +// (2) +static void to_msgpack(const basic_json& j, detail::output_adapter o); +static void to_msgpack(const basic_json& j, detail::output_adapter 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. diff --git a/doc/mkdocs/docs/api/basic_json/to_ubjson.md b/doc/mkdocs/docs/api/basic_json/to_ubjson.md new file mode 100644 index 000000000..a12a62555 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/to_ubjson.md @@ -0,0 +1,68 @@ +# basic_json::to_ubjson + +```cpp +// (1) +static std::vector 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 o, + const bool use_size = false, const bool use_type = false); +static void to_ubjson(const basic_json& j, detail::output_adapter 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. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 35c75265d..1fc298640 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/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