amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-02-21 02:46:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 update documentation (#4723)

Browse Source 
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
2025-04-05 18:54:35 +02:00
committed by GitHub
parent 11aa5f944d
commit 4424a0fcc1
90 changed files with 377 additions and 339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/mkdocs/docs/api/basic_json/accept.md
View File

@@ -17,8 +17,8 @@ Checks whether the input is valid JSON.
1. Reads from a compatible input.
2. Reads from a pair of character iterators
The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32.
Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
(i.e., a parse error) nor creates diagnostic information.
@@ -51,10 +51,10 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
(`#!cpp false`); (optional, `#!cpp false` by default)
`first` (in)
: iterator to start of character range
: iterator to the start of the character range
`last` (in)
: iterator to end of character range
: iterator to the end of the character range
## Return value
@@ -101,7 +101,7 @@ A UTF-8 byte order mark is silently ignored.
- Added in version 3.0.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
!!! warning "Deprecation"

20
docs/mkdocs/docs/api/basic_json/at.md
View File

@@ -59,29 +59,29 @@ Strong exception safety: if an exception occurs, the original value stays intact
1. The function can throw the following exceptions:
- Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an array;
in this case, calling `at` with an index makes no sense. See example below.
in this case, calling `at` with an index makes no sense. See the example below.
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if the index `idx` is out of
range of the array; that is, `idx >= size()`. See example below.
range of the array; that is, `idx >= size()`. See the example below.
2. The function can throw the following exceptions:
- Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
in this case, calling `at` with a key makes no sense. See example below.
in this case, calling `at` with a key makes no sense. See the example below.
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
stored in the object; that is, `find(key) == end()`. See example below.
stored in the object; that is, `find(key) == end()`. See the example below.
3. See 2.
4. 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'. See example below.
JSON pointer `ptr` begins with '0'. See the example below.
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
JSON pointer `ptr` is not a number. See example below.
JSON pointer `ptr` is not a number. See the example below.
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index in the passed
JSON pointer `ptr` is out of range. See example below.
JSON pointer `ptr` is out of range. See the example below.
- Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
in the passed JSON pointer `ptr`. As `at` provides checked access (and no elements are implicitly inserted), the
index '-' is always invalid. See example below.
index '-' is always invalid. See the example below.
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the JSON pointer describes a
key of an object which cannot be found. See example below.
key of an object which cannot be found. See the example below.
- Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
not be resolved. See example below.
not be resolved. See the example below.
## Complexity

4
docs/mkdocs/docs/api/basic_json/back.md
View File

@@ -17,8 +17,8 @@ return *tmp;
## Return value
In case of a structured type (array or object), a reference to the last element is returned. In case of number, string,
boolean, or binary values, a reference to the value is returned.
In the case of a structured type (array or object), a reference to the last element is returned. In the case of number,
string, boolean, or binary values, a reference to the value is returned.
## Exception safety

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

@@ -99,8 +99,8 @@ basic_json(basic_json&& other) noexcept;
2. C++ has no way of describing mapped types other than to list a list of pairs. As JSON requires that keys must be
of type string, rule 2 is the weakest constraint one can pose on initializer lists to interpret them as an
object.
3. In all other cases, the initializer list could not be interpreted as JSON object type, so interpreting it as JSON
array type is safe.
3. In all other cases, the initializer list could not be interpreted as a JSON object type, so interpreting it as a
JSON array type is safe.
With the rules described above, the following JSON values cannot be expressed by an initializer list:
@@ -113,7 +113,7 @@ basic_json(basic_json&& other) noexcept;
6. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is
created.
7. Constructs the JSON value with the contents of the range `[first, last)`. The semantics depends on the different
7. Constructs the JSON value with the contents of the range `[first, last)`. The semantics depend on the different
types a JSON value can have:
- In case of a `#!json null` type, [invalid_iterator.206](../../home/exceptions.md#jsonexceptioninvalid_iterator206)
@@ -175,10 +175,10 @@ basic_json(basic_json&& other) noexcept;
: the number of JSON copies of `val` to create
`first` (in)
: begin of the range to copy from (included)
: the beginning of the range to copy from (included)
`last` (in)
: end of the range to copy from (excluded)
: the end of the range to copy from (excluded)
`other` (in)
: the JSON value to copy/move
@@ -188,10 +188,10 @@ basic_json(basic_json&& other) noexcept;
1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
2. No-throw guarantee: this constructor never throws exceptions.
3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
`to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
`to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
JSON value.
4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
`to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
`to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
JSON value.
5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
@@ -217,7 +217,7 @@ basic_json(basic_json&& other) noexcept;
`[first, last)` is undefined.
- Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if iterators `first`
and `last` belong to a primitive type (number, boolean, or string), but `first` does not point to the first
element anymore. In this case, the range `[first, last)` is undefined. See example code below.
element anymore. In this case, the range `[first, last)` is undefined. See the example code below.
- Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
8. (none)
@@ -333,7 +333,7 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__list_init_t.output"
```
??? example "Example: (6) construct an array with count copies of given value"
??? example "Example: (6) construct an array with count copies of a given value"
The following code shows examples for creating arrays with several copies of a given value.

6
docs/mkdocs/docs/api/basic_json/binary.md
View File

@@ -21,7 +21,7 @@ create a value for serialization to those formats.
## Parameters
`init` (in)
: container containing bytes to use as binary type
: container containing bytes to use as a binary type
`subtype` (in)
: subtype to use in CBOR, MessagePack, and BSON
@@ -42,8 +42,8 @@ Linear in the size of `init`; constant for `typename binary_t::container_type&&
Note, this function exists because of the difficulty in correctly specifying the correct template overload in the
standard value ctor, as both JSON arrays and JSON binary arrays are backed with some form of a `std::vector`. Because
JSON binary arrays are a non-standard extension it was decided that it would be best to prevent automatic initialization
of a binary array type, for backwards compatibility and so it does not happen on accident.
JSON binary arrays are a non-standard extension, it was decided that it would be best to prevent automatic
initialization of a binary array type, for backwards compatibility and so it does not happen on accident.
## Examples

6
docs/mkdocs/docs/api/basic_json/binary_t.md
View File

@@ -56,11 +56,11 @@ type `#!cpp binary_t*` must be dereferenced.
- MessagePack
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
then added as signed 8-bit integer.
then added as a signed 8-bit integer.
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- BSON
- If a subtype is given, it is used and added as unsigned 8-bit integer.
- If a subtype is given, it is used and added as an unsigned 8-bit integer.
- If no subtype is given, the generic binary subtype 0x00 is used.
## Examples
@@ -86,4 +86,4 @@ type `#!cpp binary_t*` must be dereferenced.
## Version history
- Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0.
- Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0.

2
docs/mkdocs/docs/api/basic_json/clear.md
View File

@@ -33,7 +33,7 @@ Linear in the size of the JSON value.
## Notes
All iterators, pointers and references related to this container are invalidated.
All iterators, pointers, and references related to this container are invalidated.
## Examples

2
docs/mkdocs/docs/api/basic_json/contains.md
View File

@@ -35,7 +35,7 @@ bool contains(const json_pointer& ptr) const;
## Return value
1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
1. `#!cpp true` if an element with specified `key` exists. If no such element with such a key is found or the JSON value
is not an object, `#!cpp false` is returned.
2. See 1.
3. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.

4
docs/mkdocs/docs/api/basic_json/dump.md
View File

@@ -8,7 +8,7 @@ string_t dump(const int indent = -1,
```
Serialization function for JSON values. The function tries to mimic Python's
[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently supports its `indent`
[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently supports its `indent`
and `ensure_ascii` parameters.
## Parameters
@@ -49,7 +49,7 @@ Linear.
## Notes
Binary values are serialized as object containing two keys:
Binary values are serialized as an object containing two keys:
- "bytes": an array of bytes as integers
- "subtype": the subtype as integer or `#!json null` if the binary has no subtype

2
docs/mkdocs/docs/api/basic_json/flatten.md
View File

@@ -18,7 +18,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Complexity
Linear in the size the JSON value.
Linear in the size of the JSON value.
## Notes

8
docs/mkdocs/docs/api/basic_json/from_bjdata.md
View File

@@ -18,7 +18,7 @@ Deserializes a given input to a JSON value using the BJData (Binary JData) seria
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bjdata.md).
## Template parameters
@@ -40,10 +40,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
: an input in BJData format convertible to an input adapter
`first` (in)
: iterator to start of the input
: iterator to the start of the input
`last` (in)
: iterator to end of the input
: iterator to the end of the input
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -63,7 +63,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
the end of the file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
successfully

6
docs/mkdocs/docs/api/basic_json/from_bson.md
View File

@@ -18,7 +18,7 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bson.md).
## Template parameters
@@ -40,10 +40,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
: an input in BSON format convertible to an input adapter
`first` (in)
: iterator to start of the input
: iterator to the start of the input
`last` (in)
: iterator to end of the input
: iterator to the end of the input
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)

10
docs/mkdocs/docs/api/basic_json/from_cbor.md
View File

@@ -21,7 +21,7 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/cbor.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/cbor.md).
## Template parameters
@@ -43,10 +43,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
: an input in CBOR format convertible to an input adapter
`first` (in)
: iterator to start of the input
: iterator to the start of the input
`last` (in)
: iterator to end of the input
: iterator to the end of the input
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -70,10 +70,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
the end of the file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from CBOR were
used in the given input or if the input is not valid CBOR
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as a map key,
but not found
## Complexity

12
docs/mkdocs/docs/api/basic_json/from_msgpack.md
View File

@@ -18,7 +18,7 @@ Deserializes a given input to a JSON value using the MessagePack serialization f
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/messagepack.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/messagepack.md).
## Template parameters
@@ -40,10 +40,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
: an input in MessagePack format convertible to an input adapter
`first` (in)
: iterator to start of the input
: iterator to the start of the input
`last` (in)
: iterator to end of the input
: iterator to the end of the input
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -54,7 +54,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
## Exception safety
@@ -63,10 +63,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
the end of the file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from
MessagePack were used in the given input or if the input is not valid MessagePack
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as a map key,
but not found
## Complexity

8
docs/mkdocs/docs/api/basic_json/from_ubjson.md
View File

@@ -18,7 +18,7 @@ Deserializes a given input to a JSON value using the UBJSON (Universal Binary JS
1. Reads from a compatible input.
2. Reads from an iterator range.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/ubjson.md).
## Template parameters
@@ -40,10 +40,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
: an input in UBJSON format convertible to an input adapter
`first` (in)
: iterator to start of the input
: iterator to the start of the input
`last` (in)
: iterator to end of the input
: iterator to the end of the input
`strict` (in)
: whether to expect the input to be consumed until EOF (`#!cpp true` by default)
@@ -63,7 +63,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## Exceptions
- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
the end of file was not reached when `strict` was set to true
the end of the file was not reached when `strict` was set to true
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
successfully

4
docs/mkdocs/docs/api/basic_json/front.md
View File

@@ -10,8 +10,8 @@ Returns a reference to the first element in the container. For a JSON container
## Return value
In case of a structured type (array or object), a reference to the first element is returned. In case of number, string,
boolean, or binary values, a reference to the value is returned.
In the case of a structured type (array or object), a reference to the first element is returned. In the case of number,
string, boolean, or binary values, a reference to the value is returned.
## Exception safety

34
docs/mkdocs/docs/api/basic_json/index.md
View File

@@ -38,7 +38,7 @@ class basic_json;
## Specializations
- [**json**](../json.md) - default specialization
- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
- [**ordered_json**](../ordered_json.md) - a specialization that maintains the insertion order of object keys
## Iterator invalidation
@@ -58,8 +58,8 @@ The class satisfies the following concept requirements:
### Basic
- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default
constructed. The result will be a JSON null value.
- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be
default-constructed. The result will be a JSON null value.
- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed
from an rvalue argument.
- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be
@@ -167,19 +167,19 @@ Functions to inspect the type of a JSON value.
- [**type**](type.md) - return the type of the JSON value
- [**operator value_t**](operator_value_t.md) - return the type of the JSON value
- [**type_name**](type_name.md) - return the type as string
- [**is_primitive**](is_primitive.md) - return whether type is primitive
- [**is_structured**](is_structured.md) - return whether type is structured
- [**is_null**](is_null.md) - return whether value is null
- [**is_boolean**](is_boolean.md) - return whether value is a boolean
- [**is_number**](is_number.md) - return whether value is a number
- [**is_number_integer**](is_number_integer.md) - return whether value is an integer number
- [**is_number_unsigned**](is_number_unsigned.md) - return whether value is an unsigned integer number
- [**is_number_float**](is_number_float.md) - return whether value is a floating-point number
- [**is_object**](is_object.md) - return whether value is an object
- [**is_array**](is_array.md) - return whether value is an array
- [**is_string**](is_string.md) - return whether value is a string
- [**is_binary**](is_binary.md) - return whether value is a binary array
- [**is_discarded**](is_discarded.md) - return whether value is discarded
- [**is_primitive**](is_primitive.md) - return whether the type is primitive
- [**is_structured**](is_structured.md) - return whether the type is structured
- [**is_null**](is_null.md) - return whether the value is null
- [**is_boolean**](is_boolean.md) - return whether the value is a boolean
- [**is_number**](is_number.md) - return whether the value is a number
- [**is_number_integer**](is_number_integer.md) - return whether the value is an integer number
- [**is_number_unsigned**](is_number_unsigned.md) - return whether the value is an unsigned integer number
- [**is_number_float**](is_number_float.md) - return whether the value is a floating-point number
- [**is_object**](is_object.md) - return whether the value is an object
- [**is_array**](is_array.md) - return whether the value is an array
- [**is_string**](is_string.md) - return whether the value is a string
- [**is_binary**](is_binary.md) - return whether the value is a binary array
- [**is_discarded**](is_discarded.md) - return whether the value is discarded
Optional functions to access the [diagnostic positions](../macros/json_diagnostic_positions.md).
@@ -237,7 +237,7 @@ Access to the JSON value
- [**push_back**](push_back.md) - add a value to an array/object
- [**operator+=**](operator+=.md) - add a value to an array/object
- [**emplace_back**](emplace_back.md) - add a value to an array
- [**emplace**](emplace.md) - add a value to an object if key does not exist
- [**emplace**](emplace.md) - add a value to an object if a key does not exist
- [**erase**](erase.md) - remove elements
- [**insert**](insert.md) - inserts elements
- [**update**](update.md) - updates a JSON object from another object, overwriting existing keys

20
docs/mkdocs/docs/api/basic_json/insert.md
View File

@@ -18,11 +18,11 @@ iterator insert(const_iterator pos, initializer_list_t ilist);
void insert(const_iterator first, const_iterator last);
```
1. Inserts element `val` into array before iterator `pos`.
2. Inserts `cnt` copies of `val` into array before iterator `pos`.
3. Inserts elements from range `[first, last)` into array before iterator `pos`.
4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
5. Inserts elements from range `[first, last)` into object.
1. Inserts element `val` into an array before iterator `pos`.
2. Inserts `cnt` copies of `val` into an array before iterator `pos`.
3. Inserts elements from range `[first, last)` into an array before iterator `pos`.
4. Inserts elements from initializer list `ilist` into an array before iterator `pos`.
5. Inserts elements from range `[first, last)` into an object.
## Iterator invalidation
@@ -47,10 +47,10 @@ the same index which is now a different value.
: number of copies of `val` to insert
`first` (in)
: begin of the range of elements to insert
: the start of the range of elements to insert
`last` (in)
: end of the range of elements to insert
: the end of the range of elements to insert
`ilist` (in)
: initializer list to insert the values from
@@ -139,7 +139,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__count.output"
```
??? example "Example (3): insert range of elements into array"
??? example "Example (3): insert a range of elements into an array"
The example shows how `insert()` is used.
@@ -153,7 +153,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__range.output"
```
??? example "Example (4): insert elements from initializer list into array"
??? example "Example (4): insert elements from an initializer list into an array"
The example shows how `insert()` is used.
@@ -167,7 +167,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/insert__ilist.output"
```
??? example "Example (5): insert range of elements into object"
??? example "Example (5): insert a range of elements into an object"
The example shows how `insert()` is used.

2
docs/mkdocs/docs/api/basic_json/is_binary.md
View File

@@ -4,7 +4,7 @@
constexpr bool is_binary() const noexcept;
```
This function returns `#!cpp true` if and only if the JSON value is binary array.
This function returns `#!cpp true` if and only if the JSON value is a binary array.
## Return value

8
docs/mkdocs/docs/api/basic_json/is_number.md
View File

@@ -9,7 +9,7 @@ unsigned) and floating-point values.
## Return value
`#!cpp true` if type is number (regardless whether integer, unsigned integer or floating-type), `#!cpp false` otherwise.
`#!cpp true` if type is number (regardless whether integer, unsigned integer, or floating-type), `#!cpp false` otherwise.
## Exception safety
@@ -46,9 +46,9 @@ constexpr bool is_number() const noexcept
## See also
- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if value is a floating-point number
- [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if the value is a floating-point number
## Version history

6
docs/mkdocs/docs/api/basic_json/is_number_float.md
View File

@@ -37,9 +37,9 @@ Constant.
## See also
- [is_number()](is_number.md) check if value is a number
- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
- [is_number()](is_number.md) check if the value is a number
- [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
- [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
## Version history

6
docs/mkdocs/docs/api/basic_json/is_number_integer.md
View File

@@ -37,9 +37,9 @@ Constant.
## See also
- [is_number()](is_number.md) check if value is a number
- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if value is a floating-point number
- [is_number()](is_number.md) check if the value is a number
- [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
- [is_number_float()](is_number_float.md) check if the value is a floating-point number
## Version history

6
docs/mkdocs/docs/api/basic_json/is_number_unsigned.md
View File

@@ -37,9 +37,9 @@ Constant.
## See also
- [is_number()](is_number.md) check if value is a number
- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
- [is_number_float()](is_number_float.md) check if value is a floating-point number
- [is_number()](is_number.md) check if the value is a number
- [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
- [is_number_float()](is_number_float.md) check if the value is a floating-point number
## Version history

14
docs/mkdocs/docs/api/basic_json/is_primitive.md
View File

@@ -35,7 +35,7 @@ The term *primitive* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
> JSON can represent four primitive types (strings, numbers, booleans, and null) and two structured types (objects and
> arrays).
This library extends primitive types to binary types, because binary types are roughly comparable to strings. Hence,
This library extends primitive types to binary types, because binary types are roughly comparable to strings. Hence,
`is_primitive()` returns `#!cpp true` for binary values.
## Examples
@@ -56,12 +56,12 @@ This library extends primitive types to binary types, because binary types are
## See also
- [is_structured()](is_structured.md) returns whether JSON value is structured
- [is_null()](is_null.md) returns whether JSON value is `null`
- [is_string()](is_string.md) returns whether JSON value is a string
- [is_boolean()](is_boolean.md) returns whether JSON value is a boolean
- [is_number()](is_number.md) returns whether JSON value is a number
- [is_binary()](is_binary.md) returns whether JSON value is a binary array
- [is_structured()](is_structured.md) returns whether the JSON value is structured
- [is_null()](is_null.md) returns whether the JSON value is `null`
- [is_string()](is_string.md) returns whether the JSON value is a string
- [is_boolean()](is_boolean.md) returns whether the JSON value is a boolean
- [is_number()](is_number.md) returns whether the JSON value is a number
- [is_binary()](is_binary.md) returns whether the JSON value is a binary array
## Version history

4
docs/mkdocs/docs/api/basic_json/is_structured.md
View File

@@ -55,8 +55,8 @@ Note that though strings are containers in C++, they are treated as primitive va
## See also
- [is_primitive()](is_primitive.md) returns whether JSON value is primitive
- [is_array()](is_array.md) returns whether value is an array
- [is_object()](is_object.md) returns whether value is an object
- [is_array()](is_array.md) returns whether the value is an array
- [is_object()](is_object.md) returns whether the value is an object
## Version history

8
docs/mkdocs/docs/api/basic_json/number_float_t.md
View File

@@ -13,7 +13,7 @@ The type used to store JSON numbers (floating-point).
> 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
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`](number_unsigned_t.md) and `number_float_t` are
used.
@@ -28,9 +28,9 @@ With the default values for `NumberFloatType` (`double`), the default value for
#### Default behavior
- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in floating-point literals will be
ignored. Internally, the value will be stored as decimal number. For instance, the C++ floating-point literal `01.2`
will be serialized to `1.2`. During deserialization, leading zeros yield an error.
- The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in floating-point literals will
be ignored. Internally, the value will be stored as a decimal number. For instance, the C++ floating-point literal
`01.2` will be serialized to `1.2`. During deserialization, leading zeros yield an error.
- Not-a-number (NaN) values will be serialized to `null`.
#### Limits

10
docs/mkdocs/docs/api/basic_json/number_integer_t.md
View File

@@ -13,7 +13,7 @@ The type used to store JSON numbers (integers).
> 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
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.
@@ -29,9 +29,9 @@ With the default values for `NumberIntegerType` (`std::int64_t`), the default va
#### 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 are not enforced in C++. Instead, leading zeros in integer literals lead to an
interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++
integer literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
- Not-a-number (NaN) values will be serialized to `null`.
#### Limits
@@ -42,7 +42,7 @@ With the default values for `NumberIntegerType` (`std::int64_t`), the default va
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).
will automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
[RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are

10
docs/mkdocs/docs/api/basic_json/number_unsigned_t.md
View File

@@ -13,7 +13,7 @@ The type used to store JSON numbers (unsigned).
> 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
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.
@@ -29,9 +29,9 @@ With the default values for `NumberUnsignedType` (`std::uint64_t`), the default
#### 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 are not enforced in C++. Instead, leading zeros in integer literals lead to an
interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++
integer literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
- Not-a-number (NaN) values will be serialized to `null`.
#### Limits
@@ -41,7 +41,7 @@ With the default values for `NumberUnsignedType` (`std::uint64_t`), the default
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
when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored
as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
[RFC 8259](https://tools.ietf.org/html/rfc8259) further states:

4
docs/mkdocs/docs/api/basic_json/object.md
View File

@@ -25,7 +25,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
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.
`init`. See the example below.
## Complexity
@@ -34,7 +34,7 @@ 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
are no cases that 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

4
docs/mkdocs/docs/api/basic_json/object_t.md
View File

@@ -87,8 +87,8 @@ Objects are stored as pointers in a `basic_json` type. That is, for any access t
#### 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
The order name/value pairs are added to the object are *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 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON
objects.

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

@@ -121,4 +121,4 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
1. Since version 1.0.0.
2. Since version 1.0.0.
2. Since version 2.0.0.
3. Since version 2.0.0.

2
docs/mkdocs/docs/api/basic_json/operator_le.md
View File

@@ -17,7 +17,7 @@ bool operator<=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
operand is `NaN` and the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(rhs < lhs)` (see [**operator<**](operator_lt.md)).
1. Compares whether a JSON value is less than or equal to a scalar or a scalar is less than or equal
2. Compares whether a JSON value is less than or equal to a scalar or a scalar is less than or equal
to a JSON value by converting the scalar to a JSON value and comparing both JSON values according
to 1.

2
docs/mkdocs/docs/api/basic_json/out_of_range.md
View File

@@ -5,7 +5,7 @@ class out_of_range : public exception;
```
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for
instance in case of array indices or nonexisting object keys.
instance, in the case of array indices or nonexisting object keys.
Exceptions have ids 4xx (see [list of out-of-range errors](../../home/exceptions.md#out-of-range)).

12
docs/mkdocs/docs/api/basic_json/parse.md
View File

@@ -19,8 +19,8 @@ static basic_json parse(IteratorType first, IteratorType last,
1. Deserialize from a compatible input.
2. Deserialize from a pair of character iterators
The `value_type` of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
The `value_type` of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16, and UTF-32.
## Template parameters
@@ -57,10 +57,10 @@ static basic_json parse(IteratorType first, IteratorType last,
(`#!cpp false`); (optional, `#!cpp false` by default)
`first` (in)
: iterator to start of character range
: iterator to the start of a character range
`last` (in)
: iterator to end of character range
: iterator to the end of a character range
## Return value
@@ -147,7 +147,7 @@ A UTF-8 byte order mark is silently ignored.
--8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
```
??? example "Parsing from a non null-terminated string"
??? example "Parsing from a non-null-terminated string"
The example below demonstrates the `parse()` function reading from a string that is not null-terminated.
@@ -199,7 +199,7 @@ A UTF-8 byte order mark is silently ignored.
- Added in version 1.0.0.
- Overload for contiguous containers (1) added in version 2.0.3.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4.
- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
!!! warning "Deprecation"

2
docs/mkdocs/docs/api/basic_json/parse_error.md
View File

@@ -4,7 +4,7 @@
class parse_error : public exception;
```
This exception is thrown by the library when a parse error occurs. Parse errors can occur during the deserialization of
The library throws this exception when a parse error occurs. Parse errors can occur during the deserialization of
JSON text, BSON, CBOR, MessagePack, UBJSON, as well as when using JSON Patch.
Member `byte` holds the byte index of the last read character in the input file (see note below).

4
docs/mkdocs/docs/api/basic_json/patch.md
View File

@@ -37,8 +37,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
## 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 the patch affects only a fraction of
the JSON value, the complexity can usually be neglected.
## Notes

4
docs/mkdocs/docs/api/basic_json/patch_inplace.md
View File

@@ -33,8 +33,8 @@ No guarantees, value may be corrupted by an unsuccessful patch operation.
## 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 the patch affects only a fraction of
the JSON value, the complexity can usually be neglected.
## Notes

2
docs/mkdocs/docs/api/basic_json/push_back.md
View File

@@ -117,4 +117,4 @@ All functions can throw the following exception:
1. Since version 1.0.0.
2. Since version 1.0.0.
2. Since version 2.0.0.
3. Since version 2.0.0.

8
docs/mkdocs/docs/api/basic_json/sax_parse.md
View File

@@ -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 an integral type with size of 1, 2 or 4 bytes, which will be interpreted
respectively as UTF-8, UTF-16 and UTF-32.
The value_type of the iterator must be an integral type with a 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`](../json_sax/index.md).
@@ -66,10 +66,10 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
(`#!cpp false`); (optional, `#!cpp false` by default)
`first` (in)
: iterator to start of character range
: iterator to the start of a character range
`last` (in)
: iterator to end of character range
: iterator to the end of a character range
## Return value

2
docs/mkdocs/docs/api/basic_json/to_bjdata.md
View File

@@ -22,7 +22,7 @@ be more compact than JSON itself, yet more efficient to parse.
1. Returns a byte vector containing the BJData serialization.
2. Writes the BJData serialization to an output adapter.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bjdata.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bjdata.md).
## Parameters

4
docs/mkdocs/docs/api/basic_json/to_bson.md
View File

@@ -15,7 +15,7 @@ so-called document).
1. Returns a byte vector containing the BSON serialization.
2. Writes the BSON serialization to an output adapter.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/bson.md).
## Parameters
@@ -27,7 +27,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. BSON serialization as byte vector
1. BSON serialization as a byte vector
2. (none)
## Exception safety

6
docs/mkdocs/docs/api/basic_json/to_cbor.md
View File

@@ -10,13 +10,13 @@ static void to_cbor(const basic_json& j, detail::output_adapter<char> o);
```
Serializes a given JSON value `j` to a byte vector using the CBOR (Concise Binary Object Representation) serialization
format. CBOR is a binary serialization format which aims to be more compact than JSON itself, yet more efficient to
format. CBOR is a binary serialization format that aims to be more compact than JSON itself, yet more efficient to
parse.
1. Returns a byte vector containing the CBOR serialization.
2. Writes the CBOR serialization to an output adapter.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/cbor.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/cbor.md).
## Parameters
@@ -28,7 +28,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. CBOR serialization as byte vector
1. CBOR serialization as a byte vector
2. (none)
## Exception safety

6
docs/mkdocs/docs/api/basic_json/to_msgpack.md
View File

@@ -10,12 +10,12 @@ static void to_msgpack(const basic_json& j, detail::output_adapter<char> o);
```
Serializes a given JSON value `j` to a byte vector using the MessagePack serialization format. MessagePack is a binary
serialization format which aims to be more compact than JSON itself, yet more efficient to parse.
serialization format that aims to be more compact than JSON itself, yet more efficient to parse.
1. Returns a byte vector containing the MessagePack serialization.
2. Writes the MessagePack serialization to an output adapter.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/messagepack.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/messagepack.md).
## Parameters
@@ -27,7 +27,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. MessagePack serialization as byte vector
1. MessagePack serialization as a byte vector
2. (none)
## Exception safety

4
docs/mkdocs/docs/api/basic_json/to_ubjson.md
View File

@@ -19,7 +19,7 @@ aims to be more compact than JSON itself, yet more efficient to parse.
1. Returns a byte vector containing the UBJSON serialization.
2. Writes the UBJSON serialization to an output adapter.
The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
The exact mapping and its limitations are described on a [dedicated page](../../features/binary_formats/ubjson.md).
## Parameters
@@ -38,7 +38,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. UBJSON serialization as byte vector
1. UBJSON serialization as a byte vector
2. (none)
## Exception safety

4
docs/mkdocs/docs/api/basic_json/unflatten.md
View File

@@ -28,11 +28,11 @@ The function can throw the following exceptions:
## Complexity
Linear in the size the JSON value.
Linear in the size of the JSON value.
## Notes
Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and can not unflattened to
Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and cannot unflattened to
their original type. Apart from this example, for a JSON value `j`, the following is always true:
`#!cpp j == j.flatten().unflatten()`.

4
docs/mkdocs/docs/api/basic_json/update.md
View File

@@ -32,10 +32,10 @@ iterators (including the `end()` iterator) and all references to the elements ar
`#!c false`)
`first` (in)
: begin of the range of elements to insert
: the beginning of the range of elements to insert
`last` (in)
: end of the range of elements to insert
: the end of the range of elements to insert
## Exceptions