Skip to content

J
json
Unverified Commit 874f49e9 authored by Niels Lohmann's avatar Niels Lohmann
Browse files
Options

📝 add more API documentation

parent fe89049a
Hide whitespace changes
Inline Side-by-side
Showing with 290 additions and 410 deletions
doc/mkdocs/docs/api/basic_json/number_integer_t.md
View file @ 874f49e9
......@@ -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.
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.
> 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.
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
......
doc/mkdocs/docs/api/basic_json/number_unsigned_t.md
View file @ 874f49e9
......@@ -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.
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.
> 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.
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
......
doc/mkdocs/docs/api/basic_json/object.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/object_t.md
View file @ 874f49e9
......@@ -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
......
doc/mkdocs/docs/api/basic_json/operator+=.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/operator=.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/operator==.md
View file @ 874f49e9
......@@ -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,11 +45,10 @@ 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
[comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
could be used, for instance
- 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
```cpp
template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
......@@ -84,18 +82,19 @@ could be used, for instance
## Example
The example demonstrates comparing several JSON
types.
```cpp
--8<-- "examples/operator__equal.cpp"
```
??? example
Output:
```json
--8<-- "examples/operator__equal.output"
```
The example demonstrates comparing several JSON types.
```cpp
--8<-- "examples/operator__equal.cpp"
```
Output:
```json
--8<-- "examples/operator__equal.output"
```
## Version history
......
doc/mkdocs/docs/api/basic_json/operator[].md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/operator_value_t.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/parser_callback_t.md
View file @ 874f49e9
......@@ -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`
![Example when certain parse events are triggered](../../images/callback_events.png)
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
......
doc/mkdocs/docs/api/basic_json/patch.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/push_back.md
View file @ 874f49e9
......@@ -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
[#235](https://github.com/nlohmann/json/issues/235) for more information.
(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"
......
doc/mkdocs/docs/api/basic_json/rend.md
View file @ 874f49e9
......@@ -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.
![Illustration from cppreference.com](../../images/range-rbegin-rend.svg)
......
doc/mkdocs/docs/api/basic_json/sax_parse.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/size.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/string_t.md
View file @ 874f49e9
......@@ -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.
This implementation is interoperable as it does compare strings code unit
by code unit.
> 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.
#### 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
......
doc/mkdocs/docs/api/basic_json/type.md
View file @ 874f49e9
......@@ -4,9 +4,8 @@
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
the type of the JSON 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"
......
doc/mkdocs/docs/api/basic_json/type_name.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/unflatten.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/update.md
View file @ 874f49e9
......@@ -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
......
doc/mkdocs/docs/api/basic_json/value.md
View file @ 874f49e9
......@@ -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"
......
doc/mkdocs/docs/api/basic_json/value_t.md
View file @ 874f49e9
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment