mirror of
https://github.com/nlohmann/json.git
synced 2026-07-13 22:14:54 +00:00
📝 fix docs (#5217)
This commit is contained in:
Niels Lohmann
@@ -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"
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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, ...);`.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`. |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)**!
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -24,6 +24,11 @@ The parser callback distinguishes the following events:
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user