json/api/basic_json_view.md

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() (or parse() into it) or shrunk with shrink_to_fit() since the view was taken, and
• if the document borrows its source text, that text is still alive and unmodified (floating-point values and unescaped strings are read from it lazily).

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: get<T>(), get_string(), number_token(), and materialize() to build the BasicJsonType value of a subtree on demand
• comparison: 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

operator[], at, contains, and value also accept a json_pointer. Unlike basic_json, there are no implicit conversion operators (no #!cpp operator ValueType()), and no #!cpp get_ptr() or #!cpp get_ref(); see get.

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 the basic_json_document the view was taken from.

Editable

whether the view is of an editable document, matching the basic_json_document it was taken from (optional, #!cpp false by 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_view on 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
• number_format - how dump() writes numbers

Member functions

• (constructor)

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

• size - return the number of elements
• empty - return whether the value has no elements

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 BasicJsonType value 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.