lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-28 12:02:00 +03:00
Code Activity

Consolidate documentation (#3071)

Browse Source 
* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables
This commit is contained in:
Niels Lohmann
2021-12-29 13:41:01 +01:00
committed by GitHub
parent 6d3115924c
commit 29cd970b94
392 changed files with 4827 additions and 12560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
doc/mkdocs/docs/api/adl_serializer/from_json.md Normal file
View File

@ -0,0 +1,41 @@
# <small>nlohmann::adl_serializer::</small>from_json
```cpp
// (1)
template<typename BasicJsonType, typename TargetType = ValueType>
static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), val), void())
// (2)
template<typename BasicJsonType, typename TargetType = ValueType>
static auto from_json(BasicJsonType && j) noexcept(
noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))
-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {}))
```
This function is usually called by the [`get()`](../basic_json/get.md) function of the
[basic_json](../basic_json) class (either explicit or via conversion operators).
1. This function is chosen for default-constructible value types.
2. This function is chosen for value types which are not default-constructible.
## Parameters
`j` (in)
: JSON value to read from
`val` (out)
: value to write to
## Return value
Copy of the JSON value, converted to `ValueType`
!!! note
This documentation page is a stub.
## Version history
- Added in version 2.1.0.

10
doc/mkdocs/docs/api/adl_serializer.md → doc/mkdocs/docs/api/adl_serializer/index.md
View File

@ -1,4 +1,4 @@
# adl_serializer
# <small>nlohmann::</small>adl_serializer
```cpp
template<typename, typename>
@ -27,5 +27,9 @@ struct adl_serializer {
## Member functions
- **from_json** - convert a JSON value to any value type
- **to_json** - convert any value type to a JSON value
- [**from_json**](from_json.md) - convert a JSON value to any value type
- [**to_json**](to_json.md) - convert any value type to a JSON value
## Version history
- Added in version 2.1.0.

26
doc/mkdocs/docs/api/adl_serializer/to_json.md Normal file
View File

@ -0,0 +1,26 @@
# <small>nlohmann::adl_serializer::</small>to_json
```cpp
template<typename BasicJsonType, typename TargetType = ValueType>
static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))
-> decltype(::nlohmann::to_json(j, std::forward<TargetType>(val)), void())
```
This function is usually called by the constructors of the [basic_json](../basic_json) class.
## Parameters
`j` (out)
: JSON value to write to
`val` (in)
: value to read from
!!! note
This documentation page is a stub.
## Version history
- Added in version 2.1.0.

18
doc/mkdocs/docs/api/basic_json/accept.md
View File

@ -1,4 +1,4 @@
# basic_json::accept
# <small>nlohmann::basic_json::</small>accept
```cpp
// (1)
@ -17,7 +17,7 @@ Checks whether the input is valid JSON.
1. Reads from a compatible input.
2. Reads from a pair of character iterators
The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
Unlike the [`parse`](parse.md) function, this function neither throws an exception in case of invalid JSON input
@ -84,7 +84,21 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
--8<-- "examples/accept__string.output"
```
## See also
- [parse](parse.md) - deserialize from a compatible input
- [operator>>](operator_gtgt.md) - deserialize from stream
## Version history
- Added in version 3.0.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
!!! warning "Deprecation"
Overload (2) replaces calls to `accept` with a pair of iterators as their first parameter which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp accept({ptr, ptr+len}, ...);` with `#!cpp accept(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

7
doc/mkdocs/docs/api/basic_json/array.md
View File

@ -1,4 +1,4 @@
# basic_json::array
# <small>nlohmann::basic_json::</small>array
```cpp
static basic_json array(initializer_list_t init = {});
@ -50,6 +50,11 @@ This function is only needed to express two edge cases that cannot be realized w
--8<-- "examples/array.output"
```
## See also
- [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
- [`object`](object.md) - create a JSON object value from an initializer list
## Version history
- Added in version 1.0.0.

18
doc/mkdocs/docs/api/basic_json/array_t.md
View File

@ -1,4 +1,4 @@
# basic_json::array_t
# <small>nlohmann::basic_json::</small>array_t
```cpp
using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
@ -47,6 +47,22 @@ introduced by the compiler or runtime environment. A theoretical limit can be qu
Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type
`#!cpp array_t*` must be dereferenced.
## Examples
??? example
The following code shows that `array_t` is by default, a typedef to `#!cpp std::vector<nlohmann::json>`.
```cpp
--8<-- "examples/array_t.cpp"
```
Output:
```json
--8<-- "examples/array_t.output"
```
## Version history
- Added in version 1.0.0.

35
doc/mkdocs/docs/api/basic_json/at.md
View File

@ -1,4 +1,4 @@
# basic_json::at
# <small>nlohmann::basic_json::</small>at
```cpp
// (1)
@ -14,8 +14,8 @@ reference at(const json_pointer& ptr);
const_reference at(const json_pointer& ptr) const;
```
1. Returns a reference to the element at specified location `idx`, with bounds checking.
2. Returns a reference to the element at with specified key `key`, with bounds checking.
1. Returns a reference to the array element at specified location `idx`, with bounds checking.
2. Returns a reference to the object element at with specified key `key`, with bounds checking.
3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking.
## Parameters
@ -35,6 +35,10 @@ const_reference at(const json_pointer& ptr) const;
2. reference to the element at key `key`
3. reference to the element pointed to by `ptr`
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function can throw the following exceptions:
@ -45,7 +49,7 @@ const_reference at(const json_pointer& ptr) const;
2. The function can throw the following exceptions:
- Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
in this case, calling `at` with a key makes no sense. See example below.
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is is not
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
stored in the object; that is, `find(key) == end()`. See example below.
3. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
@ -62,19 +66,15 @@ const_reference at(const json_pointer& ptr) const;
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved. See example below.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
1. Constant
2. Logarithmic in the size of the container.
3. Constant
## Example
## Examples
??? example
??? example "Example: (1) access specified array element with bounds checking"
The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@ -89,7 +89,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__size_type.output"
```
??? example
??? example "Example: (1) access specified array element with bounds checking"
The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@ -104,7 +104,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__size_type_const.output"
```
??? example
??? example "Example: (2) access specified object element with bounds checking"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@ -119,7 +119,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type.output"
```
??? example
??? example "Example (2) access specified object element with bounds checking"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@ -134,7 +134,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type_const.output"
```
??? example
??? example "Example (3) access specified element via JSON Pointer"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@ -149,7 +149,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at_json_pointer.output"
```
??? example
??? example "Example (3) access specified element via JSON Pointer"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@ -164,6 +164,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at_json_pointer_const.output"
```
## See also
- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
- see [`value`](value.md) for access with default value
## Version history
1. Added in version 1.0.0.

18
doc/mkdocs/docs/api/basic_json/back.md
View File

@ -1,4 +1,4 @@
# basic_json::back
# <small>nlohmann::basic_json::</small>back
```cpp
reference back();
@ -20,26 +20,26 @@ return *tmp;
In case of a structured type (array or object), a reference to the last element is returned. In case of number, string,
boolean, or binary values, a reference to the value is returned.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
If the JSON value is `#!json null`, exception
[`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Constant.
## Note
## Notes
!!! danger
Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**!
## Example
## Examples
??? example
@ -55,6 +55,10 @@ Constant.
--8<-- "examples/back.output"
```
## See also
- [front](front.md) to access the first element
## Version history
- Added in version 1.0.0.

98
doc/mkdocs/docs/api/basic_json/basic_json.md
View File

@ -1,53 +1,55 @@
# basic_json::basic_json
# <small>nlohmann::basic_json::</small>basic_json
```cpp
// 1
// (1)
basic_json(const value_t v);
// 2
// (2)
basic_json(std::nullptr_t = nullptr) noexcept;
// 3
// (3)
template<typename CompatibleType>
basic_json(CompatibleType&& val) noexcept(noexcept(
JSONSerializer<U>::to_json(std::declval<basic_json_t&>(),
std::forward<CompatibleType>(val))));
// 4
// (4)
template<typename BasicJsonType>
basic_json(const BasicJsonType& val);
// 5
// (5)
basic_json(initializer_list_t init,
bool type_deduction = true,
value_t manual_type = value_t::array);
// 6
// (6)
basic_json(size_type cnt, const basic_json& val);
// 7
// (7)
basic_json(iterator first, iterator last);
basic_json(const_iterator first, const_iterator last);
// 8
// (8)
basic_json(const basic_json& other);
// 9
// (9)
basic_json(basic_json&& other) noexcept;
```
1. Create an empty JSON value with a given type. The value will be default initialized with an empty value which depends
on the type:
Value type | initial value
----------- | -------------
null | `#!json null`
boolean | `#!json false`
string | `#!json ""`
number | `#!json 0`
object | `#!json {}`
array | `#!json []`
binary | empty array
| Value type | initial value |
|------------|----------------|
| null | `#!json null` |
| boolean | `#!json false` |
| string | `#!json ""` |
| number | `#!json 0` |
| object | `#!json {}` |
| array | `#!json []` |
| binary | empty array |
The postcondition of this constructor can be restored by calling [`clear()`](clear.md).
2. Create a `#!json null` JSON value. It either takes a null pointer as parameter (explicitly creating `#!json null`)
or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read -- it is only used to
@ -104,6 +106,9 @@ basic_json(basic_json&& other) noexcept;
- the empty array (`#!json []`): use `array(initializer_list_t)` with an empty initializer list in this case
- arrays whose elements satisfy rule 2: use `array(initializer_list_t)` with the same initializer list in this case
Function [`array()`](array.md) and [`object()`](object.md) force array and object creation from initializer lists,
respectively.
6. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is
created.
@ -142,6 +147,9 @@ basic_json(basic_json&& other) noexcept;
- `BasicJsonType` is a `basic_json` type.
- `BasicJsonType` has different template arguments than `basic_json_t`.
`U`:
: `uncvref_t<CompatibleType>`
## Parameters
`v` (in)
@ -175,6 +183,22 @@ basic_json(basic_json&& other) noexcept;
`other` (in)
: the JSON value to copy/move
## Exception safety
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
2. No-throw guarantee: this constructor never throws exceptions.
3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
`to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
JSON value.
4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
`to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
JSON value.
5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
9. No-throw guarantee: this constructor never throws exceptions.
## Exceptions
1. /
@ -193,28 +217,12 @@ basic_json(basic_json&& other) noexcept;
`[first, last)` is undefined.
- Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if iterators `first`
and `last` belong to a primitive type (number, boolean, or string), but `first` does not point to the first
element any more. In this case, the range `[first, last)` is undefined. See example code below.
element anymore. In this case, the range `[first, last)` is undefined. See example code below.
- Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
8. /
9. The function does not throw exceptions.
## Exception safety
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
2. No-throw guarantee: this constructor never throws exceptions.
3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
`to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
JSON value.
4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
`to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
JSON value.
5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
9. No-throw guarantee: this constructor never throws exceptions.
## Complexity
1. Constant.
@ -267,9 +275,9 @@ basic_json(basic_json&& other) noexcept;
- `#!cpp `*this` has the same value as `other` before the call.
- `other` is a JSON `#!json null` value
## Example
## Examples
??? example
??? example "Example: (1) create an empty value with a given type"
The following code shows the constructor for different `value_t` values.
@ -283,7 +291,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__value_t.output"
```
??? example
??? example "Example: (2) create a `#!json null` object"
The following code shows the constructor with and without a null pointer parameter.
@ -297,7 +305,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__nullptr_t.output"
```
??? example
??? example "Example: (3) create a JSON value from compatible types"
The following code shows the constructor with several compatible types.
@ -311,7 +319,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__CompatibleType.output"
```
??? example
??? example "Example: (5) create a container (array or object) from an initializer list"
The example below shows how JSON values are created from initializer lists.
@ -325,7 +333,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__list_init_t.output"
```
??? example
??? example "Example: (6) construct an array with count copies of given value"
The following code shows examples for creating arrays with several copies of a given value.
@ -339,7 +347,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__size_type_basic_json.output"
```
??? example
??? example "Example: (7) construct a JSON container given an iterator range"
The example below shows several ways to create JSON values by specifying a subrange with iterators.
@ -353,7 +361,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__InputIt_InputIt.output"
```
??? example
??? example "Example: (8) copy constructor"
The following code shows an example for the copy constructor.
@ -367,7 +375,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__basic_json.output"
```
??? example
??? example "Example: (9) move constructor"
The code below shows the move constructor explicitly called via `std::move`.

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

@ -1,4 +1,4 @@
# basic_json::begin
# <small>nlohmann::basic_json::</small>begin
```cpp
iterator begin() noexcept;
@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

18
doc/mkdocs/docs/api/basic_json/binary.md
View File

@ -1,4 +1,4 @@
# basic_json::binary
# <small>nlohmann::basic_json::</small>binary
```cpp
// (1)
@ -45,6 +45,22 @@ standard value ctor, as both JSON arrays and JSON binary arrays are backed with
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.
## Examples
??? example
The following code shows how to create a binary value.
```cpp
--8<-- "examples/binary.cpp"
```
Output:
```json
--8<-- "examples/binary.output"
```
## Version history
- Added in version 3.8.0.

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

@ -1,4 +1,4 @@
# basic_json::binary_t
# <small>nlohmann::basic_json::</small>binary_t
```cpp
using binary_t = byte_container_with_subtype<BinaryType>;
@ -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/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
@ -18,7 +19,7 @@ incompatible with each other, and it is up to the user to translate between them
[MessagePack's documentation on the bin type
family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:
> Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
> Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
[BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to
represent the generic binary type which has the description:
@ -62,6 +63,27 @@ 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.
## Examples
??? example
The following code shows that `binary_t` is by default, a typedef to
`#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
```cpp
--8<-- "examples/binary_t.cpp"
```
Output:
```json
--8<-- "examples/binary_t.output"
```
## See also
- [byte_container_with_subtype](../byte_container_with_subtype/index.md)
## Version history
- Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0.

18
doc/mkdocs/docs/api/basic_json/boolean_t.md
View File

@ -1,4 +1,4 @@
# basic_json::boolean_t
# <small>nlohmann::basic_json::</small>boolean_t
```cpp
using boolean_t = BooleanType;
@ -21,6 +21,22 @@ With the default values for `BooleanType` (`#!cpp bool`), the default value for
Boolean values are stored directly inside a `basic_json` type.
## Examples
??? example
The following code shows that `boolean_t` is by default, a typedef to `#!cpp bool`.
```cpp
--8<-- "examples/boolean_t.cpp"
```
Output:
```json
--8<-- "examples/boolean_t.output"
```
## Version history
- Added in version 1.0.0.

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

@ -1,4 +1,4 @@
# basic_json::cbegin
# <small>nlohmann::basic_json::</small>cbegin
```cpp
const_iterator cbegin() const noexcept;
@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

2
doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
View File

@ -1,4 +1,4 @@
# basic_json::cbor_tag_handler_t
# <small>nlohmann::basic_json::</small>cbor_tag_handler_t
```cpp
enum class cbor_tag_handler_t

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

@ -1,4 +1,4 @@
# basic_json::cend
# <small>nlohmann::basic_json::</small>cend
```cpp
const_iterator cend() const noexcept;
@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

22
doc/mkdocs/docs/api/basic_json/clear.md
View File

@ -1,4 +1,4 @@
# basic_json::clear
# <small>nlohmann::basic_json::</small>clear
```cpp
void clear() noexcept;
@ -7,15 +7,15 @@ void clear() noexcept;
Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](basic_json.md) would
have been called with the current value type from [`type()`](type.md):
Value type | initial value
----------- | -------------
null | `null`
boolean | `false`
string | `""`
number | `0`
binary | An empty byte vector
object | `{}`
array | `[]`
| Value type | initial value |
|------------|----------------------|
| null | `null` |
| boolean | `false` |
| string | `""` |
| number | `0` |
| binary | An empty byte vector |
| object | `{}` |
| array | `[]` |
Has the same effect as calling
@ -35,7 +35,7 @@ Linear in the size of the JSON value.
All iterators, pointers and references related to this container are invalidated.
## Example
## Examples
??? example

58
doc/mkdocs/docs/api/basic_json/contains.md
View File

@ -1,12 +1,17 @@
# basic_json::contains
# <small>nlohmann::basic_json::</small>contains
```cpp
// (1)
template<typename KeyT>
bool contains(KeyT && key) const;
// (2)
bool contains(const json_pointer& ptr) const;
```
Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the JSON
value is not an object, `#!cpp false` is returned.
1. Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the
JSON value is not an object, `#!cpp false` is returned.
2. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
## Template parameters
@ -17,27 +22,45 @@ value is not an object, `#!cpp false` is returned.
`key` (in)
: key value to check its existence.
`ptr` (in)
: JSON pointer to check its existence.
## Return value
`#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value is
not an object, `#!cpp false` is returned.
1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
is not an object, `#!cpp false` is returned.
2. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function does not throw exceptions.
2. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with
`0`.
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a
number.
## Complexity
Logarithmic in the size of the JSON object.
## Notes
This method always returns `#!cpp false` when executed on a JSON type that is not an object.
1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
2. This method can be executed on any JSON value type.
## Example
!!! info "Postconditions"
??? example
If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
## Examples
??? example "Example (1) check with key"
The example shows how `contains()` is used.
@ -51,6 +74,21 @@ This method always returns `#!cpp false` when executed on a JSON type that is no
--8<-- "examples/contains.output"
```
??? example "Example (1) check with JSON pointer"
The example shows how `contains()` is used.
```cpp
--8<-- "examples/contains_json_pointer.cpp"
```
Output:
```json
--8<-- "examples/contains_json_pointer.output"
```
## Version history
- Added in version 3.6.0.
1. Added in version 3.6.0.
2. Added in version 3.7.0.

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

@ -1,4 +1,4 @@
# basic_json::count
# <small>nlohmann::basic_json::</small>count
```cpp
template<typename KeyT>
@ -34,7 +34,7 @@ Logarithmic in the size of the JSON object.
This method always returns `0` when executed on a JSON type that is not an object.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::crbegin
# <small>nlohmann::basic_json::</small>crbegin
```cpp
const_reverse_iterator crbegin() const noexcept;
@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::rend
# <small>nlohmann::basic_json::</small>crend
```cpp
const_reverse_iterator crend() const noexcept;
@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

10
doc/mkdocs/docs/api/basic_json/diff.md
View File

@ -1,4 +1,4 @@
# basic_json::diff
# <small>nlohmann::basic_json::</small>diff
```cpp
static basic_json diff(const basic_json& source,
@ -33,11 +33,11 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
Linear in the lengths of `source` and `target`.
## Note
## Notes
Currently, only `remove`, `add`, and `replace` operations are generated.
## Example
## Examples
??? example
@ -53,6 +53,10 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
--8<-- "examples/diff.output"
```
## See also
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
## Version history
- Added in version 2.0.0.

23
doc/mkdocs/docs/api/basic_json/dump.md
View File

@ -1,4 +1,4 @@
# basic_json::dump
# <small>nlohmann::basic_json::</small>dump
```cpp
string_t dump(const int indent = -1,
@ -7,8 +7,9 @@ string_t dump(const int indent = -1,
const error_handler_t error_handler = error_handler_t::strict) const;
```
Serialization function for JSON values. The function tries to mimic Python's `json.dumps()` function, and currently
supports its `indent` and `ensure_ascii` parameters.
Serialization function for JSON values. The function tries to mimic Python's
[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently supports its `indent`
and `ensure_ascii` parameters.
## Parameters
@ -27,7 +28,7 @@ supports its `indent` and `ensure_ascii` parameters.
: how to react on decoding errors; there are three possible values (see [`error_handler_t`](error_handler_t.md):
`strict` (throws and exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all bytes are copied to the output
unchanged).
unchanged)).
## Return value
@ -37,6 +38,11 @@ string containing the serialization of the JSON value
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
## Exceptions
Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
is not UTF-8 encoded and `error_handler` is set to `strict`
## Complexity
Linear.
@ -48,7 +54,7 @@ Binary values are serialized as object containing two keys:
- "bytes": an array of bytes as integers
- "subtype": the subtype as integer or `#!json null` if the binary has no subtype
## Example
## Examples
??? example
@ -64,3 +70,10 @@ Binary values are serialized as object containing two keys:
```json
--8<-- "examples/dump.output"
```
## Version history
- Added in version 1.0.0.
- Indentation character `indent_char`, option `ensure_ascii` and exceptions added in version 3.0.0.
- Error handlers added in version 3.4.0.
- Serialization of binary values added in version 3.8.0.

2
doc/mkdocs/docs/api/basic_json/emplace.md
View File

@ -1,4 +1,4 @@
# basic_json::emplace
# <small>nlohmann::basic_json::</small>emplace
```cpp
template<class... Args>

2
doc/mkdocs/docs/api/basic_json/emplace_back.md
View File

@ -1,4 +1,4 @@
# basic_json::emplace_back
# <small>nlohmann::basic_json::</small>emplace_back
```cpp
template<class... Args>

22
doc/mkdocs/docs/api/basic_json/empty.md
View File

@ -1,4 +1,4 @@
# basic_json::empty
# <small>nlohmann::basic_json::</small>empty
```cpp
bool empty() const noexcept;
@ -10,15 +10,15 @@ Checks if a JSON value has no elements (i.e. whether its [`size()`](size.md) is
The return value depends on the different types and is defined as follows:
Value type | return value
----------- | -------------
null | `#!cpp true`
boolean | `#!cpp false`
string | `#!cpp false`
number | `#!cpp false`
binary | `#!cpp false`
object | result of function `object_t::empty()`
array | result of function `array_t::empty()`
| Value type | return value |
|------------|----------------------------------------|
| null | `#!cpp true` |
| boolean | `#!cpp false` |
| string | `#!cpp false` |
| number | `#!cpp false` |
| binary | `#!cpp false` |
| object | result of function `object_t::empty()` |
| array | result of function `array_t::empty()` |
## Exception safety
@ -44,7 +44,7 @@ bool empty() const noexcept
This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container
itself is empty which is `#!cpp false` in the case of a string.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::end
# <small>nlohmann::basic_json::</small>end
```cpp
iterator end() noexcept;
@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

25
doc/mkdocs/docs/api/basic_json/erase.md
View File

@ -1,4 +1,4 @@
# basic_json::erase
# <small>nlohmann::basic_json::</small>erase
```cpp
// (1)
@ -17,7 +17,7 @@ void erase(const size_type idx);
```
1. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and
dereferenceable. Thus the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
dereferenceable. Thus, the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
`pos`.
If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
@ -58,6 +58,10 @@ void erase(const size_type idx);
(`key` was not found) or `1` (`key` was found).
4. /
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function can throw the following exceptions:
@ -85,10 +89,6 @@ void erase(const size_type idx);
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
`"array index 17 is out of range"`
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
1. The complexity depends on the type:
@ -107,15 +107,14 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Notes
1. Invalidates iterators and references at or after the point of the
erase, including the `end()` iterator.
1. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator.
2. /
3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
4. /
## Example
## Examples
??? example
??? example "Example: (1) remove element given an iterator"
The example shows the effect of `erase()` for different JSON types using an iterator.
@ -129,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/erase__IteratorType.output"
```
??? example
??? example "Example: (2) remove elements given an iterator range"
The example shows the effect of `erase()` for different JSON types using an iterator range.
@ -143,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/erase__IteratorType_IteratorType.output"
```
??? example
??? example "Example: (3) remove element from a JSON object given a key"
The example shows the effect of `erase()` for different JSON types using an object key.
@ -157,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/erase__key_type.output"
```
??? example
??? example "Example: (4) remove element from a JSON array given an index"
The example shows the effect of `erase()` using an array index.

2
doc/mkdocs/docs/api/basic_json/error_handler_t.md
View File

@ -1,4 +1,4 @@
# basic_json::error_handler_t
# <small>nlohmann::basic_json::</small>error_handler_t
```cpp
enum class error_handler_t {

14
doc/mkdocs/docs/api/basic_json/exception.md
View File

@ -1,4 +1,4 @@
# basic_json::exception
# <small>nlohmann::basic_json::</small>exception
```cpp
class exception : public std::exception;
@ -44,7 +44,13 @@ Subclasses:
- **id** - the id of the exception
## Example
## Notes
To have nothrow-copy-constructible exceptions, we internally use `std::runtime_error` which can cope with
arbitrary-length error messages. Intermediate strings are built with static functions and then passed to the actual
constructor.
## Examples
??? example
@ -60,6 +66,10 @@ Subclasses:
--8<-- "examples/exception.output"
```
## See also
[List of exceptions](127.0.0.1:8000/home/exceptions/)
## Version history
- Since version 3.0.0.

10
doc/mkdocs/docs/api/basic_json/find.md
View File

@ -1,11 +1,11 @@
# basic_json::find
# <small>nlohmann::basic_json::</small>find
```cpp
template<typename KeyT>
iterator find(KeyT&& key);
template<typename KeyT>
const_iterator find(KeyT&& key) const
const_iterator find(KeyT&& key) const;
```
Finds an element in a JSON object with key equivalent to `key`. If the element is not found or the JSON value is not an
@ -38,7 +38,7 @@ Logarithmic in the size of the JSON object.
This method always returns `end()` when executed on a JSON type that is not an object.
## Example
## Examples
??? example
@ -54,6 +54,10 @@ This method always returns `end()` when executed on a JSON type that is not an o
--8<-- "examples/find__key_type.output"
```
## See also
- [contains](contains.md) checks whether a key exists
## Version history
- Added in version 1.0.0.

8
doc/mkdocs/docs/api/basic_json/flatten.md
View File

@ -1,4 +1,4 @@
# basic_json::flatten
# <small>nlohmann::basic_json::</small>flatten
```cpp
basic_json flatten() const;
@ -25,7 +25,7 @@ Linear in the size the JSON value.
Empty objects and arrays are flattened to `#!json null` and will not be reconstructed correctly by the
[`unflatten()`](unflatten.md) function.
## Example
## Examples
??? example
@ -41,6 +41,10 @@ Empty objects and arrays are flattened to `#!json null` and will not be reconstr
--8<-- "examples/flatten.output"
```
## See also
- [unflatten](unflatten.md) the reverse function
## Version history
- Added in version 2.0.0.

31
doc/mkdocs/docs/api/basic_json/from_bson.md
View File

@ -1,4 +1,4 @@
# basic_json::from_bson
# <small>nlohmann::basic_json::</small>from_bson
```cpp
// (1)
@ -18,6 +18,8 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
## Template parameters
`InputType`
@ -58,11 +60,16 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
encountered.
## Complexity
Linear in the size of the input.
## Example
## Examples
??? example
@ -78,6 +85,26 @@ Linear in the size of the input.
--8<-- "examples/from_bson.output"
```
## See also
- [BSON specification](http://bsonspec.org/spec.html)
- [to_bson](to_bson.md) for the analogous serialization
- [from_cbor](from_cbor.md) for the related CBOR format
- [from_msgpack](from_msgpack.md) for the related MessagePack format
- [from_ubjson](from_ubjson.md) for the related UBJSON format
## Version history
- Added in version 3.4.0.
!!! warning "Deprecation"
- Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
- Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_bson({ptr, ptr+len}, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

27
doc/mkdocs/docs/api/basic_json/from_cbor.md
View File

@ -1,4 +1,4 @@
# basic_json::from_cbor
# <small>nlohmann::basic_json::</small>from_cbor
```cpp
// (1)
@ -21,6 +21,8 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/cbor.md).
## Template parameters
`InputType`
@ -65,11 +67,20 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from CBOR were
used in the given input or if the input is not valid CBOR
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
but not found
## Complexity
Linear in the size of the input.
## Example
## Examples
??? example
@ -92,3 +103,15 @@ Linear in the size of the input.
- Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
- Added `allow_exceptions` parameter in version 3.2.0.
- Added `tag_handler` parameter in version 3.9.0.
!!! warning "Deprecation"
- Overload (2) replaces calls to `from_cbor` with a pointer and a length as first two parameters, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_cbor(ptr, len, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`.
- Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_cbor({ptr, ptr+len}, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

27
doc/mkdocs/docs/api/basic_json/from_msgpack.md
View File

@ -1,4 +1,4 @@
# basic_json::from_msgpack
# <small>nlohmann::basic_json::</small>from_msgpack
```cpp
// (1)
@ -18,6 +18,8 @@ Deserializes a given input to a JSON value using the MessagePack serialization f
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/messagepack.md).
## Template parameters
`InputType`
@ -58,11 +60,20 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from
MessagePack were used in the given input or if the input is not valid MessagePack
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
but not found
## Complexity
Linear in the size of the input.
## Example
## Examples
??? example
@ -84,3 +95,15 @@ Linear in the size of the input.
- Parameter `start_index` since version 2.1.1.
- Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
- Added `allow_exceptions` parameter in version 3.2.0.
!!! warning "Deprecation"
- Overload (2) replaces calls to `from_msgpack` with a pointer and a length as first two parameters, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_msgpack(ptr, len, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
- Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_msgpack({ptr, ptr+len}, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

26
doc/mkdocs/docs/api/basic_json/from_ubjson.md
View File

@ -1,4 +1,4 @@
# basic_json::from_ubjson
# <small>nlohmann::basic_json::</small>from_ubjson
```cpp
// (1)
@ -18,6 +18,8 @@ Deserializes a given input to a JSON value using the UBJSON (Universal Binary JS
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
## Template parameters
`InputType`
@ -58,11 +60,19 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
successfully
## Complexity
Linear in the size of the input.
## Example
## Examples
??? example
@ -82,3 +92,15 @@ Linear in the size of the input.
- Added in version 3.1.0.
- Added `allow_exceptions` parameter in version 3.2.0.
!!! warning "Deprecation"
- Overload (2) replaces calls to `from_ubjson` with a pointer and a length as first two parameters, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_ubjson(ptr, len, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
- Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp from_ubjson({ptr, ptr+len}, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

18
doc/mkdocs/docs/api/basic_json/front.md
View File

@ -1,4 +1,4 @@
# basic_json::front
# <small>nlohmann::basic_json::</small>front
```cpp
reference front();
@ -13,26 +13,26 @@ Returns a reference to the first element in the container. For a JSON container
In case of a structured type (array or object), a reference to the first element is returned. In case of number, string,
boolean, or binary values, a reference to the value is returned.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
If the JSON value is `#!json null`, exception
[`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Constant.
## Note
## Notes
!!! danger
Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**!
## Example
## Examples
??? example
@ -48,6 +48,10 @@ Constant.
--8<-- "examples/front.output"
```
## See also
- [back](back.md) to access the last element
## Version history
- Added in version 1.0.0.

8
doc/mkdocs/docs/api/basic_json/get.md
View File

@ -1,4 +1,4 @@
# basic_json::get
# <small>nlohmann::basic_json::</small>get
```cpp
// (1)
@ -31,7 +31,7 @@ constexpr const PointerType get_ptr() const noexcept;
return ret;
```
This overloads is chosen if:
This overload is chosen if:
- `ValueType` is not `basic_json`,
- `json_serializer<ValueType>` has a `from_json()` method of the form
@ -48,7 +48,7 @@ constexpr const PointerType get_ptr() const noexcept;
return JSONSerializer<ValueTypeCV>::from_json(*this);
```
This overloads is chosen if:
This overload is chosen if:
- `ValueType` is not `basic_json` and
- `json_serializer<ValueType>` has a `from_json()` method of the form
@ -94,7 +94,7 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
Writing data to the pointee (overload 3) of the result yields an undefined state.
## Example
## Examples
??? example

6
doc/mkdocs/docs/api/basic_json/get_allocator.md
View File

@ -1,4 +1,4 @@
# basic_json::get_allocator
# <small>nlohmann::basic_json::</small>get_allocator
```cpp
static allocator_type get_allocator();
@ -13,3 +13,7 @@ associated allocator
## Version history
- Unknown.
!!! note
This documentation page is a stub.

18
doc/mkdocs/docs/api/basic_json/get_binary.md
View File

@ -1,4 +1,4 @@
# basic_json::get_binary
# <small>nlohmann::basic_json::</small>get_binary
```cpp
binary_t& get_binary();
@ -24,6 +24,22 @@ Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) i
Constant.
## Examples
??? example
The following code shows how to query a binary value.
```cpp
--8<-- "examples/get_binary.cpp"
```
Output:
```json
--8<-- "examples/get_binary.output"
```
## Version history
- Added in version 3.8.0.

10
doc/mkdocs/docs/api/basic_json/get_ptr.md
View File

@ -1,8 +1,8 @@
# basic_json::get_ptr
# <small>nlohmann::basic_json::</small>get_ptr
```cpp
template<typename PointerType>
PointerType get_ptr();
PointerType get_ptr() noexcept;
template<typename PointerType>
constexpr const PointerType get_ptr() const noexcept;
@ -10,7 +10,7 @@ constexpr const PointerType get_ptr() const noexcept;
Implicit pointer access to the internally stored JSON value. No copies are made.
## Template arguments
## Template parameters
`PointerType`
: pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
@ -25,7 +25,7 @@ otherwise
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
No-throw guarantee: this function never throws exceptions.
## Complexity
@ -37,7 +37,7 @@ Constant.
Writing data to the pointee of the result yields an undefined state.
## Example
## Examples
??? example

6
doc/mkdocs/docs/api/basic_json/get_ref.md
View File

@ -1,4 +1,4 @@
# basic_json::get_ref
# <small>nlohmann::basic_json::</small>get_ref
```cpp
template<typename ReferenceType>
@ -10,7 +10,7 @@ const ReferenceType get_ref() const;
Implicit reference access to the internally stored JSON value. No copies are made.
## Template arguments
## Template parameters
`ReferenceType`
: reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
@ -42,7 +42,7 @@ Constant.
Writing data to the referee of the result yields an undefined state.
## Example
## Examples
??? example

8
doc/mkdocs/docs/api/basic_json/get_to.md
View File

@ -1,10 +1,10 @@
# basic_json::get_to
# <small>nlohmann::basic_json::</small>get_to
```cpp
template<typename ValueType>
ValueType& get_to(ValueType& v) const noexcept(
noexcept(JSONSerializer<ValueType>::from_json(
std::declval<const basic_json_t&>(), v)))
std::declval<const basic_json_t&>(), v)));
```
Explicit type conversion between the JSON value and a compatible value. The value is filled into the input parameter by
@ -16,7 +16,7 @@ ValueType v;
JSONSerializer<ValueType>::from_json(*this, v);
```
This overloads is chosen if:
This overload is chosen if:
- `ValueType` is not `basic_json`,
- `json_serializer<ValueType>` has a `from_json()` method of the form `void from_json(const basic_json&, ValueType&)`
@ -34,7 +34,7 @@ the input parameter, allowing chaining calls
Depends on what `json_serializer<ValueType>` `from_json()` method throws
## Example
## Examples
??? example

179
doc/mkdocs/docs/api/basic_json/index.md
View File

@ -1,6 +1,6 @@
# basic_json
# <small>nlohmann::</small>basic_json
Defined in header `<json.hpp>`
<small>Defined in header `<nlohmann/json.hpp>`</small>
```cpp
template<
@ -18,41 +18,83 @@ template<
class basic_json;
```
## Template parameters
| Template parameter | Description | Derived type |
|----------------------|---------------------------------------------------------------------------|---------------------------------------------|
| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) |
| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) |
| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) |
| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) |
| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
| `AllocatorType` | type of the allocator to use | |
| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) |
## Specializations
- [**json**](../json.md) - default specialization
- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
## Template parameters
| Template parameter | Description | Derived type |
| -------------------- | ----------- | ------------ |
| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) |
| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) |
| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) |
| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) |
| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
| `AllocatorType` | type of the allocator to use | |
| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) |
## Iterator invalidation
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.md) - the default serializer
- [**adl_serializer**](../adl_serializer) - the default serializer
- [**value_t**](value_t.md) - the JSON type enumeration
- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
- initializer_list_t
- **initializer_list_t** - type for initializer lists of `basic_json` values
- [**input_format_t**](input_format_t.md) - type to choose the format to parse
- json_sax_t
- [**json_sax_t**](../json_sax/index.md) - type for SAX events
### Exceptions
@ -65,21 +107,21 @@ Todo
### Container types
| Type | Definition |
| ------------------------ | ---------- |
| `value_type` | `#!cpp basic_json` |
| `reference` | `#!cpp value_type&` |
| `const_reference` | `#!cpp const value_type&` |
| `difference_type` | `#!cpp std::ptrdiff_t` |
| `size_type` | `#!cpp std::size_t` |
| `allocator_type` | `#!cpp AllocatorType<basic_json>` |
| `pointer` | `#!cpp std::allocator_traits<allocator_type>::pointer` |
| `const_pointer` | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| Type | Definition |
|--------------------------|-----------------------------------------------------------------------------------------------------------|
| `value_type` | `#!cpp basic_json` |
| `reference` | `#!cpp value_type&` |
| `const_reference` | `#!cpp const value_type&` |
| `difference_type` | `#!cpp std::ptrdiff_t` |
| `size_type` | `#!cpp std::size_t` |
| `allocator_type` | `#!cpp AllocatorType<basic_json>` |
| `pointer` | `#!cpp std::allocator_traits<allocator_type>::pointer` |
| `const_pointer` | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| `const_iterator` | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| `reverse_iterator` | reverse iterator, derived from `iterator` |
| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
| `iteration_proxy` | helper type for [`items`](items.md) function |
| `reverse_iterator` | reverse iterator, derived from `iterator` |
| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
| `iteration_proxy` | helper type for [`items`](items.md) function |
### JSON value data types
@ -103,9 +145,9 @@ Todo
- [(constructor)](basic_json.md)
- [(destructor)](~basic_json.md)
- [**operator=**](operator=.md) - copy assignment
- [**array**](array_t.md) (static) - explicitly create an array
- [**binary**](binary.md) (static) - explicitly create a binary array
- [**object**](object_t.md) (static) - explicitly create an object
- [**array**](array_t.md) (_static_) - explicitly create an array
- [**binary**](binary.md) (_static_) - explicitly create a binary array
- [**object**](object_t.md) (_static_) - explicitly create an object
### Object inspection
@ -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
@ -197,13 +239,12 @@ Access to the JSON value
### Serialization / Dumping
- [**dump**](dump.md) - serialization
- to_string - user-defined to_string function for JSON values
### Deserialization / Parsing
- [**parse**](parse.md) (static) - deserialize from a compatible input
- [**accept**](accept.md) (static) - check if the input is valid JSON
- [**sax_parse**](sax_parse.md) (static) - generate SAX events
- [**parse**](parse.md) (_static_) - deserialize from a compatible input
- [**accept**](accept.md) (_static_) - check if the input is valid JSON
- [**sax_parse**](sax_parse.md) (_static_) - generate SAX events
### JSON Pointer functions
@ -213,7 +254,7 @@ Access to the JSON value
### JSON Patch functions
- [**patch**](patch.md) - applies a JSON patch
- [**diff**](diff.md) (static) - creates a diff as a JSON patch
- [**diff**](diff.md) (_static_) - creates a diff as a JSON patch
### JSON Merge Patch functions
@ -226,19 +267,20 @@ Access to the JSON value
### Binary formats
- [**from_bson**](from_bson.md) (static) - create a JSON value from an input in BSON format
- [**from_cbor**](from_cbor.md) (static) - create a JSON value from an input in CBOR format
- [**from_msgpack**](from_msgpack.md) (static) - create a JSON value from an input in MessagePack format
- [**from_ubjson**](from_ubjson.md) (static) - create a JSON value from an input in UBJSON format
- [**to_bson**](to_bson.md) (static) - create a BSON serialization of a given JSON value
- [**to_cbor**](to_cbor.md) (static) - create a CBOR serialization of a given JSON value
- [**to_msgpack**](to_msgpack.md) (static) - create a MessagePack serialization of a given JSON value
- [**to_ubjson**](to_ubjson.md) (static) - create a UBJSON serialization of a given JSON value
- [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
- [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
- [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
- [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
- [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
- [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
- [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value
- [**to_ubjson**](to_ubjson.md) (_static_) - create a UBJSON serialization of a given JSON value
## Non-member functions
- operator<<(std::ostream&) - serialize to stream
- operator>>(std::istream&) - deserialize from stream
- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
## Literals
@ -247,6 +289,29 @@ Access to the JSON value
## Helper classes
- std::hash<nlohmann::json\>
- std::less<nlohmann::value_t\>
- std::swap<nlohmann::json\>
- [**std::hash&lt;basic_json&gt;**](std_hash.md) - return a hash value for a JSON object
- [**std::swap&lt;basic_json&gt;**](std_swap.md) - exchanges the values of two JSON objects
## Example
??? example
The example shows how the library is used.
```cpp
--8<-- "examples/README.cpp"
```
Output:
```json
--8<-- "examples/README.output"
```
## See also
- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
## Version history
- Added in version 1.0.0.

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

@ -1,4 +1,4 @@
# basic_json::input_format_t
# <small>nlohmann::basic_json::</small>input_format_t
```cpp
enum class input_format_t {
@ -25,7 +25,7 @@ ubjson
: UBJSON (Universal Binary JSON)
bson
: BSON (Bin­ary JSON)
: BSON (Binary JSON)
## Version history

32
doc/mkdocs/docs/api/basic_json/insert.md
View File

@ -1,4 +1,4 @@
# basic_json::insert
# <small>nlohmann::basic_json::</small>insert
```cpp
// (1)
@ -18,11 +18,11 @@ iterator insert(const_iterator pos, initializer_list_t ilist);
void insert(const_iterator first, const_iterator last);
```
1. Inserts element `val` to array before iterator `pos`.
2. Inserts `cnt` copies of `val` to array before iterator `pos`.
3. Inserts elements from range `[first, last)` to array before iterator `pos`.
4. Inserts elements from initializer list `ilist` to array before iterator `pos`.
5. Inserts elements from range `[first, last)` to object.
1. Inserts element `val` into array before iterator `pos`.
2. Inserts `cnt` copies of `val` into array before iterator `pos`.
3. Inserts elements from range `[first, last)` into array before iterator `pos`.
4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
5. Inserts elements from range `[first, last)` into object.
## Parameters
@ -52,6 +52,10 @@ void insert(const_iterator first, const_iterator last);
4. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
5. /
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function can throw the following exceptions:
@ -86,10 +90,6 @@ void insert(const_iterator first, const_iterator last);
- Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
do not belong to the same JSON value; example: `"iterators do not fit"`
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
1. Constant plus linear in the distance between `pos` and end of the container.
@ -98,9 +98,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
4. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container.
5. Logarithmic: `O(N*log(size() + N))`, where `N` is the number of elements to insert.
## Example
## Examples
??? example
??? example "Example (1): insert element into array"
The example shows how `insert()` is used.
@ -114,7 +114,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert.output"
```
??? example
??? example "Example (2): insert copies of element into array"
The example shows how `insert()` is used.
@ -128,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__count.output"
```
??? example
??? example "Example (3): insert range of elements into array"
The example shows how `insert()` is used.
@ -142,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__range.output"
```
??? example
??? example "Example (4): insert elements from initializer list into array"
The example shows how `insert()` is used.
@ -156,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__ilist.output"
```
??? example
??? example "Example (5): insert range of elements into object"
The example shows how `insert()` is used.

14
doc/mkdocs/docs/api/basic_json/invalid_iterator.md
View File

@ -1,4 +1,4 @@
# basic_json::invalid_iterator
# <small>nlohmann::basic_json::</small>invalid_iterator
```cpp
class invalid_iterator : public exception;
@ -6,7 +6,7 @@ class invalid_iterator : public exception;
This exception is thrown if iterators passed to a library function do not match the expected semantics.
Exceptions have ids 2xx.
Exceptions have ids 2xx (see [list of iterator errors](../../home/exceptions.md#iterator-errors)).
```plantuml
std::exception <|-- basic_json::exception
@ -38,7 +38,7 @@ class basic_json::invalid_iterator #FFFF00 {}
- **id** - the id of the exception
## Example
## Examples
??? example
@ -54,6 +54,14 @@ class basic_json::invalid_iterator #FFFF00 {}
--8<-- "examples/invalid_iterator.output"
```
## See also
- [List of iterator errors](../../home/exceptions.md#iterator-errors)
- [`parse_error`](parse_error.md) for exceptions indicating a parse error
- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
- [`other_error`](other_error.md) for exceptions indicating other library errors
## Version history
- Since version 3.0.0.

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

@ -1,4 +1,4 @@
# basic_json::is_array
# <small>nlohmann::basic_json::</small>is_array
```cpp
constexpr bool is_array() const noexcept;
@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::is_binary
# <small>nlohmann::basic_json::</small>is_binary
```cpp
constexpr bool is_binary() const noexcept;
@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::is_boolean
# <small>nlohmann::basic_json::</small>is_boolean
```cpp
constexpr bool is_boolean() const noexcept;
@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::is_discarded
# <small>nlohmann::basic_json::</small>is_discarded
```cpp
constexpr bool is_discarded() const noexcept;
@ -51,7 +51,7 @@ Constant.
This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
during parsing, but will be removed when inside a structured value or replaced by null in other cases.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::is_null
# <small>nlohmann::basic_json::</small>is_null
```cpp
constexpr bool is_null() const noexcept;
@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

10
doc/mkdocs/docs/api/basic_json/is_number.md
View File

@ -1,4 +1,4 @@
# basic_json::is_number
# <small>nlohmann::basic_json::</small>is_number
```cpp
constexpr bool is_number() const noexcept;
@ -28,7 +28,7 @@ constexpr bool is_number() const noexcept
}
```
## Example
## Examples
??? example
@ -44,6 +44,12 @@ constexpr bool is_number() const noexcept
--8<-- "examples/is_number.output"
```
## See also
- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if value is a floating-point number
## Version history
- Added in version 1.0.0.

10
doc/mkdocs/docs/api/basic_json/is_number_float.md
View File

@ -1,4 +1,4 @@
# basic_json::is_number_float
# <small>nlohmann::basic_json::</small>is_number_float
```cpp
constexpr bool is_number_float() const noexcept;
@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example
@ -35,6 +35,12 @@ Constant.
--8<-- "examples/is_number_float.output"
```
## See also
- [is_number()](is_number.md) check if value is a number
- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
## Version history
- Added in version 1.0.0.

10
doc/mkdocs/docs/api/basic_json/is_number_integer.md
View File

@ -1,4 +1,4 @@
# basic_json::is_number_integer
# <small>nlohmann::basic_json::</small>is_number_integer
```cpp
constexpr bool is_number_integer() const noexcept;
@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example
@ -35,6 +35,12 @@ Constant.
--8<-- "examples/is_number_integer.output"
```
## See also
- [is_number()](is_number.md) check if value is a number
- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if value is a floating-point number
## Version history
- Added in version 1.0.0.

10
doc/mkdocs/docs/api/basic_json/is_number_unsigned.md
View File

@ -1,4 +1,4 @@
# basic_json::is_number_unsigned
# <small>nlohmann::basic_json::</small>is_number_unsigned
```cpp
constexpr bool is_number_unsigned() const noexcept;
@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example
@ -35,6 +35,12 @@ Constant.
--8<-- "examples/is_number_unsigned.output"
```
## See also
- [is_number()](is_number.md) check if value is a number
- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
- [is_number_float()](is_number_float.md) check if value is a floating-point number
## Version history
- Added in version 2.0.0.

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

@ -1,4 +1,4 @@
# basic_json::is_object
# <small>nlohmann::basic_json::</small>is_object
```cpp
constexpr bool is_object() const noexcept;
@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

13
doc/mkdocs/docs/api/basic_json/is_primitive.md
View File

@ -1,4 +1,4 @@
# basic_json::is_primitive
# <small>nlohmann::basic_json::</small>is_primitive
```cpp
constexpr bool is_primitive() const noexcept;
@ -38,7 +38,7 @@ The term *primitive* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
This library extends primitive types to binary types, because binary types are roughly comparable to strings. Hence,
`is_primitive()` returns `#!cpp true` for binary values.
## Example
## Examples
??? example
@ -54,6 +54,15 @@ This library extends primitive types to binary types, because binary types are
--8<-- "examples/is_primitive.output"
```
## See also
- [is_structured()](is_structured.md) returns whether JSON value is structured
- [is_null()](is_null.md) returns whether JSON value is `null`
- [is_string()](is_string.md) returns whether JSON value is a string
- [is_boolean()](is_boolean.md) returns whether JSON value is a boolean
- [is_number()](is_number.md) returns whether JSON value is a number
- [is_binary()](is_binary.md) returns whether JSON value is a binary array
## Version history
- Added in version 1.0.0.

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

@ -1,4 +1,4 @@
# basic_json::is_string
# <small>nlohmann::basic_json::</small>is_string
```cpp
constexpr bool is_string() const noexcept;
@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

19
doc/mkdocs/docs/api/basic_json/is_structured.md
View File

@ -1,4 +1,4 @@
# basic_json::is_structured
# <small>nlohmann::basic_json::</small>is_structured
```cpp
constexpr bool is_structured() const noexcept;
@ -18,6 +18,15 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Possible implementation
```cpp
constexpr bool is_primitive() const noexcept
{
return is_array() || is_object();
}
```
## Notes
The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
@ -27,7 +36,7 @@ The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259)
Note that though strings are containers in C++, they are treated as primitive values in JSON.
## Example
## Examples
??? example
@ -43,6 +52,12 @@ Note that though strings are containers in C++, they are treated as primitive va
--8<-- "examples/is_structured.output"
```
## See also
- [is_primitive()](is_primitive.md) returns whether JSON value is primitive
- [is_array()](is_array.md) returns whether value is an array
- [is_object()](is_object.md) returns whether value is an object
## Version history
- Added in version 1.0.0.

16
doc/mkdocs/docs/api/basic_json/items.md
View File

@ -1,11 +1,11 @@
# basic_json::items
# <small>nlohmann::basic_json::</small>items
```cpp
iteration_proxy<iterator> items() noexcept;
iteration_proxy<const_iterator> items() const noexcept;
```
This function allows to access `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
This function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
reference to the JSON values is returned, so there is no access to the underlying iterator.
For loop without `items()` function:
@ -36,7 +36,7 @@ for (auto& el : j_object.items())
}
```
The `items()` function also allows to use
The `items()` function also allows using
[structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding) (C++17):
```cpp
@ -68,7 +68,7 @@ When iterating over an array, `key()` will return the index of the element as st
Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
<https://github.com/nlohmann/json/issues/2040> for more information.
## Example
## Examples
??? example
@ -86,11 +86,15 @@ When iterating over an array, `key()` will return the index of the element as st
## Version history
- Added in version 3.0.0.
- Added `iterator_wrapper` in version 3.0.0.
- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
- Added structured binding support in version 3.5.0.
!!! note
!!! warning "Deprecation"
This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been
deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all
occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

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

@ -1,4 +1,4 @@
# basic_json::json_serializer
# <small>nlohmann::basic_json::</small>json_serializer
```cpp
template<typename T, typename SFINAE>
@ -17,7 +17,7 @@ using json_serializer = JSONSerializer<T, SFINAE>;
#### Default type
The default values for `json_serializer` is [`adl_serializer`](../adl_serializer.md).
The default values for `json_serializer` is [`adl_serializer`](../adl_serializer).
## Version history

22
doc/mkdocs/docs/api/basic_json/max_size.md
View File

@ -1,4 +1,4 @@
# basic_json::max_size
# <small>nlohmann::basic_json::</small>max_size
```cpp
size_type max_size() const noexcept;
@ -11,15 +11,15 @@ i.e. `std::distance(begin(), end())` for the JSON value.
The return value depends on the different types and is defined as follows:
Value type | return value
----------- | -------------
null | `0` (same as [`size()`](size.md))
boolean | `1` (same as [`size()`](size.md))
string | `1` (same as [`size()`](size.md))
number | `1` (same as [`size()`](size.md))
binary | `1` (same as [`size()`](size.md))
object | result of function `object_t::max_size()`
array | result of function `array_t::max_size()`
| Value type | return value |
|------------|-------------------------------------------|
| null | `0` (same as [`size()`](size.md)) |
| boolean | `1` (same as [`size()`](size.md)) |
| string | `1` (same as [`size()`](size.md)) |
| number | `1` (same as [`size()`](size.md)) |
| binary | `1` (same as [`size()`](size.md)) |
| object | result of function `object_t::max_size()` |
| array | result of function `array_t::max_size()` |
## Exception safety
@ -36,7 +36,7 @@ constant complexity.
This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of
string elements the JSON value can store which is `1`.
## Example
## Examples
??? example

9
doc/mkdocs/docs/api/basic_json/merge_patch.md
View File

@ -1,4 +1,4 @@
# basic_json::merge_patch
# <small>nlohmann::basic_json::</small>merge_patch
```cpp
void merge_patch(const basic_json& apply_patch);
@ -37,7 +37,7 @@ Thereby, `Target` is the current object; that is, the patch is applied to the cu
Linear in the lengths of `apply_patch`.
## Example
## Examples
??? example
@ -53,6 +53,11 @@ Linear in the lengths of `apply_patch`.
--8<-- "examples/merge_patch.output"
```
## See also
- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
- [patch](patch.md) apply a JSON patch
## Version history
- Added in version 3.0.0.

44
doc/mkdocs/docs/api/basic_json/meta.md
View File

@ -1,4 +1,4 @@
# basic_json::meta
# <small>nlohmann::basic_json::</small>meta
```cpp
static basic_json meta();
@ -11,14 +11,14 @@ the platform and compiler.
JSON object holding version information
key | description
----------- | ---------------
`compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
`copyright` | The copyright line for the library as string.
`name` | The name of the library as string.
`platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
`url` | The URL of the project as string.
`version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
| key | description |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). |
| `copyright` | The copyright line for the library as string. |
| `name` | The name of the library as string. |
| `platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`. |
| `url` | The URL of the project as string. |
| `version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string). |
## Exception safety
@ -28,20 +28,22 @@ Strong guarantee: if an exception is thrown, there are no changes to any JSON va
Constant.
## Example
## Examples
The following code shows an example output of the `meta()`
function.
??? example
```cpp
--8<-- "examples/meta.cpp"
```
Output:
```json
--8<-- "examples/meta.output"
```
The following code shows an example output of the `meta()`
function.
```cpp
--8<-- "examples/meta.cpp"
```
Output:
```json
--8<-- "examples/meta.output"
```
## Version history

18
doc/mkdocs/docs/api/basic_json/number_float_t.md
View File

@ -1,4 +1,4 @@
# basic_json::number_float_t
# <small>nlohmann::basic_json::</small>number_float_t
```cpp
using number_float_t = NumberFloatType;
@ -49,6 +49,22 @@ and be serialized to `null`.
Floating-point number values are stored directly inside a `basic_json` type.
## Examples
??? example
The following code shows that `number_float_t` is by default, a typedef to `#!cpp double`.
```cpp
--8<-- "examples/number_float_t.cpp"
```
Output:
```json
--8<-- "examples/number_float_t.output"
```
## Version history
- Added in version 1.0.0.

20
doc/mkdocs/docs/api/basic_json/number_integer_t.md
View File

@ -1,4 +1,4 @@
# basic_json::number_integer_t
# <small>nlohmann::basic_json::</small>number_integer_t
```cpp
using number_integer_t = NumberIntegerType;
@ -45,7 +45,7 @@ range will yield over/underflow when used in a constructor. During deserializati
will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
[RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
> interoperable in the sense that implementations will agree exactly on their numeric values.
As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
@ -55,6 +55,22 @@ interoperable.
Integer number values are stored directly inside a `basic_json` type.
## Examples
??? example
The following code shows that `number_integer_t` is by default, a typedef to `#!cpp std::int64_t`.
```cpp
--8<-- "examples/number_integer_t.cpp"
```
Output:
```json
--8<-- "examples/number_integer_t.output"
```
## Version history
- Added in version 1.0.0.

18
doc/mkdocs/docs/api/basic_json/number_unsigned_t.md
View File

@ -1,4 +1,4 @@
# basic_json::number_unsigned_t
# <small>nlohmann::basic_json::</small>number_unsigned_t
```cpp
using number_unsigned_t = NumberUnsignedType;
@ -55,6 +55,22 @@ range [0, UINT64_MAX], this class's integer type is interoperable.
Integer number values are stored directly inside a `basic_json` type.
## Examples
??? example
The following code shows that `number_unsigned_t` is by default, a typedef to `#!cpp std::uint64_t`.
```cpp
--8<-- "examples/number_unsigned_t.cpp"
```
Output:
```json
--8<-- "examples/number_unsigned_t.output"
```
## Version history
- Added in version 2.0.0.

15
doc/mkdocs/docs/api/basic_json/object.md
View File

@ -1,4 +1,4 @@
# basic_json::object
# <small>nlohmann::basic_json::</small>object
```cpp
static basic_json object(initializer_list_t init = {});
@ -16,6 +16,10 @@ elements must be strings. If the initializer list is empty, the empty object `#!
JSON object value
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose
@ -23,10 +27,6 @@ first elements are strings. In this case, no object can be created. When such a
`basic_json(initializer_list_t, bool, value_t)`, an array would have been created from the passed initializer list
`init`. See example below.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Linear in the size of `init`.
@ -53,6 +53,11 @@ the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`
--8<-- "examples/object.output"
```
## See also
- [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
- [`array`](array.md) - create a JSON array value from an initializer list
## Version history
- Added in version 1.0.0.

8
doc/mkdocs/docs/api/basic_json/object_comparator_t.md
View File

@ -1,11 +1,9 @@
# basic_json::object_comparator_t
# <small>nlohmann::basic_json::</small>object_comparator_t
```cpp
// until C++14
using object_comparator_t = std::less<StringType>;
using object_comparator_t = std::less<StringType>; // until C++14
// since C++14
using object_comparator_t = std::less<>;
using object_comparator_t = std::less<>; // since C++14
```
The comparator used in [`object_t`](object_t.md).

18
doc/mkdocs/docs/api/basic_json/object_t.md
View File

@ -1,4 +1,4 @@
# basic_json::object_t
# <small>nlohmann::basic_json::</small>object_t
```cpp
using object_t = ObjectType<StringType,
@ -92,6 +92,22 @@ return name/value pairs in a different order than they were originally stored. I
alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects.
## Examples
??? example
The following code shows that `object_t` is by default, a typedef to `#!cpp std::map<json::string_t, json>`.
```cpp
--8<-- "examples/object_t.cpp"
```
Output:
```json
--8<-- "examples/object_t.output"
```
## Version history
- Added in version 1.0.0.

10
doc/mkdocs/docs/api/basic_json/operator+=.md
View File

@ -1,4 +1,4 @@
# basic_json::operator+=
# <small>nlohmann::basic_json::</small>operator+=
```cpp
// (1)
@ -18,7 +18,7 @@ reference operator+=(initializer_list_t init);
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
is created before inserting `val`.
3. This function allows to use `operator+=` with an initializer list. In case
3. This function allows using `operator+=` with an initializer list. In case
1. the current value is an object,
2. the initializer list `init` contains only two elements, and
@ -62,7 +62,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
## Examples
??? example
??? example "Example: (1) add element to array"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
was silently converted to a JSON array.
@ -77,7 +77,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
--8<-- "examples/push_back.output"
```
??? example
??? example "Example: (2) add element to object"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
was silently converted to a JSON object.
@ -92,7 +92,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
--8<-- "examples/push_back__object_t__value.output"
```
??? example
??? example "Example: (3) add to object from initializer list"
The example shows how initializer lists are treated as objects when possible.

4
doc/mkdocs/docs/api/basic_json/operator=.md
View File

@ -1,4 +1,4 @@
# basic_json::operator=
# <small>nlohmann::basic_json::</small>operator=
```cpp
basic_json& operator=(basic_json other) noexcept (
@ -21,7 +21,7 @@ constructor, destructor, and the `swap()` member function.
Linear.
## Example
## Examples
??? example

49
doc/mkdocs/docs/api/basic_json/operator[].md
View File

@ -1,4 +1,4 @@
# basic_json::operator[]
# <small>nlohmann::basic_json::</small>operator[]
```cpp
// (1)
@ -18,8 +18,8 @@ reference operator[](const json_pointer& ptr);
const_reference operator[](const json_pointer& ptr) const;
```
1. Returns a reference to the element at specified location `idx`.
2. Returns a reference to the element at with specified key `key`.
1. Returns a reference to the array element at specified location `idx`.
2. Returns a reference to the object element at with specified key `key`.
3. Returns a reference to the element at with specified JSON pointer `ptr`.
## Template parameters
@ -44,6 +44,10 @@ const_reference operator[](const json_pointer& ptr) const;
2. reference to the element at key `key`
3. reference to the element pointed to by `ptr`
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. The function can throw the following exceptions:
@ -62,6 +66,12 @@ const_reference operator[](const json_pointer& ptr) const;
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved.
## Complexity
1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
2. Logarithmic in the size of the container.
3. Constant
## Notes
!!! danger
@ -80,26 +90,16 @@ const_reference operator[](const json_pointer& ptr) const;
In particular:
- If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null`
- If the JSON pointer points to an object key that does not exist, it is created and filled with a `#!json null`
value before a reference to it is returned.
- If the JSON pointer points to an array index that does not exist, it is created an filled with a `#!json null`
- If the JSON pointer points to an array index that does not exist, it is created and filled with a `#!json null`
value before a reference to it is returned. All indices between the current maximum and the given index are also
filled with `#!json null`.
- The special value `-` is treated as a synonym for the index past the end.
## Exception safety
## Examples
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
1. Constant if `idx` is in the range of the array. Otherwise linear in `idx - size()`.
2. Logarithmic in the size of the container.
3. Constant
## Example
??? example
??? example "Example (1): access specified array element"
The example below shows how array elements can be read and written using `[]` operator. Note the addition of
`#!json null` values.
@ -114,7 +114,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__size_type.output"
```
??? example
??? example "Example (1): access specified array element"
The example below shows how array elements can be read using the `[]` operator.
@ -128,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__size_type_const.output"
```
??? example
??? example "Example (2): access specified object element"
The example below shows how object elements can be read and written using the `[]` operator.
@ -142,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__key_type.output"
```
??? example
??? example "Example (2): access specified object element"
The example below shows how object elements can be read using the `[]` operator.
@ -156,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__key_type_const.output"
```
??? example
??? example "Example (3): access specified element via JSON Pointer"
The example below shows how values can be read and written using JSON Pointers.
@ -170,7 +170,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorjson_pointer.output"
```
??? example
??? example "Example (3): access specified element via JSON Pointer"
The example below shows how values can be read using JSON Pointers.
@ -184,6 +184,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorjson_pointer_const.output"
```
## See also
- see [`at`](at.md) for access by reference with range checking
- see [`value`](value.md) for access with default value
## Version history
1. Added in version 1.0.0.

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

@ -1,4 +1,4 @@
# basic_json::operator ValueType
# <small>nlohmann::basic_json::</small>operator ValueType
```cpp
template<typename ValueType>
@ -45,7 +45,7 @@ explicit operator ValueType() const;
That is, implicit conversions can be switched off by defining
[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
## Example
## Examples
??? example

18
doc/mkdocs/docs/api/basic_json/operator_eq.md
View File

@ -1,4 +1,4 @@
# basic_json::operator==
# <small>nlohmann::basic_json::</small>operator==
```cpp
bool operator==(const_reference lhs, const_reference rhs) noexcept;
@ -85,7 +85,7 @@ Linear.
}
```
## Example
## Examples
??? example
@ -101,6 +101,20 @@ Linear.
--8<-- "examples/operator__equal.output"
```
??? example
The example demonstrates comparing several JSON types against the null pointer (JSON `#!json null`).
```cpp
--8<-- "examples/operator__equal__nullptr_t.cpp"
```
Output:
```json
--8<-- "examples/operator__equal__nullptr_t.output"
```
## Version history
- Added in version 1.0.0.

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

@ -1,4 +1,4 @@
# basic_json::operator>=
# <small>nlohmann::basic_json::</small>operator>=
```cpp
bool operator>=(const_reference lhs, const_reference rhs) noexcept,
@ -38,7 +38,7 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::operator>
# <small>nlohmann::basic_json::</small>operator>
```cpp
bool operator>(const_reference lhs, const_reference rhs) noexcept,
@ -37,7 +37,7 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Example
## Examples
??? example

65
doc/mkdocs/docs/api/basic_json/operator_gtgt.md Normal file
View File

@ -0,0 +1,65 @@
# operator>>(basic_json)
```cpp
std::istream& operator>>(std::istream& i, basic_json& j);
```
Deserializes an input stream to a JSON value.
## Parameters
`i` (in, out)
: input stream to read a serialized JSON value from
`j` (in, out)
: JSON value to write the deserialized input to
## Return value
the stream `i`
## Exceptions
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate
error.
- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
## Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser.
## Notes
A UTF-8 byte order mark is silently ignored.
## Examples
??? example
The example below shows how a JSON value is constructed by reading a serialization from a stream.
```cpp
--8<-- "examples/operator_deserialize.cpp"
```
Output:
```json
--8<-- "examples/operator_deserialize.output"
```
## See also
- [accept](accept.md) - check if the input is valid JSON
- [parse](parse.md) - deserialize from a compatible input
## Version history
- Added in version 1.0.0
!!! warning "Deprecation"
This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
with `#!cpp i >> j;`.

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

@ -1,4 +1,4 @@
# basic_json::operator<=
# <small>nlohmann::basic_json::</small>operator<=
```cpp
bool operator<=(const_reference lhs, const_reference rhs) noexcept,
@ -38,7 +38,7 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Example
## Examples
??? example

20
doc/mkdocs/docs/api/basic_json/operator_literal_json.md
View File

@ -1,7 +1,7 @@
# basic_json::operator""_json
# <small>nlohmann::basic_json::</small>operator""_json
```cpp
json operator "" _json(const char* s, std::size_t n)
json operator "" _json(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a
@ -27,6 +27,22 @@ The function can throw anything that [`parse(s, s+n)`](parse.md) would throw.
Linear.
## Examples
??? example
The following code shows how to create JSON values from string literals.
```cpp
--8<-- "examples/operator_literal_json.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json.output"
```
## Version history
- Added in version 1.0.0.

26
doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md
View File

@ -1,11 +1,11 @@
# basic_json::operator""_json_pointer
# <small>nlohmann::basic_json::</small>operator""_json_pointer
```cpp
json_pointer operator "" _json_pointer(const char* s, std::size_t n)
json_pointer operator "" _json_pointer(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
to a string literal and returns a [`json_pointer`](../json_pointer.md) object if no parse error occurred.
to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred.
## Parameters
@ -17,16 +17,32 @@ to a string literal and returns a [`json_pointer`](../json_pointer.md) object if
## Return value
[`json_pointer`](../json_pointer.md) value parsed from `s`
[`json_pointer`](../json_pointer/index.md) value parsed from `s`
## Exceptions
The function can throw anything that [`json_pointer::json_pointer`](../json_pointer.md) would throw.
The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON Pointers from string literals.
```cpp
--8<-- "examples/operator_literal_json_pointer.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json_pointer.output"
```
## Version history
- Added in version 2.0.0.

6
doc/mkdocs/docs/api/basic_json/operator_lt.md
View File

@ -1,7 +1,7 @@
# basic_json::operator<
# <small>nlohmann::basic_json::</small>operator<
```cpp
bool operator<(const_reference lhs, const_reference rhs) noexcept,
bool operator<(const_reference lhs, const_reference rhs) noexcept;
template<typename ScalarType>
bool operator<(const_reference lhs, const ScalarType rhs) noexcept;
@ -52,7 +52,7 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Example
## Examples
??? example

62
doc/mkdocs/docs/api/basic_json/operator_ltlt.md Normal file
View File

@ -0,0 +1,62 @@
# operator<<(basic_json)
```cpp
std::ostream& operator<<(std::ostream& o, const basic_json& j);
```
Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
[`dump`](dump.md) member function.
- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result
is the same as calling `dump(4)`.
- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character.
## Parameters
`o` (in, out)
: stream to serialize to
`j` (in)
: JSON value to serialize
## Return value
the stream `o`
## Exceptions
Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set.
## Complexity
Linear.
## Examples
??? example
The example below shows the serialization with different parameters to `width` to adjust the indentation level.
```cpp
--8<-- "examples/operator_serialize.cpp"
```
Output:
```json
--8<-- "examples/operator_serialize.output"
```
## Version history
- Added in version 1.0.0
- Support for indentation character added in version 3.0.0.
!!! warning "Deprecation"
This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has
been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;`
with `#!cpp o << j;`.

37
doc/mkdocs/docs/api/basic_json/operator_ne.md
View File

@ -1,4 +1,4 @@
# basic_json::operator!=
# <small>nlohmann::basic_json::</small>operator!=
```cpp
bool operator!=(const_reference lhs, const_reference rhs) noexcept;
@ -37,20 +37,35 @@ No-throw guarantee: this function never throws exceptions.
Linear.
## Example
## Examples
The example demonstrates comparing several JSON
types.
??? example
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__notequal.cpp"
```
```cpp
--8<-- "examples/operator__notequal.cpp"
```
Output:
```json
--8<-- "examples/operator__notequal.output"
```
Output:
??? example
```json
--8<-- "examples/operator__notequal.output"
```
The example demonstrates comparing several JSON types against the null pointer (JSON `#!json null`).
```cpp
--8<-- "examples/operator__notequal__nullptr_t.cpp"
```
Output:
```json
--8<-- "examples/operator__notequal__nullptr_t.output"
```
## Version history

28
doc/mkdocs/docs/api/basic_json/operator_value_t.md
View File

@ -1,4 +1,4 @@
# basic_json::operator value_t
# <small>nlohmann::basic_json::</small>operator value_t
```cpp
constexpr operator value_t() const noexcept;
@ -10,18 +10,18 @@ Return the type of the JSON value as a value from the [`value_t`](value_t.md) en
the type of the JSON value
Value type | return value
------------------------- | -------------------------
`#!json null` | `value_t::null`
boolean | `value_t::boolean`
string | `value_t::string`
number (integer) | `value_t::number_integer`
number (unsigned integer) | `value_t::number_unsigned`
number (floating-point) | `value_t::number_float`
object | `value_t::object`
array | `value_t::array`
binary | `value_t::binary`
discarded | `value_t::discarded`
| Value type | return value |
|---------------------------|----------------------------|
| `#!json null` | `value_t::null` |
| boolean | `value_t::boolean` |
| string | `value_t::string` |
| number (integer) | `value_t::number_integer` |
| number (unsigned integer) | `value_t::number_unsigned` |
| number (floating-point) | `value_t::number_float` |
| object | `value_t::object` |
| array | `value_t::array` |
| binary | `value_t::binary` |
| discarded | `value_t::discarded` |
## Exception safety
@ -31,7 +31,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

14
doc/mkdocs/docs/api/basic_json/other_error.md
View File

@ -1,4 +1,4 @@
# basic_json::other_error
# <small>nlohmann::basic_json::</small>other_error
```cpp
class other_error : public exception;
@ -6,7 +6,7 @@ class other_error : public exception;
This exception is thrown in case of errors that cannot be classified with the other exception types.
Exceptions have ids 5xx.
Exceptions have ids 5xx (see [list of other errors](../../home/exceptions.md#further-exceptions)).
```plantuml
std::exception <|-- basic_json::exception
@ -38,7 +38,7 @@ class basic_json::other_error #FFFF00 {}
- **id** - the id of the exception
## Example
## Examples
??? example
@ -54,6 +54,14 @@ class basic_json::other_error #FFFF00 {}
--8<-- "examples/other_error.output"
```
## See also
- [List of other errors](../../home/exceptions.md#further-exceptions)
- [`parse_error`](parse_error.md) for exceptions indicating a parse error
- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
## Version history
- Since version 3.0.0.

14
doc/mkdocs/docs/api/basic_json/out_of_range.md
View File

@ -1,4 +1,4 @@
# basic_json::out_of_range
# <small>nlohmann::basic_json::</small>out_of_range
```cpp
class out_of_range : public exception;
@ -7,7 +7,7 @@ class out_of_range : public exception;
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for
instance in case of array indices or nonexisting object keys.
Exceptions have ids 4xx.
Exceptions have ids 4xx (see [list of out-of-range errors](../../home/exceptions.md#out-of-range)).
```plantuml
std::exception <|-- basic_json::exception
@ -39,7 +39,7 @@ class basic_json::out_of_range #FFFF00 {}
- **id** - the id of the exception
## Example
## Examples
??? example
@ -55,6 +55,14 @@ class basic_json::out_of_range #FFFF00 {}
--8<-- "examples/out_of_range.output"
```
## See also
- [List of out-of-range errors](../../home/exceptions.md#out-of-range)
- [`parse_error`](parse_error.md) for exceptions indicating a parse error
- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
- [`other_error`](other_error.md) for exceptions indicating other library errors
## Version history
- Since version 3.0.0.

16
doc/mkdocs/docs/api/basic_json/parse.md
View File

@ -1,4 +1,4 @@
# basic_json::parse
# <small>nlohmann::basic_json::</small>parse
```cpp
// (1)
@ -180,8 +180,22 @@ super-linear complexity.
--8<-- "examples/parse__allow_exceptions.output"
```
## See also
- [accept](accept.md) - check if the input is valid JSON
- [operator>>](operator_gtgt.md) - deserialize from stream
## Version history
- Added in version 1.0.0.
- Overload for contiguous containers (1) added in version 2.0.3.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
!!! warning "Deprecation"
Overload (2) replaces calls to `parse` with a pair of iterators as their first parameter which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp parse({ptr, ptr+len}, ...);` with `#!cpp parse(ptr, ptr+len, ...);`.
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
function.

20
doc/mkdocs/docs/api/basic_json/parse_error.md
View File

@ -1,4 +1,4 @@
# basic_json::parse_error
# <small>nlohmann::basic_json::</small>parse_error
```cpp
class parse_error : public exception;
@ -7,7 +7,9 @@ class parse_error : public exception;
This exception is thrown by the library when a parse error occurs. Parse errors can occur during the deserialization of
JSON text, BSON, CBOR, MessagePack, UBJSON, as well as when using JSON Patch.
Exceptions have ids 1xx.
Member `byte` holds the byte index of the last read character in the input file (see note below).
Exceptions have ids 1xx (see [list of parse errors](../../home/exceptions.md#parse-errors)).
```plantuml
std::exception <|-- basic_json::exception
@ -38,12 +40,12 @@ class basic_json::parse_error #FFFF00 {
- **id** - the id of the exception
- **byte** - byte index of the parse error
## Note
## Notes
For an input with _n_ bytes, 1 is the index of the first character and _n_+1 is the index of the terminating null byte
For an input with $n$ bytes, 1 is the index of the first character and $n+1$ is the index of the terminating null byte
or the end of file. This also holds true when reading a byte vector for binary formats.
## Example
## Examples
??? example
@ -59,6 +61,14 @@ or the end of file. This also holds true when reading a byte vector for binary f
--8<-- "examples/parse_error.output"
```
## See also
- [List of parse errors](../../home/exceptions.md#parse-errors)
- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
- [`other_error`](other_error.md) for exceptions indicating other library errors
## Version history
- Since version 3.0.0.

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

@ -1,4 +1,4 @@
# basic_json::parse_event_t
# <small>nlohmann::basic_json::</small>parse_event_t
```cpp
enum class parse_event_t : std::uint8_t {
@ -20,7 +20,7 @@ The parser callback distinguishes the following events:
- `array_end`: the parser read `]` and finished processing a JSON array
- `value`: the parser finished reading a JSON value
## Example
## Examples
![Example when certain parse events are triggered](../../images/callback_events.png)

20
doc/mkdocs/docs/api/basic_json/parser_callback_t.md
View File

@ -1,4 +1,4 @@
# basic_json::parser_callback_t
# <small>nlohmann::basic_json::</small>parser_callback_t
```cpp
template<typename BasicJsonType>
@ -14,14 +14,14 @@ is a boolean indicating whether the element that emitted the callback shall be k
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
table describes the values of the parameters `depth`, `event`, and `parsed`.
parameter `event` | description | parameter `depth` | parameter `parsed`
------------------ | ----------- | ------------------ | -------------------
`parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
`parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
`parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
`parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
`parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
`parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value
| parameter `event` | description | parameter `depth` | parameter `parsed` |
|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
| `parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded |
| `parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key |
| `parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object |
| `parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded |
| `parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array |
| `parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value |
![Example when certain parse events are triggered](../../images/callback_events.png)
@ -51,7 +51,7 @@ called:
Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
the latter case, it is either skipped completely or replaced by an empty discarded object.
# Example
## Examples
??? example

22
doc/mkdocs/docs/api/basic_json/patch.md
View File

@ -1,11 +1,11 @@
# basic_json::patch
# <small>nlohmann::basic_json::</small>patch
```cpp
basic_json patch(const basic_json& json_patch) const;
```
[JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
a JSON) document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
a JSON document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
the patch.
## Parameters
@ -17,6 +17,10 @@ the patch.
patched document
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of
@ -31,21 +35,17 @@ patched document
- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
unsuccessful.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Complexity
Linear in the size of the JSON value and the length of the JSON patch. As usually only a fraction of the JSON value is
affected by the patch, the complexity can usually be neglected.
## Note
## Notes
The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception
is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
## Example
## Examples
??? example
@ -61,6 +61,12 @@ is thrown. In any case, the original value is not changed: the patch is applied
--8<-- "examples/patch.output"
```
## See also
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
## Version history
- Added in version 2.0.0.

10
doc/mkdocs/docs/api/basic_json/push_back.md
View File

@ -1,4 +1,4 @@
# basic_json::push_back
# <small>nlohmann::basic_json::</small>push_back
```cpp
// (1)
@ -18,7 +18,7 @@ void push_back(initializer_list_t init);
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
is created before inserting `val`.
3. This function allows to use `push_back` with an initializer list. In case
3. This function allows using `push_back` with an initializer list. In case
1. the current value is an object,
2. the initializer list `init` contains only two elements, and
@ -58,7 +58,7 @@ void push_back(initializer_list_t init);
## Examples
??? example
??? example "Example: (1) add element to array"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
was silently converted to a JSON array.
@ -73,7 +73,7 @@ void push_back(initializer_list_t init);
--8<-- "examples/push_back.output"
```
??? example
??? example "Example: (2) add element to object"
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
was silently converted to a JSON object.
@ -88,7 +88,7 @@ void push_back(initializer_list_t init);
--8<-- "examples/push_back__object_t__value.output"
```
??? example
??? example "Example: (3) add to object from initializer list"
The example shows how initializer lists are treated as objects when possible.

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

@ -1,4 +1,4 @@
# basic_json::rbegin
# <small>nlohmann::basic_json::</small>rbegin
```cpp
reverse_iterator rbegin() noexcept;
@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

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

@ -1,4 +1,4 @@
# basic_json::rend
# <small>nlohmann::basic_json::</small>rend
```cpp
reverse_iterator rend() noexcept;
@ -22,7 +22,7 @@ No-throw guarantee: this member function never throws exceptions.
Constant.
## Example
## Examples
??? example

12
doc/mkdocs/docs/api/basic_json/sax_parse.md
View File

@ -1,4 +1,4 @@
# basic_json::sax_parse
# <small>nlohmann::basic_json::</small>sax_parse
```cpp
// (1)
@ -23,10 +23,10 @@ Read from input and generate SAX events
1. Read from a compatible input.
2. Read from a pair of character iterators
The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
The SAX event lister must follow the interface of `json_sax`.
The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).
## Template parameters
@ -107,3 +107,9 @@ A UTF-8 byte order mark is silently ignored.
- Added in version 3.2.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
!!! warning "Deprecation"
Overload (2) replaces calls to `sax_parse` with a pair of iterators as their first parameter which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp sax_parse({ptr, ptr+len});` with `#!cpp sax_parse(ptr, ptr+len);`.

22
doc/mkdocs/docs/api/basic_json/size.md
View File

@ -1,4 +1,4 @@
# basic_json::size
# <small>nlohmann::basic_json::</small>size
```cpp
size_type size() const noexcept;
@ -10,15 +10,15 @@ Returns the number of elements in a JSON value.
The return value depends on the different types and is defined as follows:
Value type | return value
----------- | -------------
null | `0`
boolean | `1`
string | `1`
number | `1`
binary | `1`
object | result of function object_t::size()
array | result of function array_t::size()
| Value type | return value |
|------------|-------------------------------------|
| null | `0` |
| boolean | `1` |
| string | `1` |
| number | `1` |
| binary | `1` |
| object | result of function object_t::size() |
| array | result of function array_t::size() |
## Exception safety
@ -35,7 +35,7 @@ constant complexity.
This function does not return the length of a string stored as JSON value -- it returns the number of elements in the
JSON value which is `1` in the case of a string.
## Example
## Examples
??? example

32
doc/mkdocs/docs/api/basic_json/std_hash.md Normal file
View File

@ -0,0 +1,32 @@
# <small>std::</small>hash<nlohmann::basic_json\>
```cpp
namespace std {
struct hash<nlohmann::basic_json>;
}
```
Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the
type of the JSON value is taken into account to have different hash values for `#!json null`, `#!cpp 0`, `#!cpp 0U`, and
`#!cpp false`, etc.
## Examples
??? example
The example shows how to calculate hash values for different JSON values.
```cpp
--8<-- "examples/std_hash.cpp"
```
Output:
```json
--8<-- "examples/std_hash.output"
```
## Version history
- Added in version 1.0.0.
- Extended for arbitrary basic_json types in version 3.10.5.

51
doc/mkdocs/docs/api/basic_json/std_swap.md Normal file
View File

@ -0,0 +1,51 @@
# std::swap<basic_json\>
```cpp
namespace std {
void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2);
}
```
Exchanges the values of two JSON objects.
## Parameters
`j1` (in, out)
: value to be replaced by `j2`
`j2` (in, out)
: value to be replaced by `j1`
## Possible implementation
```cpp
void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2)
{
j1.swap(j2);
}
```
## Examples
??? example
The following code shows how two values are swapped with `std::swap`.
```cpp
--8<-- "examples/std_swap.cpp"
```
Output:
```json
--8<-- "examples/std_swap.output"
```
## See also
- [swap](swap.md)
## Version history
- Added in version 1.0.0.
- Extended for arbitrary basic_json types in version 3.10.5.

Some files were not shown because too many files have changed in this diff Show More