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>
1.9 KiB
nlohmann::basic_json_document::root
// (1)
view_type root() const& noexcept;
// (2)
view_type root() const&& = delete;
- Returns a view of the root value of the document.
- Deleted: the view of a temporary document would dangle.
Return value
A view_type (i.e. #!cpp basic_json_view<BasicJsonType>) for the root value, or a
discarded view if the document is discarded.
Exception safety
No-throw guarantee: this function never throws exceptions.
Complexity
Constant.
Notes
Lifetime. A view refers into the document, so the document must outlive it. root() can therefore only be called
on a document that has a name (an lvalue); calling it on a temporary does not compile:
auto v = json_document::parse(text).root(); // error: the document is destroyed at the end of the statement
auto doc = json_document::parse(text); // OK: keep the document alive
auto v = doc.root();
root() is a cheap handle into the document's index, not a copy of anything; call it as often as needed. The
returned view is valid under the same conditions as any other view of the document — see
Object inspection — in particular, it is invalidated by the next
read() or shrink_to_fit() on this document. A view can dangle, like a
#!cpp std::string_view; see Ownership and lifetime.
Examples
??? example
```cpp
--8<-- "examples/basic_json_document__root.cpp"
```
Output:
```json
--8<-- "examples/basic_json_document__root.output"
```
See also
is_discarded- return whether the last parse failedmaterialize- build theBasicJsonTypevalue of a subtree
Version history
- Added in version 3.13.0.