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_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.
Unlike parsing with JSON_DIAGNOSTIC_POSITIONS enabled, the values
produced by materialize() do not carry source positions. The index has the start offset of every value, but not the
end of arrays, objects, and escaped strings, which the positions also need.
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 value
BasicJsonType::parse- build aBasicJsonTypevalue directly from a JSON textJSON_DIAGNOSTIC_POSITIONS- source positions on parsed values (not produced bymaterialize())
Version history
- Added in version 3.13.0.