* Bound the total number of valueless UBJSON elements per input An optimized UBJSON array of type Z, T or F has no payload, so its declared count is not bounded by the input. The limit of 1048576 applied to each array on its own, so 9 bytes (`[$Z#l` and a count) produced 1048576 values and every further 9 bytes another 1048576: 362 bytes allocated 661 MB in a DOM, and a SAX handler received 1M events per 9 bytes. The reader now adds the counts of all such arrays of one input and rejects the input with out_of_range.408 when the sum exceeds 1048576 plus 4 for every byte read so far. The base is the per-array limit, so an array that was accepted on its own before is still accepted at the start of an input. These arrays add about 80 bytes of memory per input byte (measured 77; one `Z` per byte needs 32), plus the base; the memory of a document as a whole is not bounded by this. The check runs once per valueless array, before its start event, with plain size_t arithmetic that cannot overflow for a 32-bit size_t. Containers with a payload type and objects (every member needs a key) are bounded by the input already and are unchanged. BJData rejects these types. to_ubjson counts the elements of the typed arrays it writes in one call and writes an array in the unoptimized form (`[#n Z Z ...`) once it would bring the total above 1048576, which a reader accepts at any input size. The check is made only for a typed array of a valueless type, so BJData and other arrays do not pay for it. Everything to_ubjson writes in version 3.13.0 can therefore be read back. Two consequences: - to_ubjson output changes for values with more than 1048576 elements in arrays of type Z, T or F: such an array is written at one byte per element, e.g. 270000 rows of 100 nulls take 26.8 MB instead of 1.35 MB. - Output of version 3.12.0 and earlier (typed arrays without such a total) is rejected by from_ubjson when the arrays hold more than 1048576 elements plus 4 per byte of input. 3.12.0 writes a row of up to 255 nulls in 5 bytes (6 above 255), so a table is rejected from 1075 rows of 1000 nulls or 209723 rows of 25 (accepted: 1000 rows of 1000, 209000 rows of 25); rows of 20 or fewer are never rejected. Measured on the test data: no file of json_test_data (converted with to_ubjson in all three modes, 846 round trips) holds an array of this kind with more than 0.17 values per byte. All of them are read back. Reproducer (K arrays of 1048576 nulls), Apple clang -O2: K=40 (362 bytes): before 41943040 values, 664 MB; after rejected, 33 MB K=2 (20 bytes): before 2097152 values, 53 MB; after rejected, 33 MB The new tests count events with a SAX handler where they can: building and comparing million-element values made the first version take 176 s under Valgrind, the current one about 22 s. Behaviour change: an input that holds more than 1048576 elements in arrays of type Z, T or F at more than 4 per byte is now rejected. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Report an empty array for UBJSON `[$N#<n>` instead of n elements A no-op (N) is not a value, so an optimized array of type N holds no element whatever count it declares. The reader skipped the elements but still passed the declared count to the SAX parser: a handler was told start_array(n) and no element followed, and the DOM parser reserved min(n, 16384) values (256 KB) for an array that stays empty. Nine bytes (`[$N#l 0x7FFFFFFF`) therefore committed 256 KB: 2000 of them in one input, 18 KB, committed 512 MB of heap (capacity 163,840,000 values for the 10000 arrays of the original probe: 2.6 GB for 70 KB of input). Untouched pages keep the resident size small, but the commit charge and a 32-bit address space are consumed. The reader now announces 0 elements for an optimized array of type N. The loop that skips the elements is unchanged (it never ran). A count that does not fit into std::size_t is still rejected by the count reader; a count that is too large for the array type of the DOM (before: out_of_range.408 "excessive array size" from the DOM handler) is accepted now, because the array is empty. Behaviour change: sax_parse reports start_array(0) for `[$N#n` (before: n); from_ubjson no longer throws out_of_range.408 for an N-typed array whose count exceeds the maximum size of the array type. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Bound what the DOM parsers reserve for arrays that announce a size Cause: #5476 made the DOM parsers reserve storage (up to 16384 elements) for a counted array of CBOR, MessagePack, UBJSON and BJData when it opens, before any input backs the count. The arrays that are open at the same time keep their storage until the parse ends, so N nested headers that announce 16384 elements and are never completed hold N * 16384 * sizeof(json): 100,000 nested CBOR headers `99 40 00` (300,000 bytes) peaked at 1.65 GiB, 3.12.0 at 12 MiB; the same for MessagePack `DC 40 00`, UBJSON `[#I 16384` and BJData. Fix: json_sax_dom_error_state, the base of the three DOM parsers, keeps a credit of elements that may still be reserved: 65,536 at the start plus 2 for every byte the reader has read. An array that announces no more than the credit left is reserved as before (one comparison and one subtraction per counted array); a larger one is reserved what is left and grows as its elements arrive. binary_reader tells a DOM parser (a handler whose pointer converts to json_sax_dom_error_state*; a handler that derives from one privately or protectedly, or any other SAX handler, is not told anything and reserves as in the base of this change) where to find its count of characters read for the duration of sax_parse(). An RAII guard puts back the previous binding on every exit, also by exception, so the parser never keeps a pointer to a reader that is gone (unbound, only the per-array cap of 16384 applies); the public SAX interface is unchanged, and start_array() still reports the announced number. A bound per array by the remaining input would not help, since the same bytes would back every open level; the bound has to be over all arrays. The elements of an array take at least one byte of input each, so the credit is more than honest input needs: none of the 19 inputs measured (canada, citm_catalog, twitter, mesh, update-center, random, numbers, animation, ik_rig, instruments, geo_response, jeopardy and 7 synthetic ones, each as CBOR, MessagePack, UBJSON and BJData, with and without size/type optimization) was given less than it announced. A value that nests five or more arrays of 16384 elements, each with an array as its first element, is the exception: the later ones grow as before. Measurements (clang -O2, macOS arm64, peak memory footprint of `/usr/bin/time -l`, reproducer: n nested headers): n = 20,000 n = 100,000 develop fix 3.12.0 develop fix 3.12.0 CBOR 338.7 5.9 8.2 1687.7 23.3 11.8 MiB MessagePack 338.9 6.0 7.3 1687.9 23.8 11.9 MiB UBJSON 339.0 7.6 8.0 1687.9 30.1 11.6 MiB BJData 339.0 7.3 7.9 1688.0 30.8 11.6 MiB That is at most (65,536 + 2 per input byte) values: 1 MiB plus 32 bytes per input byte with 16-byte values (a value is 24 bytes with JSON_DIAGNOSTICS and up to 40 with JSON_DIAGNOSTIC_POSITIONS), as documented in untrusted_input.md. Lower fixed caps do not get there: a cap of 64 elements still peaks at 113 MiB (n = 100,000) and costs 4.7 % on arrays of 300 elements (mat300.cbor) and 5.0 % on arrays of 10,000 (arrays_of_big.cbor). Reader instructions retired (min of 7, 108 rows: 18 inputs in the 6 forms CBOR, MessagePack, UBJSON and BJData plain and optimized; jeopardy, 46 MB, is within 0.1 %), compared with the base of this change: -0.19 % to +0.37 % in the formats that announce sizes (canada.cbor 81.9 M -> 82.1 M, many_small.cbor 333.5 M -> 334.2 M); the benefit of #5476 is kept (without any reserve canada.cbor takes 116.8 M, +42.6 %, many_small.cbor +71.5 %, mat300.cbor +81.6 %). Rows of plain UBJSON and BJData, whose arrays announce no size, move by -2.7 % to +2.6 % without any code of theirs changing: the base alternates between two instruction counts per process (452 M and 463 M for many_pairs.ubjson, equal in cycles), and a struct with three unused members added to the same class reproduces the 474 M mode. Tests (CBOR, MessagePack, UBJSON, BJData): 200 nested headers that announce 16384 elements peak at 52,433,600 bytes of DOM allocations on the base and below 128 Ki values with the fix (scaled by sizeof(value), so that it holds with the diagnostic macros) (counting allocator, no process memory measured); an array that completes is still reserved in one allocation; CBOR also checks that a DOM parser is not bound to a finished parse (ASan: stack-use-after-scope without the guard), that wrappers derived publicly (also with a parse inside the parse), privately and protectedly compile and are bound or not as described, that an array that got less than it announced decodes and that a SAX handler is told the announced size. The new tests take 4.6 s under Valgrind at -O0 (gcc:12, all four files). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Clarify the reservation note for announced array counts Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Report an empty array for UBJSON [$N#<n>] instead of n elements (#6079) * Report an empty array for UBJSON `[$N#<n>` instead of n elements A no-op (N) is not a value, so an optimized array of type N holds no element whatever count it declares. The reader skipped the elements but still passed the declared count to the SAX parser: a handler was told start_array(n) and no element followed, and the DOM parser reserved min(n, 16384) values (256 KB) for an array that stays empty. Nine bytes (`[$N#l 0x7FFFFFFF`) therefore committed 256 KB: 2000 of them in one input, 18 KB, committed 512 MB of heap (capacity 163,840,000 values for the 10000 arrays of the original probe: 2.6 GB for 70 KB of input). Untouched pages keep the resident size small, but the commit charge and a 32-bit address space are consumed. The reader now announces 0 elements for an optimized array of type N. The loop that skips the elements is unchanged (it never ran). A count that does not fit into std::size_t is still rejected by the count reader; a count that is too large for the array type of the DOM (before: out_of_range.408 "excessive array size" from the DOM handler) is accepted now, because the array is empty. Behaviour change: sax_parse reports start_array(0) for `[$N#n` (before: n); from_ubjson no longer throws out_of_range.408 for an N-typed array whose count exceeds the maximum size of the array type. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Clarify the reservation note for announced array counts Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Add JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE to set the UBJSON whole-input budget (#6083) * Add JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE to set the UBJSON whole-input budget The whole-input budget for the elements of optimized UBJSON arrays of type Z, T and F (1048576 plus 4 per byte read) rejects files written by 3.12.0 that have long arrays of these types, such as 1100 rows of 1000 nulls with a `$Z` annotation, and there was no way to read them. The per-byte rate is now the macro JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE. Semantics: - default 4, so the default build is unchanged (the generated code of from_ubjson is identical at -O2 up to source line numbers); - the value must be a positive integer: 0, negative, non-integral, bool, character and wider-than-uintmax_t values fail to compile with a static_assert that names the macro; - a value that does not fit into std::size_t is the largest size_t, so one spelling works for 32- and 64-bit targets; - the limit base + rate * bytes_read saturates at the largest size_t instead of wrapping around, for any rate and input size; a rate of 131072 (2^20 / 8) or more cannot be exceeded by any input (the shortest header of an array of more than 32767 elements is 8 bytes), which switches the whole-input budget off; - the limit of one array (1048576) and the base (1048576) stay fixed constants, so the writer fallback still follows the base only and a reader with any rate reads everything the writer produces; - the macro is not part of the ABI tag and must have the same value in every translation unit; it is documented that way. The memory the arrays can take in a DOM is about 20 bytes per rate and byte of input (measured, macOS, containers of 9 * rate elements: 25 bytes per input byte at rate 1, 81 at 4, 312 at 16, 1226 at 64, 5493 at 256) plus about 33 MB for the base. A 3.12.0 row of N values has a header of b bytes (5 up to 255, 6 up to 32767, 8 above), so a table is read completely if N <= rate * b, and otherwise up to (1048576 + h * rate, h = outer header: 6, 7 or 9 bytes) / (N - rate * b) rows; 1100 rows of 1000 nulls need a rate of 8. The new page of the macro documents the formulas, the measurements, and two examples that are run by the documentation checks. The tests of the budget move to tests/src/unit-ubjson_valueless.cpp, which derives every boundary from the macro and is built with the rates 1, 1000000 and 0xFFFFFFFFFFFFFFFF in addition to the default (the last two check that nothing is refused and that the limit does not wrap around); they fail with the unchanged header for rate 1, 1000000 and the maximum. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Refuse char8_t for JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE and clarify its documentation Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Use fseek instead of rewind in the UBJSON FILE* test clang-tidy (bugprone-unsafe-functions) rejects rewind() because it has no error detection. Check the result of fseek() instead. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Charge an announced array only what is reserved for it An array that announced more than reserve_cap() elements but no more than the credit left was charged the announced count, while reserve_array() reserved at most reserve_cap() of them. An outer array of 20000 elements therefore left a third nested array of 16384 with 12796 instead of the full reservation. reserve_count() now caps the count first and charges that, and the DOM parsers reserve it through reserve_array_capped(), which does not cap again, so the fast path costs the same as before (instructions retired within +-0.06 % on canada, citm_catalog and twitter in CBOR, MessagePack and UBJSON). Also re-wrap the comment of valueless_elements_base. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
359 lines
19 KiB
Markdown
359 lines
19 KiB
Markdown
# Supported Macros
|
|
|
|
Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header.
|
|
See also the [API documentation for macros](../api/macros/index.md) for examples and more information.
|
|
|
|
## `JSON_ASSERT(x)`
|
|
|
|
This macro controls which code is executed for [runtime assertions](assertions.md) of the library.
|
|
|
|
See [full documentation of `JSON_ASSERT(x)`](../api/macros/json_assert.md).
|
|
|
|
## `JSON_BRACE_INIT_COPY_SEMANTICS`
|
|
|
|
When defined to `1`, single-element brace initialization of a `basic_json` value (e.g., `#!cpp json j{value};`) is
|
|
treated as a copy/move of the element rather than wrapping it in a single-element array. The default value is `0`, which
|
|
preserves the existing behavior.
|
|
|
|
See [full documentation of `JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md).
|
|
|
|
## `JSON_CATCH_USER(exception)`
|
|
|
|
This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library.
|
|
|
|
See [full documentation of `JSON_CATCH_USER(exception)`](../api/macros/json_throw_user.md).
|
|
|
|
## `JSON_DELETE_DEPRECATED_FUNCTIONS`
|
|
|
|
When defined to `1`, all deprecated functions are declared as deleted instead of only being marked as deprecated, so
|
|
code that still calls them no longer compiles. This way, you can find all calls that need to be replaced before version
|
|
4.0.0 removes these functions.
|
|
|
|
The macro can also be set with the CMake option
|
|
[`JSON_DeleteDeprecatedFunctions`](../integration/cmake.md#json_deletedeprecatedfunctions) (`OFF` by default).
|
|
|
|
See [full documentation of `JSON_DELETE_DEPRECATED_FUNCTIONS`](../api/macros/json_delete_deprecated_functions.md).
|
|
|
|
## `JSON_DIAGNOSTICS`
|
|
|
|
This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable
|
|
(default).
|
|
|
|
When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the
|
|
exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. 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`](../integration/cmake.md#json_diagnostics) (`OFF` by default) which sets `JSON_DIAGNOSTICS`
|
|
accordingly.
|
|
|
|
See [full documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md).
|
|
|
|
## `JSON_DIAGNOSTIC_POSITIONS`
|
|
|
|
When enabled, two new member functions [`start_pos()`](../api/basic_json/start_pos.md) and
|
|
[`end_pos()`](../api/basic_json/end_pos.md) are added to [`basic_json`](../api/basic_json/index.md) values. If the value
|
|
was created by calling the[`parse`](../api/basic_json/parse.md) function, then these functions allow querying the byte
|
|
positions of the value in the input it was parsed from. The byte positions are also used in exceptions to help locate
|
|
errors.
|
|
|
|
The diagnostics positions can also be controlled with the CMake option
|
|
[`JSON_Diagnostic_Positions`](../integration/cmake.md#json_diagnostic_positions) (`OFF` by default) which sets
|
|
`JSON_DIAGNOSTIC_POSITIONS` accordingly.
|
|
|
|
See [full documentation of `JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md)
|
|
|
|
## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`, `JSON_HAS_CPP_23`, `JSON_HAS_CPP_26`
|
|
|
|
The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view`
|
|
support for C++17). For these new features, the library implements some preprocessor checks to determine the C++
|
|
standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is
|
|
unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be
|
|
detected incorrectly.
|
|
|
|
See [full documentation of `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`, `JSON_HAS_CPP_23`, and `JSON_HAS_CPP_26`](../api/macros/json_has_cpp_11.md).
|
|
|
|
## `JSON_HAS_FILESYSTEM`, `JSON_HAS_EXPERIMENTAL_FILESYSTEM`
|
|
|
|
When compiling with C++17, the library provides conversions from and to `std::filesystem::path`. As compiler support
|
|
for filesystem is limited, the library tries to detect whether `<filesystem>`/`std::filesystem` (`JSON_HAS_FILESYSTEM`)
|
|
or `<experimental/filesystem>`/`std::experimental::filesystem` (`JSON_HAS_EXPERIMENTAL_FILESYSTEM`) should be used.
|
|
To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERIMENTAL_FILESYSTEM` to `1`.
|
|
|
|
See [full documentation of `JSON_HAS_FILESYSTEM` and `JSON_HAS_EXPERIMENTAL_FILESYSTEM`](../api/macros/json_has_filesystem.md).
|
|
|
|
## `JSON_HAS_RANGES`
|
|
|
|
The library uses `std::ranges` (and concepts) where available, for example, to parse from C++20 ranges and to
|
|
construct JSON arrays from range views. The library detects whether the standard library supports ranges and
|
|
disables the support on toolchains with an incomplete implementation. To override the built-in check, define
|
|
`JSON_HAS_RANGES` to `1` or `0`.
|
|
|
|
See [full documentation of `JSON_HAS_RANGES`](../api/macros/json_has_ranges.md).
|
|
|
|
## `JSON_HAS_RANGE_VIEW_CONVERSION`
|
|
|
|
When `JSON_HAS_RANGES` is enabled (and the compiler is not MinGW), a JSON array can be constructed directly from a C++20
|
|
range view such as `std::views::filter(...)`. To override the built-in check, define `JSON_HAS_RANGE_VIEW_CONVERSION` to
|
|
`1` or `0`.
|
|
|
|
See [full documentation of `JSON_HAS_RANGE_VIEW_CONVERSION`](../api/macros/json_has_range_view_conversion.md).
|
|
|
|
## `JSON_HAS_STATIC_RTTI`
|
|
|
|
The library detects whether the compiler supports run time type information (RTTI), which it needs, for instance, to
|
|
exclude `std::any` from the candidate types of the implicit conversion on C++17. To override the built-in check, define
|
|
`JSON_HAS_STATIC_RTTI` to `1` or `0`.
|
|
|
|
See [full documentation of `JSON_HAS_STATIC_RTTI`](../api/macros/json_has_static_rtti.md).
|
|
|
|
## `JSON_HAS_STD_FORMAT`
|
|
|
|
When compiling with C++20 and a standard library that provides `<format>`, the library provides a `std::formatter`
|
|
specialization for JSON values. To override the built-in check, define `JSON_HAS_STD_FORMAT` to `1` or `0`.
|
|
|
|
See [full documentation of `JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md).
|
|
|
|
## `JSON_HAS_THREE_WAY_COMPARISON`
|
|
|
|
When the compiler and standard library support 3-way comparison (the spaceship operator `<=>`), the library provides it
|
|
for JSON values. To override the built-in check, define `JSON_HAS_THREE_WAY_COMPARISON` to `1` or `0`.
|
|
|
|
See [full documentation of `JSON_HAS_THREE_WAY_COMPARISON`](../api/macros/json_has_three_way_comparison.md).
|
|
|
|
## `JSON_NOEXCEPTION`
|
|
|
|
Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`.
|
|
|
|
See [full documentation of `JSON_NOEXCEPTION`](../api/macros/json_noexception.md).
|
|
|
|
## `JSON_DISABLE_ENUM_SERIALIZATION`
|
|
|
|
When defined, default parse and serialize functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](../api/macros/nlohmann_json_serialize_enum.md).
|
|
|
|
See [full documentation of `JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md).
|
|
|
|
## `JSON_DISABLE_STREAM_BULK_SCAN`
|
|
|
|
When defined to `1`, parsing from a `#!cpp std::istream` reads one character at a time instead of scanning the
|
|
characters that the stream buffer holds in bulk. Results are the same either way; the macro is an escape hatch for
|
|
stream buffers that do not follow the usual `std::streambuf` contract. The default value is `0`.
|
|
|
|
See [full documentation of `JSON_DISABLE_STREAM_BULK_SCAN`](../api/macros/json_disable_stream_bulk_scan.md).
|
|
|
|
## `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`
|
|
|
|
When defined to `1`, a JSON value can no longer be created from a one-element `std::tuple` holding a reference to a JSON
|
|
value, such as the result of `std::forward_as_tuple(j)`. This lets `std::tuple` convert such tuples element-wise. This
|
|
is planned to become the default in version 4.0.0.
|
|
|
|
See [full documentation of `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](../api/macros/json_disable_tuple_reference_conversion.md).
|
|
|
|
## `JSON_DISABLE_UNLOCKED_FILE_IO`
|
|
|
|
When defined to `1`, parsing from a `#!cpp FILE*` reads every character with `std::fgetc`, which locks the file each
|
|
time, instead of locking the file once and reading it with the unlocked stdio functions. Results are the same either
|
|
way. The default value is `0`.
|
|
|
|
See [full documentation of `JSON_DISABLE_UNLOCKED_FILE_IO`](../api/macros/json_disable_unlocked_file_io.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
|
|
relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for
|
|
security reasons (e.g., Intel Software Guard Extensions (SGX)).
|
|
|
|
See [full documentation of `JSON_NO_IO`](../api/macros/json_no_io.md).
|
|
|
|
## `JSON_NO_SIMD`
|
|
|
|
When defined, the library uses only portable code instead of vector instructions (SSE2, SSSE3, NEON) for scanning
|
|
strings and writing floating-point numbers. Results are the same either way. It is not defined by default.
|
|
|
|
See [full documentation of `JSON_NO_SIMD`](../api/macros/json_no_simd.md).
|
|
|
|
## `JSON_NO_THREAD_LOCAL`
|
|
|
|
When defined, the library does not use `#!cpp thread_local` storage. Copying a value and comparing two values then
|
|
always avoid the call stack rather than descending into a bounded number of levels first, which is slower but yields the
|
|
same values and the same comparisons.
|
|
|
|
See [full documentation of `JSON_NO_THREAD_LOCAL`](../api/macros/json_no_thread_local.md).
|
|
|
|
## `JSON_PRECISE_STREAM_POSITION`
|
|
|
|
When defined to `1`, [`operator>>`](../api/operator_gtgt.md) and non-strict
|
|
[`sax_parse`](../api/basic_json/sax_parse.md) leave an input stream positioned right after the parsed value, instead of
|
|
also consuming the character that terminates a number. The default value is `0`, which preserves the existing behavior;
|
|
this is planned to become the default in version 4.0.0.
|
|
|
|
See [full documentation of `JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md).
|
|
|
|
## `JSON_RECURSION_DEPTH_LIMIT`
|
|
|
|
Sets the number of nesting levels that the operations walking a value (copying, comparing, serializing, hashing,
|
|
merging, diffing, converting, destroying, and the binary writers) recurse into on the call stack before they continue
|
|
with an explicit stack on the heap. The default is `128`; allowed are the integers from `0` to `254`. Lower it for
|
|
threads with small stacks, raise it to trade stack for speed. Results are the same for every setting; the value must be
|
|
the same in all translation units of a program.
|
|
|
|
See [full documentation of `JSON_RECURSION_DEPTH_LIMIT`](../api/macros/json_recursion_depth_limit.md).
|
|
|
|
## `JSON_SKIP_LIBRARY_VERSION_CHECK`
|
|
|
|
When defined, the library will not create a compiler warning when a different version of the library was already
|
|
included.
|
|
|
|
See [full documentation of `JSON_SKIP_LIBRARY_VERSION_CHECK`](../api/macros/json_skip_library_version_check.md).
|
|
|
|
## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`
|
|
|
|
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows
|
|
using the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
|
|
|
|
See [full documentation of `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`](../api/macros/json_skip_unsupported_compiler_check.md).
|
|
|
|
## `JSON_STRICT_BINARY_UTF8`
|
|
|
|
When defined to `1`, [`to_cbor`](../api/basic_json/to_cbor.md), [`to_ubjson`](../api/basic_json/to_ubjson.md),
|
|
[`to_bjdata`](../api/basic_json/to_bjdata.md), and [`to_bson`](../api/basic_json/to_bson.md) throw
|
|
[`type_error.316`](../home/exceptions.md#jsonexceptiontype_error316) for a string value or object key that is not
|
|
valid UTF-8. The default value is `0`, which writes the bytes unchanged as before version 3.13.0; this is planned to
|
|
become the default in version 4.0.0.
|
|
|
|
The check can also be enabled with the CMake option
|
|
[`JSON_StrictBinaryUTF8`](../integration/cmake.md#json_strictbinaryutf8) (`OFF` by default) which sets
|
|
`JSON_STRICT_BINARY_UTF8` accordingly.
|
|
|
|
See [full documentation of `JSON_STRICT_BINARY_UTF8`](../api/macros/json_strict_binary_utf8.md).
|
|
|
|
## `JSON_STRICT_NUL_HANDLING`
|
|
|
|
When defined to `1`, a `'\0'` (NUL) byte anywhere in the input is rejected with `parse_error.101`, like any other
|
|
unexpected byte, instead of being silently treated as end of input (see the
|
|
[FAQ entry](../home/faq.md#nul-bytes-in-the-input) for background). The default value is `0`, which preserves the
|
|
existing behavior; this is planned to become the default in version 4.0.0.
|
|
|
|
The strict handling can also be enabled with the CMake option
|
|
[`JSON_StrictNulHandling`](../integration/cmake.md#json_strictnulhandling) (`OFF` by default) which sets
|
|
`JSON_STRICT_NUL_HANDLING` accordingly.
|
|
|
|
See [full documentation of `JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md).
|
|
|
|
## `JSON_THROW_USER(exception)`
|
|
|
|
This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown.
|
|
|
|
See [full documentation of `JSON_THROW_USER(exception)`](../api/macros/json_throw_user.md).
|
|
|
|
## `JSON_TRY_USER`
|
|
|
|
This macro overrides `#!cpp try` calls inside the library.
|
|
|
|
See [full documentation of `JSON_TRY_USER`](../api/macros/json_throw_user.md).
|
|
|
|
## `JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE`
|
|
|
|
Sets how many elements of optimized UBJSON arrays of `Z` (null), `T` (true), and `F` (false) a reader accepts for
|
|
every byte of input it has read, on top of a base of 1,048,576 elements. These arrays have no payload, so a few bytes
|
|
can announce a million values. The value must be a positive integer; the default is `4`, and a value of 131,072 or
|
|
more switches the limit of the whole input off. The limit of 1,048,576 elements for a single array always applies. The
|
|
macro is not part of the [ABI tag](namespace.md): use the same value in every translation unit.
|
|
|
|
See [full documentation of `JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE`](../api/macros/json_ubjson_valueless_elements_per_byte.md).
|
|
|
|
## `JSON_USE_IMPLICIT_CONVERSIONS`
|
|
|
|
When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on.
|
|
|
|
See [full documentation of `JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md).
|
|
|
|
## `JSON_USE_GLOBAL_UDLS`
|
|
|
|
When defined to `1` (default), the user-defined string literals `operator""_json` and `operator""_json_pointer` are
|
|
placed into the global namespace instead of `nlohmann::literals::json_literals`.
|
|
|
|
See [full documentation of `JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md).
|
|
|
|
## `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`
|
|
|
|
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).
|
|
|
|
## `JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`
|
|
|
|
When defined to `1`, maps with enum keys (e.g., `std::map<E, T>`) are stored as objects, using the enum's conversion for
|
|
the keys, instead of arrays of `[key, value]` pairs. It is switched off (`0`) by default.
|
|
|
|
See [full documentation of `JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS`](../api/macros/json_use_objects_for_enum_keyed_maps.md).
|
|
|
|
## `JSON_USE_SIMDUTF`
|
|
|
|
When defined, UTF-8 validation of JSON strings read from contiguous byte input is delegated to the
|
|
[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator. This is an opt-in
|
|
external dependency and is not defined by default.
|
|
|
|
See [full documentation of `JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md).
|
|
|
|
## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)`
|
|
|
|
The library defines 12 macros to simplify the serialization/deserialization of types. See the page on
|
|
[arbitrary type conversion](arbitrary_types.md#simplify-your-life-with-macros) for a detailed discussion.
|
|
|
|
## `NLOHMANN_JSON_NAMESPACE`, `NLOHMANN_JSON_NAMESPACE_BEGIN`, `NLOHMANN_JSON_NAMESPACE_END`, `NLOHMANN_JSON_NAMESPACE_NO_VERSION`
|
|
|
|
These macros relate to the versioned, inline `nlohmann` namespace:
|
|
|
|
- `NLOHMANN_JSON_NAMESPACE` evaluates to the full name of the `nlohmann` namespace (including the inline ABI namespace).
|
|
- `NLOHMANN_JSON_NAMESPACE_BEGIN` / `NLOHMANN_JSON_NAMESPACE_END` open and close the namespace (for example, to add
|
|
specializations).
|
|
- `NLOHMANN_JSON_NAMESPACE_NO_VERSION`, when defined to `1`, omits the version component from the inline namespace.
|
|
|
|
See the [`nlohmann` Namespace](namespace.md) page, and the full documentation of
|
|
[`NLOHMANN_JSON_NAMESPACE`](../api/macros/nlohmann_json_namespace.md),
|
|
[`NLOHMANN_JSON_NAMESPACE_BEGIN` / `NLOHMANN_JSON_NAMESPACE_END`](../api/macros/nlohmann_json_namespace_begin.md), and
|
|
[`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](../api/macros/nlohmann_json_namespace_no_version.md).
|
|
|
|
## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)`
|
|
|
|
This macro simplifies the serialization/deserialization of enum types. See
|
|
[Specializing enum conversion](enum_conversion.md) for more information.
|
|
|
|
See [full documentation of `NLOHMANN_JSON_SERIALIZE_ENUM`](../api/macros/nlohmann_json_serialize_enum.md).
|
|
|
|
A strict variant [`NLOHMANN_JSON_SERIALIZE_ENUM_STRICT`](../api/macros/nlohmann_json_serialize_enum_strict.md) throws an
|
|
exception on undefined input instead of falling back to the first mapping.
|
|
|
|
## `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH`
|
|
|
|
These macros are defined by the library and contain the version numbers according to
|
|
[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
|
|
|
|
See [full documentation of `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, and `NLOHMANN_JSON_VERSION_PATCH`](../api/macros/nlohmann_json_version_major.md).
|
|
|
|
## See also
|
|
|
|
- [Macros](../api/macros/index.md) - reference of all macros
|
|
- [Runtime Assertions](assertions.md) - runtime assertions in detail
|
|
- [`nlohmann` Namespace](namespace.md) - the library namespace and its macros
|
|
- [Working Without Exceptions](no_exceptions.md) - using the library without exceptions
|
|
- [Modules](modules.md) - macros and C++20 modules
|
|
- [Exceptions](../home/exceptions.md) - all exceptions and their error codes
|
|
- [CMake](../integration/cmake.md) - set macros via CMake options
|
|
- [Compile times](../integration/compile_times.md) - reduce compile times with macros
|
|
- [Architecture](../home/architecture.md) - how the library is put together
|
|
- [Specializing enum conversion](enum_conversion.md) - enum macros
|
|
- [Arbitrary Type Conversions](arbitrary_types.md) - type conversion macros
|