Niels Lohmann
54f6b3ef06
* json_view: source positions in materialize() with JSON_DIAGNOSTIC_POSITIONS With JSON_DIAGNOSTIC_POSITIONS, materialize() now gives every value the start_pos()/end_pos() that basic_json::parse() would give it, so exceptions about materialized values name the same bytes (#5864). - json_sax_dom_parser takes the lexer type as a defaulted template parameter; materialize() passes position_source, which reports the positions it derives from the index. diagnostic_positions treats npos as "no position" and keeps ranges all-or-nothing. - Strings with escapes keep the offset of their opening quote plus one in `next` (only with the macro); materialize() scans from there to the closing quote. The end of an array or object is found by scanning from the end of its last element over whitespace, comments and a trailing comma. - In editable documents, values written by edits, arrays and objects whose elements changed, and containers whose last element has no position get none. Images keep the flag is_new, and load() checks that `next` of a string is within the text. Nothing changes on the parse path without the macro. The view's own exceptions still carry no byte range, so the tests that compare them with those of materialized values skip it under the macro, as they skip the path under JSON_DIAGNOSTICS. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Indent comment in unit-json_view_from_json.cpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address review: clearer position code and docs - position_source gets clear(); set_scalar() returns early for new values, switches on node_kind, and uses no local copies; the one position_source per materialize() call is documented - no npos + 1 for containers without a position; a comment on why the end of a container is reported as its closing bracket - less duplication under #if in materialize() and the builder - diagnostic_positions sets npos explicitly - docs: positions of basic_json values after changes, positions in images depend on how the document was parsed, when next is set, and the cost of positions while parsing Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Share the comment scanners of the view builder with materialize() skip_line_comment() and find_block_comment_end() in scan.hpp are used by the builder's comment() and by position_source::container_end(), which had its own copy. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address review: if/else for container positions, clearer next field - the opening bracket of a container sets positions with an if/else instead of a ternary, and the frame takes its start from positions - the closing bracket of a container is found in nested if/else; the parent's last_end is taken from positions, so it is npos whenever no range is set - architecture.md: the next field reads "or 0 if it was not; all other values: 0" instead of "else 0; otherwise 0" Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix GCC unused-result and clang-tidy raw-string findings in unit-json_view_positions.cpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- 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.