mirror of
https://github.com/nlohmann/json.git
synced 2026-10-14 18:27:13 +00:00
Fix contradictions between the documentation, the README, and the library (#5825)
- Discarded values: the legacy macro only changes <= and >=; != is true by default - Out-of-range numbers are rejected while parsing, not stored as NaN - merge_diff round trip: point to the ordered_json caveat - ensure_ascii example shows the escaped output - out_of_range.405 is thrown for "remove"/"move" on the root, not "add" - CBOR stores binary subtypes as tags - Integer/float comparison uses exact values, not conversion - diff, flatten, and the binary writers are depth-bounded - FAQ: max_digits10 for serialization, trailing commas are supported - out_of_range.407 is still thrown by to_bon8 - FetchContent_MakeAvailable needs CMake 3.14 - json_fwd.hpp contents, operator< link, RFC 7396 for merge patch - README: dump() wording, merge_diff, MSYS2/build2, patch comment typos, operator[] link, embedded CMake example aligned with the docs Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and 
GitHub committed
1 parent
00170dab38
commit
ccc005c012
22 files changed
+85
-64
No files matched your search
@@ -116,7 +116,7 @@ There is also a [**docset**](https://github.com/Kapeli/Dash-User-Contributions/t
|
||||
- **Constructors**: [basic_json](https://json.nlohmann.me/api/basic_json/basic_json), [array](https://json.nlohmann.me/api/basic_json/array), [binary](https://json.nlohmann.me/api/basic_json/binary), [object](https://json.nlohmann.me/api/basic_json/object)
|
||||
- **Object inspection**: [type](https://json.nlohmann.me/api/basic_json/type), [operator value_t](https://json.nlohmann.me/api/basic_json/operator_value_t), [type_name](https://json.nlohmann.me/api/basic_json/type_name), [is_primitive](https://json.nlohmann.me/api/basic_json/is_primitive), [is_structured](https://json.nlohmann.me/api/basic_json/is_structured), [is_null](https://json.nlohmann.me/api/basic_json/is_null), [is_boolean](https://json.nlohmann.me/api/basic_json/is_boolean), [is_number](https://json.nlohmann.me/api/basic_json/is_number), [is_number_integer](https://json.nlohmann.me/api/basic_json/is_number_integer), [is_number_unsigned](https://json.nlohmann.me/api/basic_json/is_number_unsigned), [is_number_float](https://json.nlohmann.me/api/basic_json/is_number_float), [is_object](https://json.nlohmann.me/api/basic_json/is_object), [is_array](https://json.nlohmann.me/api/basic_json/is_array), [is_string](https://json.nlohmann.me/api/basic_json/is_string), [is_binary](https://json.nlohmann.me/api/basic_json/is_binary), [is_discarded](https://json.nlohmann.me/api/basic_json/is_discarded)
|
||||
- **Value access**: [get](https://json.nlohmann.me/api/basic_json/get), [get_to](https://json.nlohmann.me/api/basic_json/get_to), [get_ptr](https://json.nlohmann.me/api/basic_json/get_ptr), [get_ref](https://json.nlohmann.me/api/basic_json/get_ref), [operator ValueType](https://json.nlohmann.me/api/basic_json/operator_ValueType), [get_binary](https://json.nlohmann.me/api/basic_json/get_binary)
|
||||
- **Element access**: [at](https://json.nlohmann.me/api/basic_json/at), [operator[]](https://json.nlohmann.me/api/basic_json/operator[]), [value](https://json.nlohmann.me/api/basic_json/value), [front](https://json.nlohmann.me/api/basic_json/front), [back](https://json.nlohmann.me/api/basic_json/back)
|
||||
- **Element access**: [at](https://json.nlohmann.me/api/basic_json/at), [operator[]](https://json.nlohmann.me/api/basic_json/operator%5B%5D/), [value](https://json.nlohmann.me/api/basic_json/value), [front](https://json.nlohmann.me/api/basic_json/front), [back](https://json.nlohmann.me/api/basic_json/back)
|
||||
- **Lookup**: [find](https://json.nlohmann.me/api/basic_json/find), [count](https://json.nlohmann.me/api/basic_json/count), [contains](https://json.nlohmann.me/api/basic_json/contains)
|
||||
- **Iterators**: [begin](https://json.nlohmann.me/api/basic_json/begin), [cbegin](https://json.nlohmann.me/api/basic_json/cbegin), [end](https://json.nlohmann.me/api/basic_json/end), [cend](https://json.nlohmann.me/api/basic_json/cend), [rbegin](https://json.nlohmann.me/api/basic_json/rbegin), [rend](https://json.nlohmann.me/api/basic_json/rend), [crbegin](https://json.nlohmann.me/api/basic_json/crbegin), [crend](https://json.nlohmann.me/api/basic_json/crend), [items](https://json.nlohmann.me/api/basic_json/items)
|
||||
- **Capacity**: [empty](https://json.nlohmann.me/api/basic_json/empty), [size](https://json.nlohmann.me/api/basic_json/size), [max_size](https://json.nlohmann.me/api/basic_json/max_size)
|
||||
@@ -125,7 +125,7 @@ There is also a [**docset**](https://github.com/Kapeli/Dash-User-Contributions/t
|
||||
- **Serialization / Dumping**: [dump](https://json.nlohmann.me/api/basic_json/dump)
|
||||
- **Deserialization / Parsing**: [parse](https://json.nlohmann.me/api/basic_json/parse), [accept](https://json.nlohmann.me/api/basic_json/accept), [sax_parse](https://json.nlohmann.me/api/basic_json/sax_parse)
|
||||
- **JSON Pointer functions**: [flatten](https://json.nlohmann.me/api/basic_json/flatten), [unflatten](https://json.nlohmann.me/api/basic_json/unflatten)
|
||||
- **JSON Patch functions**: [patch](https://json.nlohmann.me/api/basic_json/patch), [patch_inplace](https://json.nlohmann.me/api/basic_json/patch_inplace), [diff](https://json.nlohmann.me/api/basic_json/diff), [merge_patch](https://json.nlohmann.me/api/basic_json/merge_patch)
|
||||
- **JSON Patch functions**: [patch](https://json.nlohmann.me/api/basic_json/patch), [patch_inplace](https://json.nlohmann.me/api/basic_json/patch_inplace), [diff](https://json.nlohmann.me/api/basic_json/diff), [merge_patch](https://json.nlohmann.me/api/basic_json/merge_patch), [merge_diff](https://json.nlohmann.me/api/basic_json/merge_diff)
|
||||
- **Static functions**: [meta](https://json.nlohmann.me/api/basic_json/meta), [get_allocator](https://json.nlohmann.me/api/basic_json/get_allocator)
|
||||
- **Binary formats**: [from_bjdata](https://json.nlohmann.me/api/basic_json/from_bjdata), [from_bon8](https://json.nlohmann.me/api/basic_json/from_bon8), [from_bson](https://json.nlohmann.me/api/basic_json/from_bson), [from_cbor](https://json.nlohmann.me/api/basic_json/from_cbor), [from_msgpack](https://json.nlohmann.me/api/basic_json/from_msgpack), [from_ubjson](https://json.nlohmann.me/api/basic_json/from_ubjson), [to_bjdata](https://json.nlohmann.me/api/basic_json/to_bjdata), [to_bon8](https://json.nlohmann.me/api/basic_json/to_bon8), [to_bson](https://json.nlohmann.me/api/basic_json/to_bson), [to_cbor](https://json.nlohmann.me/api/basic_json/to_cbor), [to_msgpack](https://json.nlohmann.me/api/basic_json/to_msgpack), [to_ubjson](https://json.nlohmann.me/api/basic_json/to_ubjson)
|
||||
- **Non-member functions**: [operator<<](https://json.nlohmann.me/api/operator_ltlt/), [operator>>](https://json.nlohmann.me/api/operator_gtgt/), [to_string](https://json.nlohmann.me/api/basic_json/to_string)
|
||||
@@ -360,7 +360,7 @@ std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::
|
||||
std::cout << j_string << " == " << serialized_string << std::endl;
|
||||
```
|
||||
|
||||
[`.dump()`](https://json.nlohmann.me/api/basic_json/dump/) returns the originally stored string value.
|
||||
[`.dump()`](https://json.nlohmann.me/api/basic_json/dump/) returns the serialized JSON text, so a string value is enclosed in quotes and special characters are escaped. Use [`get<std::string>()`](https://json.nlohmann.me/api/basic_json/get/) to retrieve the originally stored string value.
|
||||
|
||||
Note the library only supports UTF-8. When you store strings with different encodings in the library, calling [`dump()`](https://json.nlohmann.me/api/basic_json/dump/) may throw an exception unless `json::error_handler_t::replace`, `json::error_handler_t::ignore`, or `json::error_handler_t::keep` are used as error handlers.
|
||||
|
||||
@@ -687,15 +687,15 @@ json j_result = j_original.patch(j_patch);
|
||||
// calculate a JSON patch from two JSON values
|
||||
json::diff(j_result, j_original);
|
||||
// [
|
||||
// { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
|
||||
// { "op": "remove","path": "/hello" },
|
||||
// { "op": "replace", "path": "/baz", "value": ["one", "two", "three"] },
|
||||
// { "op": "remove", "path": "/hello" },
|
||||
// { "op": "add", "path": "/foo", "value": "bar" }
|
||||
// ]
|
||||
```
|
||||
|
||||
### JSON Merge Patch
|
||||
|
||||
The library supports **JSON Merge Patch** ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
|
||||
The library supports **JSON Merge Patch** ([RFC 7396](https://tools.ietf.org/html/rfc7396)) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
|
||||
|
||||
```cpp
|
||||
// a JSON value
|
||||
@@ -725,6 +725,20 @@ j_document.merge_patch(j_patch);
|
||||
// }
|
||||
```
|
||||
|
||||
Conversely, [`merge_diff`](https://json.nlohmann.me/api/basic_json/merge_diff/) creates a merge patch from two JSON values:
|
||||
|
||||
```cpp
|
||||
// create a merge patch that turns j_original into j_document
|
||||
json j_original = R"({"a": "b", "c": {"d": "e", "f": "g"}})"_json;
|
||||
json::merge_diff(j_original, j_document);
|
||||
// {
|
||||
// "a": "z",
|
||||
// "c": {
|
||||
// "f": null
|
||||
// }
|
||||
// }
|
||||
```
|
||||
|
||||
### Implicit conversions
|
||||
|
||||
Supported types can be implicitly converted to JSON values.
|
||||
@@ -1266,13 +1280,9 @@ The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either
|
||||
To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call `add_subdirectory()` in your `CMakeLists.txt` file:
|
||||
|
||||
```cmake
|
||||
# Typically you don't care so much for a third party library's tests to be
|
||||
# run from your own project's code.
|
||||
set(JSON_BuildTests OFF CACHE INTERNAL "")
|
||||
|
||||
# If you only include this third party in PRIVATE source files, you do not
|
||||
# need to install it when your main project gets installed.
|
||||
# set(JSON_Install OFF CACHE INTERNAL "")
|
||||
set(JSON_Install OFF CACHE INTERNAL "")
|
||||
|
||||
# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
|
||||
# unintended consequences that will break the build. It's generally
|
||||
@@ -1287,8 +1297,8 @@ target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
|
||||
|
||||
##### Embedded (FetchContent)
|
||||
|
||||
Since CMake v3.11,
|
||||
[FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
|
||||
Since CMake v3.14,
|
||||
[FetchContent](https://cmake.org/cmake/help/v3.14/module/FetchContent.html) can
|
||||
be used to automatically download a release as a dependency at configure time.
|
||||
|
||||
Example:
|
||||
@@ -1353,7 +1363,9 @@ Use your favorite [**package manager**](https://json.nlohmann.me/integration/pac
|
||||
- <img src="https://raw.githubusercontent.com/nlohmann/json/refs/heads/develop/docs/mkdocs/docs/images/package_managers/swift.svg" height="20"> [**Swift Package Manager**](https://json.nlohmann.me/integration/package_managers/#swift-package-manager) `nlohmann/json`
|
||||
- <img src="https://raw.githubusercontent.com/nlohmann/json/refs/heads/develop/docs/mkdocs/docs/images/package_managers/nuget.svg" height="20"> [**Nuget**](https://json.nlohmann.me/integration/package_managers/#nuget) `nlohmann.json`
|
||||
- <img src="https://raw.githubusercontent.com/nlohmann/json/refs/heads/develop/docs/mkdocs/docs/images/package_managers/conda.svg" height="20"> [**Conda**](https://json.nlohmann.me/integration/package_managers/#conda) `nlohmann_json`
|
||||
- [**MSYS2**](https://json.nlohmann.me/integration/package_managers/#msys2) `mingw-w64-nlohmann-json`
|
||||
- <img src="https://raw.githubusercontent.com/nlohmann/json/refs/heads/develop/docs/mkdocs/docs/images/package_managers/macports.svg" height="20"> [**MacPorts**](https://json.nlohmann.me/integration/package_managers/#macports) `nlohmann-json`
|
||||
- [**build2**](https://json.nlohmann.me/integration/package_managers/#build2) `nlohmann-json`
|
||||
- <img src="https://raw.githubusercontent.com/nlohmann/json/refs/heads/develop/docs/mkdocs/docs/images/package_managers/CPM.png" height="20"> [**cpm.cmake**](https://json.nlohmann.me/integration/package_managers/#cpmcmake) `gh:nlohmann/json`
|
||||
- <img src="https://raw.githubusercontent.com/nlohmann/json/refs/heads/develop/docs/mkdocs/docs/images/package_managers/xmake.svg" height="20"> [**xmake**](https://json.nlohmann.me/integration/package_managers/#xmake) `nlohmann_json`
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ The class satisfies the following concept requirements:
|
||||
- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with
|
||||
`==`, see [`operator==`](operator_eq.md).
|
||||
- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with
|
||||
`<`, see [`operator<`](operator_le.md).
|
||||
`<`, see [`operator<`](operator_lt.md).
|
||||
- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with
|
||||
any lvalue or rvalue of other compatible types, using unqualified function `swap`.
|
||||
- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against
|
||||
|
||||
@@ -11,7 +11,7 @@ added members with their new values, and removed members with the value `#!json
|
||||
member by member; any other value that differs, including an array, is replaced as a whole.
|
||||
|
||||
For two JSON values `source` and `target`, where `target` contains no object member whose value is `#!json null`, the
|
||||
following code always yields `#!cpp true`:
|
||||
following code always yields `#!cpp true` (for [`ordered_json`](../ordered_json.md), see the notes below):
|
||||
```cpp
|
||||
basic_json patched = source;
|
||||
patched.merge_patch(merge_diff(source, target));
|
||||
|
||||
@@ -52,9 +52,10 @@ With the default values for `NumberFloatType` (`double`), the default value for
|
||||
> interoperability can be achieved by implementations that expect no more precision or range than these provide, in the
|
||||
> sense that implementations will approximate JSON numbers within the expected precision.
|
||||
|
||||
This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values
|
||||
smaller than `-1.79769313486232e+308` and values greater than `1.79769313486232e+308` will be stored as NaN internally
|
||||
and be serialized to `null`.
|
||||
This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note that
|
||||
numbers smaller than `-1.79769313486232e+308` or greater than `1.79769313486232e+308` are rejected during parsing with
|
||||
[`out_of_range.406`](../../home/exceptions.md#jsonexceptionout_of_range406). Non-finite values (NaN and infinity) can
|
||||
only be stored by assigning them directly and are serialized to `null`.
|
||||
|
||||
During deserialization (from JSON text or any of the binary formats), a finite number that does not fit into
|
||||
`number_float_t` is rejected with [`out_of_range.406`](../../home/exceptions.md#jsonexceptionout_of_range406), for
|
||||
|
||||
@@ -20,7 +20,8 @@ bool operator==(ScalarType rhs) const noexcept(/* see below */); // (2)
|
||||
1. Compares two JSON values for equality according to the following rules:
|
||||
- Two JSON values are equal if (1) neither value is discarded, and (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.
|
||||
- Integer and floating-point numbers are compared by their exact values, without converting the integer to
|
||||
floating-point. For instance, `9007199254740993` and `9007199254740992.0` are not equal.
|
||||
|
||||
2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the
|
||||
scalar to a JSON value and comparing both JSON values according to 1.
|
||||
|
||||
@@ -15,7 +15,8 @@ bool operator<(ScalarType lhs, const const_reference rhs) noexcept(/* see below
|
||||
following rules:
|
||||
- If either operand is discarded, the comparison yields `#!cpp false`.
|
||||
- If both operands have the same type, the values are compared using their respective `operator<`.
|
||||
- Integer and floating-point numbers are automatically converted before comparison.
|
||||
- Integer and floating-point numbers are compared by their exact values, without converting the integer to
|
||||
floating-point. For instance, `9007199254740992.0` is less than `9007199254740993`.
|
||||
- In case `lhs` and `rhs` have different types, the values are ignored and the order of the types
|
||||
is considered, which is:
|
||||
1. null
|
||||
|
||||
@@ -12,10 +12,8 @@ std::partial_ordering operator<=>(const ScalarType rhs) const noexcept(/* see be
|
||||
- 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 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 converted to
|
||||
floating-point with the second value.
|
||||
- Integer and floating-point numbers are 3-way compared by their exact values, without converting the integer to
|
||||
floating-point. For instance, `9007199254740993` compares greater than `9007199254740992.0`.
|
||||
- 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
|
||||
|
||||
@@ -45,7 +45,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
|
||||
pointer inside the patch cannot be resolved, e.g., `-` in a "remove" operation or `1a` for an array; example:
|
||||
`"unresolved reference token '-'"`.
|
||||
- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
|
||||
("add", "remove", "move")
|
||||
("remove", "move")
|
||||
- Throws [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) if an "add" operation's target
|
||||
location has a parent that is neither an object nor an array.
|
||||
- Throws [`out_of_range.413`](../../home/exceptions.md#jsonexceptionout_of_range413) if a "remove" operation's target
|
||||
|
||||
@@ -41,7 +41,7 @@ No guarantees, value may be corrupted by an unsuccessful patch operation.
|
||||
pointer inside the patch cannot be resolved, e.g., `-` in a "remove" operation or `1a` for an array; example:
|
||||
`"unresolved reference token '-'"`.
|
||||
- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
|
||||
("add", "remove", "move")
|
||||
("remove", "move")
|
||||
- Throws [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) if an "add" operation's target
|
||||
location has a parent that is neither an object nor an array.
|
||||
- Throws [`out_of_range.413`](../../home/exceptions.md#jsonexceptionout_of_range413) if a "remove" operation's target
|
||||
|
||||
@@ -18,7 +18,8 @@ When enabled, comparisons involving at least one discarded JSON value yield resu
|
||||
| `>=` | `#!cpp true` |
|
||||
| `>` | `#!cpp false` |
|
||||
|
||||
Otherwise, comparisons involving at least one discarded JSON value always yield `#!cpp false`.
|
||||
Otherwise, comparisons involving at least one discarded JSON value yield `#!cpp false`, except for `!=`, which is the
|
||||
negation of `==` and yields `#!cpp true`.
|
||||
|
||||
## Default definition
|
||||
|
||||
|
||||
@@ -54,10 +54,9 @@ flowchart LR
|
||||
user code. The destructor does not recurse, so destroying a deeply nested value does not exhaust the stack.
|
||||
- **Bounded recursion.** The JSON parser and the binary readers keep their state in explicit stacks instead of
|
||||
recursing per nesting level. Operations that walk a value, such as [`dump`](../api/basic_json/dump.md), copying,
|
||||
comparison, hashing, and [`merge_patch`](../api/basic_json/merge_patch.md), recurse only up to a fixed depth and
|
||||
continue with an explicit stack below it. Some operations, such as [`diff`](../api/basic_json/diff.md),
|
||||
[`flatten`](../api/basic_json/flatten.md), and the binary writers, still recurse once per nesting level; work on them
|
||||
is in progress. Applications that process untrusted input can limit its nesting depth with a
|
||||
comparison, hashing, [`merge_patch`](../api/basic_json/merge_patch.md), [`diff`](../api/basic_json/diff.md),
|
||||
[`flatten`](../api/basic_json/flatten.md), and the binary writers, recurse only up to a fixed depth and continue with
|
||||
an explicit stack below it. Applications that process untrusted input can limit its nesting depth with a
|
||||
[parser callback](../features/parsing/parser_callbacks.md).
|
||||
- **Invariants are checked.** The class invariant (for instance, that the pointer for the stored type is never null) is
|
||||
checked with runtime assertions throughout the test suite.
|
||||
|
||||
@@ -267,9 +267,10 @@ unsigned 8-bit integer. If no subtype is given, the generic binary subtype 0x00
|
||||
|
||||
### CBOR
|
||||
|
||||
[CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Subtypes will be serialized as tags. Any binary
|
||||
value will be serialized as byte strings. The library will choose the smallest representation using the length of the
|
||||
byte array.
|
||||
[CBOR](binary_formats/cbor.md) supports binary values and subtypes. Any binary value will be serialized as a byte
|
||||
string; a subtype is serialized as a tag preceding it. When parsing, tags are only read back as subtypes with
|
||||
`cbor_tag_handler_t::store` (see [`from_cbor`](../api/basic_json/from_cbor.md)). The library will choose the smallest
|
||||
representation using the length of the byte array.
|
||||
|
||||
??? example "Example: serialize a binary value to CBOR"
|
||||
|
||||
|
||||
@@ -243,9 +243,9 @@ See [full documentation of `JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global
|
||||
|
||||
## `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`
|
||||
|
||||
When defined to `1`, the library restores the legacy behavior in which a discarded value compared equal to itself. This
|
||||
behavior is [deprecated](../integration/migration_guide.md#miscellaneous-functions) and switched off (`0`) by
|
||||
default.
|
||||
When defined to `1`, the library restores the legacy behavior in which comparing a discarded value with `<=` or `>=`
|
||||
yields `#!cpp true` instead of `#!cpp false`. This behavior is
|
||||
[deprecated](../integration/migration_guide.md#miscellaneous-functions) and switched off (`0`) by default.
|
||||
|
||||
See [full documentation of `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md).
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# JSON Merge Patch
|
||||
|
||||
The library supports JSON Merge Patch ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format.
|
||||
The library supports JSON Merge Patch ([RFC 7396](https://tools.ietf.org/html/rfc7396)) as a patch format.
|
||||
The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of
|
||||
modifications to a target resource's content. This function applies a merge patch to the current JSON value.
|
||||
|
||||
|
||||
@@ -66,7 +66,7 @@ config.update(user_settings, true);
|
||||
// {"log":{"file":"app.log","level":"debug"},"retries":3}
|
||||
```
|
||||
|
||||
[JSON Merge Patch](merge_patch.md) ([RFC 7386](https://tools.ietf.org/html/rfc7386)) also merges objects recursively,
|
||||
[JSON Merge Patch](merge_patch.md) ([RFC 7396](https://tools.ietf.org/html/rfc7396)) also merges objects recursively,
|
||||
but it is a different tool: a `#!json null` in the patch means "remove this key". It is meant for applying merge patch
|
||||
documents (e.g., received via HTTP PATCH). To merge configuration-like objects, use `#!cpp update(..., true)`. To apply
|
||||
a sequence of well-defined edit operations, see [JSON Patch](json_patch.md).
|
||||
@@ -90,6 +90,6 @@ a.erase(1); // [1,3,4] (erase by index)
|
||||
- [`push_back`](../api/basic_json/push_back.md) / [`emplace_back`](../api/basic_json/emplace_back.md) - append to an array
|
||||
- [`emplace`](../api/basic_json/emplace.md) - insert into an object if the key is absent
|
||||
- [`update`](../api/basic_json/update.md) - merge objects (shallow, or recursive with `merge_objects`)
|
||||
- [`merge_patch`](../api/basic_json/merge_patch.md) - apply an RFC 7386 merge patch
|
||||
- [`merge_patch`](../api/basic_json/merge_patch.md) - apply an RFC 7396 merge patch
|
||||
- [`erase`](../api/basic_json/erase.md) / [`clear`](../api/basic_json/clear.md) - remove elements
|
||||
- [JSON Patch and Diff](json_patch.md) and [JSON Merge Patch](merge_patch.md) - structured modifications
|
||||
@@ -50,19 +50,13 @@ stack, however deeply it is nested.
|
||||
|
||||
Once a value has been parsed, operations that walk it recursively -- serializing it with
|
||||
[`dump`](../../api/basic_json/dump.md), hashing it, copying it, comparing two values with `#!cpp ==`, `#!cpp <`, or (in
|
||||
C++20) `#!cpp <=>`, merging with [`update`](../../api/basic_json/update.md), and applying a
|
||||
[`merge_patch`](../../api/basic_json/merge_patch.md) -- descend at most 128 levels on the call stack and continue
|
||||
C++20) `#!cpp <=>`, merging with [`update`](../../api/basic_json/update.md), applying a
|
||||
[`merge_patch`](../../api/basic_json/merge_patch.md), creating a patch with [`diff`](../../api/basic_json/diff.md) or
|
||||
[`merge_diff`](../../api/basic_json/merge_diff.md), [`flatten`](../../api/basic_json/flatten.md), and the binary
|
||||
writers (`to_cbor`, `to_msgpack`, ...) -- descend at most 128 levels on the call stack and continue
|
||||
below that with an explicit stack instead, so none of them can exhaust the stack either, however deeply the value is
|
||||
nested. Destroying a value (its destructor) never recurses at all, regardless of nesting depth, for the same reason.
|
||||
|
||||
!!! note "Not every operation is bounded yet"
|
||||
|
||||
[`diff`](../../api/basic_json/diff.md), [`flatten`](../../api/basic_json/flatten.md), and the binary writers
|
||||
(`to_cbor`, `to_msgpack`, ...) still recurse once per nesting level; this is called out as work in progress in the
|
||||
[assurance case](../../community/assurance_case.md#secure-design). A value deep enough to matter for these
|
||||
operations would typically first have to survive parsing without hitting a self-imposed depth limit, as described
|
||||
above.
|
||||
|
||||
## Input size
|
||||
|
||||
The library does not limit the overall size of a JSON text; a value nested or wide enough will use memory
|
||||
|
||||
@@ -52,7 +52,7 @@ with `\uXXXX` sequences, so that the output contains only ASCII characters:
|
||||
```cpp
|
||||
json j = "苹果";
|
||||
j.dump(); // "苹果"
|
||||
j.dump(-1, ' ', true); // "苹果"
|
||||
j.dump(-1, ' ', true); // "\u82f9\u679c"
|
||||
```
|
||||
|
||||
## Handling invalid UTF-8
|
||||
|
||||
@@ -281,7 +281,7 @@ As this range is a subrange of the exactly supported range [`INT64_MIN`, `INT64_
|
||||
|
||||
> This specification allows implementations to set limits on the range and precision of numbers accepted. Since software that implements IEEE 754-2008 binary64 (double precision) numbers is generally available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide, in the sense that implementations will approximate JSON numbers within the expected precision.
|
||||
|
||||
This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values smaller than `#!c -1.79769313486232e+308` and values greater than `#!c 1.79769313486232e+308` will be stored as NaN internally and be serialized to `#!json null`.
|
||||
This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note that numbers smaller than `#!c -1.79769313486232e+308` or greater than `#!c 1.79769313486232e+308` are rejected during parsing with [`out_of_range.406`](../../home/exceptions.md#jsonexceptionout_of_range406). Non-finite values (NaN and infinity) can only be stored by assigning them directly and are serialized to `#!json null`.
|
||||
|
||||
### Storage
|
||||
|
||||
|
||||
@@ -889,7 +889,9 @@ contains other characters (e.g., `1a`), or `-` where it cannot be used.
|
||||
|
||||
### json.exception.out_of_range.405
|
||||
|
||||
The JSON Patch operations 'remove' and 'add' cannot be applied to the root element of the JSON value.
|
||||
The JSON Patch operations 'remove' and 'move' cannot be applied to the root element of the JSON value. The exception is
|
||||
also thrown when the parent or a reference token of an empty JSON Pointer is requested, for instance by
|
||||
[`back`](../api/json_pointer/back.md) or [`pop_back`](../api/json_pointer/pop_back.md).
|
||||
|
||||
!!! failure "Example message"
|
||||
|
||||
@@ -914,15 +916,23 @@ double-precision number when `number_float_t` is `#!cpp float`.
|
||||
|
||||
### json.exception.out_of_range.407
|
||||
|
||||
This exception previously indicated that the UBJSON and BSON binary formats did not support integer numbers greater than
|
||||
9223372036854775807 due to limitations in the implemented mapping. However, these limitations have since been resolved,
|
||||
and this exception no longer occurs.
|
||||
An unsigned integer number greater than 9223372036854775807 cannot be represented in the binary format. This exception
|
||||
is only thrown by [`to_bon8`](../api/basic_json/to_bon8.md), as [BON8](../features/binary_formats/bon8.md) has no
|
||||
unsigned 64-bit integer type.
|
||||
|
||||
!!! success "Exception cannot occur any more"
|
||||
!!! note "Former occurrences"
|
||||
|
||||
The UBJSON and BSON writers used to throw this exception as well:
|
||||
|
||||
- Since version 3.9.0, integer numbers beyond int64 are serialized as high-precision UBJSON numbers.
|
||||
- Since version 3.12.0, integer numbers beyond int64 are serialized as uint64 BSON numbers.
|
||||
|
||||
!!! failure "Example message"
|
||||
|
||||
```
|
||||
integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
|
||||
```
|
||||
|
||||
### json.exception.out_of_range.408
|
||||
|
||||
The size of an array or object in a [binary format](../features/binary_formats/index.md) exceeds the maximal capacity:
|
||||
|
||||
@@ -66,7 +66,9 @@ Without the macro (default behavior), `json j{obj}` creates `[{"key":"value"}]`.
|
||||
|
||||
Can you add an option to ignore trailing commas?
|
||||
|
||||
This library does not support any feature that would jeopardize interoperability.
|
||||
Yes, trailing commas in arrays and objects can be allowed by setting parameter `ignore_trailing_commas` of
|
||||
[`parse`](../api/basic_json/parse.md) to `#!cpp true`; see [trailing commas](../features/trailing_commas.md). They are
|
||||
rejected by default, and the library never adds them when serializing.
|
||||
|
||||
|
||||
### Parse errors reading non-ASCII characters
|
||||
@@ -230,11 +232,11 @@ Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_d
|
||||
- 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.
|
||||
The library serializes floating-point numbers with the shortest representation that parses back to the same value, using at most `std::numeric_limits<number_float_t>::max_digits10` (17 for IEEE `double`s) significant digits. This guarantees that value -> string -> value round-trips. The reverse direction, string -> value -> string, is only guaranteed for numbers with at most `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) significant digits; a number with more digits may not be representable exactly and is then serialized as the closest `double`.
|
||||
|
||||
!!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)"
|
||||
!!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/max_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>::max_digits10` is the number of base-10 digits that are necessary to uniquely represent all distinct values of the type T, such as necessary for serialization/deserialization to text.
|
||||
|
||||
!!! tip
|
||||
|
||||
|
||||
@@ -90,13 +90,13 @@ to the following.
|
||||
|
||||
### FetchContent
|
||||
|
||||
Since CMake v3.11, [FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can be used to
|
||||
Since CMake v3.14, [FetchContent](https://cmake.org/cmake/help/v3.14/module/FetchContent.html) can be used to
|
||||
automatically download a release as a dependency at configure time.
|
||||
|
||||
!!! example
|
||||
|
||||
```cmake title="CMakeLists.txt"
|
||||
cmake_minimum_required(VERSION 3.11)
|
||||
cmake_minimum_required(VERSION 3.14)
|
||||
project(ExampleProject LANGUAGES CXX)
|
||||
|
||||
include(FetchContent)
|
||||
|
||||
@@ -14,7 +14,8 @@ that cost, ordered by how much they typically save.
|
||||
|
||||
Header files that only need to *name* the `json` type — for function declarations, members held by pointer or
|
||||
reference, or friend declarations — can include `<nlohmann/json_fwd.hpp>` instead of `<nlohmann/json.hpp>`. It only
|
||||
forward-declares `basic_json`, `json`, `ordered_json`, `json_pointer`, and `adl_serializer`. The translation units that
|
||||
forward-declares `basic_json`, `json_pointer`, `adl_serializer`, and `ordered_map`, and defines the aliases `json` and
|
||||
`ordered_json`. The translation units that
|
||||
actually use the values then include `<nlohmann/json.hpp>`.
|
||||
|
||||
```cpp title="person.hpp"
|
||||
|
||||
Reference in new issue
Block a user