From 5534a77221a624427561c14dea63c9e08537308e Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 4 Nov 2021 14:26:05 +0100 Subject: [PATCH] :fire: consolidate documentation --- doc/mkdocs/docs/api/basic_json/binary_t.md | 9 +++- .../docs/api/byte_container_with_subtype.md | 36 ++++++++++++++++ doc/mkdocs/docs/api/ordered_map.md | 42 +++++++++++++++++++ doc/mkdocs/mkdocs.yml | 1 + include/nlohmann/adl_serializer.hpp | 38 +++-------------- single_include/nlohmann/json.hpp | 38 +++-------------- 6 files changed, 98 insertions(+), 66 deletions(-) create mode 100644 doc/mkdocs/docs/api/byte_container_with_subtype.md diff --git a/doc/mkdocs/docs/api/basic_json/binary_t.md b/doc/mkdocs/docs/api/basic_json/binary_t.md index f7da1ece0..dedcfb207 100644 --- a/doc/mkdocs/docs/api/basic_json/binary_t.md +++ b/doc/mkdocs/docs/api/basic_json/binary_t.md @@ -8,9 +8,10 @@ This type is a type designed to carry binary data that appears in various serial 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 +Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_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). +incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType` +via the helper type [byte_container_with_subtype](../byte_container_with_subtype.md). [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 @@ -62,6 +63,10 @@ type `#!cpp binary_t*` must be dereferenced. - 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. +## See also + +- [byte_container_with_subtype](../byte_container_with_subtype.md) + ## Version history - Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype.md new file mode 100644 index 000000000..f2dd12184 --- /dev/null +++ b/doc/mkdocs/docs/api/byte_container_with_subtype.md @@ -0,0 +1,36 @@ +# byte_container_with_subtype + +```cpp +template +class byte_container_with_subtype : public BinaryType +``` + +This type extends the template parameter `BinaryType` provided to [`basic_json`](basic_json/index.md) with a subtype +used by BSON and MessagePack. This type exists so that the user does not have to specify a type themselves with a +specific naming scheme in order to override the binary type. + +## Template parameters + +`BinaryType` +: container to store bytes (`#!cpp std::vector` by default) + +## Member types + +- **container_type** - the type of the underlying container (`BinaryType`) +- **subtype_type** - the type of the subtype (`#!cpp std::uint64_t`) + +## Member functions + +- (constructor) +- (destructor) +- **operator==** - comparison: equal +- **operator!=** - comparison: not equal +- **set_subtype** - sets the binary subtype +- **subtype** - return the binary subtype +- **has_subtype** - return whether the value has a subtype +- **clear_subtype** - clears the binary subtype + +## Version history + +- Added in version 3.8.0. +- Changed type of subtypes to `#!cpp std::uint64_t` in 3.10.0. diff --git a/doc/mkdocs/docs/api/ordered_map.md b/doc/mkdocs/docs/api/ordered_map.md index 1a99b636f..423821c1c 100644 --- a/doc/mkdocs/docs/api/ordered_map.md +++ b/doc/mkdocs/docs/api/ordered_map.md @@ -5,3 +5,45 @@ template, class Allocator = std::allocator>> struct ordered_map : std::vector, Allocator>; ``` + +A minimal map-like container that preserves insertion order for use within `nlohmann::basic_json`. + +## Template parameters + +`Key` +: key type + +`T` +: mapped type + +`IgnoredLess` +: comparison function (ignored and only added to ensure compatibility with `std::map`) + +`Allocator` +: allocator type + +## Member types + +- **key_type** - key type (`Key`) +- **mapped_type** - mapped type (`T`) +- **Container** - base container type (`#!cpp std::vector, Allocator>`) +- **iterator** +- **const_iterator** +- **size_type** +- **value_type** + +## Member functions + +- (constructor) +- (destructor) +- **emplace** +- **operator\[\]** +- **at** +- **erase** +- **count** +- **find** +- **insert** + +## Version history + +- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md). diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 22c5a4f85..b58138ce5 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -181,6 +181,7 @@ nav: - api/basic_json/update.md - api/basic_json/value.md - api/basic_json/value_t.md + - api/byte_container_with_subtype.md - adl_serializer: - api/adl_serializer/index.md - api/adl_serializer/from_json.md diff --git a/include/nlohmann/adl_serializer.hpp b/include/nlohmann/adl_serializer.hpp index f967612db..2fb1490f7 100644 --- a/include/nlohmann/adl_serializer.hpp +++ b/include/nlohmann/adl_serializer.hpp @@ -14,17 +14,8 @@ namespace nlohmann template struct adl_serializer { - /*! - @brief convert a JSON value to any value type - - This function is usually called by the `get()` function of the - @ref basic_json class (either explicit or via conversion operators). - - @note This function is chosen for default-constructible value types. - - @param[in] j JSON value to read from - @param[in,out] val value to write to - */ + /// @brief convert a JSON value to any value type + /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/ template static auto from_json(BasicJsonType && j, TargetType& val) noexcept( noexcept(::nlohmann::from_json(std::forward(j), val))) @@ -33,18 +24,8 @@ struct adl_serializer ::nlohmann::from_json(std::forward(j), val); } - /*! - @brief convert a JSON value to any value type - - This function is usually called by the `get()` function of the - @ref basic_json class (either explicit or via conversion operators). - - @note This function is chosen for value types which are not default-constructible. - - @param[in] j JSON value to read from - - @return copy of the JSON value, converted to @a ValueType - */ + /// @brief convert a JSON value to any value type + /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/ template static auto from_json(BasicJsonType && j) noexcept( noexcept(::nlohmann::from_json(std::forward(j), detail::identity_tag {}))) @@ -53,15 +34,8 @@ struct adl_serializer return ::nlohmann::from_json(std::forward(j), detail::identity_tag {}); } - /*! - @brief convert any value type to a JSON value - - This function is usually called by the constructors of the @ref basic_json - class. - - @param[in,out] j JSON value to write to - @param[in] val value to read from - */ + /// @brief convert any value type to a JSON value + /// @sa https://json.nlohmann.me/api/adl_serializer/to_json/ template static auto to_json(BasicJsonType& j, TargetType && val) noexcept( noexcept(::nlohmann::to_json(j, std::forward(val)))) diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 21727c2e4..39d9903d4 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -5041,17 +5041,8 @@ namespace nlohmann template struct adl_serializer { - /*! - @brief convert a JSON value to any value type - - This function is usually called by the `get()` function of the - @ref basic_json class (either explicit or via conversion operators). - - @note This function is chosen for default-constructible value types. - - @param[in] j JSON value to read from - @param[in,out] val value to write to - */ + /// @brief convert a JSON value to any value type + /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/ template static auto from_json(BasicJsonType && j, TargetType& val) noexcept( noexcept(::nlohmann::from_json(std::forward(j), val))) @@ -5060,18 +5051,8 @@ struct adl_serializer ::nlohmann::from_json(std::forward(j), val); } - /*! - @brief convert a JSON value to any value type - - This function is usually called by the `get()` function of the - @ref basic_json class (either explicit or via conversion operators). - - @note This function is chosen for value types which are not default-constructible. - - @param[in] j JSON value to read from - - @return copy of the JSON value, converted to @a ValueType - */ + /// @brief convert a JSON value to any value type + /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/ template static auto from_json(BasicJsonType && j) noexcept( noexcept(::nlohmann::from_json(std::forward(j), detail::identity_tag {}))) @@ -5080,15 +5061,8 @@ struct adl_serializer return ::nlohmann::from_json(std::forward(j), detail::identity_tag {}); } - /*! - @brief convert any value type to a JSON value - - This function is usually called by the constructors of the @ref basic_json - class. - - @param[in,out] j JSON value to write to - @param[in] val value to read from - */ + /// @brief convert any value type to a JSON value + /// @sa https://json.nlohmann.me/api/adl_serializer/to_json/ template static auto to_json(BasicJsonType& j, TargetType && val) noexcept( noexcept(::nlohmann::to_json(j, std::forward(val))))