Add json_document and json_view: node index, parser, and document

[nlohmann]

Part of the stack for the zero-copy view (#5295). This adds the internal node index and parser, and the public json_document/json_view classes built on it. Element access, values, dump(), and comparisons follow in later PRs, so each one stays reviewable.

#include <nlohmann/json_view.hpp>

std::string text = receive();
auto doc = nlohmann::json_document::parse(text);   // borrows text
nlohmann::json_view root = doc.root();
if (root.is_object() && !root.empty())
{
    nlohmann::json j = root.materialize();          // the value json::parse(text) returns
}

Summary

• A parse produces a flat array of 16-byte nodes in document order: one node per value, and one per object key.
  • Strings stay in the source text, and escaped strings are decoded into an arena.
  • Integers are converted while their digits are in the cache.
  • Floats keep only their digit layout; they are converted when read, with the library's float converter from Speed up the lexer: own float parser, string scan, and \u table #5738 (independent of the locale, no allocation).
  • Containers store the size of their subtree, so a reader can step over one in constant time.
  • Nothing is allocated per value: a document makes a handful of allocations, however many values it has. The node count is checked against max_nodes() when the index grows; beyond it, std::bad_alloc is thrown.
• The parser accepts exactly what json::parse accepts: every combination of ignore_comments and ignore_trailing_commas, with and without a trailing NUL, and under JSON_STRICT_NUL_HANDLING. It is portable C++11, and nothing depends on the byte order: words are read in a fixed order, node fields are written explicitly, and literals are compared with memcmp. The SIMD kernels come later in the stack.
• The parse state lives in a local cursor whose address never escapes, so it stays in registers; cold paths (errors, regrowth, escapes, comments) are out-of-line members.
• basic_json_document<BasicJsonType>: parse, parse_copy, accept, read (reuses the document's memory), root, is_discarded, source, owns_source, node_count, memory_usage, shrink_to_fit.
• basic_json_view<BasicJsonType>: type, the is_* queries, size, empty, materialize, source_offset.
• Aliases: json_document, json_view, ordered_json_document, ordered_json_view.
• Input: borrowed (lvalue contiguous byte containers, std::string_view, C strings, character arrays, pointer ranges, and in C++20 other contiguous iterator ranges) or owned (a non-const rvalue std::string, moved in; a const rvalue std::string and other rvalue byte containers, copied; streams and wide strings, read into a buffer). A FILE* and pointers to or arrays of wide characters are rejected at compile time.
  • parse, parse_copy, accept, and read with an integer as the second argument are deleted: parse(ptr, len) would silently convert len to allow_exceptions and read ptr with strlen. Use parse(ptr, ptr + len).
• Errors: a parse error throws the exception basic_json::parse would throw for the same input. The library parser runs on the failing input (a cold path), so message, position, and id match.
• Input limit: inputs of 4294967280 bytes (4 GiB minus 16) or more are rejected with the new out_of_range.416 ("input of 4294967280 bytes or more is not supported by json_document").
• materialize(): builds the value with the SAX handler parse() uses, so JSON_DIAGNOSTICS parent pointers are set as usual.
• root() of a temporary document is deleted: the view would dangle. Give the document a name first.
• detail::abi_config keeps JSON_STRICT_NUL_HANDLING readable after json.hpp undefines it at its end, in the ABI namespace, which already encodes the setting, so it always matches the basic_json in use.
• Docs and tooling: a feature page, API pages and examples for both classes, the architecture description of the node index, out_of_range.416 in exceptions.md, the C++20 module exports, an amalgamated single_include/nlohmann/json_view.hpp (make amalgamate, check_amalgamation), a fuzzer, the benchmarks, Bazel, and the aspect: json_view label in labeler.yml.

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. json_document::parse vs json::parse (both at this PR):

	Apple M1	x86-64 GCC	x86-64 Clang
canada	1012 vs 7633 (7.5×)	1991 vs 14672 (7.4×)	2239 vs 15589 (7.0×)
citm_catalog	390 vs 2961 (7.6×)	877 vs 7646 (8.7×)	929 vs 6722 (7.2×)
twitter	244 vs 1413 (5.8×)	538 vs 4027 (7.5×)	508 vs 4024 (7.9×)

The core library is unaffected: this PR only adds code under include/nlohmann/detail/view/ and the new public header json_view.hpp. json.hpp only gains the internal detail::abi_config constant and one include.

Tests

• unit-json_view_builder.cpp: the node index compared with json::parse for handwritten, generated, and damaged documents under all option combinations; input from std::string and from exact-size buffers with no read past the input under AddressSanitizer; deep nesting up to 100,000 levels; NUL, BOM, and whitespace cases; node integer bits and the array size limit; and the test-suite files.
• unit-json_view.cpp: materialize() equals parse() for handwritten and generated documents, with duplicate keys, deep nesting, and JSON_DIAGNOSTICS parents; parse errors equal parse()'s, message included, for malformed inputs under all option combinations; every input kind, borrowed or owned; integer arguments and root() of a temporary document do not compile; the input size limit; reuse with read(), moves, shrink_to_fit(), and source offsets.
• unit-json_view_macros.cpp: includes the header without JSON_TEST_KEEP_MACROS, as users do, and checks that the view relies on no macro json.hpp undefines and leaks none of its own NLOHMANN_VIEW_* macros.
• Fuzzer (fuzzer-parse_json_view.cpp): accept, value, and exception parity with json::parse, for a std::string and an exact-size byte vector, with and without comments and trailing commas.

Public API

No breaking changes. Everything is new and additive; nothing existing changes. The view API is new in this stack, so the following decisions are not breaking relative to a release, but they are visible to users:

• New header <nlohmann/json_view.hpp> with basic_json_document, basic_json_view, and the aliases json_document, json_view, ordered_json_document, ordered_json_view.
• json_view has no operator bool: write !v.is_discarded().
• root() of an rvalue document is deleted (it would dangle); use a named document.
• parse, parse_copy, accept, and read with an integer second argument do not compile (deleted overloads).
• A const rvalue std::string is copied, not moved.
• A new exception id, out_of_range.416 (input of 4294967280 bytes or more).
• basic_json_document<BasicJsonType> requires 64-bit integer types (static_assert).
• The C++20 module exports the new names.
• json.hpp gains the internal detail::abi_config constant (not part of the public API).

---

Written by Claude Code.

🤖 Generated with Claude Code

[nlohmann]

CI fixes for this PR (commits 87a041a and ab4f646):

• msvc (Debug, Win32, default): C4127 (conditional expression is constant) for TrailingCommas && cur() == ']', ... == '}' and Comments && cur() == '/' in detail/view/builder.hpp when the option is off. The template arguments now go through a static enabled(bool) function, the same approach as nesting_depth_exhausted() in json.hpp. Not reproduced locally (no MSVC here).
• ci_test_single_header: unit-json_view_builder.cpp includes nlohmann/detail/view/*.hpp, which is not in single_include/. At this point in the stack, the test is built only with multiple headers. From Add json_document and json_view: parse, accept, types, materialize #5621 on, it includes <nlohmann/json_view.hpp> in single-header mode instead.
• ci_test_gcc (not visible before, because the build stopped at an earlier error): -Werror=useless-cast on static_cast<std::size_t>(guess + (guess / 4) + 64) in builder::grow(), since std::uint64_t is std::size_t on Linux x86-64. The sum is now cast through a named variable. GCC does not report a cast of an lvalue.
• The remaining GCC failures were inherited from 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.

Verified with the CI's own image gcc:16 (linux/amd64) and the CI warning flags, for C++11 and C++20: the builder test builds and passes. A CMake configure with -DJSON_MultipleHeaders=OFF no longer lists the builder test.

— posted by Claude Code on behalf of @nlohmann

[github-actions]

🔴 Amalgamation check failed! 🔴

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

📎 A ready-to-apply patch is attached to the failed workflow run as the amalgamation-patch artifact. Download it, then apply it locally from the repository root with:

git apply amalgamation.patch

This does not require installing astyle yourself.