From fd054df1c66af6b98294457f84829534c70f2d4d Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sun, 31 Oct 2021 14:02:31 +0100 Subject: [PATCH] :fire: consolidate documentation --- doc/mkdocs/docs/api/basic_json/index.md | 48 ++++- doc/mkdocs/docs/api/basic_json/swap.md | 153 ++++++++++++++++ doc/mkdocs/mkdocs.yml | 1 + include/nlohmann/json.hpp | 233 ++---------------------- single_include/nlohmann/json.hpp | 233 ++---------------------- 5 files changed, 235 insertions(+), 433 deletions(-) create mode 100644 doc/mkdocs/docs/api/basic_json/swap.md diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 2d81a2261..bd88cbf1a 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -42,6 +42,48 @@ class basic_json; Todo +## Requirements + +The class satisfies the following concept requirements: + +### Basic + +- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default + constructed. The result will be a JSON null value. +- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed + from an rvalue argument. +- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be + copy-constructed from an lvalue expression. +- [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): A JSON value van be assigned from an + rvalue argument. +- [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): A JSON value can be copy-assigned from + an lvalue expression. +- [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): JSON values can be destructed. + +### Layout + +- [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): JSON values have + [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): All non-static data + members are private and standard layout types, the class has no virtual functions or (virtual) base classes. + +### Library-wide + +- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with + `==`, see [`operator==`](operator_eq.md). +- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with + `<`, see [`operator<`](operator_le). +- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with + any lvalue or rvalue of other compatible types, using unqualified function `swap`. +- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against + `std::nullptr_t` objects which are used to model the `null` value. + +### Container + +- [Container](https://en.cppreference.com/w/cpp/named_req/Container): JSON values can be used like STL containers and + provide iterator access. +- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer): JSON values can be used like + STL containers and provide reverse iterator access. + ## Member types - [**adl_serializer**](../adl_serializer) - the default serializer @@ -183,7 +225,7 @@ Access to the JSON value - [**erase**](erase.md) - remove elements - [**insert**](insert.md) - inserts elements - [**update**](update.md) - updates a JSON object from another object, overwriting existing keys -- swap - exchanges the values +- [**swap**](swap.md) - exchanges the values ### Lexicographical comparison operators @@ -250,3 +292,7 @@ Access to the JSON value - std::hash - std::less - std::swap + +## See also + +- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259) diff --git a/doc/mkdocs/docs/api/basic_json/swap.md b/doc/mkdocs/docs/api/basic_json/swap.md new file mode 100644 index 000000000..47ca2d0da --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/swap.md @@ -0,0 +1,153 @@ +# basic_json::swap + +```cpp +// (1) +void swap(reference other) noexcept; + +// (2) +void swap(reference left, reference right) noexcept; + +// (3) +void swap(array_t& other); + +// (4) +void swap(object_t& other); + +// (5) +void swap(string_t& other); + +// (6) +void swap(binary_t& other); + +// (7) +void swap(typename binary_t::container_type& other); +``` + +1. Exchanges the contents of the JSON value with those of `other`. Does not invoke any move, copy, or swap operations on + individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. +2. Exchanges the contents of the JSON value from `left` with those of `right`. Does not invoke any move, copy, or swap + operations on individual elements. All iterators and references remain valid. The past-the-end iterator is + invalidated. Implemented as a friend function callable via ADL. +3. Exchanges the contents of a JSON array with those of `other`. Does not invoke any move, copy, or swap operations on + individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. +4. Exchanges the contents of a JSON object with those of `other`. Does not invoke any move, copy, or swap operations on + individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. +5. Exchanges the contents of a JSON string with those of `other`. Does not invoke any move, copy, or swap operations on + individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. +6. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on + individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. +7. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on + individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. Unlike + version (6), no binary subtype is involved. + +## Parameters + +`other` (in, out) +: value to exchange the contents with + +`left` (in, out) +: value to exchange the contents with + +`right` (in, out) +: value to exchange the contents with + +## Exceptions + +1. No-throw guarantee: this function never throws exceptions. +2. No-throw guarantee: this function never throws exceptions. +3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than + arrays; example: `"cannot use swap() with boolean"` +4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than + objects; example: `"cannot use swap() with boolean"` +5. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than + strings; example: `"cannot use swap() with boolean"` +6. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than + binaries; example: `"cannot use swap() with boolean"` +7. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than + binaries; example: `"cannot use swap() with boolean"` + +## Complexity + +Constant. + +## Example + +??? example "Example: Swap JSON value (1, 2)" + + The example below shows how JSON values can be swapped with `swap()`. + + ```cpp + --8<-- "examples/swap__reference.cpp" + ``` + + Output: + + ```json + --8<-- "examples/swap__reference.output" + ``` + +??? example "Example: Swap array (3)" + + The example below shows how arrays can be swapped with `swap()`. + + ```cpp + --8<-- "examples/swap__array_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/swap__array_t.output" + ``` + +??? example "Example: Swap object (4)" + + The example below shows how objects can be swapped with `swap()`. + + ```cpp + --8<-- "examples/swap__object_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/swap__object_t.output" + ``` + +??? example "Example: Swap string (5)" + + The example below shows how strings can be swapped with `swap()`. + + ```cpp + --8<-- "examples/swap__string_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/swap__string_t.output" + ``` + +??? example "Example: Swap string (6)" + + The example below shows how binary values can be swapped with `swap()`. + + ```cpp + --8<-- "examples/swap__binary_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/swap__binary_t.output" + ``` + +## Version history + +1. Since version 1.0.0. +2. Since version 1.0.0. +3. Since version 1.0.0. +4. Since version 1.0.0. +5. Since version 1.0.0. +6. Since version 3.8.0. +7. Since version 3.8.0. \ No newline at end of file diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 8974f0a53..bae5ad446 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -167,6 +167,7 @@ nav: - api/basic_json/sax_parse.md - api/basic_json/size.md - api/basic_json/string_t.md + - api/basic_json/swap.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 2da1173e0..ae0dafbbf 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -91,69 +91,7 @@ namespace nlohmann /*! @brief a class to store JSON values -@tparam ObjectType type for JSON objects (`std::map` by default; will be used -in @ref object_t) -@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used -in @ref array_t) -@tparam StringType type for JSON strings and object keys (`std::string` by -default; will be used in @ref string_t) -@tparam BooleanType type for JSON booleans (`bool` by default; will be used -in @ref boolean_t) -@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by -default; will be used in @ref number_integer_t) -@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c -`uint64_t` by default; will be used in @ref number_unsigned_t) -@tparam NumberFloatType type for JSON floating-point numbers (`double` by -default; will be used in @ref number_float_t) -@tparam BinaryType type for packed binary data for compatibility with binary -serialization formats (`std::vector` by default; will be used in -@ref binary_t) -@tparam AllocatorType type of the allocator to use (`std::allocator` by -default) -@tparam JSONSerializer the serializer to resolve internal calls to `to_json()` -and `from_json()` (@ref adl_serializer by default) - -@requirement The class satisfies the following concept requirements: -- Basic - - [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): - JSON values can be default constructed. The result will be a JSON null - value. - - [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): - A JSON value can be constructed from an rvalue argument. - - [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): - A JSON value can be copy-constructed from an lvalue expression. - - [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): - A JSON value van be assigned from an rvalue argument. - - [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): - A JSON value can be copy-assigned from an lvalue expression. - - [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): - JSON values can be destructed. -- Layout - - [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): - JSON values have - [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): - All non-static data members are private and standard layout types, the - class has no virtual functions or (virtual) base classes. -- Library-wide - - [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): - JSON values can be compared with `==`, see @ref - operator==(const_reference,const_reference). - - [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): - JSON values can be compared with `<`, see @ref - operator<(const_reference,const_reference). - - [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): - Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of - other compatible types, using unqualified function call @ref swap(). - - [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): - JSON values can be compared against `std::nullptr_t` objects which are used - to model the `null` value. -- Container - - [Container](https://en.cppreference.com/w/cpp/named_req/Container): - JSON values can be used like STL containers and provide iterator access. - - [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer); - JSON values can be used like STL containers and provide reverse iterator - access. - +@internal @invariant The member variables @a m_value and @a m_type have the following relationship: - If `m_type == value_t::object`, then `m_value.object != nullptr`. @@ -161,13 +99,9 @@ relationship: - If `m_type == value_t::string`, then `m_value.string != nullptr`. The invariants are checked by member function assert_invariant(). -@internal @note ObjectType trick from https://stackoverflow.com/a/9860911 @endinternal -@see [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange -Format](https://tools.ietf.org/html/rfc8259) - @since version 1.0.0 @nosubgrouping @@ -258,17 +192,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// Classes to implement user-defined exceptions. /// @{ - /// @copydoc detail::exception using exception = detail::exception; - /// @copydoc detail::parse_error using parse_error = detail::parse_error; - /// @copydoc detail::invalid_iterator using invalid_iterator = detail::invalid_iterator; - /// @copydoc detail::type_error using type_error = detail::type_error; - /// @copydoc detail::out_of_range using out_of_range = detail::out_of_range; - /// @copydoc detail::other_error using other_error = detail::other_error; /// @} @@ -1010,33 +938,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec assert_invariant(); } - /*! - @brief explicitly create a binary array (without subtype) - - Creates a JSON binary array value from a given binary container. Binary - values are part of various binary formats, such as CBOR, MessagePack, and - BSON. This constructor is used to create a value for serialization to those - formats. - - @note Note, this function exists because of the difficulty in correctly - specifying the correct template overload in the standard value ctor, as both - JSON arrays and JSON binary arrays are backed with some form of a - `std::vector`. Because JSON binary arrays are a non-standard extension it - was decided that it would be best to prevent automatic initialization of a - binary array type, for backwards compatibility and so it does not happen on - accident. - - @param[in] init container containing bytes to use as binary type - - @return JSON binary array value - - @complexity Linear in the size of @a init. - - @exceptionsafety Strong guarantee: if an exception is thrown, there are no - changes to any JSON value. - - @since version 3.8.0 - */ + /// @brief explicitly create a binary array (without subtype) + /// @sa https://json.nlohmann.me/api/basic_json/binary/ JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json binary(const typename binary_t::container_type& init) { @@ -3322,23 +3225,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of the JSON value with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other JSON value to exchange the contents with - - @complexity Constant. - - @liveexample{The example below shows how JSON values can be swapped with - `swap()`.,swap__reference} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(reference other) noexcept ( std::is_nothrow_move_constructible::value&& std::is_nothrow_move_assignable::value&& @@ -3354,24 +3242,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec assert_invariant(); } - /*! - @brief exchanges the values - - Exchanges the contents of the JSON value from @a left with those of @a right. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. implemented as a friend function callable via ADL. - - @param[in,out] left JSON value to exchange the contents with - @param[in,out] right JSON value to exchange the contents with - - @complexity Constant. - - @liveexample{The example below shows how JSON values can be swapped with - `swap()`.,swap__reference} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ friend void swap(reference left, reference right) noexcept ( std::is_nothrow_move_constructible::value&& std::is_nothrow_move_assignable::value&& @@ -3382,26 +3254,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec left.swap(right); } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON array with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other array to exchange the contents with - - @throw type_error.310 when JSON value is not an array; example: `"cannot - use swap() with string"` - - @complexity Constant. - - @liveexample{The example below shows how arrays can be swapped with - `swap()`.,swap__array_t} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(array_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for arrays @@ -3415,26 +3269,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON object with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other object to exchange the contents with - - @throw type_error.310 when JSON value is not an object; example: - `"cannot use swap() with string"` - - @complexity Constant. - - @liveexample{The example below shows how objects can be swapped with - `swap()`.,swap__object_t} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(object_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for objects @@ -3448,26 +3284,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON string with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other string to exchange the contents with - - @throw type_error.310 when JSON value is not a string; example: `"cannot - use swap() with boolean"` - - @complexity Constant. - - @liveexample{The example below shows how strings can be swapped with - `swap()`.,swap__string_t} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(string_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for strings @@ -3481,26 +3299,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON string with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other binary to exchange the contents with - - @throw type_error.310 when JSON value is not a string; example: `"cannot - use swap() with boolean"` - - @complexity Constant. - - @liveexample{The example below shows how strings can be swapped with - `swap()`.,swap__binary_t} - - @since version 3.8.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(binary_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for strings @@ -3514,7 +3314,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /// @copydoc swap(binary_t&) + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(typename binary_t::container_type& other) // NOLINT(bugprone-exception-escape) { // swap only works for strings diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 1ced700b4..af4b6522c 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -17592,69 +17592,7 @@ namespace nlohmann /*! @brief a class to store JSON values -@tparam ObjectType type for JSON objects (`std::map` by default; will be used -in @ref object_t) -@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used -in @ref array_t) -@tparam StringType type for JSON strings and object keys (`std::string` by -default; will be used in @ref string_t) -@tparam BooleanType type for JSON booleans (`bool` by default; will be used -in @ref boolean_t) -@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by -default; will be used in @ref number_integer_t) -@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c -`uint64_t` by default; will be used in @ref number_unsigned_t) -@tparam NumberFloatType type for JSON floating-point numbers (`double` by -default; will be used in @ref number_float_t) -@tparam BinaryType type for packed binary data for compatibility with binary -serialization formats (`std::vector` by default; will be used in -@ref binary_t) -@tparam AllocatorType type of the allocator to use (`std::allocator` by -default) -@tparam JSONSerializer the serializer to resolve internal calls to `to_json()` -and `from_json()` (@ref adl_serializer by default) - -@requirement The class satisfies the following concept requirements: -- Basic - - [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): - JSON values can be default constructed. The result will be a JSON null - value. - - [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): - A JSON value can be constructed from an rvalue argument. - - [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): - A JSON value can be copy-constructed from an lvalue expression. - - [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): - A JSON value van be assigned from an rvalue argument. - - [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): - A JSON value can be copy-assigned from an lvalue expression. - - [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): - JSON values can be destructed. -- Layout - - [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): - JSON values have - [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): - All non-static data members are private and standard layout types, the - class has no virtual functions or (virtual) base classes. -- Library-wide - - [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): - JSON values can be compared with `==`, see @ref - operator==(const_reference,const_reference). - - [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): - JSON values can be compared with `<`, see @ref - operator<(const_reference,const_reference). - - [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): - Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of - other compatible types, using unqualified function call @ref swap(). - - [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): - JSON values can be compared against `std::nullptr_t` objects which are used - to model the `null` value. -- Container - - [Container](https://en.cppreference.com/w/cpp/named_req/Container): - JSON values can be used like STL containers and provide iterator access. - - [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer); - JSON values can be used like STL containers and provide reverse iterator - access. - +@internal @invariant The member variables @a m_value and @a m_type have the following relationship: - If `m_type == value_t::object`, then `m_value.object != nullptr`. @@ -17662,13 +17600,9 @@ relationship: - If `m_type == value_t::string`, then `m_value.string != nullptr`. The invariants are checked by member function assert_invariant(). -@internal @note ObjectType trick from https://stackoverflow.com/a/9860911 @endinternal -@see [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange -Format](https://tools.ietf.org/html/rfc8259) - @since version 1.0.0 @nosubgrouping @@ -17759,17 +17693,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// Classes to implement user-defined exceptions. /// @{ - /// @copydoc detail::exception using exception = detail::exception; - /// @copydoc detail::parse_error using parse_error = detail::parse_error; - /// @copydoc detail::invalid_iterator using invalid_iterator = detail::invalid_iterator; - /// @copydoc detail::type_error using type_error = detail::type_error; - /// @copydoc detail::out_of_range using out_of_range = detail::out_of_range; - /// @copydoc detail::other_error using other_error = detail::other_error; /// @} @@ -18511,33 +18439,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec assert_invariant(); } - /*! - @brief explicitly create a binary array (without subtype) - - Creates a JSON binary array value from a given binary container. Binary - values are part of various binary formats, such as CBOR, MessagePack, and - BSON. This constructor is used to create a value for serialization to those - formats. - - @note Note, this function exists because of the difficulty in correctly - specifying the correct template overload in the standard value ctor, as both - JSON arrays and JSON binary arrays are backed with some form of a - `std::vector`. Because JSON binary arrays are a non-standard extension it - was decided that it would be best to prevent automatic initialization of a - binary array type, for backwards compatibility and so it does not happen on - accident. - - @param[in] init container containing bytes to use as binary type - - @return JSON binary array value - - @complexity Linear in the size of @a init. - - @exceptionsafety Strong guarantee: if an exception is thrown, there are no - changes to any JSON value. - - @since version 3.8.0 - */ + /// @brief explicitly create a binary array (without subtype) + /// @sa https://json.nlohmann.me/api/basic_json/binary/ JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json binary(const typename binary_t::container_type& init) { @@ -20823,23 +20726,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of the JSON value with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other JSON value to exchange the contents with - - @complexity Constant. - - @liveexample{The example below shows how JSON values can be swapped with - `swap()`.,swap__reference} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(reference other) noexcept ( std::is_nothrow_move_constructible::value&& std::is_nothrow_move_assignable::value&& @@ -20855,24 +20743,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec assert_invariant(); } - /*! - @brief exchanges the values - - Exchanges the contents of the JSON value from @a left with those of @a right. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. implemented as a friend function callable via ADL. - - @param[in,out] left JSON value to exchange the contents with - @param[in,out] right JSON value to exchange the contents with - - @complexity Constant. - - @liveexample{The example below shows how JSON values can be swapped with - `swap()`.,swap__reference} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ friend void swap(reference left, reference right) noexcept ( std::is_nothrow_move_constructible::value&& std::is_nothrow_move_assignable::value&& @@ -20883,26 +20755,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec left.swap(right); } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON array with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other array to exchange the contents with - - @throw type_error.310 when JSON value is not an array; example: `"cannot - use swap() with string"` - - @complexity Constant. - - @liveexample{The example below shows how arrays can be swapped with - `swap()`.,swap__array_t} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(array_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for arrays @@ -20916,26 +20770,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON object with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other object to exchange the contents with - - @throw type_error.310 when JSON value is not an object; example: - `"cannot use swap() with string"` - - @complexity Constant. - - @liveexample{The example below shows how objects can be swapped with - `swap()`.,swap__object_t} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(object_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for objects @@ -20949,26 +20785,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON string with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other string to exchange the contents with - - @throw type_error.310 when JSON value is not a string; example: `"cannot - use swap() with boolean"` - - @complexity Constant. - - @liveexample{The example below shows how strings can be swapped with - `swap()`.,swap__string_t} - - @since version 1.0.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(string_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for strings @@ -20982,26 +20800,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /*! - @brief exchanges the values - - Exchanges the contents of a JSON string with those of @a other. Does not - invoke any move, copy, or swap operations on individual elements. All - iterators and references remain valid. The past-the-end iterator is - invalidated. - - @param[in,out] other binary to exchange the contents with - - @throw type_error.310 when JSON value is not a string; example: `"cannot - use swap() with boolean"` - - @complexity Constant. - - @liveexample{The example below shows how strings can be swapped with - `swap()`.,swap__binary_t} - - @since version 3.8.0 - */ + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(binary_t& other) // NOLINT(bugprone-exception-escape) { // swap only works for strings @@ -21015,7 +20815,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec } } - /// @copydoc swap(binary_t&) + /// @brief exchanges the values + /// @sa https://json.nlohmann.me/api/basic_json/swap/ void swap(typename binary_t::container_type& other) // NOLINT(bugprone-exception-escape) { // swap only works for strings