mirror of https://github.com/nlohmann/json.git synced 2026-10-12 20:05:23 +00:00

Files

Niels Lohmann 3058d527ce Scan json_view strings with SIMD and index large objects

Speed up json_view's parser with SIMD scanning and a hash table
for large objects.

Long runs of string bytes are scanned 16 bytes at a time with NEON
(AArch64, GCC and Clang) and SSE2 (x86-64), both baseline
instruction sets. Keys keep 16 table checks before the vector
loop, because their lengths repeat from record to record; string
values get 8, because their lengths vary more. Non-ASCII text is
validated 16 bytes at a time with simdjson's "lookup4" check
(Keiser and Lemire, 2021), with NEON on AArch64 and, on x86-64,
with SSSE3. SSSE3 is not part of baseline x86-64, so the check is
compiled for SSSE3 with a function attribute and used only where
CPUID reports it, which all x86-64 CPUs since about 2011 do; the
answer is cached in a statically initialized atomic, so there is
no guard of a local static and no global constructor. The same
input is accepted either way. JSON_VIEW_NO_SIMD selects the
portable code.

On x86-64, string runs are now checked vector-first: one SSE2
compare from the first byte finds the end of most keys and short
values, instead of a branch per byte for the first 8-16 bytes.
AArch64 keeps the byte-wise steps, where a NEON mask costs more and
the branches predict well. Entering an object or array no longer
stalls: open() stores the parent's frame field by field instead of
building it on the stack and reading it back with wider loads,
which waited for the narrower stores to retire.

Objects with 128 members or more get an open-addressing hash table
built when the object closes, so operator[], at(), find(),
contains(), count(), value(), and JSON pointers take constant time
on average in such objects; of duplicate keys, the first is kept,
as for the linear search. The idea comes from Boost.JSON.

simdjson is credited in simd.hpp's SPDX block, the README, and
license.md.

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

2026-10-11 11:30:55 +02:00

6.0 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). Objects with 128 or more members get a hash index while parsing, so that a lookup in them takes constant time on average.
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

!!! warning "Duplicate keys: the first member wins"

If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
[`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
`operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
the last value.

!!! 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.

6.0 KiB Raw Blame History