Niels Lohmann
8a0679558f
- Copying is disabled because of its cost, not because of two documents borrowing the same buffer; the unique_ptr follows from move-only. - Inputs: streams, FILE*, and wide characters (strings, arrays, pointers) are all supported and owned; point to parse_copy() for owned copies. - The error replay only runs for failing input, builds no values, and is skipped with allow_exceptions = false. - read() writes copied inputs into the previous owned copy. - Views can dangle like std::string_view, and why there is no shared/weak pointer design. - The 4 GiB limit (16-byte nodes, 16-byte scanner steps), streams being read to the end first, which macros apply, why materialize() has no source positions, and wording nits (accept() vs basic_json::accept(), is_binary, is_discarded, see-also lists, size table, "back into"). Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.6 KiB
nlohmann::basic_json_document::read
template<typename InputType>
void read(InputType&& input,
const bool allow_exceptions = true,
const bool ignore_comments = false,
const bool ignore_trailing_commas = false);
(Re-)parses input into #!cpp *this, discarding the document's previous value and reusing its memory (the node
index, the decoded-string buffer, and, if applicable, the owned copy of the text) rather than allocating a fresh
document. parse() is implemented in terms of this function, applied to a default-constructed document.
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)
Exceptions
Same as parse.
Complexity
Linear in the length of the input.
Notes
Every view taken from #!cpp *this before the call -- including the previous root() -- is invalidated,
whether or not the new parse succeeds; take fresh views from root() afterward.
input is borrowed or owned by the same rules as parse(); a document can borrow on one call and
own on the next, since ownership is decided freshly each time. An input that is copied (see the table in
parse()) is written into the document's previous owned copy, reusing its memory; a moved-in
#!cpp std::string replaces it.
An integer argument that is not a #!cpp bool where the flags are expected, such as #!cpp read(ptr, len), does not
compile; see parse.
Examples
??? example
The example below parses a sequence of messages into the same document, reusing its memory instead of allocating
a new document for each one.
```cpp
--8<-- "examples/basic_json_document__read.cpp"
```
Output:
```json
--8<-- "examples/basic_json_document__read.output"
```
See also
Version history
- Added in version 3.13.0.