External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

💄 adjust line length

Browse Source
This commit is contained in:
Niels Lohmann 2022-08-05 00:13:51 +02:00
parent 28f7780ba5
commit 823877e426
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
24 changed files with 148 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,8 +6,8 @@ using boolean_t = BooleanType;
The type used to store JSON booleans.
[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two literals
`#!json true` and `#!json false`.
[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two
literals`#!json true` and `#!json false`.
To store objects in C++, a type is defined by the template parameter `BooleanType` which chooses the type to use.

3
docs/mkdocs/docs/api/basic_json/object_comparator_t.md
View File

@ -28,4 +28,5 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
## Version history
- Added in version 3.0.0.
- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0.
- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in
version 3.11.0.

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

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

6
docs/mkdocs/docs/api/basic_json/operator[].md
View File

@ -21,7 +21,8 @@ const_reference operator[](const json_pointer& ptr) const;
```
1. Returns a reference to the array element at specified location `idx`.
2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value.
2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by
value.
3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
4. Returns a reference to the element with specified JSON pointer `ptr`.
@ -234,6 +235,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Version history
1. Added in version 1.0.0.
2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0.
2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3)
in version 3.11.0.
3. Added in version 3.11.0.
4. Added in version 2.0.0.

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

@ -20,8 +20,8 @@ class basic_json {
```
1. Compares two JSON values for equality according to the following rules:
- Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same
type and their stored values are the same according to their respective `operator==`.
- Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same type and their stored
values are the same according to their respective `operator==`.
- Integer and floating-point numbers are automatically converted before comparison.
2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the

13
docs/mkdocs/docs/api/basic_json/operator_ge.md
View File

@ -11,15 +11,14 @@ template<typename ScalarType>
bool operator>=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
```
1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs`
according to the following rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
operand is `NaN` and the other operand is either `NaN` or any other number.
1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` according to the following
rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and
the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(lhs < rhs)` (see [**operator<**](operator_lt.md)).
2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or
equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values
according to 1.
2. Compares whether a JSON value is greater than or equal to a scalar or a scalar is greater than or equal to a JSON
value by converting the scalar to a JSON value and comparing both JSON values according to 1.
## Template parameters

11
docs/mkdocs/docs/api/basic_json/operator_ne.md
View File

@ -20,13 +20,12 @@ class basic_json {
```
1. Compares two JSON values for inequality according to the following rules:
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
operand is `NaN` and the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or
`#!cpp !(*this == rhs)` (since C++20).
- The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and
the other operand is either `NaN` or any other number.
- Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or `#!cpp !(*this == rhs)` (since C++20).
2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the
scalar to a JSON value and comparing both JSON values according to 1.
2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the scalar to a JSON
value and comparing both JSON values according to 1.
## Template parameters

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

@ -12,16 +12,16 @@ class basic_json {
1. 3-way compares two JSON values producing a result of type `std::partial_ordering` according to the following rules:
- Two JSON values compare with a result of `std::partial_ordering::unordered` if either value is discarded.
- If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using their
- If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using
their respective `operator<=>`.
- Integer and floating-point numbers are converted to their common type and then 3-way compared using their
respective `operator<=>`.
- Integer and floating-point numbers are converted to their common type and then 3-way compared using their respective
`operator<=>`.
For instance, comparing an integer and a floating-point value will 3-way compare the first value convertered to
For instance, comparing an integer and a floating-point value will 3-way compare the first value converted to
floating-point with the second value.
- Otherwise, yields a result by comparing the type (see [`value_t`](value_t.md)).
2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and 3-way
comparing both JSON values (see 1).
2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and
3-way comparing both JSON values (see 1).
## Template parameters

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

@ -13,8 +13,8 @@ static void to_bjdata(const basic_json& j, detail::output_adapter<char> o,
const bool use_size = false, const bool use_type = false);
```
Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData
aims to be more compact than JSON itself, yet more efficient to parse.
Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData aims to
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.

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

@ -52,10 +52,8 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_
`operator<` and `operator<=>` (since C++20) are overloaded and compare according to the ordering described above.
Until C++20 all other relational and equality operators yield results according to the integer value of each
enumerator.
Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during overload
resolution, while others do not.
For predictable and portable behavior use:
enumerator. Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during
overload resolution, while others do not. For predictable and portable behavior use:
- `operator<` or `operator<=>` when wanting to compare according to the order described above
- `operator==` or `operator!=` when wanting to compare according to each enumerators integer value

7
docs/mkdocs/docs/api/macros/json_use_global_udls.md
View File

@ -21,8 +21,7 @@ When the macro is not defined, the library will define it to its default value.
!!! info "Future behavior change"
The user-defined string literals will be removed from the global namespace in the next major release of the
library.
The user-defined string literals will be removed from the global namespace in the next major release of the library.
To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where
needed. Refer to any of the [string literals](#see-also) for details.
@ -30,8 +29,8 @@ When the macro is not defined, the library will define it to its default value.
!!! hint "CMake option"
The placement of user-defined string literals can also be controlled with the CMake option
[`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default)
which defines `JSON_USE_GLOBAL_UDLS` accordingly.
[`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default) which defines
`JSON_USE_GLOBAL_UDLS` accordingly.
## Examples

17
docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md
View File

@ -4,8 +4,8 @@
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
```
This macro enables the (incorrect) legacy comparison behavior of discarded JSON values.
Possible values are `1` to enable or `0` to disable (default).
This macro enables the (incorrect) legacy comparison behavior of discarded JSON values. Possible values are `1` to
enable or `0` to disable (default).
When enabled, comparisons involving at least one discarded JSON value yield results as follows:
@ -42,19 +42,16 @@ When the macro is not defined, the library will define it to its default value.
`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`.
- Overloads for the equality and relational operators emulate the legacy behavior.
Code outside your control may use either 3-way comparison or the equality and
relational operators, resulting in inconsistent and unpredictable behavior.
Code outside your control may use either 3-way comparison or the equality and relational operators, resulting in
inconsistent and unpredictable behavior.
See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way
comparison.
See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way comparison.
!!! warning "Deprecation"
The legacy comparison behavior is deprecated and may be removed in a future major
version release.
The legacy comparison behavior is deprecated and may be removed in a future major version release.
New code should not depend on it and existing code should try to remove or rewrite
expressions relying on it.
New code should not depend on it and existing code should try to remove or rewrite expressions relying on it.
!!! hint "CMake option"

10
docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md
View File

@ -7,9 +7,9 @@
These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as
serialization and want to use the member variable names as object keys in that object. The macro is to be defined
**inside** the class/struct to create code for.
Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
**inside** the class/struct to create code for. Unlike
[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. The first
parameter is the name of the class/struct, and all remaining parameters name the members.
1. Will use [`at`](../basic_json/at.md) during deserialization and will throw
[`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
@ -40,8 +40,8 @@ See examples below for the concrete generated code.
!!! info "Prerequisites"
1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy]
for how to overcome this limitation.
1. The type `type` must be default constructible. See [How can I use `get()` for non-default
constructible/non-copyable types?][GetNonDefNonCopy] for how to overcome this limitation.
2. The macro must be used inside the type (class/struct).
[GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types

9
docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md
View File

@ -7,9 +7,9 @@
These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as
serialization and want to use the member variable names as object keys in that object. The macro is to be defined
**outside** the class/struct to create code for, but **inside** its namespace.
Unlike [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
**outside** the class/struct to create code for, but **inside** its namespace. Unlike
[`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. The first
parameter is the name of the class/struct, and all remaining parameters name the members.
1. Will use [`at`](../basic_json/at.md) during deserialization and will throw
[`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
@ -103,7 +103,8 @@ See examples below for the concrete generated code.
- `ns::person` is default-constructible. This is a requirement for using the macro.
- `ns::person` has only public member variables. This makes `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`
applicable.
- The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its namespace `ns`.
- The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its
namespace `ns`.
- A missing key "age" in the deserialization does not yield an exception. Instead, the default value `-1` is used.
The macro is equivalent to:

5
docs/mkdocs/docs/api/operator_literal_json.md
View File

@ -15,8 +15,9 @@ using namespace nlohmann::json_literals;
using namespace nlohmann::literals::json_literals;
using namespace nlohmann;
```
This is suggested to ease migration to the next major version release of the library.
See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
This is suggested to ease migration to the next major version release of the library. See
['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
## Parameters

4
docs/mkdocs/docs/api/operator_literal_json_pointer.md
View File

@ -15,8 +15,8 @@ using namespace nlohmann::json_literals;
using namespace nlohmann::literals::json_literals;
using namespace nlohmann;
```
This is suggested to ease migration to the next major version release of the library.
See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
This is suggested to ease migration to the next major version release of the library. See
['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
## Parameters

3
docs/mkdocs/docs/api/operator_ltlt.md
View File

@ -35,7 +35,8 @@ the stream `o`
## Exceptions
1. Throws [`type_error.316`](../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON
value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler` can be set.
value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler`
can be set.
2. None.
## Complexity

102
docs/mkdocs/docs/features/binary_formats/bjdata.md
View File

@ -1,20 +1,17 @@
# BJData
The [BJData format](https://neurojson.org) was derived from and improved upon
[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12).
Specifically, it introduces an optimized array container for efficient storage
of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers -
`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to
unambigiously map common binary numeric types; furthermore, it uses little-endian
(LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid
[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). Specifically, it introduces an optimized
array container for efficient storage of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers -
`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to unambiguously map common binary numeric types;
furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid
unnecessary conversions on commonly available platforms.
Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and
UBJSON demonstrate a rare combination of being both binary and **quasi-human-readable**. This
is because all semantic elements in BJData and UBJSON, including the data-type markers
and name/string types are directly human-readable. Data stored in the BJData/UBJSON format
are not only compact in size, fast to read/write, but also can be directly searched
or read using simple processing.
Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare
combination of being both binary and **quasi-human-readable**. This is because all semantic elements in BJData and
UBJSON, including the data-type markers and name/string types are directly human-readable. Data stored in the
BJData/UBJSON format are not only compact in size, fast to read/write, but also can be directly searched or read using
simple processing.
!!! abstract "References"
@ -74,48 +71,40 @@ The library uses the following mapping from JSON values types to BJData types ac
!!! info "NaN/infinity handling"
If NaN or Infinity are stored inside a JSON number, they are
serialized properly. This behavior differs from the `dump()`
function which serializes NaN or Infinity to `null`.
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the
`dump()` function which serializes NaN or Infinity to `#!json null`.
!!! info "Endianness"
A breaking difference between BJData and UBJSON is the endianness
of numerical values. In BJData, all numerical data types (integers
`UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE)
byte order as opposed to big-endian as used by UBJSON. Adopting LE
to store numeric records avoids unnecessary byte swapping on most modern
computers where LE is used as the default byte order.
A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data
types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as
opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on
most modern computers where LE is used as the default byte order.
!!! info "Optimized formats"
Optimized formats for containers are supported via two parameters of
[`to_bjdata`](../../api/basic_json/to_bjdata.md):
- Parameter `use_size` adds size information to the beginning of a container and
removes the closing marker.
- Parameter `use_type` further checks whether all elements of a container have the
same type and adds the type marker to the beginning of the container.
The `use_type` parameter must only be used together with `use_size = true`.
- Parameter `use_size` adds size information to the beginning of a container and removes the closing marker.
- Parameter `use_type` further checks whether all elements of a container have the same type and adds the type
marker to the beginning of the container. The `use_type` parameter must only be used together with
`use_size = true`.
Note that `use_size = true` alone may result in larger representations -
the benefit of this parameter is that the receiving side is
immediately informed of the number of elements in the container.
Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the
receiving side is immediately informed of the number of elements in the container.
!!! info "ND-array optimized format"
BJData extends UBJSON's optimized array **size** marker to support ND-arrays of
uniform numerical data types (referred to as *packed arrays*).
For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored
as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`,
can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6`
or `[$U#[i2 i3] 1 2 3 4 5 6`.
BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types
(referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested
optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to
`[$U#[$i#i2 2 3 1 2 3 4 5 6` or `[$U#[i2 i3] 1 2 3 4 5 6`.
To maintina type and size information, ND-arrays are converted to JSON objects following the
**annotated array format** (defined in the [JData specification (Draft 3)][JDataAAFmt]),
when parsed using [`from_bjdata`](../../api/basic_json/from_bjdata.md).
For example, the above 2-D `uint8` array can be parsed and accessed as
To maintina type and size information, ND-arrays are converted to JSON objects following the **annotated array
format** (defined in the [JData specification (Draft 3)][JDataAAFmt]), when parsed using
[`from_bjdata`](../../api/basic_json/from_bjdata.md). For example, the above 2-D `uint8` array can be parsed and
accessed as
```json
{
@ -126,34 +115,28 @@ The library uses the following mapping from JSON values types to BJData types ac
```
Likewise, when a JSON object in the above form is serialzed using
[`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted
into a compact BJData ND-array. The only exception is, that when the 1-dimensional
vector stored in `"_ArraySize_"` contains a single integer or two integers with one
being 1, a regular 1-D optimized array is generated.
[`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted into a compact BJData ND-array. The
only exception is, that when the 1-dimensional vector stored in `"_ArraySize_"` contains a single integer or two
integers with one being 1, a regular 1-D optimized array is generated.
The current version of this library does not yet support automatic detection of and
conversion from a nested JSON array input to a BJData ND-array.
The current version of this library does not yet support automatic detection of and conversion from a nested JSON
array input to a BJData ND-array.
[JDataAAFmt]: https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays)
!!! info "Restrictions in optimized data types for arrays and objects"
Due to diminished space saving, hampered readability, and increased
security risks, in BJData, the allowed data types following the `$` marker
in an optimized array and object container are restricted to
**non-zero-fixed-length** data types. Therefore, the valid optimized
type markers can only be one of `UiuImlMLhdDC`. This also means other
variable (`[{SH`) or zero-length types (`TFN`) can not be used in an
optimized array or object in BJData.
Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data
types following the `$` marker in an optimized array and object container are restricted to
**non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDC`.
This also means other variable (`[{SH`) or zero-length types (`TFN`) can not be used in an optimized array or object
in BJData.
!!! info "Binary values"
If the JSON data contains the binary type, the value stored is a list
of integers, as suggested by the BJData documentation. In particular,
this means that the serialization and the deserialization of JSON
containing binary values into BJData and back will result in a
different JSON object.
If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the BJData
documentation. In particular, this means that the serialization and the deserialization of JSON containing binary
values into BJData and back will result in a different JSON object.
??? example
@ -198,7 +181,6 @@ The library maps BJData types to JSON value types as follows:
The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
??? example
```cpp

3
docs/mkdocs/docs/features/binary_formats/cbor.md
View File

@ -11,7 +11,8 @@ small code size, fairly small message size, and extensibility without the need f
## Serialization
The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049):
The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification
([RFC 7049](https://www.rfc-editor.org/rfc/rfc7049.html)):
| JSON value type | value/range | CBOR type | first byte |
|-----------------|--------------------------------------------|-----------------------------------|------------|

10
docs/mkdocs/docs/features/binary_formats/messagepack.md
View File

@ -1,6 +1,8 @@
# MessagePack
MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves.
MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON.
But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one
extra byte in addition to the strings themselves.
!!! abstract "References"
@ -9,7 +11,8 @@ MessagePack is an efficient binary serialization format. It lets you exchange da
## Serialization
The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:
The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack
specification:
| JSON value type | value/range | MessagePack type | first byte |
|-----------------|------------------------------------------|------------------|------------|
@ -64,7 +67,8 @@ The library uses the following mapping from JSON values types to MessagePack typ
!!! info "NaN/infinity handling"
If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`.
If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or
Infinity to `null`.
??? example

33
docs/mkdocs/docs/features/binary_formats/ubjson.md
View File

@ -1,6 +1,7 @@
# UBJSON
Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON.
Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to
achieve the generality of JSON, combined with being much easier to process than JSON.
!!! abstract "References"
@ -55,31 +56,24 @@ The library uses the following mapping from JSON values types to UBJSON types ac
!!! info "NaN/infinity handling"
If NaN or Infinity are stored inside a JSON number, they are
serialized properly. This behavior differs from the `dump()`
function which serializes NaN or Infinity to `null`.
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the
`dump()` function which serializes NaN or Infinity to `null`.
!!! info "Optimized formats"
The optimized formats for containers are supported: Parameter
`use_size` adds size information to the beginning of a container and
removes the closing marker. Parameter `use_type` further checks
whether all elements of a container have the same type and adds the
type marker to the beginning of the container. The `use_type`
parameter must only be used together with `use_size = true`.
The optimized formats for containers are supported: Parameter `use_size` adds size information to the beginning of a
container and removes the closing marker. Parameter `use_type` further checks whether all elements of a container
have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be
used together with `use_size = true`.
Note that `use_size = true` alone may result in larger representations -
the benefit of this parameter is that the receiving side is
immediately informed on the number of elements of the container.
Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the
receiving side is immediately informed on the number of elements of the container.
!!! info "Binary values"
If the JSON data contains the binary type, the value stored is a list
of integers, as suggested by the UBJSON documentation. In particular,
this means that serialization and the deserialization of a JSON
containing binary values into UBJSON and back will result in a
different JSON object.
If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON
documentation. In particular, this means that serialization and the deserialization of a JSON containing binary
values into UBJSON and back will result in a different JSON object.
??? example
@ -119,7 +113,6 @@ The library maps UBJSON types to JSON value types as follows:
The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
??? example
```cpp

3
docs/mkdocs/docs/features/element_access/unchecked_access.md
View File

@ -99,7 +99,8 @@ that the passed index is the new maximal index. Intermediate values are filled w
!!! failure "Exceptions"
`operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.
`operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For
other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.
## Summary

13
docs/mkdocs/docs/features/parsing/parse_exceptions.md
View File

@ -1,6 +1,10 @@
# Parsing and Exceptions
When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown.
This exception contains the position in the input where the error occurred, together with a diagnostic message and the
last read input token. The exceptions page contains a
[list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted
input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
```cpp
json j;
@ -19,7 +23,9 @@ In case exceptions are undesired or not supported by the environment, there are
## Switch off exceptions
The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`).
The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an
exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned
(`#!cpp false`).
```cpp
json j = json::parse(my_input, nullptr, false);
@ -33,7 +39,8 @@ Note there is no diagnostic information available in this scenario.
## Use accept() function
Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON.
Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating
whether the input is valid JSON.
```cpp
if (!json::accept(my_input))

20
docs/mkdocs/docs/features/parsing/parser_callbacks.md
View File

@ -2,9 +2,10 @@
## Overview
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events
(passed as `parse_event_t` 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`, it is
called on certain events (passed as `parse_event_t` 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.
The type of the callback function is:
@ -17,8 +18,8 @@ using parser_callback_t =
## Callback event types
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` |
|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
@ -59,10 +60,13 @@ of the parameters `depth`, `event`, and `parsed`.
## Return value
Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called:
Discarding a value (i.e., returning `#!c 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 `#!json 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 `#!json null`. This case happens if the
top-level element is skipped.
??? example