mirror of
https://github.com/nlohmann/json.git
synced 2026-10-19 15:25:25 +00:00
481a9a216f
Add json_document and json_view, a read-only, zero-copy index of a JSON text, as the first public slice of the zero-copy view (#5295). A parse produces a flat array of 16-byte nodes in document order, one per value and one per object key. Strings stay in the source text; escaped strings are decoded into an arena. Integers are converted while their digits are in the cache; floats keep only their digit layout and are converted on read. Containers store the size of their subtree, so a reader can step over one in constant time. A document makes a handful of allocations, however many values it has. The parser accepts exactly what json::parse accepts, with every combination of ignore_comments and ignore_trailing_commas, with and without a trailing NUL, and under JSON_STRICT_NUL_HANDLING. It is portable C++11 and does not depend on byte order. basic_json_document adds parse, parse_copy, accept, read (reuses a document's memory), root, is_discarded, source, owns_source, node_count, memory_usage, and shrink_to_fit. basic_json_view adds type, the is_* queries, operator bool, size, empty, materialize, and source_offset. A parse error throws the same exception basic_json::parse would throw for the same input, message and position included. detail::abi_config keeps JSON_STRICT_NUL_HANDLING and JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON readable after json.hpp undefines them, in the ABI namespace so they always match the basic_json in use. A NUL byte that ends a // comment is the end of the input, as in parse() since #5696. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.5 KiB
2.5 KiB
nlohmann::basic_json_document::parse_copy
template<typename InputType>
static basic_json_document parse_copy(InputType&& input,
const bool allow_exceptions = true,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
Deserialize from a compatible input, always taking the document's own copy of it, regardless of the value category or
type of input. Unlike parse(), the returned document never depends on input staying alive.
Template parameters
InputType- A compatible input; see
parse.
Parameters
input(in)- Input to parse from.
allow_exceptions(in)- whether to throw exceptions in case of a parse error (optional,
#!cpp trueby default) ignore_comments(in)- whether comments should be ignored and treated like whitespace (
#!cpp true) or yield a parse error (#!cpp false); (optional,#!cpp falseby default) ignore_trailing_commas(in)- whether trailing commas in arrays or objects should be ignored and treated like whitespace (
#!cpp true) or yield a parse error (#!cpp false); (optional,#!cpp falseby default)
Return value
The parsed document, with owns_source() #!cpp true. If allow_exceptions is #!cpp false and
the input is not valid JSON, the returned document is discarded; see is_discarded.
Exceptions
Same as parse.
Complexity
Linear in the length of the input.
Notes
parse_copy() accepts and rejects exactly what parse() does, and classifies numbers the same way; it
only differs in that the input is always copied rather than sometimes borrowed. Prefer parse() when the
input's lifetime already covers the document's, since it avoids the copy for borrowed inputs.
Examples
??? example
The example below returns a document from a function whose local buffer would otherwise not outlive it.
```cpp
--8<-- "examples/basic_json_document__parse_copy.cpp"
```
Output:
```json
--8<-- "examples/basic_json_document__parse_copy.output"
```
See also
- parse - deserialize from a compatible input, borrowing it where possible
- owns_source - return whether the document holds its own copy of the text
Version history
- Added in version 3.13.0.