c9cecf76ce
basic_json_document gets a second template parameter, Editable (false by default), plus the aliases json_editable_document, json_editable_view, ordered_json_editable_document and ordered_json_editable_view. Editable documents can change values and structure without rewriting the source text: set()/push_back() on values, keys, array indices and JSON pointers; insert() before an array element; erase() of an object key, array index or JSON pointer. New values and element sequences go into edit storage that the document owns and never moves, so views keep referring to their value across edits and a parsed node never moves. Read-only documents walk the plain node array and are unaffected. Strings are checked for UTF-8 on entry, so dump() of an editable document never throws type_error.316. Binary values cannot be stored (type_error.319). A seeded differential test applies random edits to an editable document and to the equivalent ordered_json and compares both after every step. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
6.8 KiB
nlohmann::basic_json_view
Defined in header <nlohmann/json_view.hpp>
template<typename BasicJsonType, bool Editable = false>
class basic_json_view;
A read-only handle to one value of a basic_json_document: two pointers (a pointer
to the document and a pointer into its index), trivially copyable. A view is valid as long as
- the document is alive,
- the document has not been re-parsed with
read()(orparse()into it) or shrunk withshrink_to_fit()since the view was taken, and - if the document borrows its source text, that text is still alive.
Moving the document itself does not invalidate its views: the index is heap-allocated independently of the
basic_json_document object.
basic_json_view provides the read-only part of the BasicJsonType interface: the type-inspection functions, element
access, lookup, iteration, conversion, and comparison -- get<T>(), get_string(),
number_token(), and materialize() to build the BasicJsonType value of a
subtree on demand. operator[], at, contains, and
value also accept a json_pointer. operator== and
operator!= compare two views, or a view and a BasicJsonType value, without ever building a
BasicJsonType value for a view; no ordering comparison (#!cpp operator<) is provided.
basic_json_view itself is always read-only -- it never has a set or push_back of its own. A view of an
editable document (#!cpp Editable == true) sees every edit made through
basic_json_document::set and
basic_json_document::push_back: once a value is changed, every view that
still refers to it -- including ones taken before the change -- reads the new value. See
Edits.
Template parameters
BasicJsonType- a specialization of
basic_json, matching thebasic_json_documentthe view was taken from. Editable- whether the view is of an editable document, matching the
basic_json_documentit was taken from (optional,#!cpp falseby default). See Edits.
Specializations
- json_view - views of a
json_document - ordered_json_view - views of an
ordered_json_document - json_editable_view - views of a
json_editable_document - ordered_json_editable_view - views of an
ordered_json_editable_document
Member types
- value_t - the JSON type enumeration, see
basic_json::value_t - string_t, number_integer_t, number_unsigned_t, number_float_t, json_pointer - the corresponding
member types of
BasicJsonType - size_type -
#!cpp std::size_t - string_view_t -
#!cpp std::string_viewon C++17 and newer, a minimal internal substitute otherwise - iterator, const_iterator - a forward iterator over the elements of an array or the member values of an object, in document order; both names refer to the same type, since a view is always read-only
- item - a (key, value) pair produced by
items() - number_format - how
dump()writes numbers
Member functions
Object inspection
- type - return the type of the value
- type_name - return the type as string
- is_null - return whether the value is null
- is_boolean - return whether the value is a boolean
- is_number - return whether the value is a number
- is_number_integer - return whether the value is an integer number
- is_number_unsigned - return whether the value is an unsigned integer number
- is_number_float - return whether the value is a floating-point number
- is_string - return whether the value is a string
- is_array - return whether the value is an array
- is_object - return whether the value is an object
- is_binary - return whether the value is a binary array (always
#!cpp false) - is_primitive - return whether the type is primitive
- is_structured - return whether the type is structured
- is_discarded - return whether the view is invalid
Element access
- at - access specified element with bounds checking
- operator[] - access specified element
- value - access specified element with default value
- front - access the first element
- back - access the last element
Lookup
- find - find an element in an object
- count - returns the number of occurrences of a key in an object
- contains - check the existence of an element in an object
Iterators
- begin - returns an iterator to the first element
- cbegin - returns a const iterator to the first element
- end - returns an iterator to one past the last element
- cend - returns a const iterator to one past the last element
- items - wrapper to access iterator member functions in range-based for
Capacity
Conversion
- get - get a value
- get_to - get a value and write it to a destination
- get_string - get a string value without a copy
- number_token - get a number's token text without a copy
- materialize - build the
BasicJsonTypevalue of this subtree
Comparison
- operator== - comparison: equal
- operator!= - comparison: not equal
Serialization
- dump - serialize to a JSON-formatted string
- operator<< - serialize to stream
Source access
- source_offset - byte offset of this value in the document's source text
Version history
- Added in version 3.13.0.