mirror of
https://github.com/nlohmann/json.git
synced 2026-10-01 12:10:32 +00:00
Merge branch 'develop' into claude/const-json-pointer-assertion
Conflicts: - docs/mkdocs/docs/api/basic_json/operator[].md: version history item 1 keeps develop's std::length_error fix note and appends the PR's runtime assertion note Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
@@ -139,8 +139,8 @@ basic_json(basic_json&& other) noexcept;
|
||||
|
||||
- In case of a `#!json null` type, [invalid_iterator.206](../../home/exceptions.md#jsonexceptioninvalid_iterator206)
|
||||
is thrown.
|
||||
- In case of other primitive types (number, boolean, or string), `first` must be `begin()` and `last` must be
|
||||
`end()`. In this case, the value is copied. Otherwise,
|
||||
- In case of other primitive types (number, boolean, string, or binary), `first` must be `begin()` and `last`
|
||||
must be `end()`. In this case, the value is copied. Otherwise,
|
||||
[`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) is thrown.
|
||||
- In case of structured types (array, object), the constructor behaves as similar versions for `std::vector` or
|
||||
`std::map`; that is, a JSON array or object is constructed from the values in the range.
|
||||
@@ -242,8 +242,8 @@ basic_json(basic_json&& other) noexcept;
|
||||
and `last` are not compatible (i.e., do not belong to the same JSON value). In this case, the range
|
||||
`[first, last)` is undefined.
|
||||
- Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if iterators `first`
|
||||
and `last` belong to a primitive type (number, boolean, or string), but `first` does not point to the first
|
||||
element anymore. In this case, the range `[first, last)` is undefined. See the example code below.
|
||||
and `last` belong to a primitive type (number, boolean, string, or binary), but `first` does not point to the
|
||||
first element anymore. In this case, the range `[first, last)` is undefined. See the example code below.
|
||||
- Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
|
||||
and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
|
||||
8. (none)
|
||||
@@ -423,6 +423,8 @@ basic_json(basic_json&& other) noexcept;
|
||||
4. Since version 3.2.0.
|
||||
5. Since version 1.0.0.
|
||||
6. Since version 1.0.0.
|
||||
7. Since version 1.0.0.
|
||||
7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range
|
||||
that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied,
|
||||
unlike the other primitive types.
|
||||
8. Since version 1.0.0.
|
||||
9. Since version 1.0.0.
|
||||
|
||||
@@ -7,15 +7,15 @@ void clear() noexcept;
|
||||
Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](basic_json.md) would
|
||||
have been called with the current value type from [`type()`](type.md):
|
||||
|
||||
| Value type | initial value |
|
||||
|------------|----------------------|
|
||||
| null | `null` |
|
||||
| boolean | `false` |
|
||||
| string | `""` |
|
||||
| number | `0` |
|
||||
| binary | An empty byte vector |
|
||||
| object | `{}` |
|
||||
| array | `[]` |
|
||||
| Value type | initial value |
|
||||
|------------|-----------------------------------------|
|
||||
| null | `null` |
|
||||
| boolean | `false` |
|
||||
| string | `""` |
|
||||
| number | `0` |
|
||||
| binary | An empty byte vector with no subtype |
|
||||
| object | `{}` |
|
||||
| array | `[]` |
|
||||
|
||||
Has the same effect as calling
|
||||
|
||||
@@ -56,3 +56,4 @@ All iterators, pointers, and references related to this container are invalidate
|
||||
|
||||
- Added in version 1.0.0.
|
||||
- Added support for binary types in version 3.8.0.
|
||||
- Fixed in version 3.13.0 to also clear the subtype of a binary value; before, the subtype was left unchanged.
|
||||
|
||||
@@ -58,6 +58,10 @@ Logarithmic in the size of the JSON object.
|
||||
|
||||
- This method always returns `#!cpp false` when executed on a JSON type that is not an object.
|
||||
- This method can be executed on any JSON value type.
|
||||
- Calling this function with an integer argument (for example, `#!cpp contains(0)`) does not compile: such an argument
|
||||
would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when
|
||||
constructing a `#!cpp std::string` for the object key. To check for an array element instead, use [`at`](at.md),
|
||||
[`operator[]`](operator%5B%5D.md), or compare against [`size`](size.md).
|
||||
|
||||
!!! info "Postconditions"
|
||||
|
||||
@@ -117,3 +121,5 @@ Logarithmic in the size of the JSON object.
|
||||
1. Added in version 3.11.0.
|
||||
2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0.
|
||||
3. Added in version 3.7.0.
|
||||
4. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
|
||||
causing undefined behavior at runtime.
|
||||
|
||||
@@ -40,7 +40,11 @@ Logarithmic in the size of the JSON object.
|
||||
|
||||
## Notes
|
||||
|
||||
This method always returns `0` when executed on a JSON type that is not an object.
|
||||
- This method always returns `0` when executed on a JSON type that is not an object.
|
||||
- Calling this function with an integer argument (for example, `#!cpp count(0)`) does not compile: such an argument
|
||||
would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when
|
||||
constructing a `#!cpp std::string` for the object key. To check for an array element instead, use [`at`](at.md),
|
||||
[`operator[]`](operator%5B%5D.md), or compare against [`size`](size.md).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -81,3 +85,5 @@ This method always returns `0` when executed on a JSON type that is not an objec
|
||||
|
||||
1. Added in version 3.11.0.
|
||||
2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0.
|
||||
3. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of
|
||||
causing undefined behavior at runtime.
|
||||
|
||||
@@ -44,7 +44,11 @@ Logarithmic in the size of the JSON object.
|
||||
|
||||
## Notes
|
||||
|
||||
This method always returns `end()` when executed on a JSON type that is not an object.
|
||||
- This method always returns `end()` when executed on a JSON type that is not an object.
|
||||
- Calling this function with an integer argument (for example, `#!cpp find(0)`) does not compile: such an argument
|
||||
would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when
|
||||
constructing a `#!cpp std::string` for the object key. To access an array element instead, use [`at`](at.md),
|
||||
[`operator[]`](operator%5B%5D.md), or compare against [`size`](size.md).
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -85,3 +89,5 @@ This method always returns `end()` when executed on a JSON type that is not an o
|
||||
|
||||
1. Added in version 3.11.0.
|
||||
2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
|
||||
3. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
|
||||
causing undefined behavior at runtime.
|
||||
|
||||
@@ -80,8 +80,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
|
||||
the end of the file was not reached when `strict` was set to true
|
||||
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from CBOR were
|
||||
used in the given input or if the input is not valid CBOR
|
||||
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as a map key,
|
||||
but not found
|
||||
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a map key is not a string (keys of other
|
||||
types are not supported, as JSON object keys are always strings) or a string is malformed
|
||||
|
||||
## Complexity
|
||||
|
||||
|
||||
@@ -73,8 +73,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
|
||||
the end of the file was not reached when `strict` was set to true
|
||||
- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from
|
||||
MessagePack were used in the given input or if the input is not valid MessagePack
|
||||
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as a map key,
|
||||
but not found
|
||||
- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a map key is not a string (keys of other
|
||||
types are not supported, as JSON object keys are always strings) or a string is malformed
|
||||
|
||||
## Complexity
|
||||
|
||||
|
||||
@@ -195,5 +195,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. Added in version 1.0.0.
|
||||
2. Added in version 1.0.0.
|
||||
3. Added in version 1.0.0.
|
||||
4. Added in version 1.0.0.
|
||||
4. Added in version 1.0.0. Fixed in version 3.13.0 to copy the values before inserting; before, an `ilist` that
|
||||
referred to elements of the array being inserted into could insert wrong values, because the range insert could
|
||||
move from or shift an element before it was copied.
|
||||
5. Added in version 3.0.0.
|
||||
|
||||
@@ -70,6 +70,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
1. The function can throw the following exceptions:
|
||||
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
|
||||
or null; in that case, using the `[]` operator with an index makes no sense.
|
||||
- Throws `#!cpp std::length_error` if `idx` equals the maximum value of `size_type`; the array is left unchanged.
|
||||
(This is the one index for which growing the array to hold it cannot be expressed as a `size_type` size, the same
|
||||
way an oversized [`resize`](https://en.cppreference.com/w/cpp/container/vector/resize) throws.)
|
||||
2. The function can throw the following exceptions:
|
||||
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an object
|
||||
or null; in that case, using the `[]` operator with a key makes no sense.
|
||||
@@ -263,8 +266,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
|
||||
|
||||
## Version history
|
||||
|
||||
1. Added in version 1.0.0. A missing index in the const version is guarded by a runtime assertion since version
|
||||
3.13.0.
|
||||
1. Added in version 1.0.0. Fixed in version 3.13.0 to throw `#!cpp std::length_error` instead of emptying the array and
|
||||
accessing it out of bounds when `idx` equals the maximum value of `size_type`. A missing index in the const version
|
||||
is guarded by a runtime assertion since version 3.13.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. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
|
||||
|
||||
@@ -88,7 +88,12 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
|
||||
## Exceptions
|
||||
|
||||
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
|
||||
empty input like a null `FILE*` or `char*` pointer.
|
||||
empty input like a null `FILE*` or `char*` pointer, or an `std::istream` without a stream buffer
|
||||
(`#!cpp i.rdbuf() == nullptr`, for instance `#!cpp std::istream(nullptr)`).
|
||||
- If reading from an `std::istream` reaches the end of the input and `eofbit` is part of the stream's
|
||||
[`exceptions()`](https://en.cppreference.com/w/cpp/io/basic_ios/exceptions) mask, the `std::ios_base::failure`
|
||||
thrown by the stream itself propagates instead of a `parse_error`, the same as it would for the standard library's
|
||||
own extraction operators.
|
||||
|
||||
## Complexity
|
||||
|
||||
@@ -254,6 +259,8 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
|
||||
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
|
||||
- `JSON_STRICT_NUL_HANDLING` added in version 3.13.0 to optionally reject a NUL byte in the input instead of treating
|
||||
it as end of input; planned to become the default in version 4.0.0.
|
||||
- Extended empty-input detection to also cover an `std::istream` without a stream buffer, and fixed a crash
|
||||
(`std::terminate`) when parsing from an `std::istream` with `eofbit` in its exception mask, in version 3.13.0.
|
||||
|
||||
!!! warning "Deprecation"
|
||||
|
||||
|
||||
@@ -100,3 +100,6 @@ the latter case, it is skipped completely, or replaced by `null` if it is the to
|
||||
- Added in version 1.0.0.
|
||||
- Fixed in version 3.13.0 to also remove discarded values from a parent object; before, discarding an array or a value
|
||||
stored under an object key left a discarded member behind, which made the parse result serialize to invalid JSON.
|
||||
- Fixed in version 3.13.0 so that discarding an array or object at its start event also hides its content from the
|
||||
callback, as documented above; before, the callback was still called for the content, and the key of every member of
|
||||
a discarded object was kept in memory until the parse ended.
|
||||
|
||||
@@ -6,7 +6,9 @@ void swap(reference other) noexcept (
|
||||
std::is_nothrow_move_constructible<value_t>::value &&
|
||||
std::is_nothrow_move_assignable<value_t>::value &&
|
||||
std::is_nothrow_move_constructible<json_value>::value &&
|
||||
std::is_nothrow_move_assignable<json_value>::value
|
||||
std::is_nothrow_move_assignable<json_value>::value &&
|
||||
std::is_nothrow_move_constructible<json_base_class_t>::value &&
|
||||
std::is_nothrow_move_assignable<json_base_class_t>::value
|
||||
);
|
||||
|
||||
// (2)
|
||||
@@ -14,7 +16,9 @@ friend void swap(reference left, reference right) noexcept (
|
||||
std::is_nothrow_move_constructible<value_t>::value &&
|
||||
std::is_nothrow_move_assignable<value_t>::value &&
|
||||
std::is_nothrow_move_constructible<json_value>::value &&
|
||||
std::is_nothrow_move_assignable<json_value>::value
|
||||
std::is_nothrow_move_assignable<json_value>::value &&
|
||||
std::is_nothrow_move_constructible<json_base_class_t>::value &&
|
||||
std::is_nothrow_move_assignable<json_base_class_t>::value
|
||||
);
|
||||
|
||||
// (3)
|
||||
@@ -37,11 +41,15 @@ void swap(typename binary_t::container_type& other);
|
||||
individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. If macro
|
||||
[`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is defined to `#!cpp 1`, the
|
||||
[`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) diagnostic positions are exchanged along with the value.
|
||||
The [`json_base_class_t`](json_base_class_t.md) subobject is exchanged along with the value as well, the same way it
|
||||
is copied or moved by the copy/move constructors and assignment operators.
|
||||
2. Exchanges the contents of the JSON value from `left` with those of `right`. Does not invoke any move, copy, or swap
|
||||
operations on individual elements. All iterators and references remain valid. The past-the-end iterator is
|
||||
invalidated. Implemented as a friend function callable via ADL. If macro
|
||||
[`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is defined to `#!cpp 1`, the
|
||||
[`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) diagnostic positions are exchanged along with the value.
|
||||
The [`json_base_class_t`](json_base_class_t.md) subobject is exchanged along with the value as well, the same way it
|
||||
is copied or moved by the copy/move constructors and assignment operators.
|
||||
3. Exchanges the contents of a JSON array with those of `other`. Does not invoke any move, copy, or swap operations on
|
||||
individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
|
||||
4. Exchanges the contents of a JSON object with those of `other`. Does not invoke any move, copy, or swap operations on
|
||||
@@ -164,8 +172,8 @@ Constant.
|
||||
|
||||
## Version history
|
||||
|
||||
1. Since version 1.0.0.
|
||||
2. Since version 1.0.0.
|
||||
1. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
|
||||
2. Since version 1.0.0. Exchanges the `json_base_class_t` subobject along with the value since version 3.13.0.
|
||||
3. Since version 1.0.0.
|
||||
4. Since version 1.0.0.
|
||||
5. Since version 1.0.0.
|
||||
|
||||
@@ -43,6 +43,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
|
||||
- Throws [`out_of_range.412`](../../home/exceptions.md#jsonexceptionout_of_range412) if the length of a document, array,
|
||||
string, or binary value exceeds the range of the 32-bit BSON length field; example:
|
||||
`"BSON length 2147483661 exceeds maximum of 2147483647"`
|
||||
- Throws [`out_of_range.415`](../../home/exceptions.md#jsonexceptionout_of_range415) if the subtype of a binary value
|
||||
exceeds 255, the maximum of the BSON binary subtype; example:
|
||||
`"subtype 70000 is too large for the BSON binary subtype (max 255)"`
|
||||
|
||||
## Complexity
|
||||
|
||||
@@ -78,3 +81,4 @@ pass before anything is written.
|
||||
|
||||
- Added in version 3.4.0.
|
||||
- Linear in the size of `j`, and no longer limited by the call stack for deeply nested values, since version 3.13.0.
|
||||
- `out_of_range.415` is now detected before anything is written, like the other exceptions above, since version 3.13.0.
|
||||
|
||||
@@ -76,3 +76,6 @@ Linear in the size of the JSON value `j`.
|
||||
|
||||
- Added in version 2.0.9.
|
||||
- Throws `out_of_range.412` and `out_of_range.415` since version 3.13.0.
|
||||
- Fixed in version 3.13.0 to serialize `number_integer_t`/`number_unsigned_t` pairs of different width correctly;
|
||||
before, integers could be serialized with the wrong value if `number_integer_t` was narrower than
|
||||
`number_unsigned_t`.
|
||||
|
||||
@@ -52,6 +52,14 @@ This is equivalent to Python's `dict.get(key, default)`.
|
||||
- Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
|
||||
`key`/`ptr` key. This function is furthermore also applicable to const objects.
|
||||
|
||||
!!! note "Integer keys"
|
||||
|
||||
Calling this function with an integer `key` argument (for example, `#!cpp value(0, 1)`) does not compile in
|
||||
C++11, where `object_comparator_t` is not transparent: such an argument would otherwise implicitly convert to a
|
||||
null `#!cpp const char*` and, from there, cause undefined behavior when constructing a `#!cpp std::string` for the
|
||||
object key. To access an array element with a default value, use [`at`](at.md) together with a `#!cpp try`/`#!cpp
|
||||
catch` block, or compare against [`size`](size.md) instead.
|
||||
|
||||
## Template parameters
|
||||
|
||||
`KeyType`
|
||||
@@ -184,7 +192,9 @@ 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.
|
||||
1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version
|
||||
3.11.0. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time
|
||||
instead of causing undefined behavior at runtime.
|
||||
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. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving
|
||||
`ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or
|
||||
|
||||
@@ -28,6 +28,7 @@ header. See also the [macro overview page](../../features/macros.md).
|
||||
- [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support
|
||||
- [**JSON_HAS_STD_FORMAT**](json_has_std_format.md) - control `std::format`/`std::formatter` support
|
||||
- [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
|
||||
- [**JSON_NO_AUTOMATIC_UDLS**](json_no_automatic_udls.md) - do not include the user-defined string literals (UDLs) automatically
|
||||
- [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
|
||||
- [**JSON_NO_THREAD_LOCAL**](json_no_thread_local.md) - switch off the use of `thread_local` storage
|
||||
- [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
# JSON_NO_AUTOMATIC_UDLS
|
||||
|
||||
```cpp
|
||||
#define JSON_NO_AUTOMATIC_UDLS
|
||||
```
|
||||
|
||||
When defined, `<nlohmann/json.hpp>` does not include `<nlohmann/json_literals.hpp>`, so the user-defined string
|
||||
literals [`operator""_json`](../operator_literal_json.md) and
|
||||
[`operator""_json_pointer`](../operator_literal_json_pointer.md) are not declared. Include
|
||||
`<nlohmann/json_literals.hpp>` in the files that use them.
|
||||
|
||||
The literals are ordinary inline functions whose bodies call the parser, so every translation unit that includes them
|
||||
instantiates the parser — even if it never parses anything itself. Defining `JSON_NO_AUTOMATIC_UDLS` for a whole project
|
||||
avoids this cost in translation units that do not parse (e.g., ones that only define types and conversions or pass
|
||||
`json` values around) and reduces their compile time.
|
||||
|
||||
## Default definition
|
||||
|
||||
By default, `#!cpp JSON_NO_AUTOMATIC_UDLS` is not defined, and `<nlohmann/json.hpp>` includes
|
||||
`<nlohmann/json_literals.hpp>`.
|
||||
|
||||
```cpp
|
||||
#undef JSON_NO_AUTOMATIC_UDLS
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
!!! info "Header `<nlohmann/json_literals.hpp>`"
|
||||
|
||||
The header includes `<nlohmann/json.hpp>` itself and places the literals according to
|
||||
[`JSON_USE_GLOBAL_UDLS`](json_use_global_udls.md). It is part of the multi-header sources (`include/nlohmann`)
|
||||
and of the single-header sources (`single_include/nlohmann`), next to `json.hpp`.
|
||||
|
||||
!!! info "C++ modules"
|
||||
|
||||
The `nlohmann.json` [module](../../features/modules.md) always exports the literals, regardless of this macro.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The code below includes the library without the literals and adds them in a single translation unit.
|
||||
|
||||
```cpp
|
||||
// compiled with -DJSON_NO_AUTOMATIC_UDLS for the whole project
|
||||
#include <nlohmann/json.hpp>
|
||||
|
||||
// this file uses the literals, so it includes them explicitly
|
||||
#include <nlohmann/json_literals.hpp>
|
||||
|
||||
int main()
|
||||
{
|
||||
auto j = R"({"foo": 42})"_json;
|
||||
return j.at("/foo"_json_pointer) == 42 ? 0 : 1;
|
||||
}
|
||||
```
|
||||
|
||||
Without the include of `<nlohmann/json_literals.hpp>`, the code would fail to compile.
|
||||
|
||||
## See also
|
||||
|
||||
- [`operator""_json`](../operator_literal_json.md)
|
||||
- [`operator""_json_pointer`](../operator_literal_json_pointer.md)
|
||||
- [`JSON_USE_GLOBAL_UDLS`](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
@@ -16,7 +16,8 @@ byte is still not rejected:
|
||||
[`from_msgpack`](../basic_json/from_msgpack.md), [`from_ubjson`](../basic_json/from_ubjson.md)) are never affected: there, `0x00` is ordinary data.
|
||||
- A bare `const char*` pointer has no length of its own, so its length is still determined with `strlen()`. The first
|
||||
NUL byte therefore still marks the end of the input, and nothing after it is read.
|
||||
- One trailing `'\0'` at the end of a `char` array (e.g., a string literal) is trimmed; see the warning below.
|
||||
- One trailing `'\0'` at the end of a `char`, `wchar_t`, `char16_t`, `char32_t`, or (C++20) `char8_t` array (e.g., a
|
||||
string literal) is trimmed; see the warning below.
|
||||
|
||||
## Default definition
|
||||
|
||||
@@ -57,13 +58,15 @@ The default value is `0` (disabled — existing behavior is preserved).
|
||||
This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
|
||||
effect.
|
||||
|
||||
Enabling it also changes how a `char` array (including a string literal, e.g. `json::parse("123")`) is read: such
|
||||
an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With this macro
|
||||
enabled, that one trailing byte is trimmed if present so that parsing a string literal keeps working; every other
|
||||
byte in the array - including any `'\0'` that is not the very last element - is read as real data and rejected
|
||||
like any other unexpected byte. Arrays of any other element type (`unsigned char`, `std::uint8_t`, ...), as used
|
||||
for CBOR or MessagePack, are never affected by this trimming; their full extent - including a genuine trailing
|
||||
`0x00` - is always preserved, in both states of this macro.
|
||||
Enabling it also changes how an array of a text-literal element type (`char`, `wchar_t`, `char16_t`, `char32_t`,
|
||||
or, since C++20, `char8_t` - including a string literal, e.g. `json::parse("123")` or `json::parse(L"123")`) is
|
||||
read: such an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With
|
||||
this macro enabled, that one trailing element is trimmed if present so that parsing a string literal keeps
|
||||
working, for any of these character types; every other element in the array - including any `'\0'` that is not
|
||||
the very last element - is read as real data and rejected like any other unexpected byte. Arrays of any other
|
||||
element type (`unsigned char`, `std::uint8_t`, ...), as used for CBOR or MessagePack, are never affected by this
|
||||
trimming; their full extent - including a genuine trailing `0x00` - is always preserved, in both states of this
|
||||
macro.
|
||||
|
||||
!!! note "ABI compatibility"
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ The default value is `1`.
|
||||
#define JSON_USE_GLOBAL_UDLS 1
|
||||
```
|
||||
|
||||
When the macro is not defined, the library will define it to its default value.
|
||||
When the macro is not defined, the library behaves as if it were defined to its default value.
|
||||
|
||||
## Notes
|
||||
|
||||
@@ -32,6 +32,11 @@ When the macro is not defined, the library will define it to its default value.
|
||||
[`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`ON` by default) which defines
|
||||
`JSON_USE_GLOBAL_UDLS` accordingly.
|
||||
|
||||
!!! info "Leaving out the literals"
|
||||
|
||||
If [`JSON_NO_AUTOMATIC_UDLS`](json_no_automatic_udls.md) is defined, the literals are only declared where
|
||||
`<nlohmann/json_literals.hpp>` is included; this macro then applies to that header.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example "Example 1: Default behavior"
|
||||
@@ -92,6 +97,7 @@ When the macro is not defined, the library will define it to its default value.
|
||||
|
||||
- [`operator""_json`](../operator_literal_json.md)
|
||||
- [`operator""_json_pointer`](../operator_literal_json_pointer.md)
|
||||
- [`JSON_NO_AUTOMATIC_UDLS`](json_no_automatic_udls.md) - do not include the user-defined string literals automatically
|
||||
- [:simple-cmake: JSON_GlobalUDLs](../../integration/cmake.md#json_globaludls) - CMake option to control the macro
|
||||
|
||||
## Version history
|
||||
|
||||
@@ -18,9 +18,18 @@ Deserializes an input stream to a JSON value.
|
||||
|
||||
the stream `i`
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: if an exception is thrown, there are no changes in `j`.
|
||||
|
||||
## Exceptions
|
||||
|
||||
- Throws [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
|
||||
- Throws [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or if
|
||||
`i` has no stream buffer (`#!cpp i.rdbuf() == nullptr`, for instance `#!cpp std::istream(nullptr)`).
|
||||
- If reading from `i` reaches the end of the input and `eofbit` is part of `i`'s
|
||||
[`exceptions()`](https://en.cppreference.com/w/cpp/io/basic_ios/exceptions) mask, the `std::ios_base::failure`
|
||||
thrown by `i` itself propagates instead of a `parse_error`, the same as it would for the standard library's own
|
||||
extraction operators.
|
||||
|
||||
## Complexity
|
||||
|
||||
@@ -118,3 +127,7 @@ being read.
|
||||
it as end of input; planned to become the default in version 4.0.0.
|
||||
- `JSON_PRECISE_STREAM_POSITION` added in version 3.13.0 to optionally leave the character that terminates a number in
|
||||
the stream; planned to become the default in version 4.0.0.
|
||||
- Fixed a null pointer dereference for an `std::istream` without a stream buffer (now throws `parse_error.101`), and a
|
||||
crash (`std::terminate`) when `i` has `eofbit` in its exception mask, in version 3.13.0.
|
||||
- Changed to the strong exception safety guarantee in version 3.13.0: `j` is no longer left with a partially parsed
|
||||
value if parsing throws.
|
||||
|
||||
@@ -18,7 +18,9 @@ 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.
|
||||
[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. The operator is declared in header
|
||||
`<nlohmann/json_literals.hpp>`, which `<nlohmann/json.hpp>` includes unless
|
||||
[`JSON_NO_AUTOMATIC_UDLS`](macros/json_no_automatic_udls.md) is defined.
|
||||
|
||||
## Parameters
|
||||
|
||||
@@ -59,6 +61,8 @@ Linear.
|
||||
## See also
|
||||
|
||||
- [Creating JSON values](../features/creating_values.md) - the article on creating JSON values
|
||||
- [JSON_NO_AUTOMATIC_UDLS](macros/json_no_automatic_udls.md) - do not include the user-defined string literals
|
||||
automatically
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -17,7 +17,9 @@ 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.
|
||||
[`JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. The operator is declared in header
|
||||
`<nlohmann/json_literals.hpp>`, which `<nlohmann/json.hpp>` includes unless
|
||||
[`JSON_NO_AUTOMATIC_UDLS`](macros/json_no_automatic_udls.md) is defined.
|
||||
|
||||
## Parameters
|
||||
|
||||
@@ -58,6 +60,8 @@ Linear.
|
||||
## See also
|
||||
|
||||
- [json_pointer](json_pointer/index.md) - type to represent JSON Pointers
|
||||
- [JSON_NO_AUTOMATIC_UDLS](macros/json_no_automatic_udls.md) - do not include the user-defined string literals
|
||||
automatically
|
||||
|
||||
## Version history
|
||||
|
||||
|
||||
@@ -28,6 +28,11 @@ A minimal map-like container that preserves insertion order for use within [`nlo
|
||||
The type uses a `std::vector` to store object elements. Therefore, adding elements can yield a reallocation in which
|
||||
case all iterators (including the `end()` iterator) and all references to the elements are invalidated.
|
||||
|
||||
When the storage grows, the keys are copied and the mapped values are moved to the new storage. A plain `std::vector`
|
||||
would copy the whole elements instead, because their `#!cpp const` keys make them not nothrow move constructible; for
|
||||
[`ordered_json`](ordered_json.md), this would be a deep copy of every nested value. The values are only copied if
|
||||
`T` is not default constructible or not nothrow move assignable.
|
||||
|
||||
## Member types
|
||||
|
||||
- **key_type** - key type (`Key`)
|
||||
@@ -56,6 +61,11 @@ std::equal_to<> // since C++14
|
||||
- **find**
|
||||
- **insert**
|
||||
|
||||
## Exception safety
|
||||
|
||||
**emplace**, **operator\[\]**, and **insert(value)** have the strong exception guarantee: if an exception is thrown (for
|
||||
instance, because copying a key or allocating memory fails), the contents of the container are unchanged.
|
||||
|
||||
## Complexity
|
||||
|
||||
Because the elements are stored in a `std::vector` in insertion order, there is no index to look a key up by. Every
|
||||
@@ -122,3 +132,4 @@ This differs from `#!cpp std::map`, where the same operations are O(log n).
|
||||
|
||||
- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).
|
||||
- Added **key_compare** member in version 3.11.0.
|
||||
- Changed in version 3.13.0: growing the storage moves the mapped values instead of copying them.
|
||||
|
||||
@@ -174,7 +174,20 @@ 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 text strings (major type 3) are rejected with a
|
||||
[`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113) exception (or, with `allow_exceptions` set
|
||||
to `false`, a discarded value) naming the type of the key that was found, for instance:
|
||||
|
||||
```
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR object key: only string keys are supported, but found an unsigned integer; last byte: 0x01
|
||||
```
|
||||
|
||||
This applies to the [SAX interface](../parsing/sax_interface.md) as well, as the key is read before it is passed
|
||||
on. This is a deliberate restriction of the library's JSON value model, not an oversight: formats built on CBOR
|
||||
maps with integer keys, such as COSE ([RFC 9052](https://www.rfc-editor.org/rfc/rfc9052.html)) or CWT
|
||||
([RFC 8392](https://www.rfc-editor.org/rfc/rfc8392.html)), cannot be read with this library and need a
|
||||
general-purpose CBOR library instead.
|
||||
|
||||
!!! warning "UTF-8 validation of text strings"
|
||||
|
||||
|
||||
@@ -138,6 +138,21 @@ The library maps MessagePack types to JSON value types as follows:
|
||||
|
||||
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
|
||||
|
||||
!!! warning "Object keys"
|
||||
|
||||
MessagePack allows map keys of any type, whereas JSON only allows strings as keys in object values. Like the
|
||||
JSON-compatible [profile](https://github.com/msgpack/msgpack/blob/master/spec.md#profile) sketched in the
|
||||
MessagePack specification, this library restricts map keys to `str` values. Maps with keys of any other type are
|
||||
rejected with a [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113) exception (or, with
|
||||
`allow_exceptions` set to `false`, a discarded value) naming the type of the key that was found, for instance:
|
||||
|
||||
```
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing MessagePack object key: only string keys are supported, but found nil; last byte: 0xC0
|
||||
```
|
||||
|
||||
This applies to the [SAX interface](../parsing/sax_interface.md) as well, as the key is read before it is passed
|
||||
on. Such input needs a general-purpose MessagePack library instead.
|
||||
|
||||
!!! warning "UTF-8 validation of string values"
|
||||
|
||||
The MessagePack specification requires `str` values (`fixstr`, `str 8`, `str 16`, `str 32`) to be valid UTF-8.
|
||||
|
||||
@@ -83,6 +83,15 @@ When defined, default parse and serialize functions for enums are excluded and h
|
||||
|
||||
See [full documentation of `JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).
|
||||
|
||||
## `JSON_NO_AUTOMATIC_UDLS`
|
||||
|
||||
When defined, `<nlohmann/json.hpp>` does not include `<nlohmann/json_literals.hpp>` with the user-defined string literals
|
||||
`operator""_json` and `operator""_json_pointer`. This reduces the compile time of translation units that do not use
|
||||
them, because the literals instantiate the parser in every translation unit that includes them. Include
|
||||
`<nlohmann/json_literals.hpp>` where the literals are needed.
|
||||
|
||||
See [full documentation of `JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md).
|
||||
|
||||
## `JSON_NO_IO`
|
||||
|
||||
When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions
|
||||
|
||||
@@ -40,6 +40,9 @@ Only the following symbols are exported from `nlohmann.json`:
|
||||
- `nlohmann::literals::json_literals::operator""_json`
|
||||
- `nlohmann::literals::json_literals::operator""_json_pointer`
|
||||
|
||||
The module always exports the two user-defined string literals, even if
|
||||
[`JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md) is defined when building it.
|
||||
|
||||
Additionally, the following `nlohmann::detail` symbols are exported, solely to work around an MSVC compilation issue
|
||||
([#3970](https://github.com/nlohmann/json/issues/3970)). They are implementation details, not part of the public API,
|
||||
and should not be used directly:
|
||||
|
||||
@@ -389,6 +389,7 @@ using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
|
||||
| Functionality | Additional requirement |
|
||||
|-----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [`diff`](../../api/basic_json/diff.md), [`items`](../../api/basic_json/items.md), [`std::hash`](../../api/basic_json/std_hash.md) | conversion of a `#!cpp std::size_t` to `StringType`: either assignability from the result of `#!cpp std::to_string`, or an ADL overload `#!cpp void int_to_string(StringType&, std::size_t)` |
|
||||
| [`operator/(std::size_t)`](../../api/json_pointer/operator_slash.md) | the same conversion of a `#!cpp std::size_t` to `StringType` as `diff`, `items`, and `std::hash` above |
|
||||
| [`std::hash<basic_json>`](../../api/basic_json/std_hash.md) | additionally a specialization of `#!cpp std::hash<StringType>` |
|
||||
| [`to_bson`](../../api/basic_json/to_bson.md) | `find(value_type)` and `npos` |
|
||||
| [`parse`](../../api/basic_json/parse.md) from a `string_t` | the input adapters must accept it; otherwise pass a character range |
|
||||
|
||||
@@ -343,13 +343,20 @@ A string could not be read from a [binary format](../features/binary_formats/ind
|
||||
string was read where one was required (for instance as a map key), the string's length specification is invalid, or
|
||||
the string's bytes are not valid UTF-8.
|
||||
|
||||
CBOR and MessagePack allow map keys of any type, but JSON object keys are always strings. Maps with keys of any other
|
||||
type (for instance integers or `null`) are therefore not supported; see the notes on
|
||||
[CBOR](../features/binary_formats/cbor.md) and [MessagePack](../features/binary_formats/messagepack.md).
|
||||
|
||||
!!! failure "Example messages"
|
||||
|
||||
```
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR string: expected length specification (0x60-0x7B) or indefinite string type (0x7F); last byte: 0xFF
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR object key: only string keys are supported, but found an unsigned integer; last byte: 0x01
|
||||
```
|
||||
```
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing MessagePack string: expected length specification (0xA0-0xBF, 0xD9-0xDB); last byte: 0xFF
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing MessagePack object key: only string keys are supported, but found nil; last byte: 0xC0
|
||||
```
|
||||
```
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR string: expected length specification (0x60-0x7B) or indefinite string type (0x7F); last byte: 0x7C
|
||||
```
|
||||
```
|
||||
[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing UBJSON char: byte after 'C' must be in range 0x00..0x7F; last byte: 0x82
|
||||
|
||||
@@ -19,3 +19,5 @@ The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed und
|
||||
The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above). Copyright © 2009 [Florian Loitsch](https://florian.loitsch.com/)
|
||||
|
||||
The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).
|
||||
|
||||
The class contains an adapted version of the Eisel-Lemire algorithm and its table of powers of five from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright © 2021 The fast_float authors
|
||||
|
||||
@@ -15,4 +15,7 @@ Clang).
|
||||
|
||||
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.
|
||||
for forward declarations, and file
|
||||
[`single_include/nlohmann/json_literals.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_literals.hpp)
|
||||
for the user-defined string literals if you define
|
||||
[`JSON_NO_AUTOMATIC_UDLS`](../api/macros/json_no_automatic_udls.md).
|
||||
|
||||
@@ -293,6 +293,7 @@ nav:
|
||||
- 'JSON_HAS_STATIC_RTTI': api/macros/json_has_static_rtti.md
|
||||
- 'JSON_HAS_STD_FORMAT': api/macros/json_has_std_format.md
|
||||
- 'JSON_HAS_THREE_WAY_COMPARISON': api/macros/json_has_three_way_comparison.md
|
||||
- 'JSON_NO_AUTOMATIC_UDLS': api/macros/json_no_automatic_udls.md
|
||||
- 'JSON_NOEXCEPTION': api/macros/json_noexception.md
|
||||
- 'JSON_NO_IO': api/macros/json_no_io.md
|
||||
- 'JSON_NO_THREAD_LOCAL': api/macros/json_no_thread_local.md
|
||||
|
||||
Reference in New Issue
Block a user