External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

🔥 consolidate documentation

Browse Source
This commit is contained in:
Niels Lohmann 2021-11-05 13:33:21 +01:00
parent 0d06b5d5e7
commit 7bfe76848a
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
12 changed files with 165 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/mkdocs/docs/api/basic_json/binary_t.md
View File

@ -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

27
doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md Normal file
View File

@ -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

20
doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md Normal file
View File

@ -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.

23
doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md Normal file
View File

@ -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.

13
doc/mkdocs/docs/api/byte_container_with_subtype.md → doc/mkdocs/docs/api/byte_container_with_subtype/index.md
View File

@ -5,7 +5,7 @@ template<typename BinaryType>
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

0
doc/mkdocs/docs/api/byte_container_with_subtype/operator_eq.md Normal file
View File

0
doc/mkdocs/docs/api/byte_container_with_subtype/operator_ne.md Normal file
View File

25
doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md Normal file
View File

@ -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.

25
doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md Normal file
View File

@ -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.

10
doc/mkdocs/mkdocs.yml
View File

@ -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

105
include/nlohmann/byte_container_with_subtype.hpp
View File

@ -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<std::uint8_t>` 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<typename BinaryType>
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;

105
single_include/nlohmann/json.hpp
View File

@ -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<std::uint8_t>` 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<typename BinaryType>
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;