From 523f7c2c9d89f06ff47db9066e4a2af5a49f5a8b Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sun, 8 Aug 2021 13:24:17 +0200 Subject: [PATCH] :bulb: update documentation --- doc/mkdocs/docs/api/basic_json/binary_t.md | 2 +- .../docs/api/basic_json/cbor_tag_handler_t.md | 8 ++- .../docs/features/binary_formats/cbor.md | 4 +- .../docs/features/binary_formats/index.md | 2 +- doc/mkdocs/docs/features/binary_values.md | 9 +-- .../nlohmann/byte_container_with_subtype.hpp | 7 ++- include/nlohmann/detail/input/parser.hpp | 2 +- include/nlohmann/detail/output/serializer.hpp | 2 +- include/nlohmann/json.hpp | 48 ++++++++------- single_include/nlohmann/json.hpp | 59 ++++++++++--------- 10 files changed, 80 insertions(+), 63 deletions(-) diff --git a/doc/mkdocs/docs/api/basic_json/binary_t.md b/doc/mkdocs/docs/api/basic_json/binary_t.md index 2d6cd574e..0dd859dcc 100644 --- a/doc/mkdocs/docs/api/basic_json/binary_t.md +++ b/doc/mkdocs/docs/api/basic_json/binary_t.md @@ -64,4 +64,4 @@ type `#!cpp binary_t*` must be dereferenced. ## Version history -- Added in version 3.8.0. +- Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.9.2. diff --git a/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md b/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md index ea417de55..928115718 100644 --- a/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md +++ b/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md @@ -4,7 +4,8 @@ enum class cbor_tag_handler_t { error, - ignore + ignore, + store }; ``` @@ -16,6 +17,9 @@ error ignore : ignore tags +store +: store tagged values as binary container with subtype (for bytes 0xd8..0xdb) + ## Version history -- Added in version 3.9.0. +- Added in version 3.9.0. Added value `store` in 3.9.2. diff --git a/doc/mkdocs/docs/features/binary_formats/cbor.md b/doc/mkdocs/docs/features/binary_formats/cbor.md index daa29be87..a7a8fc002 100644 --- a/doc/mkdocs/docs/features/binary_formats/cbor.md +++ b/doc/mkdocs/docs/features/binary_formats/cbor.md @@ -55,6 +55,8 @@ binary | *size*: 256..65535 | byte string (2 by binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B +Binary values with subtype are mapped to tagged values (0xD8..0xDB) depending on the subtype, followed by a byte string, +see "binary" cells in the table above. !!! success "Complete mapping" @@ -162,7 +164,7 @@ Double-Precision Float | number_float | 0xFB !!! warning "Tagged items" - Tagged items will throw a parse error by default. However, they can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`. + Tagged items will throw a parse error by default. They can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`. They can be stored by passing `cbor_tag_handler_t::store` to function `from_cbor`. ??? example diff --git a/doc/mkdocs/docs/features/binary_formats/index.md b/doc/mkdocs/docs/features/binary_formats/index.md index 55f963c2d..279009d11 100644 --- a/doc/mkdocs/docs/features/binary_formats/index.md +++ b/doc/mkdocs/docs/features/binary_formats/index.md @@ -25,7 +25,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors. | Format | Binary values | Binary subtypes | | ----------- | ------------- | --------------- | | BSON | supported | supported | -| CBOR | supported | not supported | +| CBOR | supported | supported | | MessagePack | supported | supported | | UBJSON | not supported | not supported | diff --git a/doc/mkdocs/docs/features/binary_values.md b/doc/mkdocs/docs/features/binary_values.md index 4716aac7e..66e721688 100644 --- a/doc/mkdocs/docs/features/binary_values.md +++ b/doc/mkdocs/docs/features/binary_values.md @@ -9,10 +9,10 @@ JSON itself does not have a binary value. As such, binary values are an extensio ```plantuml class json::binary_t { -- setters -- - +void set_subtype(std::uint8_t subtype) + +void set_subtype(std::uint64_t subtype) +void clear_subtype() -- getters -- - +std::uint8_t subtype() const + +std::uint64_t subtype() const +bool has_subtype() const } @@ -68,7 +68,7 @@ j.get_binary().has_subtype(); // returns true j.get_binary().size(); // returns 4 ``` -For convencience, binary JSON values can be constructed via `json::binary`: +For convenience, binary JSON values can be constructed via `json::binary`: ```cpp auto j2 = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 23); @@ -76,6 +76,7 @@ auto j3 = json::binary({0xCA, 0xFE, 0xBA, 0xBE}); j2 == j; // returns true j3.get_binary().has_subtype(); // returns false +j3.get_binary().subtype(); // returns std::uint64_t(-1) as j3 has no subtype ``` @@ -184,7 +185,7 @@ JSON does not have a binary type, and this library does not introduce a new type 0xCA 0xFE 0xBA 0xBE // content ``` - Note that the subtype is serialized as tag. However, parsing tagged values yield a parse error unless `json::cbor_tag_handler_t::ignore` is passed to `json::from_cbor`. + Note that the subtype is serialized as tag. However, parsing tagged values yield a parse error unless `json::cbor_tag_handler_t::ignore` or `json::cbor_tag_handler_t::store` is passed to `json::from_cbor`. ```json { diff --git a/include/nlohmann/byte_container_with_subtype.hpp b/include/nlohmann/byte_container_with_subtype.hpp index ffbacdc6d..0c117bff5 100644 --- a/include/nlohmann/byte_container_with_subtype.hpp +++ b/include/nlohmann/byte_container_with_subtype.hpp @@ -1,6 +1,6 @@ #pragma once -#include // uint8_t +#include // uint8_t, uint64_t #include // tie #include // move @@ -18,7 +18,7 @@ order to override the binary type. @tparam BinaryType container to store bytes (`std::vector` by default) -@since version 3.8.0 +@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.9.2. */ template class byte_container_with_subtype : public BinaryType @@ -107,7 +107,8 @@ class byte_container_with_subtype : public BinaryType @sa see @ref has_subtype() -- returns whether or not the binary value has a subtype - @since version 3.8.0 + @since version 3.8.0; fixed return value to properly return + subtype_type(-1) as documented in version 3.9.2 */ constexpr subtype_type subtype() const noexcept { diff --git a/include/nlohmann/detail/input/parser.hpp b/include/nlohmann/detail/input/parser.hpp index 90f232765..a1096c733 100644 --- a/include/nlohmann/detail/input/parser.hpp +++ b/include/nlohmann/detail/input/parser.hpp @@ -23,7 +23,7 @@ namespace detail // parser // //////////// -enum class parse_event_t : uint8_t +enum class parse_event_t : std::uint8_t { /// the parser read `{` and started to process a JSON object object_start, diff --git a/include/nlohmann/detail/output/serializer.hpp b/include/nlohmann/detail/output/serializer.hpp index 440993459..b9f53477a 100644 --- a/include/nlohmann/detail/output/serializer.hpp +++ b/include/nlohmann/detail/output/serializer.hpp @@ -389,7 +389,7 @@ class serializer for (std::size_t i = 0; i < s.size(); ++i) { - const auto byte = static_cast(s[i]); + const auto byte = static_cast(s[i]); switch (decode(state, codepoint, byte)) { diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 43dc1d9d8..4ac2e7531 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -902,8 +902,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec #### Notes on subtypes - CBOR - - Binary values are represented as byte strings. No subtypes are - supported and will be ignored when CBOR is written. + - Binary values are represented as byte strings. Subtypes are serialized + as tagged values. - 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) @@ -1497,7 +1497,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @ref number_float_t, and all convertible number types such as `int`, `size_t`, `int64_t`, `float` or `double` can be used. - **boolean**: @ref boolean_t / `bool` can be used. - - **binary**: @ref binary_t / `std::vector` may be used, + - **binary**: @ref binary_t / `std::vector` may be used, unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with `const char*` will be directed to the string constructor instead. This is both @@ -7187,6 +7187,10 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B + Binary values with subtype are mapped to tagged values (0xD8..0xDB) + depending on the subtype, followed by a byte string, see "binary" cells + in the table above. + @note The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. @@ -7227,16 +7231,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @since version 2.0.9; compact representation of floating-point numbers since version 3.8.0 */ - static std::vector to_cbor(const basic_json& j) + static std::vector to_cbor(const basic_json& j) { - std::vector result; + std::vector result; to_cbor(j, result); return result; } - static void to_cbor(const basic_json& j, detail::output_adapter o) + static void to_cbor(const basic_json& j, detail::output_adapter o) { - binary_writer(o).write_cbor(j); + binary_writer(o).write_cbor(j); } static void to_cbor(const basic_json& j, detail::output_adapter o) @@ -7322,16 +7326,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @since version 2.0.9 */ - static std::vector to_msgpack(const basic_json& j) + static std::vector to_msgpack(const basic_json& j) { - std::vector result; + std::vector result; to_msgpack(j, result); return result; } - static void to_msgpack(const basic_json& j, detail::output_adapter o) + static void to_msgpack(const basic_json& j, detail::output_adapter o) { - binary_writer(o).write_msgpack(j); + binary_writer(o).write_msgpack(j); } static void to_msgpack(const basic_json& j, detail::output_adapter o) @@ -7425,19 +7429,19 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @since version 3.1.0 */ - static std::vector to_ubjson(const basic_json& j, - const bool use_size = false, - const bool use_type = false) + static std::vector to_ubjson(const basic_json& j, + const bool use_size = false, + const bool use_type = false) { - std::vector result; + std::vector result; to_ubjson(j, result, use_size, use_type); return result; } - static void to_ubjson(const basic_json& j, detail::output_adapter o, + static void to_ubjson(const basic_json& j, detail::output_adapter o, const bool use_size = false, const bool use_type = false) { - binary_writer(o).write_ubjson(j, use_size, use_type); + binary_writer(o).write_ubjson(j, use_size, use_type); } static void to_ubjson(const basic_json& j, detail::output_adapter o, @@ -7503,9 +7507,9 @@ 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_msgpack(const basic_json&) for the related MessagePack format */ - static std::vector to_bson(const basic_json& j) + static std::vector to_bson(const basic_json& j) { - std::vector result; + std::vector result; to_bson(j, result); return result; } @@ -7518,13 +7522,13 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @pre The input `j` shall be an object: `j.is_object() == true` @sa see @ref to_bson(const basic_json&) */ - static void to_bson(const basic_json& j, detail::output_adapter o) + static void to_bson(const basic_json& j, detail::output_adapter o) { - binary_writer(o).write_bson(j); + binary_writer(o).write_bson(j); } /*! - @copydoc to_bson(const basic_json&, detail::output_adapter) + @copydoc to_bson(const basic_json&, detail::output_adapter) */ static void to_bson(const basic_json& j, detail::output_adapter o) { diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 5ec21b915..1e323e0c5 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -4956,7 +4956,7 @@ struct adl_serializer // #include -#include // uint8_t +#include // uint8_t, uint64_t #include // tie #include // move @@ -4974,7 +4974,7 @@ order to override the binary type. @tparam BinaryType container to store bytes (`std::vector` by default) -@since version 3.8.0 +@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.9.2. */ template class byte_container_with_subtype : public BinaryType @@ -5063,7 +5063,8 @@ class byte_container_with_subtype : public BinaryType @sa see @ref has_subtype() -- returns whether or not the binary value has a subtype - @since version 3.8.0 + @since version 3.8.0; fixed return value to properly return + subtype_type(-1) as documented in version 3.9.2 */ constexpr subtype_type subtype() const noexcept { @@ -10783,7 +10784,7 @@ namespace detail // parser // //////////// -enum class parse_event_t : uint8_t +enum class parse_event_t : std::uint8_t { /// the parser read `{` and started to process a JSON object object_start, @@ -16468,7 +16469,7 @@ class serializer for (std::size_t i = 0; i < s.size(); ++i) { - const auto byte = static_cast(s[i]); + const auto byte = static_cast(s[i]); switch (decode(state, codepoint, byte)) { @@ -18057,8 +18058,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec #### Notes on subtypes - CBOR - - Binary values are represented as byte strings. No subtypes are - supported and will be ignored when CBOR is written. + - Binary values are represented as byte strings. Subtypes are serialized + as tagged values. - 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) @@ -18652,7 +18653,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @ref number_float_t, and all convertible number types such as `int`, `size_t`, `int64_t`, `float` or `double` can be used. - **boolean**: @ref boolean_t / `bool` can be used. - - **binary**: @ref binary_t / `std::vector` may be used, + - **binary**: @ref binary_t / `std::vector` may be used, unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with `const char*` will be directed to the string constructor instead. This is both @@ -24342,6 +24343,10 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B + Binary values with subtype are mapped to tagged values (0xD8..0xDB) + depending on the subtype, followed by a byte string, see "binary" cells + in the table above. + @note The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. @@ -24382,16 +24387,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @since version 2.0.9; compact representation of floating-point numbers since version 3.8.0 */ - static std::vector to_cbor(const basic_json& j) + static std::vector to_cbor(const basic_json& j) { - std::vector result; + std::vector result; to_cbor(j, result); return result; } - static void to_cbor(const basic_json& j, detail::output_adapter o) + static void to_cbor(const basic_json& j, detail::output_adapter o) { - binary_writer(o).write_cbor(j); + binary_writer(o).write_cbor(j); } static void to_cbor(const basic_json& j, detail::output_adapter o) @@ -24477,16 +24482,16 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @since version 2.0.9 */ - static std::vector to_msgpack(const basic_json& j) + static std::vector to_msgpack(const basic_json& j) { - std::vector result; + std::vector result; to_msgpack(j, result); return result; } - static void to_msgpack(const basic_json& j, detail::output_adapter o) + static void to_msgpack(const basic_json& j, detail::output_adapter o) { - binary_writer(o).write_msgpack(j); + binary_writer(o).write_msgpack(j); } static void to_msgpack(const basic_json& j, detail::output_adapter o) @@ -24580,19 +24585,19 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @since version 3.1.0 */ - static std::vector to_ubjson(const basic_json& j, - const bool use_size = false, - const bool use_type = false) + static std::vector to_ubjson(const basic_json& j, + const bool use_size = false, + const bool use_type = false) { - std::vector result; + std::vector result; to_ubjson(j, result, use_size, use_type); return result; } - static void to_ubjson(const basic_json& j, detail::output_adapter o, + static void to_ubjson(const basic_json& j, detail::output_adapter o, const bool use_size = false, const bool use_type = false) { - binary_writer(o).write_ubjson(j, use_size, use_type); + binary_writer(o).write_ubjson(j, use_size, use_type); } static void to_ubjson(const basic_json& j, detail::output_adapter o, @@ -24658,9 +24663,9 @@ 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_msgpack(const basic_json&) for the related MessagePack format */ - static std::vector to_bson(const basic_json& j) + static std::vector to_bson(const basic_json& j) { - std::vector result; + std::vector result; to_bson(j, result); return result; } @@ -24673,13 +24678,13 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @pre The input `j` shall be an object: `j.is_object() == true` @sa see @ref to_bson(const basic_json&) */ - static void to_bson(const basic_json& j, detail::output_adapter o) + static void to_bson(const basic_json& j, detail::output_adapter o) { - binary_writer(o).write_bson(j); + binary_writer(o).write_bson(j); } /*! - @copydoc to_bson(const basic_json&, detail::output_adapter) + @copydoc to_bson(const basic_json&, detail::output_adapter) */ static void to_bson(const basic_json& j, detail::output_adapter o) {