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.