Niels Lohmann
731f1b5bfb
* json_view: view_mode enum instead of bool Editable, node_kind for node::kind basic_json_document and basic_json_view take a view_mode (read_only, the default, or editable) instead of a bool: basic_json_document<json, true> did not say what true means. The shortcut aliases are unchanged. The kind of a node is a node_kind (the value_t values plus link, 10 as before), which removes the static_cast<std::uint8_t>(value_t::...) of every comparison. The node and image layouts are unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * json_view: node_kind in the node writers, spell out read_only, comment fixes The builder and the edit functions take and store a node_kind instead of casting a value_t; the numbering assertions and the comments now speak of node_kind, and the link kind notes that it follows value_t::discarded. The read-only aliases name view_mode::read_only like the editable ones. view_mode.md says the mode is a compile-time property of the type. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * json_view: views of read-only documents convert to editable views A read-only document has no edits, so a view of it reads correctly as a view of an editable document before its first edit. The implicit conversion lets a function taking a json_editable_view accept the views of both modes. There is no conversion the other way: a read-only view of an editable document would read wrong values after the next edit. The mode comparisons in the cross-mode operator==/!= use an is_other_mode trait, which astyle keeps compact. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
7.6 KiB
nlohmann::basic_json_document
Defined in header <nlohmann/json_view.hpp>
template<typename BasicJsonType, view_mode Mode = view_mode::read_only>
class basic_json_document;
A parsed JSON text, held as a flat index of its values
(16 bytes per value) instead of a tree of BasicJsonType values.
Strings and floating-point numbers stay in the source text; integers are converted while parsing, and strings that
contain escapes are decoded into one buffer owned by the document. basic_json_view is a read-only handle to one value of a
basic_json_document; materialize() turns a subtree into the
BasicJsonType value that BasicJsonType::parse() would have produced for it.
A document may borrow the text it was parsed from (the caller's buffer must then outlive the document) or own
it (a copy, or an rvalue #!cpp std::string that was moved in); see owns_source. basic_json_document
is move-only: a copy would duplicate the whole index, the decoded-string buffer, and the owned text, and a move is
enough in every use we know of. The index, the decoded strings, and the owned text live in one heap block that the
document holds through a #!cpp std::unique_ptr; this is also why views survive a move of the document.
With #!cpp Mode == view_mode::editable, the document also offers set, push_back,
insert, and erase to change values in place, see Edits below. The source text
itself is never written; a read-only document (#!cpp view_mode::read_only, the default) does not carry any of the
bookkeeping edits need, and calling any of them on one fails to compile (#!cpp static_assert).
Template parameters
BasicJsonType- a specialization of
basic_json, for instancejsonorordered_json. Only 64-bitnumber_integer_t/number_unsigned_ttypes are supported; this is checked with astatic_assert. Mode- a
view_mode:#!cpp view_mode::editableif the document supportsset,push_back,insert, anderase(optional,#!cpp view_mode::read_onlyby default). See Edits below.
Specializations
- json_document - read-only documents of the default specialization
json - ordered_json_document - read-only documents of
ordered_json - json_editable_document - editable documents of
json - ordered_json_editable_document - editable documents of
ordered_json
Member types
- view_type - the type of view returned by
root()(#!cpp basic_json_view<BasicJsonType, Mode>) - value_t - the JSON type enumeration, see
basic_json::value_t - image_check - how
load()validates an image (full,bounds,none), seeimage_check
Member functions
Parsing
- parse (static) - deserialize from a compatible input, borrowing or owning it as appropriate
- parse_copy (static) - deserialize a copy of a compatible input
- accept (static) - check whether the input is valid JSON
- read - (re-)parse into this document, reusing its memory
Access
- root - the view of the root value
- is_discarded - return whether the last parse failed
- source - the parsed text
- owns_source - return whether the document holds its own copy of the text
- node_count - the number of index entries (values plus object keys)
- memory_usage - the number of bytes held by the document
- shrink_to_fit - release unused index capacity
Images
- save - the document as an image that
load()reads without parsing - load (static) - read an image written by
save()
Edits
- set - replace a value, or set an object member, an array element, or the value a JSON pointer refers to (editable documents only)
- push_back - append to an array (editable documents only)
- insert - insert an element into an array before a given position (editable documents only)
- erase - remove an object member, an array element, or the value a JSON pointer refers to (editable documents only)
Edits
An editable document (#!cpp view_mode::editable) can be changed after parsing, with set,
push_back, insert, and erase;
json_editable_document and
ordered_json_editable_document are the corresponding specializations. A few
points apply to every edit:
- The source text is never written, and the parsed index never moves: every value keeps the node it was parsed
into, so views taken before an edit stay valid, including
root(). New values (and the element sequences of an edited array/object) go to storage owned by the document, allocated on demand. - A view keeps referring to the same value. After
setreplaces the value a view refers to, that view sees the new value; a view of a value that a later edit replaces or drops keeps showing what it last held. An edit of an array or object, however, invalidates the iterators taken over it (its members may now live in a different sequence), and a string obtained withget_string()stays valid even as further edits happen (earlier buffers of edited text are kept alive, not overwritten). - Values are accepted three ways: a
basic_json_viewof any document (read-only or editable; it is copied, nothing is shared with the source document), aBasicJsonTypevalue, or anythingBasicJsonTypecan be constructed from (numbers, strings,#!cpp bool,#!cpp nullptr, containers, ...). dump()writes an edited document with members in document order, new members at the end, and, withnumber_format::source, keeps the spelling of every number that was not itself edited -- see Editing a document for why this matters.read()discards all edits,shrink_to_fit()does not move the node index once there are edits, andmemory_usage()includes the memory edits use.source_offset()of a value introduced by an edit is#!cpp static_cast<std::size_t>(-1), the same value it reports for a decoded string.
See also
- Zero-copy JSON views - guide to documents and views
- basic_json_view - the non-owning handle to a value in a document
- json_document and json_editable_document - the default specializations
- materialize - build a
basic_jsonvalue from a view
Version history
- Added in version 3.13.0.