mirror of https://github.com/nlohmann/json.git synced 2026-09-30 14:05:18 +00:00

Files

Niels Lohmann 54455afa40 Document json_document and json_view

- API pages for basic_json_document and basic_json_view, one per member,
  and for the four aliases, each with an example
- features/json_view.md: the problem the view solves, ownership and
  lifetime, what matches basic_json::parse() and what differs, and when
  to choose json, ordered_json, SAX, or the view
- the examples show why one would use the view, not only how: borrowed
  vs. owned input, reading a few fields and materializing one subtree,
  reusing a document across many messages
- registered in the mkdocs navigation, llms.txt, the docset, the
  exceptions page (out_of_range.416), architecture.md, the integration
  page, and the README; the yyjson credit is added to the README and
  license.md

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-09-29 14:02:43 +02:00

2.5 KiB

Raw Blame History

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 true by default)
ignore_comments (in): whether comments should be ignored and treated like whitespace (#!cpp true) or yield a parse error (#!cpp false); (optional, #!cpp false by 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 false by 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"
```

Version history

Added in version 3.13.0.

2.5 KiB Raw Blame History