From 7c55a91004250ca9353296952b0b27df62c37f2d Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 11 Sep 2021 14:59:21 +0200 Subject: [PATCH] :memo: add documentation --- doc/examples/to_bon8.cpp | 21 +++++++ doc/examples/to_bon8.output | 1 + doc/mkdocs/docs/api/basic_json/index.md | 1 + .../docs/api/basic_json/input_format_t.md | 2 +- doc/mkdocs/docs/api/basic_json/to_bon8.md | 57 +++++++++++++++++++ .../docs/features/binary_formats/bson.md | 2 +- .../docs/features/binary_formats/index.md | 3 + doc/mkdocs/mkdocs.yml | 1 + include/nlohmann/json.hpp | 53 +++++++++++++++++ single_include/nlohmann/json.hpp | 53 +++++++++++++++++ 10 files changed, 192 insertions(+), 2 deletions(-) create mode 100644 doc/examples/to_bon8.cpp create mode 100644 doc/examples/to_bon8.output create mode 100644 doc/mkdocs/docs/api/basic_json/to_bon8.md diff --git a/doc/examples/to_bon8.cpp b/doc/examples/to_bon8.cpp new file mode 100644 index 000000000..2b4e311b4 --- /dev/null +++ b/doc/examples/to_bon8.cpp @@ -0,0 +1,21 @@ +#include +#include +#include + +using json = nlohmann::json; + +int main() +{ + // create a JSON value + json j = R"({"compact": true, "schema": 0})"_json; + + // serialize it to BON8 + std::vector v = json::to_bon8(j); + + // print the vector content + for (auto& byte : v) + { + std::cout << "0x" << std::hex << std::setw(2) << std::setfill('0') << (int)byte << " "; + } + std::cout << std::endl; +} diff --git a/doc/examples/to_bon8.output b/doc/examples/to_bon8.output new file mode 100644 index 000000000..8cce605dd --- /dev/null +++ b/doc/examples/to_bon8.output @@ -0,0 +1 @@ +0x88 0x63 0x6f 0x6d 0x70 0x61 0x63 0x74 0xf9 0x73 0x63 0x68 0x65 0x6d 0x61 0x90 diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index e8841e850..517a207ca 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -230,6 +230,7 @@ Access to the JSON value - [**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_bon8**](to_bon8.md) (static) - create a BON8 serialization of a given JSON value - [**to_bson**](to_bson.md) (static) - create a BSON serialization of a given JSON value - [**to_cbor**](to_cbor.md) (static) - create a CBOR serialization of a given JSON value - [**to_msgpack**](to_msgpack.md) (static) - create a MessagePack serialization of a given JSON value diff --git a/doc/mkdocs/docs/api/basic_json/input_format_t.md b/doc/mkdocs/docs/api/basic_json/input_format_t.md index 783085d8e..b12ef4641 100644 --- a/doc/mkdocs/docs/api/basic_json/input_format_t.md +++ b/doc/mkdocs/docs/api/basic_json/input_format_t.md @@ -25,7 +25,7 @@ ubjson : UBJSON (Universal Binary JSON) bson -: BSON (Bin­ary JSON) +: BSON (Binary JSON) ## Version history diff --git a/doc/mkdocs/docs/api/basic_json/to_bon8.md b/doc/mkdocs/docs/api/basic_json/to_bon8.md new file mode 100644 index 000000000..277fd3151 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/to_bon8.md @@ -0,0 +1,57 @@ +# basic_json::to_bon8 + +```cpp +// (1) +static std::vector to_bon8(const basic_json& j); + +// (2) +static void to_bon8(const basic_json& j, detail::output_adapter o); +static void to_bon8(const basic_json& j, detail::output_adapter o); +``` + +Serializes a given JSON value `j` to a byte vector using the BON8 serialization format. BON8 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 BON8 serialization. +2. Writes the BON8 serialization to an output adapter. + +## Parameters + +`j` (in) +: JSON value to serialize + +`o` (in) +: output adapter to write serialization to + +## Return value + +1. BON8 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 BON8 format. + + ```cpp + --8<-- "examples/to_bon8.cpp" + ``` + + Output: + + ```json + --8<-- "examples/to_bon8.output" + ``` + +## Version history + +- Added in version 3.11.0. diff --git a/doc/mkdocs/docs/features/binary_formats/bson.md b/doc/mkdocs/docs/features/binary_formats/bson.md index 0ed2a786e..e8b06f84b 100644 --- a/doc/mkdocs/docs/features/binary_formats/bson.md +++ b/doc/mkdocs/docs/features/binary_formats/bson.md @@ -1,6 +1,6 @@ # BSON -BSON, short for Bin­ary JSON, is a bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. Like JSON, BSON sup­ports the em­bed­ding of doc­u­ments and ar­rays with­in oth­er doc­u­ments and ar­rays. BSON also con­tains ex­ten­sions that al­low rep­res­ent­a­tion of data types that are not part of the JSON spec. For ex­ample, BSON has a Date type and a BinData type. +BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type. !!! abstract "References" diff --git a/doc/mkdocs/docs/features/binary_formats/index.md b/doc/mkdocs/docs/features/binary_formats/index.md index 279009d11..bfa18c3c6 100644 --- a/doc/mkdocs/docs/features/binary_formats/index.md +++ b/doc/mkdocs/docs/features/binary_formats/index.md @@ -6,6 +6,7 @@ Though JSON is a ubiquitous data format, it is not a very compact format suitabl - [CBOR](cbor.md) (Concise Binary Object Representation), - [MessagePack](messagepack.md), and - [UBJSON](ubjson.md) (Universal Binary JSON) +- BON8 to efficiently encode JSON values to byte vectors and to decode such vectors. @@ -19,6 +20,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors. | CBOR | complete | incomplete, but all JSON types are supported | | MessagePack | complete | complete | | UBJSON | complete | complete | +| BON8 | complete | not yet implemented | ### Binary values @@ -28,6 +30,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors. | CBOR | supported | supported | | MessagePack | supported | supported | | UBJSON | not supported | not supported | +| BON8 | not supported | not supported | See [binary values](../binary_values.md) for more information. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 7aa6e2c5d..cd12656c3 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -168,6 +168,7 @@ nav: - api/basic_json/sax_parse.md - api/basic_json/size.md - api/basic_json/string_t.md + - api/basic_json/to_bon8.md - api/basic_json/to_bson.md - api/basic_json/to_cbor.md - api/basic_json/to_msgpack.md diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 650730509..ff57fbeaf 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -7303,6 +7303,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the related UBJSON format + @sa see @ref to_bson(const basic_json&) for the related BSON format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format @since version 2.0.9; compact representation of floating-point numbers since version 3.8.0 @@ -7399,6 +7401,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @sa see @ref to_cbor(const basic_json& for the related CBOR format @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the related UBJSON format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format @since version 2.0.9 */ @@ -7502,6 +7505,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec analogous deserialization @sa see @ref to_cbor(const basic_json& for the related CBOR format @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format @since version 3.1.0 */ @@ -7582,6 +7586,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec related UBJSON format @sa see @ref to_cbor(const basic_json&) for the related CBOR format @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format */ static std::vector to_bson(const basic_json& j) { @@ -7611,6 +7616,44 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec binary_writer(o).write_bson(j); } + /*! + @brief Serializes the given JSON object `j` to BON8 and returns a vector + containing the corresponding BON8-representation. + + BON8 is a binary format that encodes JSON values using those byte sequences + that would form invalid UTF-8 strings. As a result, strings do not need to + be re-encoded. + + @note The mapping is **complete** in the sense that any JSON value type + can be converted to a BON8 value. + + @note The following values can **not** be converted to a BON8 value: + - integers larger than 9223372036854775807 + + @throw out_of_range.407 if `j.is_number_unsigned() && j.get() > 9223372036854775807` + + @note Any BON8 output created via @ref to_bon8 can be successfully parsed + by @ref from_bon8. + + @param[in] j JSON value to serialize + @return BON8 serialization as byte vector + + @complexity Linear in the size of the JSON value @a j. + + @liveexample{The example shows the serialization of a JSON value to a byte + vector in BON8 format.,to_bon8} + + @sa https://github.com/ttauri-project/ttauri/blob/main/docs/BON8.md + @sa see @ref from_bon8(detail::input_adapter&&, const bool strict) for the + analogous deserialization + @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the + related UBJSON format + @sa see @ref to_cbor(const basic_json&) for the related CBOR format + @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format + @sa see @ref to_bson(const basic_json&) for the related BSON format + + @since version 3.11.0 + */ static std::vector to_bon8(const basic_json& j) { std::vector result; @@ -7618,11 +7661,21 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return result; } + /*! + @brief Serializes the given JSON object `j` to BON8 and forwards the + corresponding BON8-representation to the given output_adapter `o`. + @param j The JSON object to convert to BON8. + @param o The output adapter that receives the binary BON8 representation. + @sa see @ref to_bon8(const basic_json&) + */ static void to_bon8(const basic_json& j, detail::output_adapter o) { binary_writer(o).write_bon8(j); } + /*! + @copydoc to_bon8(const basic_json&, detail::output_adapter) + */ static void to_bon8(const basic_json& j, detail::output_adapter o) { binary_writer(o).write_bon8(j); diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 1c13057e1..546bc5e95 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -25027,6 +25027,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the related UBJSON format + @sa see @ref to_bson(const basic_json&) for the related BSON format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format @since version 2.0.9; compact representation of floating-point numbers since version 3.8.0 @@ -25123,6 +25125,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @sa see @ref to_cbor(const basic_json& for the related CBOR format @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the related UBJSON format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format @since version 2.0.9 */ @@ -25226,6 +25229,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec analogous deserialization @sa see @ref to_cbor(const basic_json& for the related CBOR format @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format @since version 3.1.0 */ @@ -25306,6 +25310,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec related UBJSON format @sa see @ref to_cbor(const basic_json&) for the related CBOR format @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format + @sa see @ref to_bon8(const basic_json&) for the related BON8 format */ static std::vector to_bson(const basic_json& j) { @@ -25335,6 +25340,44 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec binary_writer(o).write_bson(j); } + /*! + @brief Serializes the given JSON object `j` to BON8 and returns a vector + containing the corresponding BON8-representation. + + BON8 is a binary format that encodes JSON values using those byte sequences + that would form invalid UTF-8 strings. As a result, strings do not need to + be re-encoded. + + @note The mapping is **complete** in the sense that any JSON value type + can be converted to a BON8 value. + + @note The following values can **not** be converted to a BON8 value: + - integers larger than 9223372036854775807 + + @throw out_of_range.407 if `j.is_number_unsigned() && j.get() > 9223372036854775807` + + @note Any BON8 output created via @ref to_bon8 can be successfully parsed + by @ref from_bon8. + + @param[in] j JSON value to serialize + @return BON8 serialization as byte vector + + @complexity Linear in the size of the JSON value @a j. + + @liveexample{The example shows the serialization of a JSON value to a byte + vector in BON8 format.,to_bon8} + + @sa https://github.com/ttauri-project/ttauri/blob/main/docs/BON8.md + @sa see @ref from_bon8(detail::input_adapter&&, const bool strict) for the + analogous deserialization + @sa see @ref to_ubjson(const basic_json&, const bool, const bool) for the + related UBJSON format + @sa see @ref to_cbor(const basic_json&) for the related CBOR format + @sa see @ref to_msgpack(const basic_json&) for the related MessagePack format + @sa see @ref to_bson(const basic_json&) for the related BSON format + + @since version 3.11.0 + */ static std::vector to_bon8(const basic_json& j) { std::vector result; @@ -25342,11 +25385,21 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return result; } + /*! + @brief Serializes the given JSON object `j` to BON8 and forwards the + corresponding BON8-representation to the given output_adapter `o`. + @param j The JSON object to convert to BON8. + @param o The output adapter that receives the binary BON8 representation. + @sa see @ref to_bon8(const basic_json&) + */ static void to_bon8(const basic_json& j, detail::output_adapter o) { binary_writer(o).write_bon8(j); } + /*! + @copydoc to_bon8(const basic_json&, detail::output_adapter) + */ static void to_bon8(const basic_json& j, detail::output_adapter o) { binary_writer(o).write_bon8(j);