amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-10-07 23:17:14 +00:00

Files

T

Niels Lohmann 77acd4563c 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-07 16:42:26 +02:00

5.5 KiB

Raw Blame History

nlohmann::basic_json_view::value

// (1)
template<typename T>
T value(string_view_t key, const T& default_value) const;
string_t value(string_view_t key, const char* default_value) const;

// (2)
template<typename T>
T value(const json_pointer& ptr, const T& default_value) const;
string_t value(const json_pointer& ptr, const char* default_value) const;

Returns the value of the object member with key key -- the first one, should the key occur more than once (see Notes on duplicate keys) -- converted to T, or default_value if there is no such member.
Returns the value a JSON pointer ptr refers to, starting at this value, converted to T, or default_value if ptr cannot be resolved.

Both overloads have a dedicated #!cpp const char* overload, so #!cpp v.value(key, "default") (and the JSON pointer equivalent) deduce string_t, not const char*, for their return type and for the comparison used to pick between key and default_value.

Template parameters

T: the type to convert the found value to; also the type of default_value

Parameters

key (in): object key of the element to access
ptr (in): JSON pointer to the element to access
default_value (in): the value to return if key/ptr resolves to no value

Return value

the first member with key key, converted to T, or default_value
the value ptr resolves to, converted to T, or default_value

Exception safety

Strong exception safety: if an exception is thrown, there are no changes to the view or the document it refers to.

Exceptions

Throws type_error.306 if the value is not an object -- the same exception, with the same message, that BasicJsonType::value throws for the same call. If a member with key key is found, throws whatever converting it to T throws (typically type_error.302, with the same message BasicJsonType::value throws for the same mismatch); a missing member never throws.
Throws type_error.306 if this value -- not the value ptr resolves to -- is neither an object nor an array. Throws parse_error.106 or parse_error.109 if ptr contains a malformed array index. If ptr resolves to a value, throws whatever converting it to T throws. Every other way ptr can fail to resolve -- a missing key, an out-of-range or "-" array index, an unresolvable token on a primitive -- yields default_value instead of throwing, exactly as BasicJsonType::value catches out_of_range and returns default_value.

None of these exceptions carry a JSON_DIAGNOSTICS path: the view has no BasicJsonType value to point at, so the exception is created without one, even if BasicJsonType was built with JSON_DIAGNOSTICS enabled.

Complexity

Linear in the number of members: as for operator[], members are compared one after another, in document order, stopping at the first match. Plus the complexity of converting the found member to T (see get).
Linear in the number of reference tokens of ptr and, for each token, in the number of members of the object at that level or the index into the array -- as for the operator[] and at overloads that take a JSON pointer. Plus the complexity of converting the resolved value to T.

Notes

!!! info "Differences to at and operator[]"

Unlike [`at`](at.md), this function does not throw if `key`/`ptr` resolves to no value. Unlike
[`operator[]`](operator[].md), it never returns a [discarded](is_discarded.md) view -- it always returns a `T` --
and it is available on any view, since it never needs to insert a missing element the way the non-const
`BasicJsonType::operator[]` would.

!!! info "Which values can be asked"

As for [`BasicJsonType::value`](../basic_json/value.md), the key overload (1) requires an object, and the JSON
pointer overload (2) an object or an array.

Examples

??? example "Example: (1) access specified object element with default value"

The example below reads a couple of optional configuration fields with a default, so that a missing key never
needs a `#!cpp try`/`#!cpp catch` of its own.

```cpp
--8<-- "examples/basic_json_view__value.cpp"
```

Output:

```json
--8<-- "examples/basic_json_view__value.output"
```

??? example "Example: (2) access specified element via JSON pointer with default value"

The example below reads an optional, nested configuration value with a default, given as a JSON pointer.

```cpp
--8<-- "examples/basic_json_view__value_json_pointer.cpp"
```

Output:

```json
--8<-- "examples/basic_json_view__value_json_pointer.output"
```

Version history

Added in version 3.13.0.

5.5 KiB Raw Blame History