Add json_document and json_view: parse, accept, types, materialize

The public classes of the zero-copy view (#5295), in the new header
<nlohmann/json_view.hpp>:

- basic_json_document<BasicJsonType>: parse (borrowing contiguous byte
  inputs, owning rvalue strings, streams, and other inputs), parse_copy,
  accept, read, root, is_discarded, source, owns_source, node_count,
  memory_usage, shrink_to_fit
- basic_json_view<BasicJsonType>: type and the is_* queries, size, empty,
  materialize (the value parse() would produce, built by the same SAX
  handler), source_offset
- the aliases json_document, json_view, ordered_json_document, and
  ordered_json_view

A parse error throws the exception basic_json::parse would throw for the
same input: the library parser is run on the failing input, so messages,
positions, and exception ids are the same. Inputs of 4 GiB or more are
rejected with out_of_range.416.

The single header single_include/nlohmann/json_view.hpp keeps including
json.hpp; make amalgamate, check-amalgamation, include.zip, and release
handle it.

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

BUILD.bazel

@@ -68,13 +68,18 @@ cc_library(
         "include/nlohmann/detail/value_t.hpp",
         "include/nlohmann/detail/view/builder.hpp",
         "include/nlohmann/detail/view/document_data.hpp",
+        "include/nlohmann/detail/view/errors.hpp",
+        "include/nlohmann/detail/view/input.hpp",
         "include/nlohmann/detail/view/macro_scope.hpp",
         "include/nlohmann/detail/view/macro_unscope.hpp",
+        "include/nlohmann/detail/view/materialize.hpp",
         "include/nlohmann/detail/view/node.hpp",
+        "include/nlohmann/detail/view/number.hpp",
         "include/nlohmann/detail/view/scan.hpp",
         "include/nlohmann/detail/view/string_ref.hpp",
         "include/nlohmann/json.hpp",
         "include/nlohmann/json_fwd.hpp",
+        "include/nlohmann/json_view.hpp",
         "include/nlohmann/ordered_map.hpp",
         "include/nlohmann/thirdparty/hedley/hedley.hpp",
         "include/nlohmann/thirdparty/hedley/hedley_undef.hpp",

Makefile

@@ -21,6 +21,7 @@ TESTS_SRCS=$(shell find tests -type f \( -name '*.hpp' -o -name '*.cpp' -o -name
 # the single headers (amalgamated from the source files)
 AMALGAMATED_FILE=single_include/nlohmann/json.hpp
 AMALGAMATED_FWD_FILE=single_include/nlohmann/json_fwd.hpp
+AMALGAMATED_VIEW_FILE=single_include/nlohmann/json_view.hpp
 
 
 ##########################################################################
@@ -29,7 +30,7 @@ AMALGAMATED_FWD_FILE=single_include/nlohmann/json_fwd.hpp
 
 # main target
 all:
-	@echo "amalgamate - amalgamate files single_include/nlohmann/json{,_fwd}.hpp from the include/nlohmann sources"
+	@echo "amalgamate - amalgamate files single_include/nlohmann/json{,_fwd,_view}.hpp from the include/nlohmann sources"
 	@echo "BUILD.bazel - regenerate the Bazel BUILD file from the include/nlohmann sources"
 	@echo "ChangeLog.md - generate ChangeLog file"
 	@echo "check-amalgamation - check whether sources have been amalgamated and BUILD.bazel is up to date"
@@ -154,14 +155,14 @@ install_astyle:
 
 # call the Artistic Style pretty printer on all source files
 pretty: install_astyle
-	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) docs/mkdocs/docs/examples/*.cpp
+	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_VIEW_FILE) docs/mkdocs/docs/examples/*.cpp
 
 # call the Clang-Format on all source files
 pretty_format:
 	for FILE in $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) docs/mkdocs/docs/examples/*.cpp; do echo $$FILE; clang-format -i $$FILE; done
 
 # create single header files and pretty print
-amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE)
+amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_VIEW_FILE)
 	$(MAKE) pretty
 
 # call the amalgamation tool for json.hpp
@@ -172,16 +173,23 @@ $(AMALGAMATED_FILE): $(SRCS)
 $(AMALGAMATED_FWD_FILE): $(SRCS)
 	tools/amalgamate/amalgamate.py -c tools/amalgamate/config_json_fwd.json -s . --verbose=yes
 
+# call the amalgamation tool for json_view.hpp (keeps including json.hpp)
+$(AMALGAMATED_VIEW_FILE): $(SRCS)
+	tools/amalgamate/amalgamate.py -c tools/amalgamate/config_json_view.json -s . --verbose=yes
+
 # check if file single_include/nlohmann/json.hpp has been amalgamated from the nlohmann sources
 # Note: this target is called by Travis
 check-amalgamation:
 	@mv $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~
 	@mv $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~
+	@mv $(AMALGAMATED_VIEW_FILE) $(AMALGAMATED_VIEW_FILE)~
 	@$(MAKE) amalgamate
 	@diff $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_FILE)~ $(AMALGAMATED_FILE) ; false)
 	@diff $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_FWD_FILE)~ $(AMALGAMATED_FWD_FILE) ; false)
+	@diff $(AMALGAMATED_VIEW_FILE) $(AMALGAMATED_VIEW_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_VIEW_FILE)~ $(AMALGAMATED_VIEW_FILE) ; false)
 	@mv $(AMALGAMATED_FILE)~ $(AMALGAMATED_FILE)
 	@mv $(AMALGAMATED_FWD_FILE)~ $(AMALGAMATED_FWD_FILE)
+	@mv $(AMALGAMATED_VIEW_FILE)~ $(AMALGAMATED_VIEW_FILE)
 	@mv BUILD.bazel BUILD.bazel~
 	@$(MAKE) BUILD.bazel
 	@diff BUILD.bazel BUILD.bazel~ || (echo "===================================================================\n  BUILD.bazel is out of date! Please run 'make BUILD.bazel'.\n===================================================================" ; mv BUILD.bazel~ BUILD.bazel ; false)
@@ -222,7 +230,7 @@ json.tar.xz:
 # We use `-X` to make the resulting ZIP file reproducible, see
 # <https://content.pivotal.io/blog/barriers-to-deterministic-reproducible-zip-files>.
 include.zip: BUILD.bazel
-	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
+	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_VIEW_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
 
 # Create the files for a release and add signatures and hashes.
 release: include.zip json.tar.xz
@@ -231,11 +239,13 @@ release: include.zip json.tar.xz
 	gpg --armor --detach-sig include.zip
 	gpg --armor --detach-sig $(AMALGAMATED_FILE)
 	gpg --armor --detach-sig $(AMALGAMATED_FWD_FILE)
+	gpg --armor --detach-sig $(AMALGAMATED_VIEW_FILE)
 	gpg --armor --detach-sig json.tar.xz
 	cp $(AMALGAMATED_FILE) release_files
 	cp $(AMALGAMATED_FWD_FILE) release_files
-	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
-	cd release_files ; shasum -a 256 json.hpp include.zip json.tar.xz > hashes.txt
+	cp $(AMALGAMATED_VIEW_FILE) release_files
+	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc $(AMALGAMATED_VIEW_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
+	cd release_files ; shasum -a 256 json.hpp json_view.hpp include.zip json.tar.xz > hashes.txt
 
 
 ##########################################################################

include/nlohmann/detail/view/errors.hpp

@@ -0,0 +1,81 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include <algorithm> // min
+#include <cstddef> // size_t
+#include <string> // string
+
+#include <nlohmann/json.hpp>
+#include <nlohmann/detail/view/builder.hpp>
+#include <nlohmann/detail/view/macro_scope.hpp>
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+namespace detail
+{
+namespace view
+{
+
+// Exceptions are thrown out of line, so that the accessors that may throw stay
+// small enough to be inlined.
+
+[[noreturn]] NLOHMANN_VIEW_NOINLINE inline void throw_type_error(int id, const char* prefix, const char* type)
+{
+    NLOHMANN_VIEW_THROW(type_error::create(id, concat(prefix, type), nullptr));
+}
+
+[[noreturn]] NLOHMANN_VIEW_NOINLINE inline void throw_out_of_range(int id, const std::string& msg)
+{
+    NLOHMANN_VIEW_THROW(out_of_range::create(id, msg, nullptr));
+}
+
+[[noreturn]] NLOHMANN_VIEW_NOINLINE inline void throw_invalid_iterator(int id, const char* msg)
+{
+    NLOHMANN_VIEW_THROW(invalid_iterator::create(id, msg, nullptr));
+}
+
+/*!
+@brief throw the exception BasicJsonType::parse would throw for this input
+
+The view accepts exactly the inputs parse() accepts, so on a failure the
+library parser is run on the same bytes: it throws the exception parse() would
+throw, with the same message, position, and "last read" token. The error path
+is cold, so this costs nothing on valid input. Should parse() accept the input
+nevertheless (a bug), the view's own failure is reported.
+*/
+template<typename BasicJsonType>
+[[noreturn]] NLOHMANN_VIEW_NOINLINE void throw_parse_failure(const parse_failure& f, const char* src, std::size_t size,
+        bool ignore_comments, bool ignore_trailing_commas)
+{
+    if (f.code == error_code::input_too_large)
+    {
+        NLOHMANN_VIEW_THROW(out_of_range::create(416, "input of 4 GiB or more is not supported by json_document", nullptr));
+    }
+    const BasicJsonType accepted = BasicJsonType::parse(src, src + size, nullptr, true, ignore_comments, ignore_trailing_commas);
+    static_cast<void>(accepted);
+
+    position_t pos;
+    const std::size_t off = (std::min)(f.offset, size);
+    pos.chars_read_total = off + 1;
+    std::size_t line_start = 0;
+    for (std::size_t i = 0; i < off; ++i)
+    {
+        if (src[i] == '\n')
+        {
+            ++pos.lines_read;
+            line_start = i + 1;
+        }
+    }
+    pos.chars_read_current_line = off + 1 - line_start;
+    NLOHMANN_VIEW_THROW(parse_error::create(101, pos, "syntax error while parsing value", nullptr));
+}
+
+}  // namespace view
+}  // namespace detail
+NLOHMANN_JSON_NAMESPACE_END

include/nlohmann/detail/view/input.hpp

@@ -0,0 +1,86 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include <string> // basic_string, char_traits, string
+#include <type_traits> // decay, integral_constant, is_array, is_lvalue_reference, is_pointer, is_same, remove_reference
+#include <utility> // forward
+
+#include <nlohmann/json.hpp>
+#include <nlohmann/detail/view/macro_scope.hpp>
+
+#if NLOHMANN_VIEW_HAS_CPP_17
+    #include <string_view> // string_view
+#endif
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+namespace detail
+{
+namespace view
+{
+
+/// how a document takes its input
+enum class input_kind
+{
+    move_string,  ///< rvalue std::string: owned without a copy
+    c_string,     ///< const char* (NUL-terminated): borrowed
+    char_array,   ///< char array (e.g. a string literal): borrowed
+    borrow_range, ///< lvalue contiguous byte container, or std::string_view: borrowed
+    copy_range,   ///< rvalue contiguous byte container: copied
+    adapter,      ///< anything else parse() accepts (streams, wide strings, ...): read into a buffer
+};
+
+template<typename InputType>
+struct classify_input
+{
+    using R = typename std::remove_reference<InputType>::type;
+    using D = typename std::decay<InputType>::type;
+    static constexpr bool is_rvalue = !std::is_lvalue_reference<InputType>::value;
+    static constexpr bool is_bytes = is_contiguous_byte_container<D>::value;
+#if NLOHMANN_VIEW_HAS_CPP_17
+    static constexpr bool is_string_view = std::is_same<D, std::string_view>::value;
+#else
+    static constexpr bool is_string_view = false;
+#endif
+    static constexpr input_kind value =
+        std::is_array<R>::value ? input_kind::char_array
+        : std::is_pointer<D>::value ? input_kind::c_string
+        : (is_rvalue && std::is_same<D, std::string>::value) ? input_kind::move_string
+        : (is_bytes && (!is_rvalue || is_string_view)) ? input_kind::borrow_range
+        : is_bytes ? input_kind::copy_range
+        : input_kind::adapter;
+};
+
+/// std::basic_string guarantees a NUL at data()[size()] (the parser's sentinel)
+template<typename T>
+struct is_std_string : std::false_type {};
+
+template<typename Traits, typename Alloc>
+struct is_std_string<std::basic_string<char, Traits, Alloc>> : std::true_type {};
+
+/// drain a json input adapter (UTF-16/32 inputs arrive as UTF-8)
+template<typename Adapter>
+std::string collect_adapter(Adapter&& ia)
+{
+    std::string buf;
+    for (;;)
+    {
+        const auto ch = ia.get_character();
+        if (ch == std::char_traits<char>::eof())
+        {
+            break;
+        }
+        buf.push_back(static_cast<char>(ch));
+    }
+    return buf;
+}
+
+}  // namespace view
+}  // namespace detail
+NLOHMANN_JSON_NAMESPACE_END

include/nlohmann/detail/view/macro_scope.hpp

@@ -37,6 +37,14 @@
     #define NLOHMANN_VIEW_NOINLINE
 #endif
 
+#if defined(__GNUC__) || defined(__clang__)
+    #define NLOHMANN_VIEW_NODISCARD __attribute__((warn_unused_result))
+#elif defined(_MSC_VER)
+    #define NLOHMANN_VIEW_NODISCARD _Check_return_
+#else
+    #define NLOHMANN_VIEW_NODISCARD
+#endif
+
 // exceptions as in json.hpp (JSON_NOEXCEPTION, JSON_THROW_USER)
 #if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION)
     #define NLOHMANN_VIEW_THROW(exception) throw exception

include/nlohmann/detail/view/macro_unscope.hpp

@@ -15,6 +15,7 @@
 #undef NLOHMANN_VIEW_UNLIKELY
 #undef NLOHMANN_VIEW_ALWAYS_INLINE
 #undef NLOHMANN_VIEW_NOINLINE
+#undef NLOHMANN_VIEW_NODISCARD
 #undef NLOHMANN_VIEW_THROW
 #undef NLOHMANN_VIEW_LITTLE_ENDIAN
 #undef NLOHMANN_VIEW_REPEAT16

include/nlohmann/detail/view/materialize.hpp

@@ -0,0 +1,130 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include <cstdint> // int64_t, uint8_t
+#include <vector> // vector
+
+#include <nlohmann/json.hpp>
+#include <nlohmann/detail/view/document_data.hpp>
+#include <nlohmann/detail/view/macro_scope.hpp>
+#include <nlohmann/detail/view/node.hpp>
+#include <nlohmann/detail/view/number.hpp>
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+namespace detail
+{
+namespace view
+{
+
+/*!
+@brief the basic_json value of the subtree at n
+
+The subtree is replayed into the SAX handler that parse() uses to build its
+values, so the result is the value parse() would produce: duplicate keys keep
+the last value, and with JSON_DIAGNOSTICS the parent pointers are set. It is
+iterative, so the nesting depth is limited by memory only, as for parse().
+Without a lexer the handler records no source positions
+(JSON_DIAGNOSTIC_POSITIONS).
+*/
+template<typename BasicJsonType>
+BasicJsonType materialize(const document_data& d, const node* n)
+{
+    using string_t = typename BasicJsonType::string_t;
+    using sax_t = json_sax_dom_parser<BasicJsonType, iterator_input_adapter<const char*>>;
+
+    BasicJsonType result;
+    sax_t sax(result, true);
+    const string_t no_token{};
+    // the ends of the open containers, and whether they are objects
+    std::vector<std::pair<const node*, bool>> open;
+    for (;;)
+    {
+        switch (static_cast<value_t>(n->kind))
+        {
+            case value_t::object:
+            case value_t::array:
+            {
+                const bool object = n->kind == static_cast<std::uint8_t>(value_t::object);
+                if (object)
+                {
+                    sax.start_object(n->len);
+                }
+                else
+                {
+                    sax.start_array(n->len);
+                }
+                open.emplace_back(document_data::child_end(n), object);
+                n = document_data::first_child(n);
+                break;
+            }
+            case value_t::string:
+            {
+                string_t s(d.str(*n), n->len);
+                sax.string(s);
+                ++n;
+                break;
+            }
+            case value_t::number_integer:
+                sax.number_integer(static_cast<typename BasicJsonType::number_integer_t>(static_cast<std::int64_t>(integer_bits(*n))));
+                ++n;
+                break;
+            case value_t::number_unsigned:
+                sax.number_unsigned(static_cast<typename BasicJsonType::number_unsigned_t>(integer_bits(*n)));
+                ++n;
+                break;
+            case value_t::number_float:
+                sax.number_float(float_value<typename BasicJsonType::number_float_t>(d.str(*n), *n), no_token);
+                ++n;
+                break;
+            case value_t::boolean:
+                sax.boolean((n->flags & node_flags::is_true) != 0);
+                ++n;
+                break;
+            case value_t::null:
+            case value_t::binary:
+            case value_t::discarded:
+            default:
+                sax.null();
+                ++n;
+                break;
+        }
+        for (;;)
+        {
+            if (open.empty())
+            {
+                return result;
+            }
+            if (n != open.back().first)
+            {
+                break;
+            }
+            if (open.back().second)
+            {
+                sax.end_object();
+            }
+            else
+            {
+                sax.end_array();
+            }
+            open.pop_back();
+        }
+        if (open.back().second)
+        {
+            // the key of the next member
+            string_t key(d.str(*n), n->len);
+            sax.key(key);
+            ++n;
+        }
+    }
+}
+
+}  // namespace view
+}  // namespace detail
+NLOHMANN_JSON_NAMESPACE_END

include/nlohmann/detail/view/number.hpp

@@ -0,0 +1,73 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include <cstddef> // size_t
+#include <string> // string
+
+#include <nlohmann/json.hpp>
+#include <nlohmann/detail/view/macro_scope.hpp>
+#include <nlohmann/detail/view/node.hpp>
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+namespace detail
+{
+namespace view
+{
+
+/*!
+@brief the value of the float token of a node, as parse() converts it
+
+Uses the lexer's conversion (detail::convert_float_fast, then the locale-aware
+strtod fallback), so that the values are bit-identical to parse(). The digit
+layout recorded while parsing locates the decimal point and the exponent
+without scanning the token.
+*/
+template<typename FloatType>
+NLOHMANN_VIEW_NOINLINE FloatType float_value(const char* first, const node& n)
+{
+    const char* const last = first + n.len;
+    const std::size_t neg = first[0] == '-' ? 1 : 0;
+    const std::size_t int_digits = n.extra & 0xFFu;
+    const std::size_t frac_digits = n.extra >> 8u;
+    std::size_t dot = std::string::npos;
+    std::size_t mantissa_end = n.len;
+    if (int_digits != 255 && frac_digits != 255)
+    {
+        dot = frac_digits != 0 ? neg + int_digits : std::string::npos;
+        mantissa_end = neg + int_digits + (frac_digits != 0 ? 1 + frac_digits : 0);
+    }
+    else
+    {
+        // more digits than the layout records: locate them
+        for (std::size_t i = 0; i < n.len; ++i)
+        {
+            if (first[i] == '.')
+            {
+                dot = i;
+            }
+            else if (first[i] == 'e' || first[i] == 'E')
+            {
+                mantissa_end = i;
+                break;
+            }
+        }
+    }
+    FloatType v{};
+    if (!convert_float_fast(first, last, dot, mantissa_end, v))
+    {
+        std::string token(first, last);
+        convert_float_locale_aware(token, dot, v);
+    }
+    return v;
+}
+
+}  // namespace view
+}  // namespace detail
+NLOHMANN_JSON_NAMESPACE_END

include/nlohmann/json_view.hpp

@@ -0,0 +1,591 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+/****************************************************************************\
+ * Zero-copy, read-only view of a parsed JSON text.                          *
+ *                                                                           *
+ * json_document::parse() builds a flat index of the values of a JSON text   *
+ * (16 bytes per value) instead of a tree of basic_json values. Strings and  *
+ * numbers stay in the source text; only strings with escapes are decoded,   *
+ * into one buffer. json_view is a handle to one value of the document, with *
+ * the read-only part of the basic_json interface; materialize() turns a     *
+ * subtree into the basic_json value that parse() would produce.             *
+ *                                                                           *
+ * The source text must outlive a document that borrows it (lvalue byte     *
+ * containers, C strings); rvalue strings, streams, and other inputs are     *
+ * owned by the document.                                                    *
+\****************************************************************************/
+
+#ifndef INCLUDE_NLOHMANN_JSON_VIEW_HPP_
+#define INCLUDE_NLOHMANN_JSON_VIEW_HPP_
+
+#include <cstddef> // size_t
+#include <cstring> // memcpy, strlen
+#include <iterator> // distance, input_iterator_tag, iterator_traits
+#include <memory> // unique_ptr
+#include <string> // string
+#include <type_traits> // enable_if, integral_constant, is_base_of, is_integral, is_same, remove_cv, remove_extent
+#include <utility> // forward, move
+
+#include <nlohmann/json.hpp>
+
+// the view builds on internals of the library: both must be the same version
+#if NLOHMANN_JSON_VERSION_MAJOR != 3 || NLOHMANN_JSON_VERSION_MINOR != 12 || NLOHMANN_JSON_VERSION_PATCH != 0
+    #error "json_view.hpp requires json.hpp of the same version (3.12.0)"
+#endif
+
+#include <nlohmann/detail/view/builder.hpp>
+#include <nlohmann/detail/view/document_data.hpp>
+#include <nlohmann/detail/view/errors.hpp>
+#include <nlohmann/detail/view/input.hpp>
+#include <nlohmann/detail/view/macro_scope.hpp>
+#include <nlohmann/detail/view/materialize.hpp>
+#include <nlohmann/detail/view/node.hpp>
+#include <nlohmann/detail/view/string_ref.hpp>
+
+NLOHMANN_JSON_NAMESPACE_BEGIN
+
+template<typename BasicJsonType>
+class basic_json_document;
+
+/*!
+@brief read-only handle to one value of a basic_json_document
+
+Trivially copyable (two pointers). Valid as long as the document is alive and
+has not been re-parsed, and as long as a borrowed source text is alive.
+*/
+template<typename BasicJsonType>
+class basic_json_view
+{
+    using node = detail::view::node;
+    using document_data = detail::view::document_data;
+
+  public:
+    using value_t = detail::value_t;
+    using string_t = typename BasicJsonType::string_t;
+    using number_integer_t = typename BasicJsonType::number_integer_t;
+    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
+    using number_float_t = typename BasicJsonType::number_float_t;
+    using json_pointer = typename BasicJsonType::json_pointer;
+    using size_type = std::size_t;
+    /// std::string_view from C++17 on
+    using string_view_t = detail::view::string_ref;
+
+    /// an invalid view (type() == value_t::discarded)
+    basic_json_view() noexcept = default;
+
+    //////////
+    // type //
+    //////////
+
+    NLOHMANN_VIEW_ALWAYS_INLINE value_t type() const noexcept
+    {
+        return m_node != nullptr ? static_cast<value_t>(m_node->kind) : value_t::discarded;
+    }
+
+    bool is_null() const noexcept
+    {
+        return type() == value_t::null;
+    }
+
+    bool is_boolean() const noexcept
+    {
+        return type() == value_t::boolean;
+    }
+
+    bool is_number() const noexcept
+    {
+        return is_number_integer() || is_number_float();
+    }
+
+    bool is_number_integer() const noexcept
+    {
+        return type() == value_t::number_integer || type() == value_t::number_unsigned;
+    }
+
+    bool is_number_unsigned() const noexcept
+    {
+        return type() == value_t::number_unsigned;
+    }
+
+    bool is_number_float() const noexcept
+    {
+        return type() == value_t::number_float;
+    }
+
+    bool is_string() const noexcept
+    {
+        return type() == value_t::string;
+    }
+
+    bool is_array() const noexcept
+    {
+        return type() == value_t::array;
+    }
+
+    bool is_object() const noexcept
+    {
+        return type() == value_t::object;
+    }
+
+    /// always false: JSON text has no binary values
+    bool is_binary() const noexcept
+    {
+        return false;
+    }
+
+    bool is_primitive() const noexcept
+    {
+        return is_null() || is_string() || is_boolean() || is_number();
+    }
+
+    bool is_structured() const noexcept
+    {
+        return is_array() || is_object();
+    }
+
+    /// the root of a failed parse with allow_exceptions == false, or a
+    /// default-constructed view
+    bool is_discarded() const noexcept
+    {
+        return type() == value_t::discarded;
+    }
+
+    /// false for discarded views
+    explicit operator bool() const noexcept
+    {
+        return m_node != nullptr;
+    }
+
+    //////////////
+    // capacity //
+    //////////////
+
+    /// the number of elements (arrays, objects), 0 for null and discarded,
+    /// 1 otherwise, as basic_json::size()
+    size_type size() const noexcept
+    {
+        switch (type())
+        {
+            case value_t::null:
+            case value_t::discarded:
+                return 0;
+            case value_t::array:
+            case value_t::object:
+                return m_node->len;
+            case value_t::string:
+            case value_t::boolean:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::number_float:
+            case value_t::binary:
+            default:
+                return 1;
+        }
+    }
+
+    /// as basic_json::empty()
+    bool empty() const noexcept
+    {
+        switch (type())
+        {
+            case value_t::null:
+            case value_t::discarded:
+                return true;
+            case value_t::array:
+            case value_t::object:
+                return m_node->len == 0;
+            case value_t::string:
+            case value_t::boolean:
+            case value_t::number_integer:
+            case value_t::number_unsigned:
+            case value_t::number_float:
+            case value_t::binary:
+            default:
+                return false;
+        }
+    }
+
+    /////////////////
+    // materialize //
+    /////////////////
+
+    /// the basic_json value of this subtree, as parse() would produce it
+    /// (a discarded value for a discarded view)
+    BasicJsonType materialize() const
+    {
+        if (m_node == nullptr)
+        {
+            return BasicJsonType(value_t::discarded);
+        }
+        return detail::view::materialize<BasicJsonType>(*m_doc, m_node);
+    }
+
+    /// byte offset of this value in the source text (for strings: of the
+    /// first byte after the opening quote); static_cast<std::size_t>(-1) for
+    /// a discarded view and for strings with escapes, which are decoded
+    std::size_t source_offset() const noexcept
+    {
+        return m_node != nullptr && (m_node->flags & detail::view::node_flags::storage) == 0
+               ? m_node->off : static_cast<std::size_t>(-1);
+    }
+
+  private:
+    template<typename> friend class basic_json_document;
+
+    basic_json_view(const document_data* d, const node* n) noexcept
+        : m_doc(d), m_node(n)
+    {}
+
+    const document_data* m_doc = nullptr;
+    const node* m_node = nullptr;
+};
+
+/*!
+@brief a parsed JSON text: owns the node index (and, optionally, the text)
+
+Borrowed parses keep a pointer to the caller's text, which must outlive the
+document. Owned parses (parse_copy, rvalue std::string, streams, and inputs
+that are not contiguous byte ranges) keep their own copy.
+*/
+template<typename BasicJsonType>
+class basic_json_document
+{
+    using document_data = detail::view::document_data;
+
+    static_assert(sizeof(typename BasicJsonType::number_integer_t) == 8 && sizeof(typename BasicJsonType::number_unsigned_t) == 8,
+                  "json_view supports 64-bit integer types only");
+
+  public:
+    using view_type = basic_json_view<BasicJsonType>;
+    using value_t = detail::value_t;
+
+    /// an empty (discarded) document
+    basic_json_document() = default;
+    basic_json_document(basic_json_document&&) noexcept = default;
+    basic_json_document& operator=(basic_json_document&&) noexcept = default;
+    basic_json_document(const basic_json_document&) = delete;
+    basic_json_document& operator=(const basic_json_document&) = delete;
+    ~basic_json_document() = default;
+
+    /////////////
+    // parsing //
+    /////////////
+
+    /// parse a JSON text; contiguous byte inputs are borrowed, everything else
+    /// (and rvalue std::string) is owned
+    template<typename InputType>
+    NLOHMANN_VIEW_NODISCARD
+    static basic_json_document parse(InputType&& input,
+                                     const bool allow_exceptions = true,
+                                     const bool ignore_comments = false,
+                                     const bool ignore_trailing_commas = false)
+    {
+        basic_json_document d;
+        d.read(std::forward<InputType>(input), allow_exceptions, ignore_comments, ignore_trailing_commas);
+        return d;
+    }
+
+    /// parse [first, last)
+    template<typename IteratorType, typename std::enable_if<
+                 std::is_base_of<std::input_iterator_tag, typename std::iterator_traits<IteratorType>::iterator_category>::value, int>::type = 0>
+    NLOHMANN_VIEW_NODISCARD
+    static basic_json_document parse(IteratorType first, IteratorType last,
+                                     const bool allow_exceptions = true,
+                                     const bool ignore_comments = false,
+                                     const bool ignore_trailing_commas = false)
+    {
+        basic_json_document d;
+        d.read_range(first, last, allow_exceptions, ignore_comments, ignore_trailing_commas);
+        return d;
+    }
+
+    /// parse a copy of the input; the document does not depend on it afterwards
+    template<typename InputType>
+    NLOHMANN_VIEW_NODISCARD
+    static basic_json_document parse_copy(InputType&& input,
+                                          const bool allow_exceptions = true,
+                                          const bool ignore_comments = false,
+                                          const bool ignore_trailing_commas = false)
+    {
+        basic_json_document d;
+        d.build_owned(collect(std::forward<InputType>(input)), allow_exceptions, ignore_comments, ignore_trailing_commas);
+        return d;
+    }
+
+    /// check whether the input is valid JSON (the result of basic_json::accept)
+    template<typename InputType>
+    static bool accept(InputType&& input, const bool ignore_comments = false, const bool ignore_trailing_commas = false)
+    {
+        basic_json_document d;
+        d.read(std::forward<InputType>(input), false, ignore_comments, ignore_trailing_commas);
+        return !d.is_discarded();
+    }
+
+    /// parse into this document, reusing its memory
+    template<typename InputType>
+    void read(InputType&& input,
+              const bool allow_exceptions = true,
+              const bool ignore_comments = false,
+              const bool ignore_trailing_commas = false)
+    {
+        read_kind(std::forward<InputType>(input), allow_exceptions, ignore_comments, ignore_trailing_commas,
+                  std::integral_constant<detail::view::input_kind, detail::view::classify_input<InputType>::value> {});
+    }
+
+    ////////////
+    // access //
+    ////////////
+
+    /// the root value (discarded if parsing failed without exceptions)
+    view_type root() const noexcept
+    {
+        if (!m_data || m_data->discarded)
+        {
+            return view_type();
+        }
+        return view_type(m_data.get(), m_data->tape);
+    }
+
+    bool is_discarded() const noexcept
+    {
+        return !m_data || m_data->discarded;
+    }
+
+    /// the parsed text
+    typename view_type::string_view_t source() const noexcept
+    {
+        return m_data ? typename view_type::string_view_t(m_data->src, m_data->size) : typename view_type::string_view_t();
+    }
+
+    /// whether the document holds its own copy of the text
+    bool owns_source() const noexcept
+    {
+        return m_data && !m_data->owned.empty() && m_data->src == m_data->owned.data();
+    }
+
+    /// number of index nodes (values plus object keys)
+    std::size_t node_count() const noexcept
+    {
+        return m_data ? m_data->tape_size : 0;
+    }
+
+    /// bytes held by the document (index, decoded strings, owned text)
+    std::size_t memory_usage() const noexcept
+    {
+        if (!m_data)
+        {
+            return 0;
+        }
+        return sizeof(document_data) + (m_data->inline_cap * sizeof(detail::view::node))
+               + (m_data->tape != m_data->inline_tape ? m_data->tape_cap * sizeof(detail::view::node) : 0)
+               + m_data->arena.capacity() + m_data->owned.capacity();
+    }
+
+    /// release unused capacity of the index and the decoded strings; like
+    /// std::vector::shrink_to_fit, this invalidates the views of the document
+    /// (take new ones from root())
+    void shrink_to_fit()
+    {
+        if (!m_data)
+        {
+            return;
+        }
+        using node = detail::view::node;
+        document_data& d = *m_data;
+
+        // allocate everything first, so that an exception leaves the document
+        // unchanged
+        const bool shrink_arena = d.arena.capacity() > d.arena.size();
+        std::string arena(shrink_arena ? d.arena : std::string());
+        const bool shrink_tape = d.tape != d.inline_tape && d.tape_size != d.tape_cap;
+        const bool into_header = d.tape_size <= d.inline_cap;
+        node* fresh = (shrink_tape && !into_header) ? static_cast<node*>(::operator new (d.tape_size * sizeof(node))) : d.inline_tape;
+
+        if (shrink_tape)
+        {
+            std::memcpy(fresh, d.tape, d.tape_size * sizeof(node));
+            ::operator delete (d.tape);
+            d.tape = fresh;
+            d.tape_cap = into_header ? d.inline_cap : d.tape_size;
+        }
+        if (shrink_arena)
+        {
+            d.arena.swap(arena);
+            d.base[1] = d.arena.data();
+        }
+    }
+
+  private:
+    using input_kind = detail::view::input_kind;
+
+    /// create the storage (sized for the input) on first use
+    void ensure_data(const char* src, std::size_t size)
+    {
+        if (!m_data)
+        {
+            m_data.reset(document_data::create(detail::view::estimate_nodes(src, size)));
+        }
+    }
+
+    /// parse a buffer the document takes ownership of
+    void build_owned(std::string&& buf, bool allow_exceptions, bool comments, bool trailing_commas)
+    {
+        ensure_data(buf.data(), buf.size());
+        m_data->owned = std::move(buf);
+        build(m_data->owned.data(), m_data->owned.size(), allow_exceptions, comments, trailing_commas, true, true);
+    }
+
+    /// sentinel: src[size] is readable and 0 (std::string, C strings)
+    void build(const char* src, std::size_t size, bool allow_exceptions, bool comments, bool trailing_commas, bool owned, bool sentinel)
+    {
+        ensure_data(src, size);
+        document_data& d = *m_data;
+        if (!owned)
+        {
+            d.owned.clear();
+        }
+        d.src = src;
+        d.size = size;
+        d.tape_size = 0;
+        d.arena.clear();
+        d.discarded = true;
+        detail::view::parse_failure failure;
+        bool ok = false;
+        if (NLOHMANN_VIEW_UNLIKELY(size >= 0xFFFFFFF0u))
+        {
+            failure.code = detail::view::error_code::input_too_large;
+        }
+        else
+        {
+            ok = detail::view::build < !detail::abi_config::strict_nul_handling > (d, src, size, comments, trailing_commas, sentinel, failure);
+        }
+        if (NLOHMANN_VIEW_LIKELY(ok))
+        {
+            d.base[0] = d.src;
+            d.base[1] = d.arena.data();
+            d.discarded = false;
+            return;
+        }
+        if (allow_exceptions)
+        {
+            detail::view::throw_parse_failure<BasicJsonType>(failure, src, size, comments, trailing_commas);
+        }
+    }
+
+    // --- input dispatch (see detail::view::input_kind) ---
+
+    void read_kind(std::string&& s, bool ae, bool c, bool tc, std::integral_constant<input_kind, input_kind::move_string> /*unused*/)
+    {
+        build_owned(std::move(s), ae, c, tc);
+    }
+
+    template<typename CharT>
+    void read_kind(CharT* s, bool ae, bool c, bool tc, std::integral_constant<input_kind, input_kind::c_string> /*unused*/)
+    {
+        static_assert(sizeof(CharT) == 1 && std::is_integral<typename std::remove_cv<CharT>::type>::value, "json_view parses byte (char-like) input");
+        if (s == nullptr)
+        {
+            build("", 0, ae, c, tc, false, true);
+            return;
+        }
+        const char* cs = reinterpret_cast<const char*>(s); // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+        build(cs, std::strlen(cs), ae, c, tc, false, true);
+    }
+
+    template<typename Array>
+    void read_kind(Array& a, bool ae, bool c, bool tc, std::integral_constant<input_kind, input_kind::char_array> /*unused*/)
+    {
+        using CharT = typename std::remove_cv<typename std::remove_extent<Array>::type>::type;
+        static_assert(sizeof(CharT) == 1 && std::is_integral<CharT>::value, "json_view parses byte (char-like) input");
+        const std::size_t n = std::extent<Array>::value;
+        // a trailing NUL (string literals) is not part of the text, as for
+        // parse(), and serves as sentinel
+        const bool terminated = n > 0 && a[n - 1] == 0 && (!detail::abi_config::strict_nul_handling || std::is_same<CharT, char>::value);
+        build(reinterpret_cast<const char*>(&a[0]), terminated ? n - 1 : n, ae, c, tc, false, terminated); // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+    }
+
+    template<typename T>
+    void read_kind(T&& s, bool ae, bool c, bool tc, std::integral_constant<input_kind, input_kind::borrow_range> /*unused*/)
+    {
+        // std::basic_string guarantees data()[size()] == 0: use it as sentinel
+        build(s.size() == 0 ? "" : reinterpret_cast<const char*>(s.data()), static_cast<std::size_t>(s.size()), ae, c, tc, false, // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+              detail::view::is_std_string<typename std::decay<T>::type>::value || s.size() == 0);
+    }
+
+    template<typename T>
+    void read_kind(T&& s, bool ae, bool c, bool tc, std::integral_constant<input_kind, input_kind::copy_range> /*unused*/)
+    {
+        build_owned(std::string(reinterpret_cast<const char*>(s.data()), static_cast<std::size_t>(s.size())), ae, c, tc); // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+    }
+
+    template<typename T>
+    void read_kind(T&& input, bool ae, bool c, bool tc, std::integral_constant<input_kind, input_kind::adapter> /*unused*/)
+    {
+        build_owned(detail::view::collect_adapter(detail::input_adapter(std::forward<T>(input))), ae, c, tc);
+    }
+
+    template<typename IteratorType>
+    void read_range(IteratorType first, IteratorType last, bool ae, bool c, bool tc)
+    {
+        using value_type = typename std::remove_cv<typename std::iterator_traits<IteratorType>::value_type>::type;
+        // borrow the range where the library's input adapter scans it as one
+        // block: pointers and, in C++20, contiguous iterators (std::vector,
+        // std::string, ...) over single bytes
+        read_range_impl(first, last, ae, c, tc, std::integral_constant < bool, std::is_integral<value_type>::value
+                        && detail::iterator_input_adapter<IteratorType>::supports_bulk_scan > {});
+    }
+
+    template<typename IteratorType>
+    void read_range_impl(IteratorType first, IteratorType last, bool ae, bool c, bool tc, std::true_type /*contiguous bytes*/)
+    {
+        const auto size = static_cast<std::size_t>(std::distance(first, last));
+        build(size == 0 ? "" : reinterpret_cast<const char*>(&*first), size, ae, c, tc, false, size == 0); // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+    }
+
+    template<typename IteratorType>
+    void read_range_impl(IteratorType first, IteratorType last, bool ae, bool c, bool tc, std::false_type /*other*/)
+    {
+        build_owned(detail::view::collect_adapter(detail::input_adapter(first, last)), ae, c, tc);
+    }
+
+    template<typename T>
+    static std::string collect(T&& input)
+    {
+        return collect_impl(std::forward<T>(input), std::integral_constant<bool, detail::is_contiguous_byte_container<typename std::decay<T>::type>::value> {});
+    }
+
+    template<typename T>
+    static std::string collect_impl(T&& s, std::true_type /*contiguous*/)
+    {
+        return std::string(reinterpret_cast<const char*>(s.data()), static_cast<std::size_t>(s.size())); // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+    }
+
+    template<typename T>
+    static std::string collect_impl(T&& s, std::false_type /*other*/)
+    {
+        return detail::view::collect_adapter(detail::input_adapter(std::forward<T>(s)));
+    }
+
+    std::unique_ptr<document_data, document_data::deleter> m_data{};
+};
+
+/// a parsed JSON text for json
+using json_document = basic_json_document<json>;
+/// a value of a json_document
+using json_view = basic_json_view<json>;
+/// a parsed JSON text for ordered_json
+using ordered_json_document = basic_json_document<ordered_json>;
+/// a value of an ordered_json_document
+using ordered_json_view = basic_json_view<ordered_json>;
+
+NLOHMANN_JSON_NAMESPACE_END
+
+#include <nlohmann/detail/view/macro_unscope.hpp>
+
+#endif  // INCLUDE_NLOHMANN_JSON_VIEW_HPP_