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 6ee5e89803 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-06 10:48:07 +02:00

5.9 KiB

Raw Blame History

nlohmann::basic_json_view::at

// (1)
basic_json_view at(string_view_t key) const;
basic_json_view at(const char* key) const;
basic_json_view at(const string_t& key) const;

// (2)
basic_json_view at(size_type idx) const;
basic_json_view at(int idx) const;

// (3)
basic_json_view at(const json_pointer& ptr) 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).
Returns the array element at index idx.
Returns the value a JSON pointer ptr refers to, starting at this value.

Parameters

key (in): object key of the element to access
idx (in): index of the element to access
ptr (in): JSON pointer to the element to access

Return value

the value of the first member with key key
the element at index idx
the value ptr resolves to, starting at this 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

The function can throw the following exceptions, both with the same message as the corresponding call to BasicJsonType::at:
- Throws type_error.304 if the value is not an object.
- Throws out_of_range.403 if no member has key key.
The function can throw the following exceptions, both with the same message as the corresponding call to BasicJsonType::at:
- Throws type_error.304 if the value is not an array.
- Throws out_of_range.401 if #!cpp idx >= size().
The function can throw the following exceptions, all with the same message as the corresponding call to BasicJsonType::at:
- Throws parse_error.106 if an array index in ptr begins with #!cpp '0'.
- Throws parse_error.109 if an array index in ptr is not a number.
- Throws out_of_range.401 if an array index in ptr is out of range.
- Throws out_of_range.402 if a reference token is #!cpp "-" at an array -- at never inserts an element, so #!cpp "-" is always invalid.
- Throws out_of_range.403 if a reference token names an object member that does not exist.
- Throws out_of_range.404 if ptr cannot be resolved because a reference token is used on a primitive 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 ordered_json, members are compared one after another, in document order, stopping at the first match. Each comparison first checks the key's length -- already known from the index, without reading the key bytes -- before comparing its content. 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 idx: elements are skipped one at a time from the first one, since they are not a fixed size in the index (unlike BasicJsonType's array, which is random-access).
Linear in the number of reference tokens of ptr and, for each token, in the number of members of the object at that level (as 1.) or the index into the array (as 2.).

Notes

Unlike operator[], which returns a discarded view for a missing key or an out-of-range index, at always throws -- exactly as BasicJsonType::at does, and with the same messages, so existing error handling written against BasicJsonType::at keeps working unchanged when switched to a view. This also holds for overload 3: unlike operator[] with a JSON pointer, which returns a discarded view for a missing key or an out-of-range index, at throws for those too (out_of_range.403/out_of_range.401).

Examples

??? example "Example: (1)/(2) access specified element with bounds checking"

The example below reads required fields out of a service configuration with `at`, and shows that the exceptions
it throws -- for a wrong type and for a missing key -- carry the same messages
[`BasicJsonType::at`](../basic_json/at.md) would produce for the same JSON text.

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

Output:

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

??? example "Example: (3) access specified element via JSON pointer with bounds checking"

The example below shows that `at` with a JSON pointer throws exactly the exceptions, with exactly the messages,
that [`BasicJsonType::at`](../basic_json/at.md) throws for the same pointer and the same document.

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

Output:

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

Version history

Added in version 3.13.0.

5.9 KiB Raw Blame History