Add element access, iteration, values, and JSON pointers to json_view by nlohmann · Pull Request #5622 · nlohmann/json

nlohmann · 2026-09-29T14:19:45Z

Part of the stack for the zero-copy view (#5295). This adds element and member access to basic_json_view, and the value conversions built on it.

Summary

basic_json_view gains the read-only access functions of basic_json: operator[] and at() with keys, indices, and JSON pointers, front() and back(), find(), contains(), and count(), begin()/end() and cbegin()/cend(), items() with structured bindings from C++17 on, and type_name().
Index types. operator[] and at() accept an index of any integer type (int, unsigned, long, std::int64_t, ...) through a template; a single int overload would have been ambiguous for unsigned, long, and int64_t. Negative values are out of range.
Exceptions: 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 index out of range returns a discarded view; front()/back() of an empty container throw invalid_iterator.214.
Chained access is safe. operator[] (key, index, JSON pointer) on a discarded view returns a discarded view, so v["a"]["b"][0] can be tested once at the end. at() still throws.
Order: objects are iterated in document order, and all members are visited.
Duplicate keys (please review): lookups return the first member, with early exit, so a lookup can stop at the first match; yyjson and simdjson do the same. parse() keeps the last value, and so do materialize() and the conversions to maps. This is documented prominently in a "Duplicate keys" section of the feature page, with a recipe for getting the last member. Returning the last member would mean scanning every object to its end on each lookup, which made lookups in small objects 1.6 to 3.4 times slower.
Lookup cost: keys of up to 16 bytes are compared with two overlapping loads, and most keys are rejected by their length alone, which the index already holds.
Array access: operator[](index) is linear in the index, because elements are not fixed-size in the flat index. The docs say so.
get<T>(), get_to(): convert directly, without building a basic_json value: arithmetic types (booleans become 0/1, as in basic_json); bool and std::nullptr_t; strings (std::basic_string as a copy, string_view_t without a copy); BasicJsonType (the same as materialize()); views themselves; std::vector, and maps with string keys, e.g. std::map<std::string, json_view>. Everything else, including user types with from_json(), goes through materialize() of that subtree. Floats are bit-identical to parse().
get_string(): the string without a copy, pointing into the source text or, for strings with escapes, into the document's buffer of decoded strings.
number_token(): the number as it appears in the source ("1.50", "1E2", all digits of a long integer) -- basic_json cannot provide this.
value(): with keys and with JSON pointers; the pointer overload also accepts arrays, as since Extend value to arrays when using JSON pointers #5223.
JSON pointers: operator[], at(), and contains(). The exceptions are those of basic_json, message included; where const basic_json::operator[] has undefined behavior, the result is a discarded view; value() returns the default wherever basic_json::value() catches out_of_range; contains() never throws; array indices follow json_pointer's rules (parse_error.106/109, out_of_range.404/410).
Core files touched: json.hpp, json_pointer.hpp, and value_t.hpp gain two small internal helpers. detail::json_pointer_access gives code outside basic_json the reference tokens of a pointer, so they need not be parsed from to_string() again. detail::value_type_name(value_t) holds the names that basic_json::type_name() used to switch over; type_name() now calls it, so the view uses the same names (no behavior change).
Other: NLOHMANN_VIEW_ALWAYS_INLINE is plain inline on MSVC, because __forceinline triggers C4714 (an error under /WX) for templates MSVC cannot inline. IWYU pragmas are added. Docs: API pages and examples for every new function, the "Duplicate keys" and "Getting values out without copying" sections, and fixes of the operator[] and is_discarded pages.

Performance

Measured on Apple M1 Max (Apple clang, -O2) and an x86-64 KVM Haswell VPS pinned to one core (GCC 13 / Clang 18, -O2; the VPS is noisy, about ±5-10%). µs, best of 3 interleaved rounds of 15 runs; files from nativejson-benchmark. Traversing every value (numbers read as double, strings copied) at this PR:

	Apple M1	x86-64 GCC	x86-64 Clang
canada	2074	4296	4331
citm_catalog	128	261	265
twitter	107	149	171

get<T>() of arithmetic types is inlined down to the conversion, so its checks of the node kind merge with those of the caller, and reading an integer needs no call.

The core library is unaffected: the three core files only gain the helpers above, and basic_json::type_name() returns the same strings.

Tests

Every element and member of 2,000 generated documents, compared with ordered_json.
Keys of every length around the load sizes.
Duplicate keys: lookups find the first member, iteration visits all.
The exceptions, compared with const basic_json.
Chained access on discarded views, and every integer type as an array index.
Iterators, items, and structured bindings.
The conversions of 2,000 generated documents.
20,000 float tokens, compared bit for bit with parse() for double and for float.
Every JSON pointer (leaves and their parents) of 1,000 documents.
27 malformed pointers, with the exceptions of at(), operator[], contains(), and value() compared with basic_json, also with JSON_DIAGNOSTICS and JSON_DIAGNOSTIC_POSITIONS.

Public API

No breaking changes to the existing API: this PR adds members of basic_json_view (access functions and value conversions), plus the internal detail::json_pointer_access and detail::value_type_name(). basic_json::type_name() behaves as before. The view API is new in this stack, so its decisions are not breaking relative to a release, but they are visible to users:

operator[] and at() accept any integer type as an index.
operator[] on a missing key, an out-of-range index, an unresolvable pointer, or a discarded view returns a discarded view instead of invoking undefined behavior as const basic_json::operator[] does; at() throws.
Lookups with duplicate keys return the first member; parse(), materialize(), and map conversions keep the last.
Exceptions thrown by the view's access functions never carry the JSON_DIAGNOSTICS path.

Written by Claude Code.

🤖 Generated with Claude Code

nlohmann · 2026-09-29T22:38:04Z

CI fixes for this PR (commit 958fbc3, plus the lower fixes merged in):

The reported failures (msvc x64 C4127, ci_test_gcc/standards, ci_test_single_header, check) were all inherited. They are fixed in Convert floats with Eisel-Lemire when std::from_chars is unavailable #5617, Find the stop byte of a string run without a byte loop #5618, Add json_document and json_view: node index, parser, and document #5620 and Add json_document and json_view: parse, accept, types, materialize #5621.
ci_test_noexceptions (latent): the element-access tests compare exceptions through exception_of(), which catches outside a CHECK_THROWS. With JSON_NOEXCEPTION this aborted in "errors are those of const basic_json". Those comparisons are now compiled only with exceptions.
clang 3.6 (latent): another const json_view invalid; is now value-initialized.
Three new doc examples (basic_json_view__cbegin/cend/type_name.cpp) were reformatted with the pinned astyle. The "check" job runs astyle over the examples once it gets past the amalgamation step.

Verified with gcc:16 (linux/amd64, CI flags, C++11/C++20) and with a JSON_NOEXCEPTION build run as --no-throw.

— posted by Claude Code on behalf of @nlohmann

github-actions · 2026-09-30T06:10:36Z

🔴 Amalgamation check failed! 🔴

The source code has not been amalgamated and/or formatted correctly, or BUILD.bazel is out of date.

* Lookups (operator[], at, find, contains, count, value, JSON pointers) return the last member of a duplicate key, as materialize() and parse() keep it. * operator[] on a discarded view returns a discarded view instead of throwing, so v["a"]["b"] is safe for a missing "a". * operator[] and at() take any integer type (not only int and size_t), fixing ambiguous calls with unsigned, long, std::int64_t, ... * Fix the operator[] documentation, which claimed a discarded view for a type mismatch where type_error.305 is thrown. Signed-off-by: Niels Lohmann <mail@nlohmann.me>

…d its tests A view is tested with is_discarded(); the lookups in at(), value() and contains(json_pointer) and the unit tests no longer rely on the explicit conversion to bool. Signed-off-by: Niels Lohmann <mail@nlohmann.me>

…mporary root() of an rvalue document is deleted, because the views would dangle. Signed-off-by: Niels Lohmann <mail@nlohmann.me>

…xamples The explicit conversion to bool of basic_json_view is gone. Signed-off-by: Niels Lohmann <mail@nlohmann.me>

Looking up the last member of a duplicate key cannot stop at a match, so every lookup scanned the whole object (1.6 to 3.4 times slower for small objects). operator[](key), at, find, value, contains, count, and JSON pointer resolution return the first member again, as yyjson and simdjson do; materialize() and get<map>() keep the last value, as parse(). The documentation says so in the feature page and on each lookup page, and explains how to get the value parse() would give. The integer index templates and the discarded chaining of operator[] stay. Signed-off-by: Niels Lohmann <mail@nlohmann.me>

__forceinline makes MSVC report C4714 for function templates it cannot inline (get<std::string>), an error under /WX. The forced inlining is only a performance hint, so use plain inline there. Signed-off-by: Niels Lohmann <mail@nlohmann.me>

Mark the includes that are needed by design (json.hpp, the macro unscope, <tuple> for the tuple_size specialization), take size_t from <cstring>, and drop the forward declaration of basic_json_document that the friend declaration makes redundant. Signed-off-by: Niels Lohmann <mail@nlohmann.me>