mirror of https://github.com/nlohmann/json.git synced 2026-10-03 05:00:30 +00:00

Files

T

Niels Lohmann 54455afa40 Document json_document and json_view

- API pages for basic_json_document and basic_json_view, one per member,
  and for the four aliases, each with an example
- features/json_view.md: the problem the view solves, ownership and
  lifetime, what matches basic_json::parse() and what differs, and when
  to choose json, ordered_json, SAX, or the view
- the examples show why one would use the view, not only how: borrowed
  vs. owned input, reading a few fields and materializing one subtree,
  reusing a document across many messages
- registered in the mkdocs navigation, llms.txt, the docset, the
  exceptions page (out_of_range.416), architecture.md, the integration
  page, and the README; the yyjson credit is added to the README and
  license.md

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

2026-09-29 14:02:43 +02:00

3.6 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, and materialize() to build the BasicJsonType value of a subtree on demand. It does not (yet) provide element access, iteration, get<T>(), JSON Pointer support, 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

Member functions

(constructor)

Object inspection

type - return the type of the value
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

Capacity

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

Conversion

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.

3.6 KiB Raw Blame History