amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-10-06 22:47:13 +00:00

Files

T

Niels Lohmann 0adb7783a4 Add element access, iteration, values, and JSON pointers to json_view

Give basic_json_view the read-only access functions of basic_json:
operator[] and at() with keys and indices, front()/back(), find(),
contains(), count(), begin()/end() and cbegin()/cend(), items()
with structured bindings from C++17 on, and type_name().

Exceptions have the ids and messages of the const functions of
basic_json. Where basic_json has undefined behavior the view
answers safely: operator[] with a missing key or an out-of-range
index returns a discarded view, and front()/back() of an empty
container throw invalid_iterator.214. Objects are iterated in
document order, and all members are visited; duplicate-key lookups
find the first member (as yyjson and simdjson do), while parse(),
materialize(), and the map conversions keep the last value, as
parse() does. Keys of up to 16 bytes are compared with two
overlapping loads.

Add value conversions: get<T>()/get_to() for arithmetic types,
bool, nullptr_t, strings (std::basic_string copied,
string_view_t without a copy), BasicJsonType, views, std::vector,
and maps with string keys; get_string() for the string without a
copy; number_token() for the number exactly as written in the
source; value() with keys and JSON pointers; and operator[]/at()/
contains() with JSON pointers. Everything else, including types
with from_json(), goes through materialize() of that subtree.
get<T>() of arithmetic types is inlined down to the conversion, so
reading an integer needs no call.

detail::json_pointer_access exposes a pointer's reference tokens
to code outside basic_json.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-10-06 10:48:06 +02:00

5.4 KiB

Raw Blame History

nlohmann::basic_json_view

Defined in header <nlohmann/json_view.hpp>

template<typename BasicJsonType>
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.

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, and conversion -- 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. It does not (yet) provide dump() or comparison.

Template parameters

BasicJsonType: a specialization of basic_json, matching the basic_json_document the view was taken from.

Specializations

json_view - views of a json_document
ordered_json_view - views of an ordered_json_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
item - a (key, value) pair produced by items()

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
operator bool - return whether the view refers to a value

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

Source access

source_offset - byte offset of this value in the document's source text

Version history

Added in version 3.13.0.

5.4 KiB Raw Blame History