📝 add more API documentation
This commit is contained in:
Niels Lohmann
parent
fe89049aee
commit
874f49e945
@ -7,41 +7,31 @@ using number_integer_t = NumberIntegerType;
|
||||
The type used to store JSON numbers (integers).
|
||||
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
|
||||
> The representation of numbers is similar to that used in most
|
||||
> programming languages. A number is represented in base 10 using decimal
|
||||
> digits. It contains an integer component that may be prefixed with an
|
||||
> optional minus sign, which may be followed by a fraction part and/or an
|
||||
> exponent part. Leading zeros are not allowed. (...) Numeric values that
|
||||
> cannot be represented in the grammar below (such as Infinity and NaN)
|
||||
> are not permitted.
|
||||
> The representation of numbers is similar to that used in most programming languages. A number is represented in base
|
||||
> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
|
||||
> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
|
||||
> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
|
||||
|
||||
This description includes both integer and floating-point numbers.
|
||||
However, C++ allows more precise storage if it is known whether the number
|
||||
is a signed integer, an unsigned integer or a floating-point number.
|
||||
Therefore, three different types, `number_integer_t`,
|
||||
[`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are used.
|
||||
This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
|
||||
known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
|
||||
types, `number_integer_t`, [`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are
|
||||
used.
|
||||
|
||||
To store integer numbers in C++, a type is defined by the template
|
||||
parameter `NumberIntegerType` which chooses the type to use.
|
||||
To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type
|
||||
to use.
|
||||
|
||||
## Notes
|
||||
|
||||
#### Default type
|
||||
|
||||
With the default values for `NumberIntegerType` (`std::int64_t`), the default
|
||||
value for `number_integer_t` is:
|
||||
|
||||
```cpp
|
||||
std::int64_t
|
||||
```
|
||||
With the default values for `NumberIntegerType` (`std::int64_t`), the default value for `number_integer_t` is
|
||||
`#!cpp std::int64_t`.
|
||||
|
||||
#### Default behavior
|
||||
|
||||
- The restrictions about leading zeros is not enforced in C++. Instead,
|
||||
leading zeros in integer literals lead to an interpretation as octal
|
||||
number. Internally, the value will be stored as decimal number. For
|
||||
instance, the C++ integer literal `010` will be serialized to `8`.
|
||||
During deserialization, leading zeros yield an error.
|
||||
- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an
|
||||
interpretation as octal number. Internally, the value will be stored as 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
|
||||
@ -49,21 +39,17 @@ std::int64_t
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) specifies:
|
||||
> An implementation may set limits on the range and precision of numbers.
|
||||
|
||||
When the default type is used, the maximal integer number that can be
|
||||
stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
|
||||
that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
|
||||
that are out of range will yield over/underflow when used in a
|
||||
constructor. During deserialization, too large or small integer numbers
|
||||
will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md)
|
||||
or [`number_float_t`](number_float_t.md).
|
||||
When the default type is used, the maximal integer number that can be stored is `9223372036854775807` (INT64_MAX) and
|
||||
the minimal integer number that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers that are out of
|
||||
range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers
|
||||
will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
|
||||
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) 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 interoperable in the sense
|
||||
> that implementations will agree exactly on their numeric values.
|
||||
> 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
|
||||
> interoperable in the sense that implementations will agree exactly on their numeric values.
|
||||
|
||||
As this range is a subrange of the exactly supported range [INT64_MIN,
|
||||
INT64_MAX], this class's integer type is interoperable.
|
||||
As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
|
||||
interoperable.
|
||||
|
||||
#### Storage
|
||||
|
||||
|
||||
@ -7,41 +7,31 @@ using number_unsigned_t = NumberUnsignedType;
|
||||
The type used to store JSON numbers (unsigned).
|
||||
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
|
||||
> The representation of numbers is similar to that used in most
|
||||
> programming languages. A number is represented in base 10 using decimal
|
||||
> digits. It contains an integer component that may be prefixed with an
|
||||
> optional minus sign, which may be followed by a fraction part and/or an
|
||||
> exponent part. Leading zeros are not allowed. (...) Numeric values that
|
||||
> cannot be represented in the grammar below (such as Infinity and NaN)
|
||||
> are not permitted.
|
||||
> The representation of numbers is similar to that used in most programming languages. A number is represented in base
|
||||
> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
|
||||
> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
|
||||
> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
|
||||
|
||||
This description includes both integer and floating-point numbers.
|
||||
However, C++ allows more precise storage if it is known whether the number
|
||||
is a signed integer, an unsigned integer or a floating-point number.
|
||||
Therefore, three different types, [`number_integer_t`](number_integer_t.md),
|
||||
`number_unsigned_t` and [`number_float_t`](number_float_t.md) are used.
|
||||
This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
|
||||
known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
|
||||
types, [`number_integer_t`](number_integer_t.md), `number_unsigned_t` and [`number_float_t`](number_float_t.md) are
|
||||
used.
|
||||
|
||||
To store unsigned integer numbers in C++, a type is defined by the
|
||||
template parameter `NumberUnsignedType` which chooses the type to use.
|
||||
To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses
|
||||
the type to use.
|
||||
|
||||
## Notes
|
||||
|
||||
#### Default type
|
||||
|
||||
With the default values for `NumberUnsignedType` (`std::uint64_t`), the
|
||||
default value for `number_unsigned_t` is:
|
||||
|
||||
```cpp
|
||||
std::uint64_t
|
||||
```
|
||||
With the default values for `NumberUnsignedType` (`std::uint64_t`), the default value for `number_unsigned_t` is
|
||||
`#!cpp std::uint64_t`.
|
||||
|
||||
#### Default behavior
|
||||
|
||||
- The restrictions about leading zeros is not enforced in C++. Instead,
|
||||
leading zeros in integer literals lead to an interpretation as octal
|
||||
number. Internally, the value will be stored as decimal number. For
|
||||
instance, the C++ integer literal `010` will be serialized to `8`.
|
||||
During deserialization, leading zeros yield an error.
|
||||
- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an
|
||||
interpretation as octal number. Internally, the value will be stored as 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
|
||||
@ -49,22 +39,17 @@ std::uint64_t
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) specifies:
|
||||
> An implementation may set limits on the range and precision of numbers.
|
||||
|
||||
When the default type is used, the maximal integer number that can be
|
||||
stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
|
||||
number that can be stored is `0`. Integer numbers that are out of range
|
||||
will yield over/underflow when used in a constructor. During
|
||||
deserialization, too large or small integer numbers will be automatically
|
||||
be stored as [`number_integer_t`](number_integer_t.md) or
|
||||
[`number_float_t`](number_float_t.md).
|
||||
When the default type is used, the maximal integer number that can be stored is `18446744073709551615` (UINT64_MAX) and
|
||||
the minimal integer number that can be stored is `0`. Integer numbers that are out of range will yield over/underflow
|
||||
when used in a constructor. During deserialization, too large or small integer numbers will be automatically be stored
|
||||
as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
|
||||
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) 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 interoperable in the sense
|
||||
> that implementations will agree exactly on their numeric values.
|
||||
> 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
|
||||
> 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 range [0, UINT64_MAX],
|
||||
this class's integer type is interoperable.
|
||||
As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported
|
||||
range [0, UINT64_MAX], this class's integer type is interoperable.
|
||||
|
||||
#### Storage
|
||||
|
||||
|
||||
@ -4,9 +4,8 @@
|
||||
static basic_json object(initializer_list_t init = {});
|
||||
```
|
||||
|
||||
Creates a JSON object value from a given initializer list. The initializer
|
||||
lists elements must be pairs, and their first elements must be strings. If
|
||||
the initializer list is empty, the empty object `#!json {}` is created.
|
||||
Creates a JSON object value from a given initializer list. The initializer lists elements must be pairs, and their first
|
||||
elements must be strings. If the initializer list is empty, the empty object `#!json {}` is created.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -19,17 +18,14 @@ JSON object value
|
||||
|
||||
## Exceptions
|
||||
|
||||
Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301)
|
||||
if `init` is not a list of pairs whose first
|
||||
elements are strings. In this case, no object can be created. When such a
|
||||
value is passed to `basic_json(initializer_list_t, bool, value_t)`,
|
||||
an array would have been created from the passed initializer list `init`.
|
||||
See example below.
|
||||
Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose
|
||||
first elements are strings. In this case, no object can be created. When such a value is passed to
|
||||
`basic_json(initializer_list_t, bool, value_t)`, an array would have been created from the passed initializer list
|
||||
`init`. See example below.
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no
|
||||
changes in the JSON value.
|
||||
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
|
||||
|
||||
## Complexity
|
||||
|
||||
@ -37,18 +33,15 @@ Linear in the size of `init`.
|
||||
|
||||
## Notes
|
||||
|
||||
This function is only added for symmetry reasons. In contrast to the
|
||||
related function `array(initializer_list_t)`, there are
|
||||
no cases which can only be expressed by this function. That is, any
|
||||
initializer list `init` can also be passed to the initializer list
|
||||
constructor `basic_json(initializer_list_t, bool, value_t)`.
|
||||
This function is only added for symmetry reasons. In contrast to the related function `array(initializer_list_t)`, there
|
||||
are no cases which can only be expressed by this function. That is, any initializer list `init` can also be passed to
|
||||
the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The following code shows an example for the `object`
|
||||
function.
|
||||
The following code shows an example for the `object` function.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/object.cpp"
|
||||
|
||||
@ -10,12 +10,10 @@ using object_t = ObjectType<StringType,
|
||||
The type used to store JSON objects.
|
||||
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
|
||||
> An object is an unordered collection of zero or more name/value pairs,
|
||||
> where a name is a string and a value is a string, number, boolean, null,
|
||||
> object, or array.
|
||||
> An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a
|
||||
> string, number, boolean, null, object, or array.
|
||||
|
||||
To store objects in C++, a type is defined by the template parameters
|
||||
described below.
|
||||
To store objects in C++, a type is defined by the template parameters described below.
|
||||
|
||||
## Template parameters
|
||||
|
||||
@ -23,9 +21,8 @@ described below.
|
||||
: the container to store objects (e.g., `std::map` or `std::unordered_map`)
|
||||
|
||||
`StringType`
|
||||
: the type of the keys or names (e.g., `std::string`).
|
||||
The comparison function `std::less<StringType>` is used to order elements
|
||||
inside the container.
|
||||
: the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to
|
||||
order elements inside the container.
|
||||
|
||||
`AllocatorType`
|
||||
: the allocator to use for objects (e.g., `std::allocator`)
|
||||
@ -34,9 +31,8 @@ described below.
|
||||
|
||||
#### Default type
|
||||
|
||||
With the default values for `ObjectType` (`std::map`), `StringType`
|
||||
(`std::string`), and `AllocatorType` (`std::allocator`), the default
|
||||
value for `object_t` is:
|
||||
With the default values for `ObjectType` (`std::map`), `StringType` (`std::string`), and `AllocatorType`
|
||||
(`std::allocator`), the default value for `object_t` is:
|
||||
|
||||
```cpp
|
||||
std::map<
|
||||
@ -49,23 +45,19 @@ std::map<
|
||||
|
||||
#### Behavior
|
||||
|
||||
The choice of `object_t` influences the behavior of the JSON class. With
|
||||
the default type, objects have the following behavior:
|
||||
The choice of `object_t` influences the behavior of the JSON class. With the default type, objects have the following
|
||||
behavior:
|
||||
|
||||
- When all names are unique, objects will be interoperable in the sense
|
||||
that all software implementations receiving that object will agree on
|
||||
the name-value mappings.
|
||||
- When the names within an object are not unique, it is unspecified which
|
||||
one of the values for a given key will be chosen. For instance,
|
||||
`#!json {"key": 2, "key": 1}` could be equal to either `#!json {"key": 1}` or
|
||||
- When all names are unique, objects will be interoperable in the sense that all software implementations receiving that
|
||||
object will agree on the name-value mappings.
|
||||
- When the names within an object are not unique, it is unspecified which one of the values for a given key will be
|
||||
chosen. For instance, `#!json {"key": 2, "key": 1}` could be equal to either `#!json {"key": 1}` or
|
||||
`#!json {"key": 2}`.
|
||||
- Internally, name/value pairs are stored in lexicographical order of the
|
||||
names. Objects will also be serialized (see [`dump`](dump.md)) in this order.
|
||||
For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored
|
||||
- Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see
|
||||
[`dump`](dump.md)) in this order. For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored
|
||||
and serialized as `#!json {"a": 2, "b": 1}`.
|
||||
- When comparing objects, the order of the name/value pairs is irrelevant.
|
||||
This makes objects interoperable in the sense that they will not be
|
||||
affected by these differences. For instance, `#!json {"b": 1, "a": 2}` and
|
||||
- When comparing objects, the order of the name/value pairs is irrelevant. This makes objects interoperable in the sense
|
||||
that they will not be affected by these differences. For instance, `#!json {"b": 1, "a": 2}` and
|
||||
`#!json {"a": 2, "b": 1}` will be treated as equal.
|
||||
|
||||
#### Limits
|
||||
@ -73,26 +65,21 @@ the default type, objects have the following behavior:
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) specifies:
|
||||
> An implementation may set limits on the maximum depth of nesting.
|
||||
|
||||
In this class, the object's limit of nesting is not explicitly constrained.
|
||||
However, a maximum depth of nesting may be introduced by the compiler or
|
||||
runtime environment. A theoretical limit can be queried by calling the
|
||||
In this class, the object's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be
|
||||
introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the
|
||||
[`max_size`](max_size.md) function of a JSON object.
|
||||
|
||||
#### Storage
|
||||
|
||||
Objects are stored as pointers in a `basic_json` type. That is, for any
|
||||
access to object values, a pointer of type `object_t*` must be
|
||||
dereferenced.
|
||||
Objects are stored as pointers in a `basic_json` type. That is, for any access to object values, a pointer of type
|
||||
`object_t*` must be dereferenced.
|
||||
|
||||
#### Object key order
|
||||
|
||||
The order name/value pairs are added to the object is *not*
|
||||
preserved by the library. Therefore, iterating an object may return
|
||||
name/value pairs in a different order than they were originally stored. In
|
||||
fact, keys will be traversed in alphabetical order as `std::map` with
|
||||
`std::less` is used by default. Please note this behavior conforms to [RFC
|
||||
7159](http://rfc7159.net/rfc7159), because any order implements the
|
||||
specified "unordered" nature of JSON objects.
|
||||
The order name/value pairs are added to the object is *not* preserved by the library. Therefore, iterating an object may
|
||||
return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in
|
||||
alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
|
||||
[RFC 7159](http://rfc7159.net/rfc7159), because any order implements the specified "unordered" nature of JSON objects.
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@ -12,13 +12,11 @@ reference operator+=(const typename object_t::value_type& val);
|
||||
reference operator+=(initializer_list_t init);
|
||||
```
|
||||
|
||||
1. Appends the given element `val` to the end of the JSON array. If the
|
||||
function is called on a JSON null value, an empty array is created before
|
||||
appending `val`.
|
||||
1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an
|
||||
empty array is created before appending `val`.
|
||||
|
||||
2. Inserts the given element `val` to the JSON object. If the function is
|
||||
called on a JSON null value, an empty object is created before inserting
|
||||
`val`.
|
||||
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
|
||||
is created before inserting `val`.
|
||||
|
||||
3. This function allows to use `operator+=` with an initializer list. In case
|
||||
|
||||
@ -26,9 +24,8 @@ reference operator+=(initializer_list_t init);
|
||||
2. the initializer list `init` contains only two elements, and
|
||||
3. the first element of `init` is a string,
|
||||
|
||||
`init` is converted into an object element and added using
|
||||
`operator+=(const typename object_t::value_type&)`. Otherwise, `init`
|
||||
is converted to a JSON value and added using `operator+=(basic_json&&)`.
|
||||
`init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
|
||||
Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -45,11 +42,11 @@ reference operator+=(initializer_list_t init);
|
||||
## Exceptions
|
||||
|
||||
1. The function can throw the following exceptions:
|
||||
- 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"`
|
||||
- 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"`
|
||||
2. The function can throw the following exceptions:
|
||||
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON object or
|
||||
null; example: `"cannot use operator+=() with number"`
|
||||
- Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
|
||||
JSON object or null; example: `"cannot use operator+=() with number"`
|
||||
|
||||
## Complexity
|
||||
|
||||
@ -59,18 +56,16 @@ reference operator+=(initializer_list_t init);
|
||||
|
||||
## Notes
|
||||
|
||||
(3) This function is required to resolve an ambiguous overload error,
|
||||
because pairs like `{"key", "value"}` can be both interpreted as
|
||||
`object_t::value_type` or `std::initializer_list<basic_json>`, see
|
||||
(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both
|
||||
interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, see
|
||||
[#235](https://github.com/nlohmann/json/issues/235) for more information.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example shows how `push_back()` and `+=` can be used to
|
||||
add elements to a JSON array. Note how the `null` value was silently
|
||||
converted to a JSON array.
|
||||
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
|
||||
was silently converted to a JSON array.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/push_back.cpp"
|
||||
@ -84,9 +79,8 @@ because pairs like `{"key", "value"}` can be both interpreted as
|
||||
|
||||
??? example
|
||||
|
||||
The example shows how `push_back()` and `+=` can be used to
|
||||
add elements to a JSON object. Note how the `null` value was silently
|
||||
converted to a JSON object.
|
||||
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
|
||||
was silently converted to a JSON object.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/push_back__object_t__value.cpp"
|
||||
@ -100,8 +94,7 @@ because pairs like `{"key", "value"}` can be both interpreted as
|
||||
|
||||
??? example
|
||||
|
||||
The example shows how initializer lists are treated as
|
||||
objects when possible.
|
||||
The example shows how initializer lists are treated as objects when possible.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/push_back__initializer_list.cpp"
|
||||
|
||||
@ -9,9 +9,8 @@ basic_json& operator=(basic_json other) noexcept (
|
||||
);
|
||||
```
|
||||
|
||||
Copy assignment operator. Copies a JSON value via the "copy and swap"
|
||||
strategy: It is expressed in terms of the copy constructor, destructor,
|
||||
and the `swap()` member function.
|
||||
Copy assignment operator. Copies a JSON value via the "copy and swap" strategy: It is expressed in terms of the copy
|
||||
constructor, destructor, and the `swap()` member function.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -26,10 +25,8 @@ Linear.
|
||||
|
||||
??? example
|
||||
|
||||
The code below shows and example for the copy assignment. It
|
||||
creates a copy of value `a` which is then swapped with `b`. Finally\, the
|
||||
copy of `a` (which is the null value after the swap) is
|
||||
destroyed.
|
||||
The code below shows and example for the copy assignment. It creates a copy of value `a` which is then swapped with
|
||||
`b`. Finally, the copy of `a` (which is the null value after the swap) is destroyed.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__copyassignment.cpp"
|
||||
|
||||
@ -12,11 +12,10 @@ bool operator==(ScalarType lhs, const const_reference rhs) noexcept;
|
||||
|
||||
Compares two JSON values for equality according to the following rules:
|
||||
|
||||
- Two JSON values are equal if (1) they are from the same type and (2)
|
||||
their stored values are the same according to their respective
|
||||
`operator==`.
|
||||
- Integer and floating-point numbers are automatically converted before
|
||||
comparison. Note that two NaN values are always treated as unequal.
|
||||
- Two JSON values are equal if (1) they are from the same type and (2) their stored values are the same according to
|
||||
their respective `operator==`.
|
||||
- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
|
||||
treated as unequal.
|
||||
- Two JSON null values are equal.
|
||||
|
||||
## Template parameters
|
||||
@ -46,9 +45,8 @@ Linear.
|
||||
|
||||
## Notes
|
||||
|
||||
- Floating-point inside JSON values numbers are compared with
|
||||
`json::number_float_t::operator==` which is `double::operator==` by
|
||||
default. To compare floating-point while respecting an epsilon, an alternative
|
||||
- Floating-point inside JSON values numbers are compared with `json::number_float_t::operator==` which is
|
||||
`double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative
|
||||
[comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
|
||||
could be used, for instance
|
||||
|
||||
@ -84,8 +82,9 @@ could be used, for instance
|
||||
|
||||
## Example
|
||||
|
||||
The example demonstrates comparing several JSON
|
||||
types.
|
||||
??? example
|
||||
|
||||
The example demonstrates comparing several JSON types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/operator__equal.cpp"
|
||||
|
||||
@ -47,51 +47,45 @@ const_reference operator[](const json_pointer& ptr) const;
|
||||
## Exceptions
|
||||
|
||||
1. The function can throw the following exceptions:
|
||||
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array or null; in that
|
||||
cases, using the `[]` operator with an index makes no sense.
|
||||
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
|
||||
or null; in that cases, using the `[]` operator with an index makes no sense.
|
||||
2. The function can throw the following exceptions:
|
||||
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array or null; in that
|
||||
cases, using the `[]` operator with an index makes no sense.
|
||||
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
|
||||
or null; in that cases, using the `[]` operator with an index makes no sense.
|
||||
3. The function can throw the following exceptions:
|
||||
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed JSON pointer `ptr`
|
||||
begins with '0'.
|
||||
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed JSON pointer `ptr`
|
||||
is not a number.
|
||||
- Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used 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 [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
|
||||
JSON pointer `ptr` begins with '0'.
|
||||
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
|
||||
JSON pointer `ptr` is not a number.
|
||||
- Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
|
||||
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.
|
||||
|
||||
## Notes
|
||||
|
||||
!!! danger
|
||||
|
||||
1. If the element with key `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 an assertion**!
|
||||
1. If the element with key `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 an assertion**!
|
||||
|
||||
1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`),
|
||||
then the array is silently filled up with `#!json null` values to make `idx` a
|
||||
valid reference to the last stored element.
|
||||
In case the value was `#!json null` before, it is converted to an array.
|
||||
1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the
|
||||
array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In
|
||||
case the value was `#!json null` before, it is converted to an array.
|
||||
|
||||
2. If `key` is not found in the object, then it is silently added to
|
||||
the object and filled with a `#!json null` value to make `key` a valid reference.
|
||||
In case the value was `#!json null` before, it is converted to an object.
|
||||
2. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to
|
||||
make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object.
|
||||
|
||||
3. `null` values are created in arrays and objects if necessary.
|
||||
|
||||
In particular:
|
||||
|
||||
- If the JSON pointer points to an object key that does not exist, it
|
||||
is created an filled with a `null` value before a reference to it
|
||||
is returned.
|
||||
- If the JSON pointer points to an array index that does not exist, it
|
||||
is created an filled with a `null` value before a reference to it
|
||||
is returned. All indices between the current maximum and the given
|
||||
index are also filled with `null`.
|
||||
- The special value `-` is treated as a synonym for the index past the
|
||||
end.
|
||||
- If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null`
|
||||
value before a reference to it is returned.
|
||||
- If the JSON pointer points to an array index that does not exist, it is created an filled with a `#!json null`
|
||||
value before a reference to it is returned. All indices between the current maximum and the given index are also
|
||||
filled with `#!json null`.
|
||||
- The special value `-` is treated as a synonym for the index past the end.
|
||||
|
||||
## Exception safety
|
||||
|
||||
@ -107,9 +101,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how array elements can be read and
|
||||
written using `[]` operator. Note the addition of `null`
|
||||
values.
|
||||
The example below shows how array elements can be read and written using `[]` operator. Note the addition of
|
||||
`#!json null` values.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/operatorarray__size_type.cpp"
|
||||
@ -123,8 +116,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how array elements can be read using
|
||||
the `[]` operator.
|
||||
The example below shows how array elements can be read using the `[]` operator.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/operatorarray__size_type_const.cpp"
|
||||
@ -138,8 +130,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how object elements can be read and
|
||||
written using the `[]` operator.
|
||||
The example below shows how object elements can be read and written using the `[]` operator.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/operatorarray__key_type.cpp"
|
||||
@ -153,8 +144,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how object elements can be read using
|
||||
the `[]` operator.
|
||||
The example below shows how object elements can be read using the `[]` operator.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/operatorarray__key_type_const.cpp"
|
||||
|
||||
@ -4,8 +4,7 @@
|
||||
constexpr operator value_t() const noexcept;
|
||||
```
|
||||
|
||||
Return the type of the JSON value as a value from the [`value_t`](value_t.md)
|
||||
enumeration.
|
||||
Return the type of the JSON value as a value from the [`value_t`](value_t.md) enumeration.
|
||||
|
||||
## Return value
|
||||
|
||||
@ -36,8 +35,7 @@ Constant.
|
||||
|
||||
??? example
|
||||
|
||||
The following code exemplifies `operator value_t()` for all JSON
|
||||
types.
|
||||
The following code exemplifies `operator value_t()` for all JSON types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/operator__value_t.cpp"
|
||||
|
||||
@ -6,16 +6,13 @@ using parser_callback_t =
|
||||
std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
|
||||
```
|
||||
|
||||
With a parser callback function, the result of parsing a JSON text can be
|
||||
influenced. When passed to [`parse`](parse.md), it is called on certain events
|
||||
(passed as [`parse_event_t`](parse_event_t.md) via parameter `event`) with a set recursion
|
||||
depth `depth` and context JSON value `parsed`. The return value of the
|
||||
callback function is a boolean indicating whether the element that emitted
|
||||
the callback shall be kept or not.
|
||||
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to
|
||||
[`parse`](parse.md), it is called on certain events (passed as [`parse_event_t`](parse_event_t.md) via parameter
|
||||
`event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the callback function
|
||||
is a boolean indicating whether the element that emitted the callback shall be kept or not.
|
||||
|
||||
We distinguish six scenarios (determined by the event type) in which the
|
||||
callback function can be called. The following table describes the values
|
||||
of the parameters `depth`, `event`, and `parsed`.
|
||||
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
|
||||
table describes the values of the parameters `depth`, `event`, and `parsed`.
|
||||
|
||||
parameter `event` | description | parameter `depth` | parameter `parsed`
|
||||
------------------ | ----------- | ------------------ | -------------------
|
||||
@ -28,13 +25,13 @@ parameter `event` | description | parameter `depth` | parameter `parsed`
|
||||
|
||||
|
||||
|
||||
Discarding a value (i.e., returning `#!cpp false`) has different effects
|
||||
depending on the context in which function was called:
|
||||
Discarding a value (i.e., returning `#!cpp false`) has different effects depending on the context in which function was
|
||||
called:
|
||||
|
||||
- Discarded values in structured types are skipped. That is, the parser
|
||||
will behave as if the discarded value was never read.
|
||||
- In case a value outside a structured type is skipped, it is replaced
|
||||
with `null`. This case happens if the top-level element is skipped.
|
||||
- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
|
||||
read.
|
||||
- In case a value outside a structured type is skipped, it is replaced with `null`. This case happens if the top-level
|
||||
element is skipped.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -51,9 +48,8 @@ depending on the context in which function was called:
|
||||
|
||||
## Return value
|
||||
|
||||
Whether the JSON value which called the function during parsing
|
||||
should be kept (`#!cpp true`) or not (`#!cpp false`). In the latter case, it is either
|
||||
skipped completely or replaced by an empty discarded object.
|
||||
Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
|
||||
the latter case, it is either skipped completely or replaced by an empty discarded object.
|
||||
|
||||
# Example
|
||||
|
||||
|
||||
@ -4,10 +4,9 @@
|
||||
basic_json patch(const basic_json& json_patch) const;
|
||||
```
|
||||
|
||||
[JSON Patch](http://jsonpatch.com) defines a JSON document structure for
|
||||
expressing a sequence of operations to apply to a JSON) document. With
|
||||
this function, a JSON Patch is applied to the current JSON value by
|
||||
executing all operations from the patch.
|
||||
[JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
|
||||
a JSON) document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
|
||||
the patch.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -20,40 +19,37 @@ patched document
|
||||
|
||||
## Exceptions
|
||||
|
||||
- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of an array of
|
||||
objects.
|
||||
- Throws [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105) if the JSON patch is malformed (e.g., mandatory
|
||||
attributes are missing); example: `"operation add must have member path"`.
|
||||
- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of
|
||||
an array of objects.
|
||||
- Throws [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105) if the JSON patch is malformed (e.g.,
|
||||
mandatory attributes are missing); example: `"operation add must have member path"`.
|
||||
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index is out of range.
|
||||
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch 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 unsuccessful.
|
||||
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch
|
||||
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
|
||||
unsuccessful.
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no
|
||||
changes in the JSON value.
|
||||
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the size of the JSON value and the length of the
|
||||
JSON patch. As usually only a fraction of the JSON value is affected by
|
||||
the patch, the complexity can usually be neglected.
|
||||
Linear in the size of the JSON value and the length of the JSON patch. As usually only a fraction of the JSON value is
|
||||
affected by the patch, the complexity can usually be neglected.
|
||||
|
||||
## Note
|
||||
|
||||
The application of a patch is atomic: Either all operations succeed
|
||||
and the patched document is returned or an exception is thrown. In
|
||||
any case, the original value is not changed: the patch is applied
|
||||
to a copy of the value.
|
||||
The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception
|
||||
is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
|
||||
|
||||
## Example
|
||||
|
||||
??? example
|
||||
|
||||
The following code shows how a JSON patch is applied to a
|
||||
value.
|
||||
The following code shows how a JSON patch is applied to a value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/patch.cpp"
|
||||
|
||||
@ -12,13 +12,11 @@ void push_back(const typename object_t::value_type& val);
|
||||
void push_back(initializer_list_t init);
|
||||
```
|
||||
|
||||
1. Appends the given element `val` to the end of the JSON array. If the
|
||||
function is called on a JSON null value, an empty array is created before
|
||||
appending `val`.
|
||||
1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an
|
||||
empty array is created before appending `val`.
|
||||
|
||||
2. Inserts the given element `val` to the JSON object. If the function is
|
||||
called on a JSON null value, an empty object is created before inserting
|
||||
`val`.
|
||||
2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
|
||||
is created before inserting `val`.
|
||||
|
||||
3. This function allows to use `push_back` with an initializer list. In case
|
||||
|
||||
@ -26,9 +24,8 @@ void push_back(initializer_list_t init);
|
||||
2. the initializer list `init` contains only two elements, and
|
||||
3. the first element of `init` is a string,
|
||||
|
||||
`init` is converted into an object element and added using
|
||||
`push_back(const typename object_t::value_type&)`. Otherwise, `init`
|
||||
is converted to a JSON value and added using `push_back(basic_json&&)`.
|
||||
`init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`.
|
||||
Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -41,11 +38,11 @@ void push_back(initializer_list_t init);
|
||||
## Exceptions
|
||||
|
||||
1. The function can throw the following exceptions:
|
||||
- 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"`
|
||||
- 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. The function can throw the following exceptions:
|
||||
- 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"`
|
||||
- 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"`
|
||||
|
||||
## Complexity
|
||||
|
||||
@ -55,18 +52,16 @@ void push_back(initializer_list_t init);
|
||||
|
||||
## Notes
|
||||
|
||||
(3) This function is required to resolve an ambiguous overload error,
|
||||
because pairs like `{"key", "value"}` can be both interpreted as
|
||||
`object_t::value_type` or `std::initializer_list<basic_json>`, see
|
||||
(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both
|
||||
interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, see
|
||||
[#235](https://github.com/nlohmann/json/issues/235) for more information.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example shows how `push_back()` and `+=` can be used to
|
||||
add elements to a JSON array. Note how the `null` value was silently
|
||||
converted to a JSON array.
|
||||
The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
|
||||
was silently converted to a JSON array.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/push_back.cpp"
|
||||
@ -80,9 +75,8 @@ because pairs like `{"key", "value"}` can be both interpreted as
|
||||
|
||||
??? example
|
||||
|
||||
The example shows how `push_back()` and `+=` can be used to
|
||||
add elements to a JSON object. Note how the `null` value was silently
|
||||
converted to a JSON object.
|
||||
The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
|
||||
was silently converted to a JSON object.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/push_back__object_t__value.cpp"
|
||||
@ -96,8 +90,7 @@ because pairs like `{"key", "value"}` can be both interpreted as
|
||||
|
||||
??? example
|
||||
|
||||
The example shows how initializer lists are treated as
|
||||
objects when possible.
|
||||
The example shows how initializer lists are treated as objects when possible.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/push_back__initializer_list.cpp"
|
||||
|
||||
@ -5,8 +5,8 @@ reverse_iterator rend() noexcept;
|
||||
const_reverse_iterator rend() const noexcept;
|
||||
```
|
||||
|
||||
Returns an iterator to the reverse-end; that is, one before the first
|
||||
element. This element acts as a placeholder, attempting to access it results in undefined behavior.
|
||||
Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder,
|
||||
attempting to access it results in undefined behavior.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -23,8 +23,8 @@ Read from input and generate SAX events
|
||||
1. Read from a compatible input.
|
||||
2. Read from a pair of character iterators
|
||||
|
||||
The value_type of the iterator must be a integral type with size of 1, 2 or
|
||||
4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32.
|
||||
The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
|
||||
respectively as UTF-8, UTF-16 and UTF-32.
|
||||
|
||||
The SAX event lister must follow the interface of `json_sax`.
|
||||
|
||||
@ -61,9 +61,8 @@ The SAX event lister must follow the interface of `json_sax`.
|
||||
: whether the input has to be consumed completely (optional, `#!cpp true` by default)
|
||||
|
||||
`ignore_comments` (in)
|
||||
: whether comments should be ignored and treated
|
||||
like whitespace (`#!cpp true`) or yield a parse error (`#!cpp false`); (optional, `#!cpp false` by
|
||||
default)
|
||||
: whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
|
||||
(`#!cpp false`); (optional, `#!cpp false` by default)
|
||||
|
||||
`first` (in)
|
||||
: iterator to start of character range
|
||||
@ -79,9 +78,8 @@ return value of the last processed SAX event
|
||||
|
||||
## Complexity
|
||||
|
||||
Linear in the length of the input. The parser is a predictive
|
||||
LL(1) parser. The complexity can be higher if the SAX consumer `sax` has
|
||||
a super-linear complexity.
|
||||
Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX
|
||||
consumer `sax` has a super-linear complexity.
|
||||
|
||||
## Notes
|
||||
|
||||
@ -91,9 +89,8 @@ A UTF-8 byte order mark is silently ignored.
|
||||
|
||||
??? example
|
||||
|
||||
The example below demonstrates the `sax_parse()` function
|
||||
reading from string and processing the events with a user-defined SAX
|
||||
event consumer.
|
||||
The example below demonstrates the `sax_parse()` function reading from string and processing the events with a
|
||||
user-defined SAX event consumer.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/sax_parse.cpp"
|
||||
|
||||
@ -8,8 +8,7 @@ Returns the number of elements in a JSON value.
|
||||
|
||||
## Return value
|
||||
|
||||
The return value depends on the different types and is
|
||||
defined as follows:
|
||||
The return value depends on the different types and is defined as follows:
|
||||
|
||||
Value type | return value
|
||||
----------- | -------------
|
||||
@ -27,22 +26,20 @@ No-throw guarantee: this function never throws exceptions.
|
||||
|
||||
## Complexity
|
||||
|
||||
Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy
|
||||
the Container concept; that is, their `size()` functions have constant
|
||||
complexity.
|
||||
Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy the
|
||||
[Container](https://en.cppreference.com/w/cpp/named_req/Container) concept; that is, their `size()` functions have
|
||||
constant complexity.
|
||||
|
||||
## Notes
|
||||
|
||||
This function does not return the length of a string stored as JSON
|
||||
value - it returns the number of elements in the JSON value which is `1` in
|
||||
the case of a string.
|
||||
This function does not return the length of a string stored as JSON value -- it returns the number of elements in the
|
||||
JSON value which is `1` in the case of a string.
|
||||
|
||||
## Example
|
||||
|
||||
??? example
|
||||
|
||||
The following code calls `size()` on the different value
|
||||
types.
|
||||
The following code calls `size()` on the different value types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/size.cpp"
|
||||
|
||||
@ -9,53 +9,41 @@ The type used to store JSON strings.
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) 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 JSON class into
|
||||
byte-sized characters during deserialization.
|
||||
To store objects 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
|
||||
|
||||
`StringType`
|
||||
: the container to store strings (e.g., `std::string`).
|
||||
Note this container is used for keys/names in objects, see [object_t](object_t.md).
|
||||
: the container to store strings (e.g., `std::string`). Note this container is used for keys/names in objects, see
|
||||
[object_t](object_t.md).
|
||||
|
||||
## Notes
|
||||
|
||||
#### Default type
|
||||
|
||||
With the default values for `StringType` (`std::string`), the default
|
||||
value for `string_t` is:
|
||||
|
||||
```cpp
|
||||
std::string
|
||||
```
|
||||
With the default values for `StringType` (`std::string`), the default value for `string_t` is `#!cpp std::string`.
|
||||
|
||||
#### Encoding
|
||||
|
||||
Strings are stored in UTF-8 encoding. Therefore, functions like
|
||||
`std::string::size()` or `std::string::length()` return the number of
|
||||
bytes in the string rather than the number of characters or glyphs.
|
||||
Strings are stored in UTF-8 encoding. Therefore, functions like `std::string::size()` or `std::string::length()` return
|
||||
the number of bytes in the string rather than the number of characters or glyphs.
|
||||
|
||||
#### String comparison
|
||||
|
||||
[RFC 7159](http://rfc7159.net/rfc7159) states:
|
||||
> Software implementations are typically required to test names of object
|
||||
> members for equality. Implementations that transform the textual
|
||||
> representation into sequences of Unicode code units and then perform the
|
||||
> comparison numerically, code unit by code unit, are interoperable in the
|
||||
> sense that implementations will agree in all cases on equality or
|
||||
> inequality of two strings. For example, implementations that compare
|
||||
> strings with escaped characters unconverted may incorrectly find that
|
||||
> `"a\\b"` and `"a\u005Cb"` are not equal.
|
||||
> Software implementations are typically required to test names of object members for equality. Implementations that
|
||||
> transform the textual representation into sequences of Unicode code units and then perform the comparison numerically,
|
||||
> code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or
|
||||
> inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may
|
||||
> incorrectly find that `"a\\b"` and `"a\u005Cb"` are not equal.
|
||||
|
||||
This implementation is interoperable as it does compare strings code unit
|
||||
by code unit.
|
||||
This implementation is interoperable as it does compare strings code unit by code unit.
|
||||
|
||||
#### Storage
|
||||
|
||||
String values are stored as pointers in a `basic_json` type. That is,
|
||||
for any access to string values, a pointer of type `string_t*` must be
|
||||
dereferenced.
|
||||
String values are stored as pointers in a `basic_json` type. That is, for any access to string values, a pointer of type
|
||||
`string_t*` must be dereferenced.
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@ -4,8 +4,7 @@
|
||||
constexpr value_t type() const noexcept;
|
||||
```
|
||||
|
||||
Return the type of the JSON value as a value from the [`value_t`](value_t.md)
|
||||
enumeration.
|
||||
Return the type of the JSON value as a value from the [`value_t`](value_t.md) enumeration.
|
||||
|
||||
## Return value
|
||||
|
||||
@ -36,8 +35,7 @@ Constant.
|
||||
|
||||
??? example
|
||||
|
||||
The following code exemplifies `type()` for all JSON
|
||||
types.
|
||||
The following code exemplifies `type()` for all JSON types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/type.cpp"
|
||||
|
||||
@ -4,8 +4,8 @@
|
||||
const char* type_name() const noexcept;
|
||||
```
|
||||
|
||||
Returns the type name as string to be used in error messages - usually to
|
||||
indicate that a function was called on a wrong JSON type.
|
||||
Returns the type name as string to be used in error messages -- usually to indicate that a function was called on a
|
||||
wrong JSON type.
|
||||
|
||||
## Return value
|
||||
|
||||
@ -34,8 +34,7 @@ Constant.
|
||||
|
||||
??? example
|
||||
|
||||
The following code exemplifies `type_name()` for all JSON
|
||||
types.
|
||||
The following code exemplifies `type_name()` for all JSON types.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/type_name.cpp"
|
||||
|
||||
@ -4,13 +4,11 @@
|
||||
basic_json unflatten() const;
|
||||
```
|
||||
|
||||
The function restores the arbitrary nesting of a JSON value that has been
|
||||
flattened before using the [`flatten()`](flatten.md) function. The JSON value must
|
||||
meet certain constraints:
|
||||
The function restores the arbitrary nesting of a JSON value that has been flattened before using the
|
||||
[`flatten()`](flatten.md) function. The JSON value must meet certain constraints:
|
||||
|
||||
1. The value must be an object.
|
||||
2. The keys must be JSON pointers (see
|
||||
[RFC 6901](https://tools.ietf.org/html/rfc6901))
|
||||
2. The keys must be JSON pointers (see [RFC 6901](https://tools.ietf.org/html/rfc6901))
|
||||
3. The mapped values must be primitive JSON types.
|
||||
|
||||
## Return value
|
||||
@ -34,17 +32,15 @@ Linear in the size the JSON value.
|
||||
|
||||
## Notes
|
||||
|
||||
Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null`
|
||||
values and can not unflattened to their original type. Apart from
|
||||
this example, for a JSON value `j`, the following is always true:
|
||||
Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and can not unflattened to
|
||||
their original type. Apart from this example, for a JSON value `j`, the following is always true:
|
||||
`#!cpp j == j.flatten().unflatten()`.
|
||||
|
||||
## Example
|
||||
|
||||
??? example
|
||||
|
||||
The following code shows how a flattened JSON object is
|
||||
unflattened into the original nested JSON object.
|
||||
The following code shows how a flattened JSON object is unflattened into the original nested JSON object.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/unflatten.cpp"
|
||||
|
||||
@ -11,7 +11,8 @@ void update(const_iterator first, const_iterator last);
|
||||
1. Inserts all values from JSON object `j` and overwrites existing keys.
|
||||
2. Inserts all values from from range `[first, last)` and overwrites existing keys.
|
||||
|
||||
The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update) function.
|
||||
The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update)
|
||||
function.
|
||||
|
||||
## Parameters
|
||||
|
||||
@ -27,16 +28,15 @@ The function is motivated by Python's [dict.update](https://docs.python.org/3.6/
|
||||
## Exceptions
|
||||
|
||||
1. The function can throw thw 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 [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
|
||||
objects; example: `"cannot use update() with string"`
|
||||
2. The function can throw thw 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"`
|
||||
- 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"`
|
||||
|
||||
## Complexity
|
||||
|
||||
|
||||
@ -12,8 +12,8 @@ ValueType value(const json_pointer& ptr,
|
||||
const ValueType& default_value) const;
|
||||
```
|
||||
|
||||
1. Returns either a copy of an object's element at the specified key `key`
|
||||
or a given default value if no element with key `key` exists.
|
||||
1. Returns either a copy of an object's element at the specified key `key` or a given default value if no element with
|
||||
key `key` exists.
|
||||
|
||||
The function is basically equivalent to executing
|
||||
```cpp
|
||||
@ -24,8 +24,8 @@ ValueType value(const json_pointer& ptr,
|
||||
}
|
||||
```
|
||||
|
||||
2. Returns either a copy of an object's element at the specified JSON pointer `ptr`
|
||||
or a given default value if no value at `ptr` exists.
|
||||
2. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
|
||||
at `ptr` exists.
|
||||
|
||||
The function is basically equivalent to executing
|
||||
```cpp
|
||||
@ -36,16 +36,14 @@ ValueType value(const json_pointer& ptr,
|
||||
}
|
||||
```
|
||||
|
||||
Unlike [`operator[]`](operator[].md), this
|
||||
function does not implicitly add an element to the position defined by `key`/`ptr`
|
||||
key. This function is furthermore also applicable to const objects.
|
||||
Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
|
||||
`key`/`ptr` key. This function is furthermore also applicable to const objects.
|
||||
|
||||
## Template parameters
|
||||
|
||||
`ValueType`
|
||||
: type compatible to JSON values, for instance `#!cpp int` for
|
||||
JSON integer numbers, `#!cpp bool` for JSON booleans, or `#!cpp std::vector` types for
|
||||
JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
|
||||
: type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans,
|
||||
or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
|
||||
value `default_value` must be compatible.
|
||||
|
||||
## Parameters
|
||||
@ -72,15 +70,15 @@ changes to any JSON value.
|
||||
## Exceptions
|
||||
|
||||
1. The function can throw thw following exceptions:
|
||||
- Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match the type of the
|
||||
value at `key`
|
||||
- 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.
|
||||
- Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
|
||||
the type of the value at `key`
|
||||
- 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.
|
||||
2. The function can throw thw following exceptions:
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
## Complexity
|
||||
|
||||
@ -91,8 +89,7 @@ changes to any JSON value.
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how object elements can be queried
|
||||
with a default value.
|
||||
The example below shows how object elements can be queried with a default value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__value.cpp"
|
||||
@ -106,8 +103,7 @@ changes to any JSON value.
|
||||
|
||||
??? example
|
||||
|
||||
The example below shows how object elements can be queried
|
||||
with a default value.
|
||||
The example below shows how object elements can be queried with a default value.
|
||||
|
||||
```cpp
|
||||
--8<-- "examples/basic_json__value_ptr.cpp"
|
||||
|
||||
@ -15,23 +15,19 @@ enum class value_t : std::uint8_t {
|
||||
};
|
||||
```
|
||||
|
||||
This enumeration collects the different JSON types. It is internally used to
|
||||
distinguish the stored values, and the functions [`is_null`](is_null.md),
|
||||
[`is_object`](is_object.md), [`is_array`](is_array.md),
|
||||
[`is_string`](is_string.md), [`is_boolean`](is_boolean.md),
|
||||
[`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md),
|
||||
This enumeration collects the different JSON types. It is internally used to distinguish the stored values, and the
|
||||
functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_array.md), [`is_string`](is_string.md),
|
||||
[`is_boolean`](is_boolean.md), [`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md),
|
||||
[`is_number_unsigned`](is_number_unsigned.md), and [`is_number_float`](is_number_float.md)),
|
||||
[`is_discarded`](is_discarded.md), [`is_binary`](is_binary.md), [`is_primitive`](is_primitive.md), and
|
||||
[`is_structured`](is_structured.md) rely on it.
|
||||
|
||||
## Note
|
||||
|
||||
There are three enumeration entries (number_integer, number_unsigned, and
|
||||
number_float), because the library distinguishes these three types for numbers:
|
||||
[`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
|
||||
[`number_integer_t`](number_integer_t.md) is used for signed integers, and
|
||||
[`number_float_t`](number_float_t.md) is used for floating-point numbers or to
|
||||
approximate integers which do not fit in the limits of their respective type.
|
||||
There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library
|
||||
distinguishes these three types for numbers: [`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
|
||||
[`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
|
||||
for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user