amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-04-07 16:48:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'develop' of https://github.com/nlohmann/json into bon8

Browse Source
This commit is contained in:
Niels Lohmann
2022-08-13 11:42:08 +02:00
parent dfdbbc71bb 8fcdbf2e77
commit 47934f8400
411 changed files with 32052 additions and 5692 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/mkdocs/Makefile
View File

@@ -28,6 +28,7 @@ publish: prepare_files
# install a Python virtual environment
install_venv: requirements.txt
python3 -mvenv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install wheel
venv/bin/pip install -r requirements.txt

40
docs/mkdocs/docs/api/adl_serializer/from_json.md
View File

@@ -14,8 +14,8 @@ noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_
-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {}))
```
This function is usually called by the [`get()`](../basic_json/get.md) function of the
[basic_json](../basic_json) class (either explicit or via conversion operators).
This function is usually called by the [`get()`](../basic_json/get.md) function of the [basic_json](../basic_json)
class (either explicitly or via the conversion operators).
1. This function is chosen for default-constructible value types.
2. This function is chosen for value types which are not default-constructible.
@@ -32,9 +32,41 @@ This function is usually called by the [`get()`](../basic_json/get.md) function
Copy of the JSON value, converted to `ValueType`
!!! note
## Examples
This documentation page is a stub.
??? example "Example: (1) Default-constructible type"
The example below shows how a `from_json` function can be implemented for a user-defined type. This function is
called by the `adl_serializer` when `get<ns::person>()` is called.
```cpp
--8<-- "examples/from_json__default_constructible.cpp"
```
Output:
```json
--8<-- "examples/from_json__default_constructible.output"
```
??? example "Example: (2) Non-default-constructible type"
The example below shows how a `from_json` is implemented as part of a specialization of the `adl_serializer` to
realize the conversion of a non-default-constructible type.
```cpp
--8<-- "examples/from_json__non_default_constructible.cpp"
```
Output:
```json
--8<-- "examples/from_json__non_default_constructible.output"
```
## See also
- [to_json](to_json.md)
## Version history

21
docs/mkdocs/docs/api/adl_serializer/to_json.md
View File

@@ -17,9 +17,26 @@ This function is usually called by the constructors of the [basic_json](../basic
`val` (in)
: value to read from
!!! note
## Examples
This documentation page is a stub.
??? example
The example below shows how a `to_json` function can be implemented for a user-defined type. This function is called
by the `adl_serializer` when the constructor `basic_json(ns::person)` is called.
```cpp
--8<-- "examples/to_json.cpp"
```
Output:
```json
--8<-- "examples/to_json.output"
```
## See also
- [from_json](from_json.md)
## Version history

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

@@ -29,7 +29,7 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti
: A compatible input, for instance:
- an `std::istream` object
- a `FILE` pointer
- a `FILE` pointer (must not be null)
- a C-style array of characters
- a pointer to a null-terminated string of single byte characters
- a `std::string`
@@ -72,6 +72,11 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
(1) A UTF-8 byte order mark is silently ignored.
!!! danger "Runtime assertion"
The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a
[runtime assertion](../../features/assertions.md).
## Examples
??? example
@@ -91,7 +96,7 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
## See also
- [parse](parse.md) - deserialize from a compatible input
- [operator>>](operator_gtgt.md) - deserialize from stream
- [operator>>](../operator_gtgt.md) - deserialize from stream
## Version history

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

@@ -137,11 +137,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type.output"
```
??? example "Example (2) access specified object element with bounds checking"
??? example "Example: (2) access specified object element with bounds checking"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
--8<-- "examples/at__object_t_key_type_const.cpp"
```
@@ -152,34 +152,64 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type_const.output"
```
??? example "Example (4) access specified element via JSON Pointer"
??? example "Example: (3) access specified object element using string_view with bounds checking"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
```cpp
--8<-- "examples/at__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/at__keytype.c++17.output"
```
??? example "Example: (3) access specified object element using string_view with bounds checking"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
--8<-- "examples/at__keytype_const.c++17.cpp"
```
Output:
```json
--8<-- "examples/at__keytype_const.c++17.output"
```
??? example "Example: (4) access specified element via JSON Pointer"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
```cpp
--8<-- "examples/at_json_pointer.cpp"
--8<-- "examples/at__json_pointer.cpp"
```
Output:
```json
--8<-- "examples/at_json_pointer.output"
--8<-- "examples/at__json_pointer.output"
```
??? example "Example (4) access specified element via JSON Pointer"
??? example "Example: (4) access specified element via JSON Pointer"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
--8<-- "examples/at_json_pointer_const.cpp"
--8<-- "examples/at__json_pointer_const.cpp"
```
Output:
```json
--8<-- "examples/at_json_pointer_const.output"
--8<-- "examples/at__json_pointer_const.output"
```
## See also

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

@@ -317,6 +317,8 @@ basic_json(basic_json&& other) noexcept;
--8<-- "examples/basic_json__CompatibleType.output"
```
Note the output is platform-dependent.
??? example "Example: (5) create a container (array or object) from an initializer list"
The example below shows how JSON values are created from initializer lists.

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.

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

@@ -69,32 +69,46 @@ Logarithmic in the size of the JSON object.
## Examples
??? example "Example (1) check with key"
??? example "Example: (1) check with key"
The example shows how `contains()` is used.
```cpp
--8<-- "examples/contains.cpp"
--8<-- "examples/contains__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/contains.output"
--8<-- "examples/contains__object_t_key_type.output"
```
??? example "Example (3) check with JSON pointer"
??? example "Example: (2) check with key using string_view"
The example shows how `contains()` is used.
```cpp
--8<-- "examples/contains_json_pointer.cpp"
--8<-- "examples/contains__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/contains_json_pointer.output"
--8<-- "examples/contains__keytype.c++17.output"
```
??? example "Example: (3) check with JSON pointer"
The example shows how `contains()` is used.
```cpp
--8<-- "examples/contains__json_pointer.cpp"
```
Output:
```json
--8<-- "examples/contains__json_pointer.output"
```
## Version history

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

@@ -44,18 +44,32 @@ This method always returns `0` when executed on a JSON type that is not an objec
## Examples
??? example
??? example "Example: (1) count number of elements"
The example shows how `count()` is used.
```cpp
--8<-- "examples/count.cpp"
--8<-- "examples/count__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/count.output"
--8<-- "examples/count__object_t_key_type.output"
```
??? example "Example: (2) count number of elements using string_view"
The example shows how `count()` is used.
```cpp
--8<-- "examples/count__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/count__keytype.c++17.output"
```
## Version history

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

@@ -165,13 +165,27 @@ Strong exception safety: if an exception occurs, the original value stays intact
The example shows the effect of `erase()` for different JSON types using an object key.
```cpp
--8<-- "examples/erase__key_type.cpp"
--8<-- "examples/erase__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/erase__key_type.output"
--8<-- "examples/erase__object_t_key_type.output"
```
??? example "Example: (4) remove element from a JSON object given a key using string_view"
The example shows the effect of `erase()` for different JSON types using an object key.
```cpp
--8<-- "examples/erase__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/erase__keytype.c++17.output"
```
??? example "Example: (5) remove element from a JSON array given an index"

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

@@ -48,18 +48,32 @@ This method always returns `end()` when executed on a JSON type that is not an o
## Examples
??? example
??? example "Example: (1) find object element by key"
The example shows how `find()` is used.
```cpp
--8<-- "examples/find__key_type.cpp"
--8<-- "examples/find__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/find__key_type.output"
--8<-- "examples/find__object_t_key_type.output"
```
??? example "Example: (2) find object element by key using string_view"
The example shows how `find()` is used.
```cpp
--8<-- "examples/find__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/find__keytype.c++17.output"
```
## See also

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

@@ -256,6 +256,7 @@ Access to the JSON value
### JSON Patch functions
- [**patch**](patch.md) - applies a JSON patch
- [**patch_inplace**](patch_inplace.md) - applies a JSON patch in place
- [**diff**](diff.md) (_static_) - creates a diff as a JSON patch
### JSON Merge Patch functions
@@ -283,14 +284,13 @@ Access to the JSON value
## Non-member functions
- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
- [**operator<<(std::ostream&)**](../operator_ltlt.md) - serialize to stream
- [**operator>>(std::istream&)**](../operator_gtgt.md) - deserialize from stream
- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
## Literals
- [**operator""_json**](operator_literal_json.md) - user-defined string literal for JSON values
- [**operator""_json_pointer**](operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
- [**operator""_json**](../operator_literal_json.md) - user-defined string literal for JSON values
## Helper classes

17
docs/mkdocs/docs/api/basic_json/json_serializer.md
View File

@@ -19,6 +19,23 @@ using json_serializer = JSONSerializer<T, SFINAE>;
The default values for `json_serializer` is [`adl_serializer`](../adl_serializer).
## Examples
??? example
The example below shows how a conversion of a non-default-constructible type is implemented via a specialization of
the `adl_serializer`.
```cpp
--8<-- "examples/from_json__non_default_constructible.cpp"
```
Output:
```json
--8<-- "examples/from_json__non_default_constructible.output"
```
## Version history
- Since version 2.0.0.

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

@@ -40,7 +40,7 @@ string elements the JSON value can store which is `1`.
??? example
The following code calls `max_size()` on the different value types. Note the output is implementation specific.
The following code calls `max_size()` on the different value types.
```cpp
--8<-- "examples/max_size.cpp"
@@ -52,6 +52,8 @@ string elements the JSON value can store which is `1`.
--8<-- "examples/max_size.output"
```
Note the output is platform-dependent.
## Version history
- Added in version 1.0.0.

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

@@ -32,8 +32,7 @@ Constant.
??? example
The following code shows an example output of the `meta()`
function.
The following code shows an example output of the `meta()` function.
```cpp
--8<-- "examples/meta.cpp"
@@ -45,9 +44,12 @@ Constant.
--8<-- "examples/meta.output"
```
Note the output is platform-dependent.
## See also
- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md) - library version information
- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md)
\- library version information
## Version history

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

70
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`.
@@ -111,89 +112,117 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Examples
??? example "Example (1): access specified array element"
??? example "Example: (1) access specified array element"
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"
--8<-- "examples/operator_array__size_type.cpp"
```
Output:
```json
--8<-- "examples/operatorarray__size_type.output"
--8<-- "examples/operator_array__size_type.output"
```
??? example "Example (1): access specified array element"
??? example "Example: (1) access specified array element (const)"
The example below shows how array elements can be read using the `[]` operator.
```cpp
--8<-- "examples/operatorarray__size_type_const.cpp"
--8<-- "examples/operator_array__size_type_const.cpp"
```
Output:
```json
--8<-- "examples/operatorarray__size_type_const.output"
--8<-- "examples/operator_array__size_type_const.output"
```
??? example "Example (2): access specified object element"
??? example "Example: (2) access specified object element"
The example below shows how object elements can be read and written using the `[]` operator.
```cpp
--8<-- "examples/operatorarray__key_type.cpp"
--8<-- "examples/operator_array__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/operatorarray__key_type.output"
--8<-- "examples/operator_array__object_t_key_type.output"
```
??? example "Example (2): access specified object element (const)"
??? example "Example: (2) access specified object element (const)"
The example below shows how object elements can be read using the `[]` operator.
```cpp
--8<-- "examples/operatorarray__key_type_const.cpp"
--8<-- "examples/operator_array__object_t_key_type_const.cpp"
```
Output:
```json
--8<-- "examples/operatorarray__key_type_const.output"
--8<-- "examples/operator_array__object_t_key_type_const.output"
```
??? example "Example (4): access specified element via JSON Pointer"
??? example "Example: (3) access specified object element using string_view"
The example below shows how object elements can be read using the `[]` operator.
```cpp
--8<-- "examples/operator_array__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/operator_array__keytype.c++17.output"
```
??? example "Example: (3) access specified object element using string_view (const)"
The example below shows how object elements can be read using the `[]` operator.
```cpp
--8<-- "examples/operator_array__keytype_const.c++17.cpp"
```
Output:
```json
--8<-- "examples/operator_array__keytype_const.c++17.output"
```
??? example "Example: (4) access specified element via JSON Pointer"
The example below shows how values can be read and written using JSON Pointers.
```cpp
--8<-- "examples/operatorjson_pointer.cpp"
--8<-- "examples/operator_array__json_pointer.cpp"
```
Output:
```json
--8<-- "examples/operatorjson_pointer.output"
--8<-- "examples/operator_array__json_pointer.output"
```
??? example "Example (4): access specified element via JSON Pointer (const)"
??? example "Example: (4) access specified element via JSON Pointer (const)"
The example below shows how values can be read using JSON Pointers.
```cpp
--8<-- "examples/operatorjson_pointer_const.cpp"
--8<-- "examples/operator_array__json_pointer_const.cpp"
```
Output:
```json
--8<-- "examples/operatorjson_pointer_const.output"
--8<-- "examples/operator_array__json_pointer_const.output"
```
## See also
@@ -206,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.

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

@@ -78,5 +78,5 @@ Linear in the size of the JSON value.
## Version history
- Since version 1.0.0.
- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) added
- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
in version 3.9.0.

37
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
@@ -99,6 +99,39 @@ Linear.
}
```
!!! note "Comparing different `basic_json` specializations"
Comparing different `basic_json` specializations can have surprising effects. For instance, the result of comparing
the JSON objects
```json
{
"version": 1,
"type": "integer"
}
```
and
```json
{
"type": "integer",
"version": 1
}
```
depends on whether [`nlohmann::json`](../json.md) or [`nlohmann::ordered_json`](../ordered_json.md) is used:
```cpp
--8<-- "examples/operator__equal__specializations.cpp"
```
Output:
```json
--8<-- "examples/operator__equal__specializations.output"
```
## Examples
??? example

15
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.
- Otherwise, returns the result of `#!cpp !(lhs < rhs)`.
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

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

@@ -15,7 +15,7 @@ bool operator>(ScalarType lhs, const const_reference rhs) noexcept; // (2)
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)`.
- Otherwise, returns the result of `#!cpp !(lhs <= rhs)` (see [**operator<=**](operator_le.md)).
2. Compares wether a JSON value is greater than a scalar or a scalar is greater than 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/operator_le.md
View File

@@ -15,7 +15,7 @@ bool operator<=(ScalarType lhs, const const_reference rhs) noexcept; // (2)
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 !(rhs < lhs)`.
- Otherwise, returns the result of `#!cpp !(rhs < lhs)` (see [**operator<**](operator_lt.md)).
1. Compares wether 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

48
docs/mkdocs/docs/api/basic_json/operator_literal_json.md
View File

@@ -1,48 +0,0 @@
# <small>nlohmann::basic_json::</small>operator""_json
```cpp
json operator "" _json(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a
string literal and returns a [`json`](../json.md) object if no parse error occurred.
## Parameters
`s` (in)
: a string representation of a JSON object
`n` (in)
: length of string `s`
## Return value
[`json`](../json.md) value parsed from `s`
## Exceptions
The function can throw anything that [`parse(s, s+n)`](parse.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON values from string literals.
```cpp
--8<-- "examples/operator_literal_json.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json.output"
```
## Version history
- Added in version 1.0.0.

52
docs/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md
View File

@@ -1,52 +0,0 @@
# <small>nlohmann::basic_json::</small>operator""_json_pointer
```cpp
json_pointer operator "" _json_pointer(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred.
## Parameters
`s` (in)
: a string representation of a JSON Pointer
`n` (in)
: length of string `s`
## Return value
[`json_pointer`](../json_pointer/index.md) value parsed from `s`
## Exceptions
The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON Pointers from string literals.
```cpp
--8<-- "examples/operator_literal_json_pointer.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json_pointer.output"
```
## See also
- [json_pointer](../json_pointer/index.md) - type to represent JSON Pointers
## Version history
- Added in version 2.0.0.

62
docs/mkdocs/docs/api/basic_json/operator_ltlt.md
View File

@@ -1,62 +0,0 @@
# operator<<(basic_json)
```cpp
std::ostream& operator<<(std::ostream& o, const basic_json& j);
```
Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
[`dump`](dump.md) member function.
- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result
is the same as calling `dump(4)`.
- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character.
## Parameters
`o` (in, out)
: stream to serialize to
`j` (in)
: JSON value to serialize
## Return value
the stream `o`
## Exceptions
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`](dump.md) member functions, no `error_handler` can be set.
## Complexity
Linear.
## Examples
??? example
The example below shows the serialization with different parameters to `width` to adjust the indentation level.
```cpp
--8<-- "examples/operator_serialize.cpp"
```
Output:
```json
--8<-- "examples/operator_serialize.output"
```
## Version history
- Added in version 1.0.0
- Support for indentation character added in version 3.0.0.
!!! warning "Deprecation"
This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has
been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;`
with `#!cpp o << j;`.

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

42
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
@@ -55,6 +55,36 @@ Linear.
2. Comparing a `NaN` with another `NaN`.
3. Comparing a `NaN` and any other number.
## Examples
??? example "Example: (1) comparing JSON values"
The example demonstrates comparing several JSON values.
```cpp
--8<-- "examples/operator_spaceship__const_reference.c++20.cpp"
```
Output:
```json
--8<-- "examples/operator_spaceship__const_reference.c++20.output"
```
??? example "Example: (2) comparing JSON values and scalars"
The example demonstrates comparing several JSON values and scalars.
```cpp
--8<-- "examples/operator_spaceship__scalartype.c++20.cpp"
```
Output:
```json
--8<-- "examples/operator_spaceship__scalartype.c++20.output"
```
## See also
- [**operator==**](operator_eq.md) - comparison: equal

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

@@ -28,7 +28,7 @@ static basic_json parse(IteratorType first, IteratorType last,
: A compatible input, for instance:
- an `std::istream` object
- a `FILE` pointer
- a `FILE` pointer (must not be null)
- a C-style array of characters
- a pointer to a null-terminated string of single byte characters
- a `std::string`
@@ -71,6 +71,13 @@ Deserialized JSON value; in case of a parse error and `allow_exceptions` set to
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
## Exceptions
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate
error.
- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
## Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the parser
@@ -81,6 +88,11 @@ super-linear complexity.
(1) A UTF-8 byte order mark is silently ignored.
!!! danger "Runtime assertion"
The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a
[runtime assertion](../../features/assertions.md).
## Examples
??? example "Parsing from a character array"
@@ -184,7 +196,7 @@ super-linear complexity.
## See also
- [accept](accept.md) - check if the input is valid JSON
- [operator>>](operator_gtgt.md) - deserialize from stream
- [operator>>](../operator_gtgt.md) - deserialize from stream
## Version history

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

@@ -65,6 +65,7 @@ is thrown. In any case, the original value is not changed: the patch is applied
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
- [patch_inplace](patch_inplace.md) applies a JSON Patch without creating a copy of the document
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
## Version history

70
docs/mkdocs/docs/api/basic_json/patch_inplace.md Normal file
View File

@@ -0,0 +1,70 @@
# <small>nlohmann::basic_json::</small>patch_inplace
```cpp
void patch_inplace(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. This function applies a JSON patch in place and returns void.
## Parameters
`json_patch` (in)
: JSON patch document
## Exception safety
No guarantees, value may be corrupted by an unsuccessful patch operation.
## 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 [`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.
## 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.
## Notes
Unlike [`patch`](patch.md), `patch_inplace` applies the operation "in place" and no copy of the JSON value is created.
That makes it faster for large documents by avoiding the copy. However, the JSON value might be corrupted if the
function throws an exception.
## Examples
??? example
The following code shows how a JSON patch is applied to a value.
```cpp
--8<-- "examples/patch_inplace.cpp"
```
Output:
```json
--8<-- "examples/patch_inplace.output"
```
## See also
- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
- [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
- [patch](patch.md) applies a JSON Merge Patch
- [merge_patch](merge_patch.md) applies a JSON Merge Patch
## Version history
- Added in version 3.11.0.

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

@@ -26,6 +26,8 @@ type of the JSON value is taken into account to have different hash values for `
--8<-- "examples/std_hash.output"
```
Note the output is platform-dependent.
## Version history
- Added in version 1.0.0.

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.

30
docs/mkdocs/docs/api/basic_json/value.md
View File

@@ -7,7 +7,7 @@ ValueType value(const typename object_t::key_type& key,
ValueType&& default_value) const;
// (2)
template<class KeyType, class ValueType>
template<class ValueType, class KeyType>
ValueType value(KeyType&& key,
ValueType&& default_value) const;
@@ -105,32 +105,46 @@ changes to any JSON value.
## Examples
??? example "Example (1): access specified object element with default value"
??? example "Example: (1) access specified object element with default value"
The example below shows how object elements can be queried with a default value.
```cpp
--8<-- "examples/basic_json__value.cpp"
--8<-- "examples/value__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/basic_json__value.output"
--8<-- "examples/value__object_t_key_type.output"
```
??? example "Example (3): access specified object element via JSON Pointer with default value"
??? example "Example: (2) access specified object element using string_view with default value"
The example below shows how object elements can be queried with a default value.
```cpp
--8<-- "examples/basic_json__value_ptr.cpp"
--8<-- "examples/value__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/basic_json__value_ptr.output"
--8<-- "examples/value__keytype.c++17.output"
```
??? example "Example: (3) access specified object element via JSON Pointer with default value"
The example below shows how object elements can be queried with a default value.
```cpp
--8<-- "examples/value__json_ptr.cpp"
```
Output:
```json
--8<-- "examples/value__json_ptr.output"
```
## See also
@@ -141,5 +155,5 @@ changes to any JSON value.
## Version history
1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version 3.11.0.
2. Added in version 3.11.0.
2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2.
3. Added in version 2.0.2.

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

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

@@ -14,6 +14,8 @@ No-throw guarantee: this member function never throws exceptions.
Linear.
<!-- NOLINT Examples -->
## Version history
- Added in version 1.0.0.

8
docs/mkdocs/docs/api/json_pointer/index.md
View File

@@ -28,7 +28,9 @@ are the base for JSON patches.
- [(constructor)](json_pointer.md)
- [**to_string**](to_string.md) - return a string representation of the JSON pointer
- [**operator string_t**](operator_string.md) - return a string representation of the JSON pointer
- [**operator string_t**](operator_string_t.md) - return a string representation of the JSON pointer
- [**operator==**](operator_eq.md) - compare: equal
- [**operator!=**](operator_ne.md) - compare: not equal
- [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer
- [**operator/**](operator_slash.md) - create JSON Pointer by appending
- [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer
@@ -37,9 +39,11 @@ are the base for JSON patches.
- [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
- [**empty**](empty.md) - return whether pointer points to the root document
## Literals
- [**operator""_json_pointer**](../operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
## See also
- [operator""_json_pointer](../basic_json/operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
- [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
## Version history

113
docs/mkdocs/docs/api/json_pointer/operator_eq.md Normal file
View File

@@ -0,0 +1,113 @@
# <small>nlohmann::json_pointer::</small>operator==
```cpp
// until C++20
template<typename RefStringTypeLhs, typename RefStringTypeRhs>
bool operator==(
const json_pointer<RefStringTypeLhs>& lhs,
const json_pointer<RefStringTypeRhs>& rhs) noexcept; // (1)
template<typename RefStringTypeLhs, typename StringType>
bool operator==(
const json_pointer<RefStringTypeLhs>& lhs,
const StringType& rhs); // (2)
template<typename RefStringTypeRhs, typename StringType>
bool operator==(
const StringType& lhs,
const json_pointer<RefStringTypeRhs>& rhs); // (2)
// since C++20
class json_pointer {
template<typename RefStringTypeRhs>
bool operator==(
const json_pointer<RefStringTypeRhs>& rhs) const noexcept; // (1)
bool operator==(const string_t& rhs) const; // (2)
};
```
1. Compares two JSON pointers for equality by comparing their reference tokens.
2. Compares a JSON pointer and a string or a string and a JSON pointer for equality by converting the string to a JSON
pointer and comparing the JSON pointers according to 1.
## Template parameters
`RefStringTypeLhs`, `RefStringTypeRhs`
: the string type of the left-hand side or right-hand side JSON pointer, respectively
`StringType`
: the string type derived from the `json_pointer` operand ([`json_pointer::string_t`](string_t.md))
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether the values `lhs`/`*this` and `rhs` are equal
## Exception safety
1. No-throw guarantee: this function never throws exceptions.
2. Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. (none)
2. The function can throw the following exceptions:
- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is
nonempty and does not begin with a slash (`/`); see example below.
- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON
pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below.
## Complexity
Constant if `lhs` and `rhs` differ in the number of reference tokens, otherwise linear in the number of reference
tokens.
## Notes
!!! warning "Deprecation"
Overload 2 is deprecated and will be removed in a future major version release.
## Examples
??? example "Example: (1) Comparing JSON pointers"
The example demonstrates comparing JSON pointers.
```cpp
--8<-- "examples/json_pointer__operator__equal.cpp"
```
Output:
```
--8<-- "examples/json_pointer__operator__equal.output"
```
??? example "Example: (2) Comparing JSON pointers and strings"
The example demonstrates comparing JSON pointers and strings, and when doing so may raise an exception.
```cpp
--8<-- "examples/json_pointer__operator__equal_stringtype.cpp"
```
Output:
```
--8<-- "examples/json_pointer__operator__equal_stringtype.output"
```
## Version history
1. Added in version 2.1.0. Added C++20 member functions in version 3.11.2.
2. Added for backward compatibility and deprecated in version 3.11.2.

109
docs/mkdocs/docs/api/json_pointer/operator_ne.md Normal file
View File

@@ -0,0 +1,109 @@
# <small>nlohmann::json_pointer::</small>operator!=
```cpp
// until C++20
template<typename RefStringTypeLhs, typename RefStringTypeRhs>
bool operator!=(
const json_pointer<RefStringTypeLhs>& lhs,
const json_pointer<RefStringTypeRhs>& rhs) noexcept; // (1)
template<typename RefStringTypeLhs, typename StringType>
bool operator!=(
const json_pointer<RefStringTypeLhs>& lhs,
const StringType& rhs); // (2)
template<typename RefStringTypeRhs, typename StringType>
bool operator!=(
const StringType& lhs,
const json_pointer<RefStringTypeRhs>& rhs); // (2)
```
1. Compares two JSON pointers for inequality by comparing their reference tokens.
2. Compares a JSON pointer and a string or a string and a JSON pointer for inequality by converting the string to a
JSON pointer and comparing the JSON pointers according to 1.
## Template parameters
`RefStringTypeLhs`, `RefStringTypeRhs`
: the string type of the left-hand side or right-hand side JSON pointer, respectively
`StringType`
: the string type derived from the `json_pointer` operand ([`json_pointer::string_t`](string_t.md))
## Parameters
`lhs` (in)
: first value to consider
`rhs` (in)
: second value to consider
## Return value
whether the values `lhs`/`*this` and `rhs` are not equal
## Exception safety
1. No-throw guarantee: this function never throws exceptions.
2. Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
1. (none)
2. The function can throw the following exceptions:
- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is
nonempty and does not begin with a slash (`/`); see example below.
- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON
pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below.
## Complexity
Constant if `lhs` and `rhs` differ in the number of reference tokens, otherwise linear in the number of reference
tokens.
## Notes
!!! note "Operator overload resolution"
Since C++20 overload resolution will consider the _rewritten candidate_ generated from
[`operator==`](operator_eq.md).
!!! warning "Deprecation"
Overload 2 is deprecated and will be removed in a future major version release.
## Examples
??? example "Example: (1) Comparing JSON pointers"
The example demonstrates comparing JSON pointers.
```cpp
--8<-- "examples/json_pointer__operator__notequal.cpp"
```
Output:
```
--8<-- "examples/json_pointer__operator__notequal.output"
```
??? example "Example: (2) Comparing JSON pointers and strings"
The example demonstrates comparing JSON pointers and strings, and when doing so may raise an exception.
```cpp
--8<-- "examples/json_pointer__operator__notequal_stringtype.cpp"
```
Output:
```
--8<-- "examples/json_pointer__operator__notequal_stringtype.output"
```
## Version history
1. Added in version 2.1.0.
2. Added for backward compatibility and deprecated in version 3.11.2.

13
docs/mkdocs/docs/api/json_pointer/operator_string.md → docs/mkdocs/docs/api/json_pointer/operator_string_t.md
View File

@@ -19,6 +19,13 @@ operator string_t() const
}
```
## Notes
!!! warning "Deprecation"
This function is deprecated in favor of [`to_string`](to_string.md) and will be removed in a future major version
release.
## Examples
??? example
@@ -26,16 +33,16 @@ operator string_t() const
The example shows how JSON Pointers can be implicitly converted to strings.
```cpp
--8<-- "examples/json_pointer__operator_string.cpp"
--8<-- "examples/json_pointer__operator_string_t.cpp"
```
Output:
```json
--8<-- "examples/json_pointer__operator_string.output"
--8<-- "examples/json_pointer__operator_string_t.output"
```
## Version history
- Since version 2.0.0.
- Changed type to `string_t` in version 3.11.0.
- Changed type to `string_t` and deprecated in version 3.11.0.

2
docs/mkdocs/docs/api/json_sax/binary.md
View File

@@ -23,7 +23,7 @@ It is safe to move the passed binary value.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse__binary.cpp"

2
docs/mkdocs/docs/api/json_sax/boolean.md
View File

@@ -19,7 +19,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/end_array.md
View File

@@ -14,7 +14,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/end_object.md
View File

@@ -14,7 +14,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/key.md
View File

@@ -23,7 +23,7 @@ It is safe to move the passed object key value.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/null.md
View File

@@ -14,7 +14,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/number_float.md
View File

@@ -22,7 +22,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/number_integer.md
View File

@@ -19,7 +19,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/number_unsigned.md
View File

@@ -19,7 +19,7 @@ Whether parsing should proceed.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

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

@@ -27,7 +27,7 @@ Whether parsing should proceed (**must return `#!cpp false`**).
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/start_array.md
View File

@@ -23,7 +23,7 @@ Binary formats may report the number of elements.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/start_object.md
View File

@@ -23,7 +23,7 @@ Binary formats may report the number of elements.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

2
docs/mkdocs/docs/api/json_sax/string.md
View File

@@ -23,7 +23,7 @@ It is safe to move the passed string value.
??? example
.The example below shows how the SAX interface is used.
The example below shows how the SAX interface is used.
```cpp
--8<-- "examples/sax_parse.cpp"

24
docs/mkdocs/docs/api/macros/index.md
View File

@@ -21,11 +21,21 @@ header. See also the [macro overview page](../../features/macros.md).
- [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
- [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
- [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
- [**JSON_USE_GLOBAL_UDLS**](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
## Library version
- [**JSON_SKIP_LIBRARY_VERSION_CHECK**](json_skip_library_version_check.md) - skip library version check
- [**NLOHMANN_JSON_VERSION_MAJOR**<br>**NLOHMANN_JSON_VERSION_MINOR**<br>**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md) - library version information
- [**NLOHMANN_JSON_VERSION_MAJOR**<br>**NLOHMANN_JSON_VERSION_MINOR**<br>**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md)
\- library version information
## Library namespace
- [**NLOHMANN_JSON_NAMESPACE**](nlohmann_json_namespace.md) - full name of the `nlohmann` namespace
- [**NLOHMANN_JSON_NAMESPACE_BEGIN**<br>**NLOHMANN_JSON_NAMESPACE_END**](nlohmann_json_namespace_begin.md) - open and
close the library namespace
- [**NLOHMANN_JSON_NAMESPACE_NO_VERSION**](nlohmann_json_namespace_no_version.md) - disable the version component of
the inline namespace
## Type conversions
@@ -40,7 +50,11 @@ header. See also the [macro overview page](../../features/macros.md).
## Serialization/deserialization macros
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_intrusive.md) - serialization/deserialization of types _with_ access to private variables
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_non_intrusive.md) - serialization/deserialization of types _without_ access to private variables
- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum
types
- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**][DefInt]
\- serialization/deserialization of types _with_ access to private variables
- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**][DefNonInt]
\- serialization/deserialization of types _without_ access to private variables
- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum types
[DefInt]: nlohmann_define_type_intrusive.md
[DefNonInt]: nlohmann_define_type_non_intrusive.md

23
docs/mkdocs/docs/api/macros/json_diagnostics.md
View File

@@ -11,9 +11,6 @@ When enabled, exception messages contain a [JSON Pointer](../json_pointer/json_p
triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds
some runtime overhead.
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
`JSON_DIAGNOSTICS` accordingly.
## Default definition
The default value is `0` (extended diagnostics are switched off).
@@ -26,11 +23,22 @@ When the macro is not defined, the library will define it to its default value.
## Notes
!!! danger "ABI incompatibility"
!!! note "ABI compatibility"
As this macro changes the definition of the `basic_json` object, it MUST be defined in the same way globally, even
across different compilation units: `basic_json` objects with differently defined `JSON_DIAGNOSTICS` macros are
not compatible!
As of version 3.11.0, this macro is no longer required to be defined consistently throughout a codebase to avoid
One Definition Rule (ODR) violations, as the value of this macro is encoded in the namespace, resulting in distinct
symbol names.
This allows different parts of a codebase to use different versions or configurations of this library without
causing improper behavior.
Where possible, it is still recommended that all code define this the same way for maximum interoperability.
!!! hint "CMake option"
Diagnostic messages can also be controlled with the CMake option
[`JSON_Diagnostics`](../../integration/cmake.md#json_diagnostics) (`OFF` by default)
which defines `JSON_DIAGNOSTICS` accordingly.
## Examples
@@ -65,3 +73,4 @@ When the macro is not defined, the library will define it to its default value.
## Version history
- Added in version 3.10.0.
- As of version 3.11.0 the definition is allowed to vary between translation units.

33
docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md
View File

@@ -1,10 +1,12 @@
# JSON_DISABLE_ENUM_SERIALIZATION
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION
#define JSON_DISABLE_ENUM_SERIALIZATION /* value */
```
When defined, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see [arbitrary type conversions](../../features/arbitrary_types.md) for more details).
When defined to `1`, default serialization and deserialization functions for enums are excluded and have to be provided
by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see
[arbitrary type conversions](../../features/arbitrary_types.md) for more details).
Parsing or serializing an enum will result in a compiler error.
@@ -12,17 +14,26 @@ This works for both unscoped and scoped enums.
## Default definition
By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
The default value is `0`.
```cpp
#undef JSON_DISABLE_ENUM_SERIALIZATION
#define JSON_DISABLE_ENUM_SERIALIZATION 0
```
## Notes
!!! hint "CMake option"
Enum serialization can also be controlled with the CMake option
[`JSON_DisableEnumSerialization`](../../integration/cmake.md#json_disableenumserialization)
(`OFF` by default) which defines `JSON_DISABLE_ENUM_SERIALIZATION` accordingly.
## Examples
??? example "Example 1: Disabled behavior"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below **does not** compile.
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below
**does not** compile.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -48,7 +59,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
??? example "Example 2: Serialize enum macro"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses
[`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -80,7 +92,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
??? example "Example 3: User-defined serialization/deserialization functions"
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined functions to parse and serialize the enum.
The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined
functions to parse and serialize the enum.
```cpp
#define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -132,4 +145,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
## See also
- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md)
- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md)
## Version history
- Added in version 3.11.0.

13
docs/mkdocs/docs/api/macros/json_has_ranges.md
View File

@@ -13,6 +13,19 @@ The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_r
When the macro is not defined, the library will define it to its default value.
## Examples
??? example
The code below forces the library to enable support for ranges:
```cpp
#define JSON_HAS_RANGES 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.11.0.

13
docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md
View File

@@ -14,6 +14,19 @@ and `#!cpp __cpp_lib_three_way_comparison`.
When the macro is not defined, the library will define it to its default value.
## Examples
??? example
The code below forces the library to use 3-way comparison:
```cpp
#define JSON_HAS_THREE_WAY_COMPARISON 1
#include <nlohmann/json.hpp>
...
```
## Version history
- Added in version 3.11.0.

98
docs/mkdocs/docs/api/macros/json_use_global_udls.md Normal file
View File

@@ -0,0 +1,98 @@
# JSON_USE_GLOBAL_UDLS
```cpp
#define JSON_USE_GLOBAL_UDLS /* value */
```
When defined to `1`, the user-defined string literals (UDLs) are placed into the global namespace instead of
`nlohmann::literals::json_literals`.
## Default definition
The default value is `1`.
```cpp
#define JSON_USE_GLOBAL_UDLS 1
```
When the macro is not defined, the library will define it to its default value.
## Notes
!!! info "Future behavior change"
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.
!!! 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) (`ON` by default) which defines
`JSON_USE_GLOBAL_UDLS` accordingly.
## Examples
??? example "Example 1: Default behavior"
The code below shows the default behavior using the `_json` UDL.
```cpp
#include <nlohmann/json.hpp>
#include <iostream>
int main()
{
auto j = "42"_json;
std::cout << j << std::endl;
}
```
Output:
```json
42
```
??? example "Example 2: Namespaced UDLs"
The code below shows how UDLs need to be brought into scope before using `_json` when `JSON_USE_GLOBAL_UDLS` is
defined to `0`.
```cpp
#define JSON_USE_GLOBAL_UDLS 0
#include <nlohmann/json.hpp>
#include <iostream>
int main()
{
// auto j = "42"_json; // This line would fail to compile,
// because the UDLs are not in the global namespace
// Bring the UDLs into scope
using namespace nlohmann::json_literals;
auto j = "42"_json;
std::cout << j << std::endl;
}
```
Output:
```json
42
```
## See also
- [`operator""_json`](../operator_literal_json.md)
- [`operator""_json_pointer`](../operator_literal_json_pointer.md)
## Version history
- Added in version 3.11.0.

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

@@ -7,9 +7,6 @@
When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The
value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md).
Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which
sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
## Default definition
By default, implicit conversions are enabled.
@@ -27,6 +24,12 @@ By default, implicit conversions are enabled.
You can prepare existing code by already defining `JSON_USE_IMPLICIT_CONVERSIONS` to `0` and replace any implicit
conversions with calls to [`get`](../basic_json/get.md).
!!! hint "CMake option"
Implicit conversions can also be controlled with the CMake option
[`JSON_ImplicitConversions`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
(`ON` by default) which defines `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
## Examples
??? example

36
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,35 @@ 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"
Legacy comparison can also be controlled with the CMake option
[`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
(`OFF` by default) which defines `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON` accordingly.
## Examples
??? example
The code below switches on the legacy discarded value comparison behavior in the library.
```cpp
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
#include <nlohmann/json.hpp>
...
```
## Version history

14
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,10 +40,12 @@ 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?](../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types)
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
!!! warning "Implementation limits"
- The current implementation is limited to at most 64 member variables. If you want to serialize/deserialize types
@@ -116,7 +118,7 @@ See examples below for the concrete generated code.
- [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE / NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_non_intrusive.md)
for a similar macro that can be defined _outside_ the type.
- [Arbitrary Types Conversions](../../features/arbitrary_types.md) for an overview.
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history

15
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.
@@ -40,11 +40,13 @@ 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?](../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types)
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 outside the type (class/struct).
3. The passed members must be public.
[GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types
!!! warning "Implementation limits"
- The current implementation is limited to at most 64 member variables. If you want to serialize/deserialize types
@@ -101,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:
@@ -116,7 +119,7 @@ See examples below for the concrete generated code.
- [NLOHMANN_DEFINE_TYPE_INTRUSIVE / NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_intrusive.md)
for a similar macro that can be defined _inside_ the type.
- [Arbitrary Types Conversions](../../features/arbitrary_types.md) for an overview.
- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
## Version history

41
docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md Normal file
View File

@@ -0,0 +1,41 @@
# NLOHMANN_JSON_NAMESPACE
```cpp
#define NLOHMANN_JSON_NAMESPACE /* value */
```
This macro evaluates to the full name of the `nlohmann` namespace.
## Default definition
The default value consists of the root namespace (`nlohmann`) and an inline ABI namespace. See
[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
When the macro is not defined, the library will define it to its default value. Overriding this value has no effect on
the library.
## Examples
??? example
The example shows how to use `NLOHMANN_JSON_NAMESPACE` instead of just `nlohmann`, as well as how to output the value
of `NLOHMANN_JSON_NAMESPACE`.
```cpp
--8<-- "examples/nlohmann_json_namespace.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_namespace.output"
```
## See also
- [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
- [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](nlohmann_json_namespace_no_version.md)
## Version history
- Added in version 3.11.0. Changed inline namespace name in version 3.11.2.

61
docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md Normal file
View File

@@ -0,0 +1,61 @@
# NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END
```cpp
#define NLOHMANN_JSON_NAMESPACE_BEGIN /* value */ // (1)
#define NLOHMANN_JSON_NAMESPACE_END /* value */ // (2)
```
These macros can be used to open and close the `nlohmann` namespace. See
[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
1. Opens the namespace.
2. Closes the namespace.
## Default definition
The default definitions open and close the `nlohmann` namespace. The precise definition of
[`NLOHMANN_JSON_NAMESPACE_BEGIN`] varies as described [here](../../features/namespace.md#structure).
1. Default definition of `NLOHMANN_JSON_NAMESPACE_BEGIN`:
```cpp
namespace nlohmann
{
inline namespace json_abi_v3_11_2
{
```
2. Default definition of `NLOHMANN_JSON_NAMESPACE_END`:
```cpp
} // namespace json_abi_v3_11_2
} // namespace nlohmann
```
When these macros are not defined, the library will define them to their default definitions.
## Examples
??? example
The example shows how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
[How do I convert third-party types?](../../features/arbitrary_types.md#how-do-i-convert-third-party-types) page.
```cpp
--8<-- "examples/nlohmann_json_namespace_begin.c++17.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_namespace_begin.c++17.output"
```
## See also
- [`nlohmann` Namespace](../../features/namespace.md)
- [NLOHMANN_JSON_NAMESPACE](nlohmann_json_namespace.md)
- [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](nlohmann_json_namespace_no_version.md)
## Version history
- Added in version 3.11.0. Changed inline namespace name in version 3.11.2.

45
docs/mkdocs/docs/api/macros/nlohmann_json_namespace_no_version.md Normal file
View File

@@ -0,0 +1,45 @@
# NLOHMANN_JSON_NAMESPACE_NO_VERSION
```cpp
#define NLOHMANN_JSON_NAMESPACE_NO_VERSION /* value */
```
If defined to `1`, the version component is omitted from the inline namespace. See
[`nlohmann` Namespace](../../features/namespace.md#structure) for details.
## Default definition
The default value is `0`.
```cpp
#define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
```
When the macro is not defined, the library will define it to its default value.
## Examples
??? example
The example shows how to use `NLOHMANN_JSON_NAMESPACE_NO_VERSION` to disable the version component of the inline
namespace.
```cpp
--8<-- "examples/nlohmann_json_namespace_no_version.cpp"
```
Output:
```json
--8<-- "examples/nlohmann_json_namespace_no_version.output"
```
## See also
- [`nlohmann` Namespace](../../features/namespace.md)
- [`NLOHMANN_JSON_NAMESPACE`](nlohmann_json_namespace.md)
- [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)
## Version history
- Added in version 3.11.2.

27
docs/mkdocs/docs/api/basic_json/operator_gtgt.md → docs/mkdocs/docs/api/operator_gtgt.md
View File

@@ -1,4 +1,4 @@
# operator>>(basic_json)
# <small>nlohmann::</small>operator>>(basic_json)
```cpp
std::istream& operator>>(std::istream& i, basic_json& j);
@@ -20,10 +20,9 @@ the stream `i`
## Exceptions
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate
error.
- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
- Throws [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate error.
- Throws [`parse_error.103`](../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
## Complexity
@@ -33,6 +32,12 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
A UTF-8 byte order mark is silently ignored.
!!! warning "Deprecation"
This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
with `#!cpp i >> j;`.
## Examples
??? example
@@ -51,15 +56,9 @@ A UTF-8 byte order mark is silently ignored.
## See also
- [accept](accept.md) - check if the input is valid JSON
- [parse](parse.md) - deserialize from a compatible input
- [accept](basic_json/accept.md) - check if the input is valid JSON
- [parse](basic_json/parse.md) - deserialize from a compatible input
## Version history
- Added in version 1.0.0
!!! warning "Deprecation"
This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
with `#!cpp i >> j;`.
- Added in version 1.0.0. Deprecated in version 3.0.0.

61
docs/mkdocs/docs/api/operator_literal_json.md Normal file
View File

@@ -0,0 +1,61 @@
# <small>nlohmann::</small>operator""_json
```cpp
json operator "" _json(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a
string literal and returns a [`json`](json.md) object if no parse error occurred.
It is recommended to bring the operator into scope using any of the following lines:
```cpp
using nlohmann::literals::operator "" _json;
using namespace nlohmann::literals;
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.
## Parameters
`s` (in)
: a string representation of a JSON object
`n` (in)
: length of string `s`
## Return value
[`json`](json.md) value parsed from `s`
## Exceptions
The function can throw anything that [`parse(s, s+n)`](basic_json/parse.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON values from string literals.
```cpp
--8<-- "examples/operator_literal_json.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json.output"
```
## Version history
- Added in version 1.0.0.
- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.

64
docs/mkdocs/docs/api/operator_literal_json_pointer.md Normal file
View File

@@ -0,0 +1,64 @@
# <small>nlohmann::</small>operator""_json_pointer
```cpp
json_pointer operator "" _json_pointer(const char* s, std::size_t n);
```
This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
to a string literal and returns a [`json_pointer`](json_pointer/index.md) object if no parse error occurred.
It is recommended to bring the operator into scope using any of the following lines:
```cpp
using nlohmann::literals::operator "" _json_pointer;
using namespace nlohmann::literals;
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.
## Parameters
`s` (in)
: a string representation of a JSON Pointer
`n` (in)
: length of string `s`
## Return value
[`json_pointer`](json_pointer/index.md) value parsed from `s`
## Exceptions
The function can throw anything that [`json_pointer::json_pointer`](json_pointer/index.md) would throw.
## Complexity
Linear.
## Examples
??? example
The following code shows how to create JSON Pointers from string literals.
```cpp
--8<-- "examples/operator_literal_json_pointer.cpp"
```
Output:
```json
--8<-- "examples/operator_literal_json_pointer.output"
```
## See also
- [json_pointer](json_pointer/index.md) - type to represent JSON Pointers
## Version history
- Added in version 2.0.0.
- Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.

87
docs/mkdocs/docs/api/operator_ltlt.md Normal file
View File

@@ -0,0 +1,87 @@
# <small>nlohmann::</small>operator<<(basic_json), <small>nlohmann::</small>operator<<(json_pointer)
```cpp
std::ostream& operator<<(std::ostream& o, const basic_json& j); // (1)
std::ostream& operator<<(std::ostream& o, const json_pointer& ptr); // (2)
```
1. Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
[`dump`](basic_json/dump.md) member function.
- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization
result is the same as calling `dump(4)`.
- The indentation character can be controlled with the member variable `fill` of the output stream `o`.
For instance, the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the
default space character.
2. Write a string representation of the given JSON pointer `ptr` to the output stream `o`. The string representation is
obtained using the [`to_string`](json_pointer/to_string.md) member function.
## Parameters
`o` (in, out)
: stream to write to
`j` (in)
: JSON value to serialize
`ptr` (in)
: JSON pointer to write
## Return value
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.
2. None.
## Complexity
Linear.
## Notes
!!! warning "Deprecation"
Function `#!cpp std::ostream& operator<<(std::ostream& o, const basic_json& j)` replaces function
`#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has been deprecated in version 3.0.0.
It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;` with `#!cpp o << j;`.
## Examples
??? example "Example: (1) serialize JSON value to stream"
The example below shows the serialization with different parameters to `width` to adjust the indentation level.
```cpp
--8<-- "examples/operator_ltlt__basic_json.cpp"
```
Output:
```json
--8<-- "examples/operator_ltlt__basic_json.output"
```
??? example "Example: (2) write JSON pointer to stream"
The example below shows how to write a JSON pointer to a stream.
```cpp
--8<-- "examples/operator_ltlt__json_pointer.cpp"
```
Output:
```json
--8<-- "examples/operator_ltlt__json_pointer.output"
```
## Version history
1. Added in version 1.0.0. Added support for indentation character and deprecated
`#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` in version 3.0.0.
3. Added in version 3.11.0.

49
docs/mkdocs/docs/features/arbitrary_types.md
View File

@@ -1,4 +1,4 @@
# Arbitrary Types Conversions
# Arbitrary Type Conversions
Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:
@@ -10,7 +10,7 @@ namespace ns {
std::string address;
int age;
};
}
} // namespace ns
ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
@@ -155,30 +155,35 @@ To solve this, you need to add a specialization of `adl_serializer` to the `nloh
```cpp
// partial specialization (full specialization works too)
namespace nlohmann {
template <typename T>
struct adl_serializer<boost::optional<T>> {
static void to_json(json& j, const boost::optional<T>& opt) {
if (opt == boost::none) {
j = nullptr;
} else {
j = *opt; // this will call adl_serializer<T>::to_json which will
// find the free function to_json in T's namespace!
}
NLOHMANN_JSON_NAMESPACE_BEGIN
template <typename T>
struct adl_serializer<boost::optional<T>> {
static void to_json(json& j, const boost::optional<T>& opt) {
if (opt == boost::none) {
j = nullptr;
} else {
j = *opt; // this will call adl_serializer<T>::to_json which will
// find the free function to_json in T's namespace!
}
}
static void from_json(const json& j, boost::optional<T>& opt) {
if (j.is_null()) {
opt = boost::none;
} else {
opt = j.get<T>(); // same as above, but with
// adl_serializer<T>::from_json
}
static void from_json(const json& j, boost::optional<T>& opt) {
if (j.is_null()) {
opt = boost::none;
} else {
opt = j.get<T>(); // same as above, but with
// adl_serializer<T>::from_json
}
};
}
}
};
NLOHMANN_JSON_NAMESPACE_END
```
!!! note "ABI compatibility"
Use [`NLOHMANN_JSON_NAMESPACE_BEGIN`](../api/macros/nlohmann_json_namespace_begin.md) and `NLOHMANN_JSON_NAMESPACE_END`
instead of `#!cpp namespace nlohmann { }` in code which may be linked with different versions of this library.
## How can I use `get()` for non-default constructible/non-copyable types?
There is a way, if your type is [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible). You will need to specialize the `adl_serializer` as well, but with a special `from_json` overload:
@@ -214,7 +219,7 @@ namespace nlohmann {
## Can I write my own serializer? (Advanced use)
Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/test/src/unit-udt.cpp) in the test suite, to see a few examples.
Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/tests/src/unit-udt.cpp) in the test suite, to see a few examples.
If you write your own serializer, you'll need to do a few things:

27
docs/mkdocs/docs/features/assertions.md
View File

@@ -102,3 +102,30 @@ behavior and yields a runtime assertion.
```
Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368.
```
### Reading from a null `FILE` pointer
Reading from a null `#!cpp FILE` pointer is undefined behavior and yields a runtime assertion. This can happen when
calling `#!cpp std::fopen` on a nonexistent file.
??? example "Example 4: Uninitialized iterator"
The following code will trigger an assertion at runtime:
```cpp
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
std::FILE* f = std::fopen("nonexistent_file.json", "r");
json j = json::parse(f);
}
```
Output:
```
Assertion failed: (m_file != nullptr), function file_input_adapter, file input_adapters.hpp, line 55.
```

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

@@ -1,24 +1,21 @@
# 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"
- [BJData Specification](https://neurojson.org/bjdata/draft2)
- [BJData Specification](https://neurojson.org/bjdata/draft2)
## Serialization
@@ -55,66 +52,59 @@ The library uses the following mapping from JSON values types to BJData types ac
!!! success "Complete mapping"
The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value.
The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value.
Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`.
Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`.
!!! warning "Size constraints"
The following values can **not** be converted to a BJData value:
The following values can **not** be converted to a BJData value:
- strings with more than 18446744073709551615 bytes (theoretical)
- strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical)
!!! info "Unused BJData markers"
The following markers are not used in the conversion:
The following markers are not used in the conversion:
- `Z`: no-op values are not created.
- `C`: single-byte strings are serialized with `S` markers.
!!! 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. To adopt 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"
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`.
Optimized formats for containers are supported via two parameters of
[`to_bjdata`](../../api/basic_json/to_bjdata.md):
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.
- 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.
!!! info "ND-array optimized format"
BJData extends UBJSON's optimized array **size** marker to support
ND-array of uniform numerical data types (referred to as the *packed array*).
For example, 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]` that can be 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 and stored as `[$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`.
In order to maintain the type and dimension information of an ND-array,
when this library parses a BJData ND-array via `from_bjdata`, it converts the
data into a JSON object, following the **annotated array format** as defined in the
[JData specification (Draft 3)](https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays).
For example, the above 2-D `uint8` array can be parsed and accessed as
To maintain 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
{
@@ -124,33 +114,29 @@ The library uses the following mapping from JSON values types to BJData types ac
}
```
In the reversed direction, when `to_bjdata` detects a JSON object in the
above form, it automatically converts such object into a BJData ND-array
to generate compact output. The only exception is that when the 1-D dimensional
vector stored in `"_ArraySize_"` contains a single integer, or two integers with
one being 1, a regular 1-D optimized array is generated.
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.
The current version of this library has not yet supported automatic
recognition 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 serialization and the deserialization of a 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
@@ -193,8 +179,7 @@ The library maps BJData types to JSON value types as follows:
!!! success "Complete mapping"
The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
??? example

4
docs/mkdocs/docs/features/binary_formats/bson.md
View File

@@ -6,8 +6,8 @@ representation of data types that are not part of the JSON spec. For example, BS
!!! abstract "References"
- [BSON Website](http://bsonspec.org) - the main source on BSON
- [BSON Specification](http://bsonspec.org/spec.html) - the specification
- [BSON Website](http://bsonspec.org) - the main source on BSON
- [BSON Specification](http://bsonspec.org/spec.html) - the specification
## Serialization

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

@@ -5,13 +5,14 @@ small code size, fairly small message size, and extensibility without the need f
!!! abstract "References"
- [CBOR Website](http://cbor.io) - the main source on CBOR
- [CBOR Website](http://cbor.io) - the main source on CBOR
- [CBOR Playground](http://cbor.me) - an interactive webpage to translate between JSON and CBOR
- [RFC 7049](https://tools.ietf.org/html/rfc7049) - the CBOR specification
## 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 |
|-----------------|--------------------------------------------|-----------------------------------|------------|
@@ -61,15 +62,15 @@ see "binary" cells in the table above.
!!! success "Complete mapping"
The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value.
The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value.
!!! info "NaN/infinity handling"
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization 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 normal JSON serialization which serializes NaN or Infinity to `null`.
!!! info "Unused CBOR types"
The following CBOR types are not used in the conversion:
The following CBOR types are not used in the conversion:
- UTF-8 strings terminated by "break" (0x7F)
- arrays terminated by "break" (0x9F)
@@ -149,7 +150,7 @@ The library maps CBOR types to JSON value types as follows:
!!! warning "Incomplete mapping"
The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:
The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:
- date/time (0xC0..0xC1)
- bignum (0xC2..0xC3)
@@ -161,7 +162,7 @@ The library maps CBOR types to JSON value types as follows:
!!! warning "Object keys"
CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
!!! warning "Tagged items"

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

@@ -1,15 +1,18 @@
# 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"
- [MessagePack website](https://msgpack.org)
- [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md)
- [MessagePack website](https://msgpack.org)
- [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md)
## 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 |
|-----------------|------------------------------------------|------------------|------------|
@@ -49,22 +52,23 @@ The library uses the following mapping from JSON values types to MessagePack typ
!!! success "Complete mapping"
The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value.
The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value.
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
!!! warning "Size constraints"
The following values can **not** be converted to a MessagePack value:
The following values can **not** be converted to a MessagePack value:
- strings with more than 4294967295 bytes
- byte strings with more than 4294967295 bytes
- arrays with more than 4294967295 elements
- objects with more than 4294967295 elements
- strings with more than 4294967295 bytes
- byte strings with more than 4294967295 bytes
- arrays with more than 4294967295 elements
- objects with more than 4294967295 elements
!!! 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 in contrast to the
[dump](../../api/basic_json/dump.md) function which serializes NaN or Infinity to `null`.
??? example
@@ -123,7 +127,7 @@ The library maps MessagePack types to JSON value types as follows:
!!! info
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
??? example

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

@@ -1,10 +1,11 @@
# 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"
- [UBJSON Website](http://ubjson.org)
- [UBJSON Website](http://ubjson.org)
## Serialization
@@ -36,50 +37,43 @@ The library uses the following mapping from JSON values types to UBJSON types ac
!!! success "Complete mapping"
The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value.
The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value.
Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`.
Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`.
!!! warning "Size constraints"
The following values can **not** be converted to a UBJSON value:
The following values can **not** be converted to a UBJSON value:
- strings with more than 9223372036854775807 bytes (theoretical)
!!! info "Unused UBJSON markers"
The following markers are not used in the conversion:
The following markers are not used in the conversion:
- `Z`: no-op values are not created.
- `C`: single-byte strings are serialized with `S` markers.
!!! 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
@@ -117,8 +111,7 @@ The library maps UBJSON types to JSON value types as follows:
!!! success "Complete mapping"
The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
??? example

4
docs/mkdocs/docs/features/comments.md
View File

@@ -5,9 +5,9 @@ This library does not support comments *by default*. It does so for three reason
1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.

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

2
docs/mkdocs/docs/features/json_pointer.md
View File

@@ -3,7 +3,7 @@
## Introduction
The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address
structured values. A JSON Pointer is a string that identifies a specific value withing a JSON document.
structured values. A JSON Pointer is a string that identifies a specific value within a JSON document.
Consider the following JSON document

93
docs/mkdocs/docs/features/namespace.md Normal file
View File

@@ -0,0 +1,93 @@
# `nlohmann` Namespace
The 3.11.0 release introduced an
[inline namespace](https://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces) to allow different parts of
a codebase to safely use different versions of the JSON library as long as they never exchange instances of library
types.
## Structure
The complete default namespace name is derived as follows:
- The root namespace is always `nlohmann`.
- The inline namespace starts with `json_abi` and is followed by serveral optional ABI tags according to the value of
these ABI-affecting macros, in order:
- [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) defined non-zero appends `_diag`.
- [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md)
defined non-zero appends `_ldvcmp`.
- The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by
underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component)
below.
For example, the namespace name for version 3.11.2 with `JSON_DIAGNOSTICS` defined to `1` is:
```cpp
nlohmann::json_abi_diag_v3_11_2
```
## Purpose
Several incompatibilities have been observed. Amongst the most common ones is linking code compiled with different
definitions of [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This is illustrated in the diagram below.
```plantuml
[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=0] as [json]
[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=1] as [json_diag]
[**some_library**] as [library]
[**application**] as [app]
[library] ..|> [json]
[app] ..|> [json_diag]
[app] ..|>[library]
```
In releases prior to 3.11.0, mixing any version of the JSON library with different `JSON_DIAGNOSTICS` settings would
result in a crashing application. If `some_library` never passes instances of JSON library types to the application,
this scenario became safe in version 3.11.0 and above due to the inline namespace yielding distinct symbol names.
## Limitations
Neither the compiler nor the linker will issue as much as a warning when translation units – intended to be linked
together and that include different versions and/or configurations of the JSON library – exchange and use library
types.
There is an exception when forward declarations are used (i.e., when including `json_fwd.hpp`) in which case the linker
may complain about undefined references.
## Disabling the version component
Different versions are not necessarily ABI-incompatible, but the project does not actively track changes in the ABI and
recommends that all parts of a codebase exchanging library types be built with the same version. Users can, **at their
own risk**, disable the version component of the linline namespace, allowing different versions – but not
configurations – to be used in cases where the linker would otherwise output undefined reference errors.
To do so, define [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](../api/macros/nlohmann_json_namespace_no_version.md) to `1`.
This applies to version 3.11.2 and above only, versions 3.11.0 and 3.11.1 can apply the technique described in the next
section to emulate the effect of the `NLOHMANN_JSON_NAMESPACE_NO_VERSION` macro.
!!! danger "Use at your own risk"
Disabling the namespace version component and mixing ABI-incompatible versions will result in crashes or incorrect
behavior. You have been warned!
## Disabling the inline namespace completely
When interoperability with code using a pre-3.11.0 version of the library is required, users can, **at their own risk**
restore the old namespace layout by redefining
[`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](../api/macros/nlohmann_json_namespace_begin.md) as
follows:
```cpp
#define NLOHMANN_JSON_NAMESPACE_BEGIN namespace nlohmann {
#define NLOHMANN_JSON_NAMESPACE_END }
```
!!! danger "Use at your own risk"
Overriding the namespace and mixing ABI-incompatible versions will result in crashes or incorrect behavior. You
have been warned!
## Version history
- Introduced inline namespace (`json_v3_11_0[_abi-tag]*`) in version 3.11.0.
- Changed structure of inline namespace in version 3.11.2.

2
docs/mkdocs/docs/features/parsing/json_lines.md
View File

@@ -36,7 +36,7 @@ JSON Lines input with more than one value is treated as invalid JSON by the [`pa
!!! warning "Note"
Using [`operator>>`](../../api/basic_json/operator_gtgt.md) like
Using [`operator>>`](../../api/operator_gtgt.md) like
```cpp
json j;

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 a `#!cpp bool` parameter `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 the 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

2
docs/mkdocs/docs/home/exceptions.md
View File

@@ -74,7 +74,7 @@ Exceptions in the library are thrown in the local context of the JSON value they
To create better diagnostics messages, each JSON value needs a pointer to its parent value such that a global context (i.e., a path from the root value to the value that lead to the exception) can be created. That global context is provided as [JSON Pointer](../features/json_pointer.md).
As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to `1` before including `json.hpp`.
As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to `1` before including `json.hpp`.
??? example

26
docs/mkdocs/docs/home/faq.md
View File

@@ -44,7 +44,7 @@ for objects.
!!! question
Can you add an option to ignore trailing commas?
Can you add an option to ignore trailing commas?
This library does not support any feature which would jeopardize interoperability.
@@ -53,9 +53,9 @@ This library does not support any feature which would jeopardize interoperabilit
!!! question "Questions"
- Why is the parser complaining about a Chinese character?
- Does the library support Unicode?
- I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"`
- Why is the parser complaining about a Chinese character?
- Does the library support Unicode?
- I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"`
The library supports **Unicode input** as follows:
@@ -124,9 +124,9 @@ Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md).
!!! question
Can I get the key of the object item that caused an exception?
Can I get the key of the object item that caused an exception?
Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages).
Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages).
## Serialization issues
@@ -136,18 +136,18 @@ Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../features/macros.m
!!! question
- It seems that precision is lost when serializing a double.
- Can I change the precision for floating-point serialization?
- It seems that precision is lost when serializing a double.
- Can I change the precision for floating-point serialization?
The library uses `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) digits for serialization. This value is sufficient to guarantee roundtripping. If one uses more than this number of digits of precision, then string -> value -> string is not guaranteed to round-trip.
!!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)"
The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow.
The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow.
!!! tip
The website https://float.exposed gives a good insight into the internal storage of floating-point numbers.
The website https://float.exposed gives a good insight into the internal storage of floating-point numbers.
See [this section](../features/types/number_handling.md#number-serialization) on the library's number handling for more information.
@@ -157,7 +157,7 @@ See [this section](../features/types/number_handling.md#number-serialization) on
!!! question
Why does the code not compile with Android SDK?
Why does the code not compile with Android SDK?
Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your `Application.mk`. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
@@ -174,7 +174,7 @@ The code compiles successfully with [Android NDK](https://developer.android.com/
!!! question "Questions"
- Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)?
- Why does the code not compile with MinGW or Android SDK?
- Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)?
- Why does the code not compile with MinGW or Android SDK?
This is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to [this site](http://tehsausage.com/mingw-to-string) and [this discussion](https://github.com/nlohmann/json/issues/136) for information on how to fix this bug. For Android NDK using `APP_STL := gnustl_static`, please refer to [this discussion](https://github.com/nlohmann/json/issues/219).

20
docs/mkdocs/docs/home/releases.md
View File

@@ -252,18 +252,18 @@ http://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a0a45fc74063
- Fixed documentation of parse function. #1473
- Suppressed warning that cannot be fixed inside the library. #1401 #1468
- Imroved package manager suppert:
- Updated Buckaroo instructions. #1495
- Improved Meson support. #1463
- Added Conda package manager documentation. #1430
- Added NuGet package manager documentation. #1132
- Updated Buckaroo instructions. #1495
- Improved Meson support. #1463
- Added Conda package manager documentation. #1430
- Added NuGet package manager documentation. #1132
- Continuous Integration
- Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder.
- Added Clang 7 to Travis CI.
- Fixed AppVeyor x64 builds. #1374 #1414
- Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder.
- Added Clang 7 to Travis CI.
- Fixed AppVeyor x64 builds. #1374 #1414
- Updated thirdparty libraries:
- Catch 1.12.0 -> 1.12.2
- Google Benchmark 1.3.0 -> 1.4.1
- Doxygen 1.8.15 -> 1.8.16
- Catch 1.12.0 -> 1.12.2
- Google Benchmark 1.3.0 -> 1.4.1
- Doxygen 1.8.15 -> 1.8.16
### :fire: Deprecated functions

24
docs/mkdocs/docs/integration/cmake.md
View File

@@ -18,7 +18,7 @@ and use the namespaced imported target from the generated package configuration:
cmake_minimum_required(VERSION 3.1)
project(ExampleProject LANGUAGES CXX)
find_package(nlohmann_json 3.10.5 REQUIRED)
find_package(nlohmann_json 3.11.2 REQUIRED)
add_executable(example example.cpp)
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
@@ -77,7 +77,7 @@ to the following.
```cmake title="thirdparty/CMakeLists.txt"
if(EXAMPLE_USE_EXTERNAL_JSON)
find_package(nlohmann_json 3.10.5 REQUIRED)
find_package(nlohmann_json 3.11.2 REQUIRED)
else()
set(JSON_BuildTests OFF CACHE INTERNAL "")
add_subdirectory(nlohmann_json)
@@ -100,7 +100,7 @@ automatically download a release as a dependency at configure type.
include(FetchContent)
FetchContent_Declare(json URL https://github.com/nlohmann/json/releases/download/v3.10.5/json.tar.xz)
FetchContent_Declare(json URL https://github.com/nlohmann/json/releases/download/v3.11.2/json.tar.xz)
FetchContent_MakeAvailable(json)
add_executable(example example.cpp)
@@ -115,11 +115,11 @@ automatically download a release as a dependency at configure type.
```cmake
FetchContent_Declare(json
GIT_REPOSITORY https://github.com/nlohmann/json
GIT_TAG v3.10.5
GIT_TAG v3.11.2
)
```
However, the repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on
However, the repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on
a smaller repository. For instance, you might want to replace the URL in the example by
<https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
@@ -135,15 +135,25 @@ Enable CI build targets. The exact targets are used during the several CI steps
### `JSON_Diagnostics`
Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics). This option is `OFF` by default.
Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This option is `OFF` by default.
### `JSON_DisableEnumSerialization`
Disable default `enum` serialization by defining the macro
[`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md). This option is `OFF` by default.
### `JSON_FastTests`
Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JSON_BuildTests`.
### `JSON_GlobalUDLs`
Place user-defined string literals in the global namespace by defining the macro
[`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md). This option is `OFF` by default.
### `JSON_ImplicitConversions`
Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../features/macros.md#json_use_implicit_conversions). This option is `ON` by default.
Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md). This option is `ON` by default.
### `JSON_Install`

6
docs/mkdocs/docs/integration/index.md
View File

@@ -13,6 +13,6 @@ using json = nlohmann::json;
to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and
Clang).
You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp)
for forward-declarations. The installation of `json_fwd.hpp` (as part of CMake's install step), can be achieved by
setting `-DJSON_MultipleHeaders=ON`.
You can further use file
[`single_include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp)
for forward declarations.

60
docs/mkdocs/docs/integration/package_managers.md
View File

@@ -30,29 +30,29 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for
??? example
1. Create the following file:
1. Create the following file:
```cpp title="example.cpp"
--8<-- "integration/example.cpp"
```
2. Install the package
2. Install the package
```sh
brew install nlohmann-json
```
```sh
brew install nlohmann-json
```
3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with
3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with
```sh
brew list nlohmann-json
```
```sh
brew list nlohmann-json
```
4. Compile the code. For instance, the code can be compiled using Clang with
4. Compile the code. For instance, the code can be compiled using Clang with
```sh
clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example
```
```sh
clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example
```
:material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically.
@@ -68,7 +68,7 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
??? example
1. Create the following files:
1. Create the following files:
```ini title="Conanfile.txt"
--8<-- "integration/conan/Conanfile.txt"
@@ -82,15 +82,15 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
--8<-- "integration/conan/example.cpp"
```
2. Build:
2. Build:
```sh
mkdir build
cd build
conan install ..
cmake ..
cmake --build .
```
```sh
mkdir build
cd build
conan install ..
cmake ..
cmake --build .
```
:material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically.
@@ -112,7 +112,7 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
??? example
1. Create the following files:
1. Create the following files:
```cmake title="CMakeLists.txt"
--8<-- "integration/vcpkg/CMakeLists.txt"
@@ -128,14 +128,14 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
vcpkg install nlohmann-json
```
3. Build:
3. Build:
```sh
mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build .
```
```sh
mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build .
```
Note you need to adjust `/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake` to your system.

27
docs/mkdocs/mkdocs.yml
View File

@@ -58,6 +58,7 @@ nav:
- features/json_pointer.md
- features/json_patch.md
- features/merge_patch.md
- 'nlohmann Namespace': features/namespace.md
- features/object_order.md
- Parsing:
- features/parsing/index.md
@@ -162,10 +163,6 @@ nav:
- 'operator<=': api/basic_json/operator_le.md
- 'operator>=': api/basic_json/operator_ge.md
- 'operator<=>': api/basic_json/operator_spaceship.md
- 'operator<<': api/basic_json/operator_ltlt.md
- 'operator>>': api/basic_json/operator_gtgt.md
- 'operator""_json': api/basic_json/operator_literal_json.md
- 'operator""_json_pointer': api/basic_json/operator_literal_json_pointer.md
- 'out_of_range': api/basic_json/out_of_range.md
- 'other_error': api/basic_json/other_error.md
- 'parse': api/basic_json/parse.md
@@ -173,6 +170,7 @@ nav:
- 'parse_event_t': api/basic_json/parse_event_t.md
- 'parser_callback_t': api/basic_json/parser_callback_t.md
- 'patch': api/basic_json/patch.md
- 'patch_inplace': api/basic_json/patch_inplace.md
- 'push_back': api/basic_json/push_back.md
- 'rbegin': api/basic_json/rbegin.md
- 'rend': api/basic_json/rend.md
@@ -212,7 +210,9 @@ nav:
- '(Constructor)': api/json_pointer/json_pointer.md
- 'back': api/json_pointer/back.md
- 'empty': api/json_pointer/empty.md
- 'operator std::string': api/json_pointer/operator_string.md
- 'operator string_t': api/json_pointer/operator_string_t.md
- 'operator==': api/json_pointer/operator_eq.md
- 'operator!=': api/json_pointer/operator_ne.md
- 'operator/': api/json_pointer/operator_slash.md
- 'operator/=': api/json_pointer/operator_slasheq.md
- 'parent_pointer': api/json_pointer/parent_pointer.md
@@ -235,6 +235,11 @@ nav:
- 'start_array': api/json_sax/start_array.md
- 'start_object': api/json_sax/start_object.md
- 'string': api/json_sax/string.md
- 'operator<<(basic_json)': api/operator_ltlt.md
- 'operator<<(json_pointer)': api/operator_ltlt.md
- 'operator>>(basic_json)': api/operator_gtgt.md
- 'operator""_json': api/operator_literal_json.md
- 'operator""_json_pointer': api/operator_literal_json_pointer.md
- 'ordered_json': api/ordered_json.md
- 'ordered_map': api/ordered_map.md
- macros:
@@ -257,12 +262,17 @@ nav:
- 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
- 'JSON_THROW_USER': api/macros/json_throw_user.md
- 'JSON_TRY_USER': api/macros/json_throw_user.md
- 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md
- 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
- 'JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON': api/macros/json_use_legacy_discarded_value_comparison.md
- 'NLOHMANN_DEFINE_TYPE_INTRUSIVE': api/macros/nlohmann_define_type_intrusive.md
- 'NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT': api/macros/nlohmann_define_type_intrusive.md
- 'NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE': api/macros/nlohmann_define_type_non_intrusive.md
- 'NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT': api/macros/nlohmann_define_type_non_intrusive.md
- 'NLOHMANN_JSON_NAMESPACE': api/macros/nlohmann_json_namespace.md
- 'NLOHMANN_JSON_NAMESPACE_BEGIN': api/macros/nlohmann_json_namespace_begin.md
- 'NLOHMANN_JSON_NAMESPACE_END': api/macros/nlohmann_json_namespace_begin.md
- 'NLOHMANN_JSON_NAMESPACE_NO_VERSION': api/macros/nlohmann_json_namespace_no_version.md
- 'NLOHMANN_JSON_SERIALIZE_ENUM': api/macros/nlohmann_json_serialize_enum.md
- 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md
- 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md
@@ -324,6 +334,13 @@ plugins:
- minify:
minify_html: true
- git-revision-date-localized
- redirects:
redirect_maps:
'api/basic_json/operator_gtgt.md': api/operator_gtgt.md
'api/basic_json/operator_ltlt.md': api/operator_ltlt.md
'api/basic_json/operator_literal_json.md': api/operator_literal_json.md
'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md
'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md
extra_css:
- css/custom.css

45
docs/mkdocs/requirements.txt
View File

@@ -1,48 +1,49 @@
Babel==2.10.1
certifi==2021.10.8
charset-normalizer==2.0.12
click==8.1.2
Babel==2.10.3
certifi==2022.6.15
charset-normalizer==2.1.0
click==8.1.3
csscompressor==0.9.5
future==0.18.2
ghp-import==2.0.2
ghp-import==2.1.0
gitdb==4.0.9
GitPython==3.1.27
htmlmin==0.1.12
httplib2==0.20.4
idna==3.3
importlib-metadata==4.11.3
Jinja2==3.1.1
importlib-metadata==4.12.0
Jinja2==3.1.2
joblib==1.1.0
jsmin==3.0.1
livereload==2.6.3
lunr==0.6.2
Markdown==3.3.6
markdown-include==0.6.0
Markdown==3.3.0 # pinned due to version conflict with markdown-include and mkdocs
markdown-include==0.7.0
MarkupSafe==2.1.1
mergedeep==1.3.4
mkdocs==1.3.0
mkdocs-git-revision-date-localized-plugin==1.0.1
mkdocs-material==8.2.10
mkdocs==1.3.1
mkdocs-git-revision-date-localized-plugin==1.1.0
mkdocs-material==8.3.9
mkdocs-material-extensions==1.0.3
mkdocs-minify-plugin==0.5.0
mkdocs-redirects==1.0.5
mkdocs-simple-hooks==0.1.5
nltk==3.7
packaging==21.3
plantuml==0.3.0
plantuml-markdown==3.5.2
Pygments==2.11.0
pymdown-extensions==9.3
pyparsing==3.0.8
plantuml-markdown==3.6.3
Pygments==2.12.0
pymdown-extensions==9.5
pyparsing==3.0.9
python-dateutil==2.8.2
pytz==2022.1
PyYAML==6.0
pyyaml_env_tag==0.1
regex==2022.4.24
requests==2.27.1
regex==2022.7.25
requests==2.28.1
six==1.16.0
smmap==5.0.0
tornado==6.1
tornado==6.2
tqdm==4.64.0
urllib3==1.26.9
watchdog==2.1.7
zipp==3.8.0
urllib3==1.26.11
watchdog==2.1.9
zipp==3.8.1

14
docs/mkdocs/scripts/check_structure.py
View File

@@ -3,6 +3,7 @@
import glob
import os.path
import re
import sys
warnings = 0
@@ -75,6 +76,12 @@ def check_structure():
if len(line) > 160 and '|' not in line:
report('whitespace/line_length', f'{file}:{lineno+1} ({current_section})', f'line is too long ({len(line)} vs. 160 chars)')
# sections in `<!-- NOLINT -->` comments are treated as present
if line.startswith('<!-- NOLINT'):
current_section = line.strip('<!-- NOLINT')
current_section = current_section.strip(' -->')
existing_sections.append(current_section)
# check if sections are correct
if line.startswith('## '):
# before starting a new section, check if the previous one documented all overloads
@@ -112,7 +119,7 @@ def check_structure():
if line == '```cpp' and section_idx == -1:
in_initial_code_example = True
if in_initial_code_example and line.startswith('//'):
if in_initial_code_example and line.startswith('//') and line not in ['// since C++20', '// until C++20']:
# check numbering of overloads
if any(map(str.isdigit, line)):
number = int(re.findall(r'\d+', line)[0])
@@ -121,7 +128,7 @@ def check_structure():
last_overload = number
if any(map(str.isdigit, line)) and '(' not in line:
report('style/numbering', f'{file}:{lineno+1}', 'number should be in parentheses: {line}')
report('style/numbering', f'{file}:{lineno+1}', f'number should be in parentheses: {line}')
if line == '```' and in_initial_code_example:
in_initial_code_example = False
@@ -167,3 +174,6 @@ if __name__ == '__main__':
check_structure()
check_examples()
print(120 * '-')
if warnings > 0:
sys.exit(1)