amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-07-09 12:05:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

📡 fix docs (#5217)

Browse Source
This commit is contained in:
Niels Lohmann
2026-06-29 22:15:18 +02:00
committed by GitHub
parent c37f82e563
commit c5b2b26fdc
93 changed files with 743 additions and 1209 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/docs/api/adl_serializer/from_json.md
+2 -1
View File
@@ -30,7 +30,8 @@ class (either explicitly or via the conversion operators).
## Return value
Copy of the JSON value, converted to `ValueType`
1. (none) -- the converted value is written to the output parameter `val`.
2. the JSON value `j` converted to `TargetType`
## Examples
docs/mkdocs/docs/api/basic_json/accept.md
+2 -1
View File
@@ -101,6 +101,7 @@ A UTF-8 byte order mark is silently ignored.
## See also
- [parse](parse.md) - deserialize from a compatible input
- [sax_parse](sax_parse.md) - parse input using the SAX interface
- [operator>>](../operator_gtgt.md) - deserialize from stream
## Version history
@@ -108,7 +109,7 @@ A UTF-8 byte order mark is silently ignored.
- Added in version 3.0.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
- Added `ignore_trailing_commas` in version 3.12.1.
- Added `ignore_trailing_commas` in version 3.12.x.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/at.md
+2
View File
@@ -82,6 +82,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
key of an object which cannot be found. See the example below.
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved. See the example below.
- Throws [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) if an array index in the passed
JSON pointer `ptr` exceeds the range of `size_type` (e.g., on 32-bit platforms).
## Complexity
docs/mkdocs/docs/api/basic_json/boolean_t.md
+1 -1
View File
@@ -9,7 +9,7 @@ The type used to store JSON booleans.
[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two
literals `#!json true` and `#!json false`.
To store objects in C++, a type is defined by the template parameter `BooleanType` which chooses the type to use.
To store boolean values in C++, a type is defined by the template parameter `BooleanType` which chooses the type to use.
## Notes
docs/mkdocs/docs/api/basic_json/contains.md
+6 -5
View File
@@ -48,11 +48,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
1. The function does not throw exceptions.
2. The function does not throw exceptions.
3. 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.
3. The function does not throw exceptions.
## Complexity
@@ -111,6 +107,11 @@ Logarithmic in the size of the JSON object.
--8<-- "examples/contains__json_pointer.output"
```
## See also
- [find](find.md) find a value in an object
- [count](count.md) returns the number of occurrences of a key
## Version history
1. Added in version 3.11.0.
docs/mkdocs/docs/api/basic_json/count.md
+5
View File
@@ -72,6 +72,11 @@ This method always returns `0` when executed on a JSON type that is not an objec
--8<-- "examples/count__keytype.c++17.output"
```
## See also
- [find](find.md) find a value in an object
- [contains](contains.md) checks whether a key exists
## Version history
1. Added in version 3.11.0.
docs/mkdocs/docs/api/basic_json/crbegin.md
+1 -1
View File
@@ -10,7 +10,7 @@ Returns an iterator to the reverse-beginning; that is, the last element.
## Return value
reverse iterator to the first element
reverse iterator to the last element
## Exception safety
docs/mkdocs/docs/api/basic_json/crend.md
+1 -1
View File
@@ -25,7 +25,7 @@ Constant.
??? example
The following code shows an example for `eend()`.
The following code shows an example for `crend()`.
```cpp
--8<-- "examples/crend.cpp"
docs/mkdocs/docs/api/basic_json/diff.md
+3
View File
@@ -56,6 +56,9 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
## See also
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- [patch](patch.md) applies a JSON Patch
- [patch_inplace](patch_inplace.md) applies a JSON Patch in place
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
## Version history
docs/mkdocs/docs/api/basic_json/dump.md
+6 -1
View File
@@ -26,7 +26,7 @@ and `ensure_ascii` parameters.
`error_handler` (in)
: 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
`strict` (throws an 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)).
@@ -71,6 +71,11 @@ Binary values are serialized as an object containing two keys:
--8<-- "examples/dump.output"
```
## See also
- [to_string](to_string.md) returns a string representation of a JSON value
- [operator<<](../operator_ltlt.md) serialize to stream
## Version history
- Added in version 1.0.0.
docs/mkdocs/docs/api/basic_json/emplace.md
+9
View File
@@ -29,6 +29,10 @@ iterators (including the `end()` iterator) and all references to the elements ar
a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and
a `#!cpp bool` denoting whether the insertion took place.
## Exception safety
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
## Exceptions
Throws [`type_error.311`](../../home/exceptions.md#jsonexceptiontype_error311) when called on a type other than JSON
@@ -56,6 +60,11 @@ Logarithmic in the size of the container, O(log(`size()`)).
--8<-- "examples/emplace.output"
```
## See also
- [emplace_back](emplace_back.md) add a value to an array
- [insert](insert.md) add values to an array/object
## Version history
- Since version 2.0.8.
docs/mkdocs/docs/api/basic_json/erase.md
+6 -1
View File
@@ -101,7 +101,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
4. See 3.
5. The function can throw the following exceptions:
- Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
JSON object; example: `"cannot use erase() with null"`
JSON array; example: `"cannot use erase() with null"`
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
`"array index 17 is out of range"`
@@ -202,6 +202,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/erase__size_type.output"
```
## See also
- [clear](clear.md) clears the contents
- [insert](insert.md) add values to an array/object
## Version history
1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
docs/mkdocs/docs/api/basic_json/find.md
+1
View File
@@ -78,6 +78,7 @@ This method always returns `end()` when executed on a JSON type that is not an o
## See also
- [count](count.md) returns the number of occurrences of a key
- [contains](contains.md) checks whether a key exists
## Version history
docs/mkdocs/docs/api/basic_json/from_bjdata.md
+10
View File
@@ -67,6 +67,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
- 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
- Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the size of an optimized container
or n-dimensional array cannot be represented by `std::size_t`
## Complexity
@@ -88,6 +90,14 @@ Linear in the size of the input.
--8<-- "examples/from_bjdata.output"
```
## See also
- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
## Version history
- Added in version 3.11.0.
docs/mkdocs/docs/api/basic_json/from_bson.md
+7 -2
View File
@@ -62,8 +62,12 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## Exceptions
Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
encountered.
- Throws [`parse_error.110`](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of the input was not reached when `strict` was set to true
- Throws [`parse_error.112`](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs (e.g., an
invalid string or byte array length)
- Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
encountered
## Complexity
@@ -92,6 +96,7 @@ Linear in the size of the input.
- [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
- [from_bjdata](from_bjdata.md) for the related BJData format
## Version history
docs/mkdocs/docs/api/basic_json/from_cbor.md
+8
View File
@@ -96,6 +96,14 @@ Linear in the size of the input.
--8<-- "examples/from_cbor.output"
```
## See also
- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
## Version history
- Added in version 2.0.9.
docs/mkdocs/docs/api/basic_json/from_msgpack.md
+9 -1
View File
@@ -89,6 +89,14 @@ Linear in the size of the input.
--8<-- "examples/from_msgpack.output"
```
## See also
- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
## Version history
- Added in version 2.0.9.
@@ -101,7 +109,7 @@ Linear in the size of the input.
- 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
- Overload (2) replaces calls to `from_msgpack` 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, ...);`.
docs/mkdocs/docs/api/basic_json/from_ubjson.md
+11 -1
View File
@@ -65,8 +65,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of the 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
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
successfully
- Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the size of an optimized container
or n-dimensional array cannot be represented by `std::size_t`
## Complexity
@@ -88,6 +90,14 @@ Linear in the size of the input.
--8<-- "examples/from_ubjson.output"
```
## See also
- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
## Version history
- Added in version 3.1.0.
docs/mkdocs/docs/api/basic_json/get.md
+12
View File
@@ -88,6 +88,11 @@ constexpr const PointerType get_ptr() const noexcept;
Depends on what `json_serializer<ValueType>` `from_json()` method throws
## Complexity
Depends on the `json_serializer<ValueType>::from_json()` implementation for overloads (1) and (2); constant for
overload (3).
## Notes
!!! danger "Undefined behavior for pointers"
@@ -144,6 +149,13 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
--8<-- "examples/get__PointerType.output"
```
## See also
- [get_to](get_to.md) convert and write into a passed value
- [get_ptr](get_ptr.md) get a pointer to the stored value
- [get_ref](get_ref.md) get a reference to the stored value
- [operator ValueType](operator_ValueType.md) get a value via implicit conversion
## Version history
1. Since version 2.1.0.
docs/mkdocs/docs/api/basic_json/get_binary.md
+5
View File
@@ -40,6 +40,11 @@ Constant.
--8<-- "examples/get_binary.output"
```
## See also
- [get](get.md) get a value (explicit conversion)
- [get_ref](get_ref.md) get a reference to the stored value
## Version history
- Added in version 3.8.0.
docs/mkdocs/docs/api/basic_json/get_to.md
+10
View File
@@ -34,6 +34,10 @@ the input parameter, allowing chaining calls
Depends on what `json_serializer<ValueType>` `from_json()` method throws
## Complexity
Depends on the `json_serializer<ValueType>::from_json()` implementation.
## Examples
??? example
@@ -53,6 +57,12 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
--8<-- "examples/get_to.output"
```
## See also
- [get](get.md) get a value (explicit conversion)
- [get_ref](get_ref.md) get a reference to the stored value
- [get_ptr](get_ptr.md) get a pointer to the stored value
## Version history
- Since version 3.3.0.
docs/mkdocs/docs/api/basic_json/insert.md
+9 -2
View File
@@ -96,8 +96,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
5. The function can throw the following exceptions:
- Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if called on JSON values other than
objects; example: `"cannot use insert() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if `first` or `last`
do not point to an object; example: `"iterators first and last must point to objects"`
- 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"`
@@ -181,6 +181,13 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__range_object.output"
```
## See also
- [emplace](emplace.md) add a value to an object
- [emplace_back](emplace_back.md) add a value to an array
- [push_back](push_back.md) add a value to an array/object
- [update](update.md) merges objects
## Version history
1. Added in version 1.0.0.
docs/mkdocs/docs/api/basic_json/invalid_iterator.md
+1
View File
@@ -66,6 +66,7 @@ classDiagram
## See also
- [`exception`](exception.md) for the base class of all exceptions thrown by the library
- [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
docs/mkdocs/docs/api/basic_json/is_discarded.md
+6 -4
View File
@@ -45,11 +45,13 @@ Constant.
When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
then it is removed when it is part of a structured value. For instance, if the second value of an array is discarded,
instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level
value is discarded, the return value of the `parse` call is discarded.
instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. If the top-level value
itself is discarded by the callback, the `parse` call returns a `#!json null` value.
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.
After a successful parse, this function always returns `#!cpp false`: discarded values can only occur during parsing and
are either removed when inside a structured value or replaced by `#!json null` at the top level. The exception is parsing
with `allow_exceptions` set to `#!cpp false`: a parse error then yields a discarded value for which this function returns
`#!cpp true` (see [`parse`](parse.md)).
## Examples
docs/mkdocs/docs/api/basic_json/is_number.md
+1 -1
View File
@@ -9,7 +9,7 @@ unsigned) and floating-point values.
## Return value
`#!cpp true` if type is number (regardless whether integer, unsigned integer, or floating-type), `#!cpp false` otherwise.
`#!cpp true` if type is number (regardless whether integer, unsigned integer, or floating-point), `#!cpp false` otherwise.
## Exception safety
docs/mkdocs/docs/api/basic_json/items.md
+5
View File
@@ -84,6 +84,11 @@ When iterating over an array, `key()` will return the index of the element as st
--8<-- "examples/items.output"
```
## See also
- [begin](begin.md) returns an iterator to the first element
- [end](end.md) returns an iterator to one past the last element
## Version history
- Added `iterator_wrapper` in version 3.0.0.
docs/mkdocs/docs/api/basic_json/meta.md
+1 -1
View File
@@ -13,7 +13,7 @@ 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). |
| `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). On HP aCC compilers, `compiler` is instead the plain string `hp`. |
| `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`. |
docs/mkdocs/docs/api/basic_json/number_integer_t.md
-1
View File
@@ -32,7 +32,6 @@ With the default values for `NumberIntegerType` (`std::int64_t`), the default va
- The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an
interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++
integer literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
- Not-a-number (NaN) values will be serialized to `null`.
#### Limits
docs/mkdocs/docs/api/basic_json/number_unsigned_t.md
+1 -2
View File
@@ -32,7 +32,6 @@ With the default values for `NumberUnsignedType` (`std::uint64_t`), the default
- The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an
interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++
integer literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
- Not-a-number (NaN) values will be serialized to `null`.
#### Limits
@@ -45,7 +44,7 @@ when used in a constructor. During deserialization, too large or small integer n
as [`number_integer_t`](number_integer_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 (when considered in conjunction with the `number_integer_t` type) of the exactly supported
docs/mkdocs/docs/api/basic_json/operator+=.md
+6 -3
View File
@@ -50,9 +50,12 @@ invalidates all iterators and all references.
## Exceptions
All functions can throw the following exception:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use operator+=() with number"`
1. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
2. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON object or null; example: `"cannot use push_back() with number"`
3. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
## Complexity
docs/mkdocs/docs/api/basic_json/operator=.md
+11 -1
View File
@@ -5,7 +5,8 @@ basic_json& operator=(basic_json other) noexcept (
std::is_nothrow_move_constructible<value_t>::value &&
std::is_nothrow_move_assignable<value_t>::value &&
std::is_nothrow_move_constructible<json_value>::value &&
std::is_nothrow_move_assignable<json_value>::value
std::is_nothrow_move_assignable<json_value>::value &&
std::is_nothrow_move_assignable<json_base_class_t>::value
);
```
@@ -17,6 +18,10 @@ constructor, destructor, and the `swap()` member function.
`other` (in)
: value to copy from
## Exception safety
Strong guarantee: if an exception is thrown while copying `other`, there are no changes to `#!cpp *this`.
## Complexity
Linear.
@@ -38,6 +43,11 @@ Linear.
--8<-- "examples/basic_json__copyassignment.output"
```
## See also
- [basic_json](basic_json.md) create a JSON value
- [swap](swap.md) exchanges the contents of two JSON values
## Version history
- Added in version 1.0.0.
docs/mkdocs/docs/api/basic_json/operator[].md
+6 -1
View File
@@ -83,6 +83,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
in the passed JSON pointer `ptr` for the const version.
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved.
- Throws [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) if an array index in the passed
JSON pointer `ptr` exceeds the range of `size_type` (e.g., on 32-bit platforms).
## Complexity
@@ -95,7 +97,10 @@ Strong exception safety: if an exception occurs, the original value stays intact
!!! danger "Undefined behavior and runtime assertions"
1. If the element with key `idx` does not exist, the behavior is undefined.
The following cases apply to the **const** overloads; the non-const overloads instead insert the missing element
(see the notes below).
1. If the element at index `idx` does not exist, the behavior is undefined.
2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a
[runtime assertion](../../features/assertions.md)**!
docs/mkdocs/docs/api/basic_json/operator_ValueType.md
+4
View File
@@ -75,6 +75,10 @@ Linear in the size of the JSON value.
--8<-- "examples/operator__ValueType.output"
```
## See also
- [get](get.md) get a value (explicit conversion)
## Version history
- Since version 1.0.0.
docs/mkdocs/docs/api/basic_json/operator_eq.md
+9 -4
View File
@@ -20,7 +20,7 @@ class basic_json {
```
1. Compares two JSON values for equality according to the following rules:
- Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same type and their stored
- Two JSON values are equal if (1) neither value is discarded, and (2) they are of the same type and their stored
values are the same according to their respective `operator==`.
- Integer and floating-point numbers are automatically converted before comparison.
@@ -79,13 +79,13 @@ Linear.
}
```
Or you can self-defined operator equal function like this:
Or you can define your own equality function like this:
```cpp
bool my_equal(const_reference lhs, const_reference rhs)
{
const auto lhs_type lhs.type();
const auto rhs_type rhs.type();
const auto lhs_type = lhs.type();
const auto rhs_type = rhs.type();
if (lhs_type == rhs_type)
{
switch(lhs_type)
@@ -162,6 +162,11 @@ Linear.
--8<-- "examples/operator__equal__nullptr_t.output"
```
## See also
- [operator!=](operator_ne.md) compare for inequality
- [operator<=>](operator_spaceship.md) comparison: 3-way (C++20)
## Version history
1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
docs/mkdocs/docs/api/basic_json/operator_ge.md
+1 -1
View File
@@ -35,7 +35,7 @@ bool operator>=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
## Return value
whether `lhs` is less than or equal to `rhs`
whether `lhs` is greater than or equal to `rhs`
## Exception safety
docs/mkdocs/docs/api/basic_json/other_error.md
+1
View File
@@ -66,6 +66,7 @@ classDiagram
## See also
- [`exception`](exception.md) for the base class of all exceptions thrown by the library
- [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
docs/mkdocs/docs/api/basic_json/out_of_range.md
+1
View File
@@ -67,6 +67,7 @@ classDiagram
## See also
- [`exception`](exception.md) for the base class of all exceptions thrown by the library
- [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
docs/mkdocs/docs/api/basic_json/parse.md
+6 -5
View File
@@ -81,9 +81,6 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
empty input like a null `FILE*` or `char*` pointer.
- 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
@@ -95,6 +92,9 @@ super-linear complexity.
A UTF-8 byte order mark is silently ignored.
Invalid Unicode escapes and unpaired surrogates in the input are reported as
[`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) with a detailed message.
## Examples
??? example "Parsing from a character array"
@@ -183,7 +183,7 @@ A UTF-8 byte order mark is silently ignored.
??? example "Effect of `allow_exceptions` parameter"
The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.
The example below demonstrates the effect of the `allow_exceptions` parameter in the `parse()` function.
```cpp
--8<-- "examples/parse__allow_exceptions.cpp"
@@ -226,6 +226,7 @@ A UTF-8 byte order mark is silently ignored.
## See also
- [accept](accept.md) - check if the input is valid JSON
- [sax_parse](sax_parse.md) - parse input using the SAX interface
- [operator>>](../operator_gtgt.md) - deserialize from stream
## Version history
@@ -234,7 +235,7 @@ A UTF-8 byte order mark is silently ignored.
- Overload for contiguous containers (1) added in version 2.0.3.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
- Added `ignore_trailing_commas` in version 3.12.1.
- Added `ignore_trailing_commas` in version 3.12.x.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/parse_error.md
+1
View File
@@ -75,6 +75,7 @@ or the end of file. This also holds true when reading a byte vector for binary f
## See also
- [`exception`](exception.md) for the base class of all exceptions thrown by the library
- [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
docs/mkdocs/docs/api/basic_json/parse_event_t.md
+5
View File
@@ -24,6 +24,11 @@ The parser callback distinguishes the following events:
![Example when certain parse events are triggered](../../images/callback_events.png)
## See also
- [parser_callback_t](parser_callback_t.md) callback function type for the parser
- [parse](parse.md) deserialize from a compatible input
## Version history
- Added in version 1.0.0.
docs/mkdocs/docs/api/basic_json/parser_callback_t.md
+5
View File
@@ -68,6 +68,11 @@ the latter case, it is either skipped completely or replaced by an empty discard
--8<-- "examples/parse__string__parser_callback_t.output"
```
## See also
- [parse](parse.md) deserialize from a compatible input
- [parse_event_t](parse_event_t.md) enumeration of parser events
## Version history
- Added in version 1.0.0.
docs/mkdocs/docs/api/basic_json/patch.md
+1 -1
View File
@@ -32,7 +32,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
("add", "remove", "move")
- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
- Throws [`other_error.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
unsuccessful.
## Complexity
docs/mkdocs/docs/api/basic_json/patch_inplace.md
+3 -3
View File
@@ -1,7 +1,7 @@
# <small>nlohmann::basic_json::</small>patch_inplace
```cpp
void patch_inplace(const basic_json& json_patch) const;
void patch_inplace(const basic_json& json_patch);
```
[JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
@@ -28,7 +28,7 @@ No guarantees, value may be corrupted by an unsuccessful patch operation.
could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
("add", "remove", "move")
- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
- Throws [`other_error.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
unsuccessful.
## Complexity
@@ -62,7 +62,7 @@ function throws an exception.
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
- [patch](patch.md) applies a JSON Merge Patch
- [patch](patch.md) applies a JSON Patch
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
## Version history
docs/mkdocs/docs/api/basic_json/push_back.md
+6 -3
View File
@@ -46,9 +46,12 @@ invalidates all iterators and all references.
## Exceptions
All functions can throw the following exception:
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
1. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
2. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON object or null; example: `"cannot use push_back() with number"`
3. Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
JSON array or null; example: `"cannot use push_back() with number"`
## Complexity
docs/mkdocs/docs/api/basic_json/rbegin.md
+1 -1
View File
@@ -11,7 +11,7 @@ Returns an iterator to the reverse-beginning; that is, the last element.
## Return value
reverse iterator to the first element
reverse iterator to the last element
## Exception safety
docs/mkdocs/docs/api/basic_json/rend.md
+1 -1
View File
@@ -26,7 +26,7 @@ Constant.
??? example
The following code shows an example for `eend()`.
The following code shows an example for `rend()`.
```cpp
--8<-- "examples/rend.cpp"
docs/mkdocs/docs/api/basic_json/sax_parse.md
+9 -6
View File
@@ -43,10 +43,11 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
iterators.
`IteratorType`
: Description
: a compatible iterator type for overload (2); a pair of character iterators whose `value_type` is an integral type
with a size of 1, 2, or 4 bytes (interpreted respectively as UTF-8, UTF-16, and UTF-32)
`SAX`
: Description
: a class fulfilling the SAX event listener interface; see [`json_sax`](../json_sax/index.md)
## Parameters
@@ -89,9 +90,6 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
empty input like a null `FILE*` or `char*` pointer.
- 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
@@ -119,11 +117,16 @@ A UTF-8 byte order mark is silently ignored.
--8<-- "examples/sax_parse.output"
```
## See also
- [parse](parse.md) - deserialize from a compatible input
- [accept](accept.md) - check if the input is valid JSON
## Version history
- Added in version 3.2.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Added `ignore_trailing_commas` in version 3.12.1.
- Added `ignore_trailing_commas` in version 3.12.x.
!!! warning "Deprecation"
docs/mkdocs/docs/api/basic_json/std_swap.md
+8
View File
@@ -16,6 +16,14 @@ Exchanges the values of two JSON objects.
`j2` (in, out)
: value to be replaced by `j1`
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Constant.
## Possible implementation
```cpp
docs/mkdocs/docs/api/basic_json/string_t.md
+1 -1
View File
@@ -9,7 +9,7 @@ The type used to store JSON strings.
[RFC 8259](https://tools.ietf.org/html/rfc8259) describes JSON strings as follows:
> A string is a sequence of zero or more Unicode characters.
To store objects in C++, a type is defined by the template parameter described below. Unicode values are split by the
To store strings in C++, a type is defined by the template parameter described below. Unicode values are split by the
JSON class into byte-sized characters during deserialization.
## Template parameters
docs/mkdocs/docs/api/basic_json/swap.md
+20 -8
View File
@@ -2,10 +2,20 @@
```cpp
// (1)
void swap(reference other) noexcept;
void swap(reference other) noexcept (
std::is_nothrow_move_constructible<value_t>::value &&
std::is_nothrow_move_assignable<value_t>::value &&
std::is_nothrow_move_constructible<json_value>::value &&
std::is_nothrow_move_assignable<json_value>::value
);
// (2)
void swap(reference left, reference right) noexcept;
friend void swap(reference left, reference right) noexcept (
std::is_nothrow_move_constructible<value_t>::value &&
std::is_nothrow_move_assignable<value_t>::value &&
std::is_nothrow_move_constructible<json_value>::value &&
std::is_nothrow_move_assignable<json_value>::value
);
// (3)
void swap(array_t& other);
@@ -56,15 +66,15 @@ void swap(typename binary_t::container_type& other);
1. No-throw guarantee: this function never throws exceptions.
2. No-throw guarantee: this function never throws exceptions.
3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
arrays; example: `"cannot use swap() with boolean"`
arrays; example: `"cannot use swap(array_t&) with boolean"`
4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
objects; example: `"cannot use swap() with boolean"`
objects; example: `"cannot use swap(object_t&) with boolean"`
5. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
strings; example: `"cannot use swap() with boolean"`
strings; example: `"cannot use swap(string_t&) with boolean"`
6. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
binaries; example: `"cannot use swap() with boolean"`
binaries; example: `"cannot use swap(binary_t&) with boolean"`
7. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
binaries; example: `"cannot use swap() with boolean"`
binaries; example: `"cannot use swap(binary_t::container_type&) with boolean"`
## Complexity
@@ -128,7 +138,7 @@ Constant.
--8<-- "examples/swap__string_t.output"
```
??? example "Example: Swap string (6)"
??? example "Example: Swap binary (6)"
The example below shows how binary values can be swapped with `swap()`.
@@ -145,6 +155,8 @@ Constant.
## See also
- [std::swap<basic_json\>](std_swap.md)
- [operator=](operator=.md) copy assignment
- [basic_json](basic_json.md) create a JSON value
## Version history
docs/mkdocs/docs/api/basic_json/to_bjdata.md
+8
View File
@@ -72,6 +72,14 @@ Linear in the size of the JSON value `j`.
--8<-- "examples/to_bjdata.output"
```
## See also
- [from_bjdata](from_bjdata.md) create a JSON value from an input in BJData format
- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
- [to_bson](to_bson.md) create a BSON serialization of a JSON value
- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
## Version history
- Added in version 3.11.0.
docs/mkdocs/docs/api/basic_json/to_bson.md
+15
View File
@@ -34,6 +34,13 @@ The exact mapping and its limitations are described on a [dedicated page](../../
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
- Throws [`type_error.317`](../../home/exceptions.md#jsonexceptiontype_error317) if the top-level type of the JSON value
is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
- Throws [`out_of_range.409`](../../home/exceptions.md#jsonexceptionout_of_range409) if a key in the JSON object contains
a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
## Complexity
Linear in the size of the JSON value `j`.
@@ -54,6 +61,14 @@ Linear in the size of the JSON value `j`.
--8<-- "examples/to_bson.output"
```
## See also
- [from_bson](from_bson.md) create a JSON value from an input in BSON format
- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
## Version history
- Added in version 3.4.0.
docs/mkdocs/docs/api/basic_json/to_cbor.md
+8
View File
@@ -55,6 +55,14 @@ Linear in the size of the JSON value `j`.
--8<-- "examples/to_cbor.output"
```
## See also
- [from_cbor](from_cbor.md) create a JSON value from an input in CBOR format
- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
- [to_bson](to_bson.md) create a BSON serialization of a JSON value
- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
## Version history
- Added in version 2.0.9.
docs/mkdocs/docs/api/basic_json/to_msgpack.md
+8
View File
@@ -54,6 +54,14 @@ Linear in the size of the JSON value `j`.
--8<-- "examples/to_msgpack.output"
```
## See also
- [from_msgpack](from_msgpack.md) create a JSON value from an input in MessagePack format
- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
- [to_bson](to_bson.md) create a BSON serialization of a JSON value
- [to_ubjson](to_ubjson.md) create a UBJSON serialization of a JSON value
- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
## Version history
- Added in version 2.0.9.
docs/mkdocs/docs/api/basic_json/to_ubjson.md
+8
View File
@@ -65,6 +65,14 @@ Linear in the size of the JSON value `j`.
--8<-- "examples/to_ubjson.output"
```
## See also
- [from_ubjson](from_ubjson.md) create a JSON value from an input in UBJSON format
- [to_cbor](to_cbor.md) create a CBOR serialization of a JSON value
- [to_msgpack](to_msgpack.md) create a MessagePack serialization of a JSON value
- [to_bson](to_bson.md) create a BSON serialization of a JSON value
- [to_bjdata](to_bjdata.md) create a BJData serialization of a JSON value
## Version history
- Added in version 3.1.0.
docs/mkdocs/docs/api/basic_json/type_error.md
+1
View File
@@ -67,6 +67,7 @@ classDiagram
## See also
- [`exception`](exception.md) for the base class of all exceptions thrown by the library
- [List of type errors](../../home/exceptions.md#type-errors)
- [`parse_error`](parse_error.md) for exceptions indicating a parse error
- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
docs/mkdocs/docs/api/basic_json/unflatten.md
+4
View File
@@ -25,6 +25,10 @@ The function can throw the following exceptions:
- Throws [`type_error.314`](../../home/exceptions.md#jsonexceptiontype_error314) if value is not an object
- Throws [`type_error.315`](../../home/exceptions.md#jsonexceptiontype_error315) if object values are not primitive
- Throws [`type_error.313`](../../home/exceptions.md#jsonexceptiontype_error313) if a key (JSON pointer) leads to a
conflicting nesting; example: `"invalid value to unflatten"`
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in a key is not a
number; example: `"array index 'one' is not a number"`
## Complexity
docs/mkdocs/docs/api/basic_json/update.md
+13 -4
View File
@@ -14,6 +14,8 @@ void update(const_iterator first, const_iterator last, bool merge_objects = fals
When `merge_objects` is `#!c false` (default), existing keys are overwritten. When `merge_objects` is `#!c true`,
recursively merges objects with common keys.
If the JSON value is `#!json null`, it is implicitly converted to an empty object before the values are inserted.
The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update)
function.
@@ -28,8 +30,8 @@ iterators (including the `end()` iterator) and all references to the elements ar
: JSON object to read values from
`merge_objects` (in)
: when `#!c true`, existing keys are not overwritten, but contents of objects are merged recursively (default:
`#!c false`)
: when `#!c true`, keys that exist in both objects and whose value in the source is itself an object are merged
recursively; all other values are overwritten as usual (default: `#!c false`)
`first` (in)
: the beginning of the range of elements to insert
@@ -37,6 +39,10 @@ iterators (including the `end()` iterator) and all references to the elements ar
`last` (in)
: the end of the range of elements to insert
## Exception safety
Basic guarantee: if an exception is thrown during the operation, the JSON value may be partially modified.
## Exceptions
1. The function can throw the following exceptions:
@@ -45,8 +51,6 @@ iterators (including the `end()` iterator) and all references to the elements ar
2. The function can throw the following exceptions:
- Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
objects; example: `"cannot use update() with string"`
- Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
- 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"`
@@ -141,6 +145,11 @@ iterators (including the `end()` iterator) and all references to the elements ar
}
```
## See also
- [insert](insert.md) add values to an array/object
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
## Version history
- Added in version 3.0.0.
docs/mkdocs/docs/api/basic_json/value.md
+1 -1
View File
@@ -95,7 +95,7 @@ changes to any JSON value.
- Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
the type of the value at `ptr`
- Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
in that case, using `value()` with a key makes no sense.
in that case, using `value()` with a JSON pointer makes no sense.
## Complexity
docs/mkdocs/docs/api/byte_container_with_subtype/index.md
+1 -1
View File
@@ -24,7 +24,7 @@ specific naming scheme in order to override the binary type.
- [(constructor)](byte_container_with_subtype.md)
- **operator==** - comparison: equal
- **operator!=** - comparison: not equal
- [**set_subtype**](subtype.md) - sets the binary subtype
- [**set_subtype**](set_subtype.md) - sets the binary subtype
- [**subtype**](subtype.md) - return the binary subtype
- [**has_subtype**](has_subtype.md) - return whether the value has a subtype
- [**clear_subtype**](clear_subtype.md) - clears the binary subtype
docs/mkdocs/docs/api/json_pointer/front.md
+2
View File
@@ -35,3 +35,5 @@ Constant.
```
## Version history
- Added in version 3.12.x.
docs/mkdocs/docs/api/json_pointer/parent_pointer.md
+9
View File
@@ -10,6 +10,10 @@ Returns the parent of this JSON pointer.
Parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned.
## Exception safety
No-throw guarantee: this function never throws exceptions.
## Complexity
Linear in the length of the JSON pointer.
@@ -30,6 +34,11 @@ Linear in the length of the JSON pointer.
--8<-- "examples/json_pointer__parent_pointer.output"
```
## See also
- [pop_back](pop_back.md) remove the last reference token
- [back](back.md) return the last reference token
## Version history
Added in version 3.6.0.
docs/mkdocs/docs/api/json_pointer/pop_front.md
+2
View File
@@ -31,3 +31,5 @@ Linear in the number of reference tokens in the `json_pointer`.
```
## Version history
- Added in version 3.12.x.
docs/mkdocs/docs/api/json_pointer/push_front.md
+2
View File
@@ -34,3 +34,5 @@ Linear in the number of reference tokens in the `json_pointer`.
```
## Version history
- Added in version 3.12.x.
docs/mkdocs/docs/api/json_sax/start_array.md
+1 -1
View File
@@ -9,7 +9,7 @@ The beginning of an array was read.
## Parameters
`elements` (in)
: number of object elements or `#!cpp -1` if unknown
: number of array elements, or `#!cpp std::numeric_limits<std::size_t>::max()` if unknown
## Return value
docs/mkdocs/docs/api/json_sax/start_object.md
+1 -1
View File
@@ -9,7 +9,7 @@ The beginning of an object was read.
## Parameters
`elements` (in)
: number of object elements or `#!cpp -1` if unknown
: number of object elements, or `#!cpp std::numeric_limits<std::size_t>::max()` if unknown
## Return value
docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md
+1 -1
View File
@@ -92,4 +92,4 @@ The default value is `0` (disabled — existing behavior is preserved).
## Version history
- Added in version 3.12.0.
- Added in version 3.12.x.
docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md
+4 -5
View File
@@ -122,14 +122,13 @@ The default value is `0`.
void to_json(json& j, const Choice& ch)
{
auto value = j.get<std::string>();
if (value == "first")
if (ch == Choice::first)
{
ch = Choice::first;
j = "first";
}
else if (value == "second")
else if (ch == Choice::second)
{
ch = Choice::second;
j = "second";
}
}
docs/mkdocs/docs/api/macros/json_has_cpp_11.md
+8 -2
View File
@@ -1,10 +1,12 @@
# JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20
# JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26
```cpp
#define JSON_HAS_CPP_11
#define JSON_HAS_CPP_14
#define JSON_HAS_CPP_17
#define JSON_HAS_CPP_20
#define JSON_HAS_CPP_23
#define JSON_HAS_CPP_26
```
The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view`
@@ -20,7 +22,9 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu
## Notes
- `#!cpp JSON_HAS_CPP_11` is always defined.
- When the C++ standard is detected automatically, `#!cpp JSON_HAS_CPP_11` is always defined. When you override the
detection by defining one of these macros manually, the automatic detection is skipped entirely, so you should define
all applicable macros (including `#!cpp JSON_HAS_CPP_11`) yourself.
- All macros are undefined outside the library.
## Examples
@@ -39,3 +43,5 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu
## Version history
- Added in version 3.10.5.
- Added `JSON_HAS_CPP_23` in version 3.12.0.
- Added `JSON_HAS_CPP_26` in version 3.12.x.
docs/mkdocs/docs/api/macros/json_has_filesystem.md
+1 -1
View File
@@ -21,7 +21,7 @@ The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_
## Notes
- Note that older compilers or older versions of libstd++ also require the library `stdc++fs` to be linked to for
- Note that older compilers or older versions of libstdc++ also require the library `stdc++fs` to be linked to for
filesystem support.
- Both macros are undefined outside the library.
docs/mkdocs/docs/api/macros/json_skip_library_version_check.md
+11
View File
@@ -24,6 +24,17 @@ By default, the macro is not defined.
## Examples
??? example
The code below switches off the warning about including a different version of the library.
```cpp
#define JSON_SKIP_LIBRARY_VERSION_CHECK 1
#include <nlohmann/json.hpp>
...
```
!!! example
The following warning will be shown in case a different version of the library was already included:
docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md
+2 -2
View File
@@ -56,7 +56,7 @@ When the macro is not defined, the library will define it to its default value.
!!! hint "CMake option"
Legacy comparison can also be controlled with the CMake option
[`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_implicitconversions)
[`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
(`OFF` by default) which defines `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON` accordingly.
## Examples
@@ -72,7 +72,7 @@ When the macro is not defined, the library will define it to its default value.
...
```
### See also
## See also
- [:simple-cmake: JSON_LegacyDiscardedValueComparison](../../integration/cmake.md#json_legacydiscardedvaluecomparison) - CMake option to control the macro
docs/mkdocs/docs/api/macros/nlohmann_define_derived_type.md
+3 -3
View File
@@ -39,7 +39,7 @@ The base type **must** be already serializable/deserializable.
Summary:
| Need access to private members | Need only de-serialization | Allow missing values when de-serializing | macro |
| Need access to private members | Need only serialization | Allow missing values when de-serializing | macro |
|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------|
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE** |
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT** |
@@ -160,10 +160,10 @@ void to_json(BasicJsonType& j, const B& b) {
## See also
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE / NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT /
NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_intrusive.md)
NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_intrusive.md)
for similar macros that can be defined _inside_ a non-derived type.
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE / NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT /
NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_non_intrusive.md)
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE](nlohmann_define_type_non_intrusive.md)
for similar macros that can be defined _outside_ a non-derived type.
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md
+1 -1
View File
@@ -21,7 +21,7 @@ parameter is the name of the class/struct, and all remaining parameters name the
Summary:
| Need access to private members | Need only de-serialization | Allow missing values when de-serializing | macro |
| Need access to private members | Need only serialization | Allow missing values when de-serializing | macro |
|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------|
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_INTRUSIVE** |
| <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT** |
docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md
+1 -1
View File
@@ -21,7 +21,7 @@ parameter is the name of the class/struct, and all remaining parameters name the
Summary:
| Need access to private members | Need only de-serialization | Allow missing values when de-serializing | macro |
| Need access to private members | Need only serialization | Allow missing values when de-serializing | macro |
|------------------------------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------|
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE** |
| <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: red;">:octicons-x-circle-fill-24:</div> | <div style="color: green;">:octicons-check-circle-fill-24:</div> | **NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT** |
docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md
+1 -1
View File
@@ -75,4 +75,4 @@ For further information please refer to the corresponding macros without `WITH_N
## Version history
1. Added in version 3.11.x.
1. Added in version 3.12.x.
docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md
+2 -2
View File
@@ -21,13 +21,13 @@ The default definitions open and close the `nlohmann` namespace. The precise def
```cpp
namespace nlohmann
{
inline namespace json_abi_v3_11_2
inline namespace json_abi_v3_12_0
{
```
2. Default definition of `NLOHMANN_JSON_NAMESPACE_END`:
```cpp
} // namespace json_abi_v3_11_2
} // namespace json_abi_v3_12_0
} // namespace nlohmann
```
docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md
+5 -2
View File
@@ -38,7 +38,10 @@ inline void from_json(const BasicJsonType& j, type& e);
!!! important "Important notes"
- When using [`get<ENUM_TYPE>()`](../basic_json/get.md), undefined JSON values will throw an exception.
- Undefined input throws [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) in both
directions: when serializing an enum value not listed in the conversions, and when deserializing (e.g., via
[`get<ENUM_TYPE>()`](../basic_json/get.md)) a JSON value that matches no conversion; example:
`"enum value out of range for <type>"`.
- If an enum or JSON value is specified in multiple conversions, the first matching conversion from the top of the
list will be returned when converting to or from JSON. See example 2 below.
@@ -99,4 +102,4 @@ inline void from_json(const BasicJsonType& j, type& e);
## Version history
Added in version 3.12.0.
Added in version 3.12.x.
docs/mkdocs/docs/api/operator_gtgt.md
+4 -3
View File
@@ -21,8 +21,6 @@ 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
@@ -32,6 +30,9 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
A UTF-8 byte order mark is silently ignored.
Invalid Unicode escapes and unpaired surrogates in the input are reported as
[`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) with a detailed message.
!!! warning "Deprecation"
This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
@@ -61,4 +62,4 @@ A UTF-8 byte order mark is silently ignored.
## Version history
- Added in version 1.0.0. Deprecated in version 3.0.0.
- Added in version 1.0.0.
docs/mkdocs/docs/api/operator_literal_json.md
+1 -1
View File
@@ -60,4 +60,4 @@ Linear.
- Added in version 1.0.0.
- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.
- Added `char8_t*` overload in 3.12.1.
- Added `char8_t*` overload in 3.12.x.
docs/mkdocs/docs/api/operator_literal_json_pointer.md
+1 -1
View File
@@ -63,4 +63,4 @@ Linear.
- Added in version 2.0.0.
- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.
- Added `char8_t*` overload in 3.12.1.
- Added `char8_t*` overload in 3.12.x.