Niels Lohmann
f64464daf1
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>
3.8 KiB
nlohmann::basic_json_view::materialize
BasicJsonType materialize() const;
Builds the BasicJsonType value of this subtree: the value BasicJsonType::parse() would
have produced for the same source text, allocated for the first time by this call.
Return value
The BasicJsonType value of this subtree, or a discarded BasicJsonType value (#!cpp BasicJsonType(value_t::discarded))
if the view is discarded.
Exception safety
Strong guarantee: there are no changes to the view or the document it refers to (nothing about either is mutated by this function).
Exceptions
May throw #!cpp std::bad_alloc (via BasicJsonType's allocator) if constructing the result fails.
Complexity
Linear in the size of the subtree.
Notes
materialize() replays the subtree through the same SAX builder BasicJsonType::parse()
uses, so the result matches it exactly — including, for an object, that a repeated key keeps only its
last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion
would be; the JSON nesting depth is limited only by available memory, as for BasicJsonType::parse() itself.
With JSON_DIAGNOSTIC_POSITIONS enabled, the values get the source
positions BasicJsonType::parse() would give them, also for the subtree of a view (the
positions are those in the document's whole source text), and exceptions about them name the same bytes. For values of
an editable document, positions are all-or-nothing, and start_pos()
and end_pos() return std::string::npos for
- a value written by an edit (a copy of an array or object of the document is also new; copies of its scalars keep their positions),
- an array or object whose elements were changed (its elements keep theirs), and
- an array or object whose last element has no positions (its end is found from that element).
This differs from a basic_json value, whose positions are not updated when it is changed: they stay as they were
parsed, even if they no longer match the value (see start_pos()).
Documents loaded from an image have the positions of the saved document. Its strings
with escapes have positions only if the document was parsed with JSON_DIAGNOSTIC_POSITIONS: the position of their
opening quote is recorded while parsing, and save() and load() keep it whether or not they are compiled with the
macro.
Calling materialize() on the same view repeatedly builds a new, independent BasicJsonType value each time; it
never caches the result.
Examples
??? example
The example below skips messages that are not useful — a discarded value, or an empty array — using only
[`is_array()`](is_array.md) and [`empty()`](empty.md), and calls `materialize()` only for the messages that are
actually used, so no `BasicJsonType` value (and none of its per-element allocations) is ever built for the
skipped ones.
```cpp
--8<-- "examples/basic_json_view__materialize.cpp"
```
Output:
```json
--8<-- "examples/basic_json_view__materialize.output"
```
See also
root- the view of a document's root valueBasicJsonType::parse- build aBasicJsonTypevalue directly from a JSON textJSON_DIAGNOSTIC_POSITIONS- source positions on parsed values- Zero-copy JSON views - when to build a basic_json value from a view
Version history
- Added in version 3.13.0.