diff --git a/doc/mkdocs/docs/api/basic_json/binary_t.md b/doc/mkdocs/docs/api/basic_json/binary_t.md index 469f99f61..1879fb0d2 100644 --- a/doc/mkdocs/docs/api/basic_json/binary_t.md +++ b/doc/mkdocs/docs/api/basic_json/binary_t.md @@ -11,7 +11,7 @@ compatibility with these binary types. As such, it is simply defined as an order 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). The subtype is added to `BinaryType` -via the helper type [byte_container_with_subtype](../byte_container_with_subtype.md). +via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.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 @@ -65,7 +65,7 @@ type `#!cpp binary_t*` must be dereferenced. ## See also -- [byte_container_with_subtype](../byte_container_with_subtype.md) +- [byte_container_with_subtype](../byte_container_with_subtype/index.md) ## Version history diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md new file mode 100644 index 000000000..0ad701eb4 --- /dev/null +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md @@ -0,0 +1,27 @@ +# byte_container_with_subtype::byte_container_with_subtype + +```cpp +// (1) +byte_container_with_subtype(); + +// (2) +byte_container_with_subtype(const container_type& container); +byte_container_with_subtype(container_type&& container); + +// (3) +byte_container_with_subtype(const container_type& container, subtype_type subtype); +byte_container_with_subtype(container_type&& container, subtype_type subtype); +``` + +1. Create empty binary container without subtype. +2. Create binary container without subtype. +3. Create binary container with subtype. + +## Parameters + +`container` (in) +: binary container + +`subtype` (in) +: subtype + diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md new file mode 100644 index 000000000..b7afbda0f --- /dev/null +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md @@ -0,0 +1,20 @@ +# byte_container_with_subtype::clear_subtype + +```cpp +void clear_subtype() noexcept; +``` + +Clears the binary subtype and flags the value as not having a subtype, which has implications for serialization; for +instance MessagePack will prefer the bin family over the ext family. + +## Complexity + +Constant. + +## Exception safety + +No-throw guarantee: this function never throws exceptions. + +## Version history + +Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md new file mode 100644 index 000000000..5fcec994d --- /dev/null +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md @@ -0,0 +1,23 @@ +# byte_container_with_subtype::has_subtype + +```cpp +constexpr bool has_subtype() const noexcept; +``` + +Returns whether the value has a subtype. + +## Return value + +whether the value has a subtype + +## Complexity + +Constant. + +## Exception safety + +No-throw guarantee: this function never throws exceptions. + +## Version history + +Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/index.md similarity index 70% rename from doc/mkdocs/docs/api/byte_container_with_subtype.md rename to doc/mkdocs/docs/api/byte_container_with_subtype/index.md index f2dd12184..3db24ae63 100644 --- a/doc/mkdocs/docs/api/byte_container_with_subtype.md +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/index.md @@ -5,7 +5,7 @@ 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 +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. @@ -21,14 +21,13 @@ specific naming scheme in order to override the binary type. ## Member functions -- (constructor) -- (destructor) +- [(constructor)](byte_container_with_subtype.md) - **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 +- [**set_subtype**](subtype.md) - sets the binary subtype +- [**subtype**](subtype.md) - return the binary subtype +- [**has_subtype**](has_subtype.md) - return whether the value has a subtype +- [**clear_subtype**](clear_subtype.md) - clears the binary subtype ## Version history diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/operator_eq.md b/doc/mkdocs/docs/api/byte_container_with_subtype/operator_eq.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/operator_ne.md b/doc/mkdocs/docs/api/byte_container_with_subtype/operator_ne.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md new file mode 100644 index 000000000..f9b44fc3a --- /dev/null +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md @@ -0,0 +1,25 @@ +# byte_container_with_subtype::set_subtype + +```cpp +void set_subtype(subtype_type subtype) noexcept +``` + +Sets the binary subtype of the value, also flags a binary JSON value as having a subtype, which has implications for +serialization. + +## Parameters + +`subtype` (in) +: subtype to set + +## Complexity + +Constant. + +## Exception safety + +No-throw guarantee: this function never throws exceptions. + +## Version history + +Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md new file mode 100644 index 000000000..d7bc5ba74 --- /dev/null +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md @@ -0,0 +1,25 @@ +# byte_container_with_subtype::subtype + +```cpp +constexpr subtype_type subtype() const noexcept; +``` + +Returns the numerical subtype of the value if it has a subtype. If it does not have a subtype, this function will return +`subtype_type(-1)` as a sentinel value. + +## Return value + +the numerical subtype of the binary value, or `subtype_type(-1)` if no subtype is set + +## Complexity + +Constant. + +## Exception safety + +No-throw guarantee: this function never throws exceptions. + +## Version history + +- Added in version 3.8.0 +- Fixed return value to properly return `subtype_type(-1)` as documented in version 3.10.0. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index d67ee200a..d75fc3dba 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -145,8 +145,6 @@ nav: - api/basic_json/operator_value_t.md - api/basic_json/operator[].md - api/basic_json/operator=.md - - api/basic_json/operator_eq.md - - api/basic_json/operator_ne.md - api/basic_json/operator_lt.md - api/basic_json/operator_ltlt.md - api/basic_json/operator_le.md @@ -182,7 +180,13 @@ nav: - api/basic_json/update.md - api/basic_json/value.md - api/basic_json/value_t.md - - api/byte_container_with_subtype.md + - byte_container_with_subtype: + - 'Overview': api/byte_container_with_subtype/index.md + - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md + - 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md + - 'has_subtype': api/byte_container_with_subtype/has_subtype.md + - 'set_subtype': api/byte_container_with_subtype/set_subtype.md + - 'subtype': api/byte_container_with_subtype/subtype.md - adl_serializer: - api/adl_serializer/index.md - api/adl_serializer/from_json.md diff --git a/include/nlohmann/byte_container_with_subtype.hpp b/include/nlohmann/byte_container_with_subtype.hpp index 4086e0834..21a78a31b 100644 --- a/include/nlohmann/byte_container_with_subtype.hpp +++ b/include/nlohmann/byte_container_with_subtype.hpp @@ -7,46 +7,38 @@ namespace nlohmann { -/*! -@brief an internal type for a backed binary type - -This type extends the template parameter @a BinaryType provided to `basic_json` -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. - -@tparam BinaryType container to store bytes (`std::vector` by - default) - -@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.10.0. -*/ +/// @brief an internal type for a backed binary type +/// @sa https://json.nlohmann.me/api/byte_container_with_subtype/ template class byte_container_with_subtype : public BinaryType { public: - /// the type of the underlying container using container_type = BinaryType; - /// the type of the subtype using subtype_type = std::uint64_t; + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype() noexcept(noexcept(container_type())) : container_type() {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(const container_type& b) noexcept(noexcept(container_type(b))) : container_type(b) {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(container_type&& b) noexcept(noexcept(container_type(std::move(b)))) : container_type(std::move(b)) {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(const container_type& b, subtype_type subtype_) noexcept(noexcept(container_type(b))) : container_type(b) , m_subtype(subtype_) , m_has_subtype(true) {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(container_type&& b, subtype_type subtype_) noexcept(noexcept(container_type(std::move(b)))) : container_type(std::move(b)) , m_subtype(subtype_) @@ -64,97 +56,30 @@ class byte_container_with_subtype : public BinaryType return !(rhs == *this); } - /*! - @brief sets the binary subtype - - Sets the binary subtype of the value, also flags a binary JSON value as - having a subtype, which has implications for serialization. - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref subtype() -- return the binary subtype - @sa see @ref clear_subtype() -- clears the binary subtype - @sa see @ref has_subtype() -- returns whether or not the binary value has a - subtype - - @since version 3.8.0 - */ + /// @brief sets the binary subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/set_subtype/ void set_subtype(subtype_type subtype_) noexcept { m_subtype = subtype_; m_has_subtype = true; } - /*! - @brief return the binary subtype - - Returns the numerical subtype of the value if it has a subtype. If it does - not have a subtype, this function will return subtype_type(-1) as a sentinel - value. - - @return the numerical subtype of the binary value - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref set_subtype() -- sets the binary subtype - @sa see @ref clear_subtype() -- clears the binary subtype - @sa see @ref has_subtype() -- returns whether or not the binary value has a - subtype - - @since version 3.8.0; fixed return value to properly return - subtype_type(-1) as documented in version 3.10.0 - */ + /// @brief return the binary subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype/ constexpr subtype_type subtype() const noexcept { return m_has_subtype ? m_subtype : subtype_type(-1); } - /*! - @brief return whether the value has a subtype - - @return whether the value has a subtype - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref subtype() -- return the binary subtype - @sa see @ref set_subtype() -- sets the binary subtype - @sa see @ref clear_subtype() -- clears the binary subtype - - @since version 3.8.0 - */ + /// @brief return whether the value has a subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/has_subtype/ constexpr bool has_subtype() const noexcept { return m_has_subtype; } - /*! - @brief clears the binary subtype - - Clears the binary subtype and flags the value as not having a subtype, which - has implications for serialization; for instance MessagePack will prefer the - bin family over the ext family. - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref subtype() -- return the binary subtype - @sa see @ref set_subtype() -- sets the binary subtype - @sa see @ref has_subtype() -- returns whether or not the binary value has a - subtype - - @since version 3.8.0 - */ + /// @brief clears the binary subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/clear_subtype/ void clear_subtype() noexcept { m_subtype = 0; diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index a9bb8d478..a91784d4a 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -5083,46 +5083,38 @@ struct adl_serializer namespace nlohmann { -/*! -@brief an internal type for a backed binary type - -This type extends the template parameter @a BinaryType provided to `basic_json` -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. - -@tparam BinaryType container to store bytes (`std::vector` by - default) - -@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.10.0. -*/ +/// @brief an internal type for a backed binary type +/// @sa https://json.nlohmann.me/api/byte_container_with_subtype/ template class byte_container_with_subtype : public BinaryType { public: - /// the type of the underlying container using container_type = BinaryType; - /// the type of the subtype using subtype_type = std::uint64_t; + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype() noexcept(noexcept(container_type())) : container_type() {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(const container_type& b) noexcept(noexcept(container_type(b))) : container_type(b) {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(container_type&& b) noexcept(noexcept(container_type(std::move(b)))) : container_type(std::move(b)) {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(const container_type& b, subtype_type subtype_) noexcept(noexcept(container_type(b))) : container_type(b) , m_subtype(subtype_) , m_has_subtype(true) {} + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/ byte_container_with_subtype(container_type&& b, subtype_type subtype_) noexcept(noexcept(container_type(std::move(b)))) : container_type(std::move(b)) , m_subtype(subtype_) @@ -5140,97 +5132,30 @@ class byte_container_with_subtype : public BinaryType return !(rhs == *this); } - /*! - @brief sets the binary subtype - - Sets the binary subtype of the value, also flags a binary JSON value as - having a subtype, which has implications for serialization. - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref subtype() -- return the binary subtype - @sa see @ref clear_subtype() -- clears the binary subtype - @sa see @ref has_subtype() -- returns whether or not the binary value has a - subtype - - @since version 3.8.0 - */ + /// @brief sets the binary subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/set_subtype/ void set_subtype(subtype_type subtype_) noexcept { m_subtype = subtype_; m_has_subtype = true; } - /*! - @brief return the binary subtype - - Returns the numerical subtype of the value if it has a subtype. If it does - not have a subtype, this function will return subtype_type(-1) as a sentinel - value. - - @return the numerical subtype of the binary value - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref set_subtype() -- sets the binary subtype - @sa see @ref clear_subtype() -- clears the binary subtype - @sa see @ref has_subtype() -- returns whether or not the binary value has a - subtype - - @since version 3.8.0; fixed return value to properly return - subtype_type(-1) as documented in version 3.10.0 - */ + /// @brief return the binary subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype/ constexpr subtype_type subtype() const noexcept { return m_has_subtype ? m_subtype : subtype_type(-1); } - /*! - @brief return whether the value has a subtype - - @return whether the value has a subtype - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref subtype() -- return the binary subtype - @sa see @ref set_subtype() -- sets the binary subtype - @sa see @ref clear_subtype() -- clears the binary subtype - - @since version 3.8.0 - */ + /// @brief return whether the value has a subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/has_subtype/ constexpr bool has_subtype() const noexcept { return m_has_subtype; } - /*! - @brief clears the binary subtype - - Clears the binary subtype and flags the value as not having a subtype, which - has implications for serialization; for instance MessagePack will prefer the - bin family over the ext family. - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this member function never throws - exceptions. - - @sa see @ref subtype() -- return the binary subtype - @sa see @ref set_subtype() -- sets the binary subtype - @sa see @ref has_subtype() -- returns whether or not the binary value has a - subtype - - @since version 3.8.0 - */ + /// @brief clears the binary subtype + /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/clear_subtype/ void clear_subtype() noexcept { m_subtype = 0;