Niels Lohmann
6a852ab96d
* Split the json_view feature page into sub-pages
The single features/json_view.md page grew to ~600 lines covering eight
topics. Split it into features/json_view/ with an overview page and
pages for ownership and lifetime, differences from basic_json, reading
values, generic code, editing, and images.
The new differences page collects what was spread over several sections
("What is the same", "What is different", "Duplicate keys", and notes in
the conversion and serialization sections) under one summary table, and
adds the parts of the basic_json interface a view does not have. The
other pages now link to it instead of restating the rules.
Internal links across the documentation point to the new pages.
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
* Docs: fix stale comments and trim repeated text in json_view pages
- fig-jsonview.js/.css: point the header comments at the new pages
- reading.md: views' strings are valid as long as the document (and a
borrowed source text), as lifetime.md says
- reading.md, generic_code.md: link to differences.md instead of
restating the member-order and repeated-key rules
- differences.md: drop the third mention of ordering comparisons, name
rbegin()/rend() in the iterator row
- exceptions.md: link editable documents to editing.md
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---------
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.7 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.
An integer argument that is not a #!cpp bool where the flags are expected, such as #!cpp parse_copy(ptr, len), does not
compile; see parse.
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 possibleowns_source- return whether the document holds its own copy of the text- Zero-copy JSON views - borrowing or copying the source text
Version history
- Added in version 3.13.0.