Document json_document and json_view

- API pages for basic_json_document and basic_json_view, one per member,
  and for the four aliases, each with an example
- features/json_view.md: the problem the view solves, ownership and
  lifetime, what matches basic_json::parse() and what differs, and when
  to choose json, ordered_json, SAX, or the view
- the examples show why one would use the view, not only how: borrowed
  vs. owned input, reading a few fields and materializing one subtree,
  reusing a document across many messages
- registered in the mkdocs navigation, llms.txt, the docset, the
  exceptions page (out_of_range.416), architecture.md, the integration
  page, and the README; the yyjson credit is added to the README and
  license.md

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

docs/mkdocs/docs/api/basic_json/empty.md

@@ -60,6 +60,10 @@ itself is empty which is `#!cpp false` in the case of a string.
     --8<-- "examples/empty.output"
     ```
 
+## See also
+
+- [basic_json_view::empty](../basic_json_view/empty.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_array.md

@@ -34,6 +34,10 @@ Constant.
     --8<-- "examples/is_array.output"
     ```
 
+## See also
+
+- [basic_json_view::is_array](../basic_json_view/is_array.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_binary.md

@@ -34,6 +34,10 @@ Constant.
     --8<-- "examples/is_binary.output"
     ```
 
+## See also
+
+- [basic_json_view::is_binary](../basic_json_view/is_binary.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 3.8.0.

docs/mkdocs/docs/api/basic_json/is_boolean.md

@@ -34,6 +34,10 @@ Constant.
     --8<-- "examples/is_boolean.output"
     ```
 
+## See also
+
+- [basic_json_view::is_boolean](../basic_json_view/is_boolean.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_discarded.md

@@ -69,6 +69,11 @@ with `allow_exceptions` set to `#!cpp false`: a parse error then yields a discar
     --8<-- "examples/is_discarded.output"
     ```
 
+## See also
+
+- [basic_json_view::is_discarded](../basic_json_view/is_discarded.md) - the corresponding check on a zero-copy view,
+  which is `#!cpp true` if the view refers to no value
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_null.md

@@ -34,6 +34,10 @@ Constant.
     --8<-- "examples/is_null.output"
     ```
 
+## See also
+
+- [basic_json_view::is_null](../basic_json_view/is_null.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_number.md

@@ -49,6 +49,7 @@ constexpr bool is_number() const noexcept
 - [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
 - [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
 - [is_number_float()](is_number_float.md) check if the value is a floating-point number
+- [basic_json_view::is_number](../basic_json_view/is_number.md) - the same check on a zero-copy view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/is_number_float.md

@@ -40,6 +40,7 @@ Constant.
 - [is_number()](is_number.md) check if the value is a number
 - [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
 - [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
+- [basic_json_view::is_number_float](../basic_json_view/is_number_float.md) - the same check on a zero-copy view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/is_number_integer.md

@@ -40,6 +40,7 @@ Constant.
 - [is_number()](is_number.md) check if the value is a number
 - [is_number_unsigned()](is_number_unsigned.md) check if the value is an unsigned integer number
 - [is_number_float()](is_number_float.md) check if the value is a floating-point number
+- [basic_json_view::is_number_integer](../basic_json_view/is_number_integer.md) - the same check on a zero-copy view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/is_number_unsigned.md

@@ -40,6 +40,7 @@ Constant.
 - [is_number()](is_number.md) check if the value is a number
 - [is_number_integer()](is_number_integer.md) check if the value is an integer or unsigned integer number
 - [is_number_float()](is_number_float.md) check if the value is a floating-point number
+- [basic_json_view::is_number_unsigned](../basic_json_view/is_number_unsigned.md) - the same check on a zero-copy view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/is_object.md

@@ -34,6 +34,10 @@ Constant.
     --8<-- "examples/is_object.output"
     ```
 
+## See also
+
+- [basic_json_view::is_object](../basic_json_view/is_object.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_primitive.md

@@ -62,6 +62,7 @@ This library extends primitive types to binary types, because binary types are r
 - [is_boolean()](is_boolean.md) returns whether the JSON value is a boolean
 - [is_number()](is_number.md) returns whether the JSON value is a number
 - [is_binary()](is_binary.md) returns whether the JSON value is a binary array
+- [basic_json_view::is_primitive](../basic_json_view/is_primitive.md) - the same check on a zero-copy view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/is_string.md

@@ -34,6 +34,10 @@ Constant.
     --8<-- "examples/is_string.output"
     ```
 
+## See also
+
+- [basic_json_view::is_string](../basic_json_view/is_string.md) - the same check on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/is_structured.md

@@ -57,6 +57,7 @@ Note that though strings are containers in C++, they are treated as primitive va
 - [is_primitive()](is_primitive.md) returns whether JSON value is primitive
 - [is_array()](is_array.md) returns whether the value is an array
 - [is_object()](is_object.md) returns whether the value is an object
+- [basic_json_view::is_structured](../basic_json_view/is_structured.md) - the same check on a zero-copy view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/size.md

@@ -51,6 +51,10 @@ JSON value which is `1` in the case of a string.
     --8<-- "examples/size.output"
     ```
 
+## See also
+
+- [basic_json_view::size](../basic_json_view/size.md) - the same function on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json/type.md

@@ -47,6 +47,10 @@ Constant.
     --8<-- "examples/type.output"
     ```
 
+## See also
+
+- [basic_json_view::type](../basic_json_view/type.md) - the same function on a zero-copy view
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/basic_json_document/accept.md

@@ -0,0 +1,67 @@
+# <small>nlohmann::basic_json_document::</small>accept
+
+```cpp
+template<typename InputType>
+static bool accept(InputType&& input,
+                   const bool ignore_comments = false,
+                   const bool ignore_trailing_commas = false);
+```
+
+Checks whether the input is valid JSON, accepting and rejecting exactly what
+[`BasicJsonType::accept()`](../basic_json/accept.md) does, with the same options. Unlike [`parse()`](parse.md), this
+function never throws an exception for invalid input, and the returned `#!cpp bool` is the only result -- no document
+is returned.
+
+## Template parameters
+
+`InputType`
+:   A compatible input; see [`parse`](parse.md#template-parameters).
+
+## Parameters
+
+`input` (in)
+:   Input to check.
+
+`ignore_comments` (in)
+:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or
+    yield a parse error (`#!cpp false`); (optional, `#!cpp false` by default)
+
+## Return value
+
+Whether the input is valid JSON.
+
+## Exception safety
+
+Strong guarantee: this function itself never throws for an invalid input; it can only throw what allocating the
+input's own copy (for inputs that are always read into a buffer) throws.
+
+## Complexity
+
+Linear in the length of the input.
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__accept.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__accept.output"
+    ```
+
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [`BasicJsonType::accept`](../basic_json/accept.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/basic_json_document.md

@@ -0,0 +1,58 @@
+# <small>nlohmann::basic_json_document::</small>basic_json_document
+
+```cpp
+// (1)
+basic_json_document() = default;
+
+// (2)
+basic_json_document(basic_json_document&& other) noexcept = default;
+
+// (3)
+basic_json_document(const basic_json_document&) = delete;
+```
+
+1. Creates an empty (discarded) document: [`root()`](root.md) returns a discarded view, and
+   [`is_discarded()`](is_discarded.md) is `#!cpp true`.
+2. Move constructor. Takes over `other`'s index and, if owned, its text; `other` is left as an empty document. Views
+   taken from `other` before the move remain valid, because the index is heap-allocated independently of the
+   `basic_json_document` object.
+3. `basic_json_document` is move-only. Copying is disabled because it would either duplicate a potentially large index
+   and text, or leave two documents claiming to borrow the same buffer.
+
+## Parameters
+
+`other` (in)
+:   another document to move the index and text from
+
+## Exception safety
+
+No-throw guarantee: the default and move constructors never throw exceptions.
+
+## Complexity
+
+Constant, for the default and move constructors.
+
+## Examples
+
+??? example
+
+    The example below shows the default constructor and demonstrates that `basic_json_document` is move-only.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__basic_json_document.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__basic_json_document.output"
+    ```
+
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [is_discarded](is_discarded.md) - return whether the last parse failed
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/index.md

@@ -0,0 +1,55 @@
+# <small>nlohmann::</small>basic_json_document
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+template<typename BasicJsonType>
+class basic_json_document;
+```
+
+A parsed JSON text, held as a flat index of its values (16 bytes per value) instead of a tree of `BasicJsonType`
+values. Strings and numbers stay in the source text; only strings that contain escapes are decoded, into one buffer
+owned by the document. [`basic_json_view`](../basic_json_view/index.md) is a read-only handle to one value of a
+`basic_json_document`; [`materialize()`](../basic_json_view/materialize.md) turns a subtree back into the
+`BasicJsonType` value that [`BasicJsonType::parse()`](../basic_json/parse.md) would have produced for it.
+
+A document may **borrow** the text it was parsed from (the caller's buffer must then outlive the document) or **own**
+it (a copy, or an rvalue `#!cpp std::string` that was moved in); see [`owns_source`](owns_source.md). `basic_json_document`
+is move-only: copying a document would either duplicate a potentially large index and text, or leave two documents
+claiming to borrow the same buffer, so it is disabled.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](../basic_json/index.md), for instance [`json`](../json.md) or
+    [`ordered_json`](../ordered_json.md). Only 64-bit `number_integer_t`/`number_unsigned_t` types are supported; this
+    is checked with a `static_assert`.
+
+## Specializations
+
+- [**json_document**](../json_document.md) - documents of the default specialization [`json`](../json.md)
+- [**ordered_json_document**](../ordered_json_document.md) - documents of [`ordered_json`](../ordered_json.md)
+
+## Member types
+
+- **view_type** - the type of view returned by [`root()`](root.md) (`#!cpp basic_json_view<BasicJsonType>`)
+- **value_t** - the JSON type enumeration, see [`basic_json::value_t`](../basic_json/value_t.md)
+
+## Member functions
+
+- [(constructor)](basic_json_document.md)
+- [**parse**](parse.md) (_static_) - deserialize from a compatible input, borrowing or owning it as appropriate
+- [**parse_copy**](parse_copy.md) (_static_) - deserialize a copy of a compatible input
+- [**accept**](accept.md) (_static_) - check whether the input is valid JSON
+- [**read**](read.md) - (re-)parse into this document, reusing its memory
+- [**root**](root.md) - the view of the root value
+- [**is_discarded**](is_discarded.md) - return whether the last parse failed
+- [**source**](source.md) - the parsed text
+- [**owns_source**](owns_source.md) - return whether the document holds its own copy of the text
+- [**node_count**](node_count.md) - the number of index entries (values plus object keys)
+- [**memory_usage**](memory_usage.md) - the number of bytes held by the document
+- [**shrink_to_fit**](shrink_to_fit.md) - release unused index capacity
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/is_discarded.md

@@ -0,0 +1,49 @@
+# <small>nlohmann::basic_json_document::</small>is_discarded
+
+```cpp
+bool is_discarded() const noexcept;
+```
+
+Returns whether the document holds no value, either because it was default-constructed or because the last call to
+[`parse()`](parse.md), [`parse_copy()`](parse_copy.md), or [`read()`](read.md) failed with `allow_exceptions` set to
+`#!cpp false`.
+
+## Return value
+
+`#!cpp true` if the document is discarded, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+When the document is discarded, [`root()`](root.md) returns a discarded view (its
+[`is_discarded()`](../basic_json_view/is_discarded.md) is also `#!cpp true`).
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__is_discarded.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__is_discarded.output"
+    ```
+
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [is_discarded (basic_json_view)](../basic_json_view/is_discarded.md) - return whether a view is invalid
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/memory_usage.md

@@ -0,0 +1,50 @@
+# <small>nlohmann::basic_json_document::</small>memory_usage
+
+```cpp
+std::size_t memory_usage() const noexcept;
+```
+
+Returns the number of bytes held by the document: the node index, the decoded-string buffer (for strings that
+contain escapes), and, for an owned document, its copy of the source text.
+
+## Return value
+
+The number of bytes the document holds, `0` for a [discarded](is_discarded.md) document.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+The exact value depends on the platform, the allocator, and the library's own layout, and may change between
+versions; do not rely on it being a specific number, and do not compare it across different builds or platforms.
+Compare it for the same document over time, or between documents built with the same binary, instead -- for instance
+to observe the effect of [`shrink_to_fit()`](shrink_to_fit.md).
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__memory_usage.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__memory_usage.output"
+    ```
+
+## See also
+
+- [node_count](node_count.md) - the number of index entries
+- [shrink_to_fit](shrink_to_fit.md) - release unused index capacity
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/node_count.md

@@ -0,0 +1,48 @@
+# <small>nlohmann::basic_json_document::</small>node_count
+
+```cpp
+std::size_t node_count() const noexcept;
+```
+
+Returns the number of entries in the document's flat index.
+
+## Return value
+
+The number of index entries: one per value (of any type, at any nesting depth) plus one per object key. `0` for a
+[discarded](is_discarded.md) document.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+Each index entry is 16 bytes, so `#!cpp node_count() * 16` is the size of the index itself (part, but not all, of
+[`memory_usage()`](memory_usage.md), which also counts decoded strings and, for an owned document, the text).
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__node_count.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__node_count.output"
+    ```
+
+## See also
+
+- [memory_usage](memory_usage.md) - the number of bytes held by the document
+- [shrink_to_fit](shrink_to_fit.md) - release unused index capacity
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/owns_source.md

@@ -0,0 +1,49 @@
+# <small>nlohmann::basic_json_document::</small>owns_source
+
+```cpp
+bool owns_source() const noexcept;
+```
+
+Returns whether the document holds its own copy of the parsed text, as opposed to borrowing the caller's buffer.
+
+## Return value
+
+`#!cpp true` if the document owns the text returned by [`source()`](source.md), `#!cpp false` if it borrows it (or if
+the document is [discarded](is_discarded.md)).
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+See the ownership table on [`parse`](parse.md#notes) for which inputs are borrowed and which are owned. A borrowed
+document (`#!cpp owns_source() == false`) is only valid while the buffer it was parsed from is still alive.
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__owns_source.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__owns_source.output"
+    ```
+
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [parse_copy](parse_copy.md) - deserialize a copy of a compatible input, always owned
+- [source](source.md) - the parsed text
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/parse.md

@@ -0,0 +1,139 @@
+# <small>nlohmann::basic_json_document::</small>parse
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json_document parse(InputType&& input,
+                                 const bool allow_exceptions = true,
+                                 const bool ignore_comments = false,
+                                 const bool ignore_trailing_commas = false);
+
+// (2)
+template<typename IteratorType>
+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);
+```
+
+1. Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).
+2. Deserialize from a pair of input iterators.
+
+Both overloads accept exactly what [`BasicJsonType::parse()`](../basic_json/parse.md) accepts, with the same
+`ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](index.md) (a flat index into
+the input) instead of a tree of `BasicJsonType` values.
+
+## Template parameters
+
+`InputType`
+:   A compatible input, for instance:
+
+    - a `#!cpp std::string`, `#!cpp std::string_view`, or a C-style array of characters
+    - a pointer to a null-terminated string of single byte characters
+    - a container for which `#!cpp obj.data()` and `#!cpp obj.size()` give contiguous single-byte access, e.g.
+      `#!cpp std::vector<char>` or `#!cpp std::vector<std::uint8_t>`
+    - an `#!cpp std::istream` object, or anything else [`BasicJsonType::parse()`](../basic_json/parse.md) accepts
+
+`IteratorType`
+:   a compatible iterator type, for instance a pair of pointers such as `ptr` and `ptr + len`, or a pair of
+    `#!cpp std::string::iterator`
+
+## Parameters
+
+`input` (in)
+:   Input to parse from.
+
+`allow_exceptions` (in)
+:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+`ignore_comments` (in)
+:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or
+    yield a parse error (`#!cpp false`); (optional, `#!cpp false` by default)
+
+`first` (in)
+:   iterator to the start of a character range
+
+`last` (in)
+:   iterator to the end of a character range
+
+## Return value
+
+The parsed document. If `allow_exceptions` is `#!cpp false` and the input is not valid JSON, the returned document is
+discarded; see [`is_discarded`](is_discarded.md).
+
+## Exceptions
+
+Throws the same exception [`BasicJsonType::parse()`](../basic_json/parse.md) throws for the same input and options --
+the same exception id, message, and position -- because on a failing input the library's own parser is run on the
+same bytes to produce the diagnostic. Additionally throws
+[`out_of_range.416`](../../home/exceptions.md#jsonexceptionout_of_range416) if the input is 4 GiB or larger, a size
+[`BasicJsonType::parse()`](../basic_json/parse.md) does not reject.
+
+## Complexity
+
+Linear in the length of the input.
+
+## Notes
+
+**Ownership.** Whether the document borrows `input` or owns a copy of it depends on its value category and type:
+
+| `input`                                                                             | ownership                                                    |
+|--------------------------------------------------------------------------------------|--------------------------------------------------------------|
+| lvalue byte container (`std::string`, `std::vector<char>`, ...), `std::string_view`, C string, character array | **borrowed** -- `input` must outlive the document |
+| rvalue `#!cpp std::string`                                                            | **owned**, moved in without a copy                            |
+| rvalue byte container other than `#!cpp std::string`                                  | **owned**, copied                                             |
+| stream, wide string, or anything else read through the general input adapter          | **owned**, read into a buffer (a stream is read to its end)   |
+
+For overload (2), a pair of pointers to single-byte integers (e.g. `#!cpp const char*`, `#!cpp std::uint8_t*`) is
+borrowed. From C++20 on, so is any other contiguous iterator over single bytes, such as
+`#!cpp std::vector<char>::iterator` or `#!cpp std::string::const_iterator`. Before C++20 these iterators cannot be
+told apart from other class-type iterators, so their range is read into an owned buffer, as is any non-contiguous
+range (e.g. of a `#!cpp std::list<char>`).
+
+See [`owns_source`](owns_source.md) to check which happened after a call, and the
+[feature page](../../features/json_view.md) for the reasoning.
+
+**Numbers.** As for [`BasicJsonType::parse()`](../basic_json/parse.md), an integer literal too large for the 64-bit
+integer type becomes a floating-point value.
+
+## Examples
+
+??? example "Example: (1) borrowed vs. owned input, and errors identical to `BasicJsonType::parse()`"
+
+    ```cpp
+    --8<-- "examples/basic_json_document__parse.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__parse.output"
+    ```
+
+??? example "Example: (2) parse an iterator range (no NUL terminator required)"
+
+    ```cpp
+    --8<-- "examples/basic_json_document__parse_iterator_pair.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__parse_iterator_pair.output"
+    ```
+
+## See also
+
+- [parse_copy](parse_copy.md) - deserialize a copy of a compatible input
+- [accept](accept.md) - check whether the input is valid JSON
+- [read](read.md) - (re-)parse into this document, reusing its memory
+- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
+- [`BasicJsonType::parse`](../basic_json/parse.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/parse_copy.md

@@ -0,0 +1,77 @@
+# <small>nlohmann::basic_json_document::</small>parse_copy
+
+```cpp
+template<typename InputType>
+static basic_json_document parse_copy(InputType&& input,
+                                      const bool allow_exceptions = true,
+                                      const bool ignore_comments = false,
+                                      const bool ignore_trailing_commas = false);
+```
+
+Deserialize from a compatible input, always taking the document's own copy of it, regardless of the value category or
+type of `input`. Unlike [`parse()`](parse.md), the returned document never depends on `input` staying alive.
+
+## Template parameters
+
+`InputType`
+:   A compatible input; see [`parse`](parse.md#template-parameters).
+
+## Parameters
+
+`input` (in)
+:   Input to parse from.
+
+`allow_exceptions` (in)
+:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+`ignore_comments` (in)
+:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or
+    yield a parse error (`#!cpp false`); (optional, `#!cpp false` by default)
+
+## Return value
+
+The parsed document, with [`owns_source()`](owns_source.md) `#!cpp true`. If `allow_exceptions` is `#!cpp false` and
+the input is not valid JSON, the returned document is discarded; see [`is_discarded`](is_discarded.md).
+
+## Exceptions
+
+Same as [`parse`](parse.md#exceptions).
+
+## Complexity
+
+Linear in the length of the input.
+
+## Notes
+
+`parse_copy()` accepts and rejects exactly what [`parse()`](parse.md) does, and classifies numbers the same way; it
+only differs in that the input is always copied rather than sometimes borrowed. Prefer [`parse()`](parse.md) when the
+input's lifetime already covers the document's, since it avoids the copy for borrowed inputs.
+
+## Examples
+
+??? example
+
+    The example below returns a document from a function whose local buffer would otherwise not outlive it.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__parse_copy.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__parse_copy.output"
+    ```
+
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input, borrowing it where possible
+- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/read.md

@@ -0,0 +1,76 @@
+# <small>nlohmann::basic_json_document::</small>read
+
+```cpp
+template<typename InputType>
+void read(InputType&& input,
+         const bool allow_exceptions = true,
+         const bool ignore_comments = false,
+         const bool ignore_trailing_commas = false);
+```
+
+(Re-)parses `input` into `#!cpp *this`, discarding the document's previous value and reusing its memory (the node
+index, the decoded-string buffer, and, if applicable, the owned copy of the text) rather than allocating a fresh
+document. [`parse()`](parse.md) is implemented in terms of this function, applied to a default-constructed document.
+
+## Template parameters
+
+`InputType`
+:   A compatible input; see [`parse`](parse.md#template-parameters).
+
+## Parameters
+
+`input` (in)
+:   Input to parse from.
+
+`allow_exceptions` (in)
+:   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+`ignore_comments` (in)
+:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
+    (`#!cpp false`); (optional, `#!cpp false` by default)
+
+`ignore_trailing_commas` (in)
+:   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or
+    yield a parse error (`#!cpp false`); (optional, `#!cpp false` by default)
+
+## Exceptions
+
+Same as [`parse`](parse.md#exceptions).
+
+## Complexity
+
+Linear in the length of the input.
+
+## Notes
+
+Every view taken from `#!cpp *this` before the call -- including the previous [`root()`](root.md) -- is invalidated,
+whether or not the new parse succeeds; take fresh views from [`root()`](root.md) afterward.
+
+`input` is borrowed or owned by the same rules as [`parse()`](parse.md#notes); a document can borrow on one call and
+own on the next, since ownership is decided freshly each time.
+
+## Examples
+
+??? example
+
+    The example below parses a sequence of messages into the same document, reusing its memory instead of allocating
+    a new document for each one.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__read.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__read.output"
+    ```
+
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [root](root.md) - the view of the root value
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/root.md

@@ -0,0 +1,50 @@
+# <small>nlohmann::basic_json_document::</small>root
+
+```cpp
+view_type root() const noexcept;
+```
+
+Returns a view of the root value of the document.
+
+## Return value
+
+A [`view_type`](index.md#member-types) (i.e. `#!cpp basic_json_view<BasicJsonType>`) for the root value, or a
+discarded view if the document is [discarded](is_discarded.md).
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+`root()` is a cheap handle into the document's index, not a copy of anything; call it as often as needed. The
+returned view is valid under the same conditions as any other view of the document -- see
+[Object inspection](../basic_json_view/index.md) -- in particular, it is invalidated by the next
+[`read()`](read.md) or [`shrink_to_fit()`](shrink_to_fit.md) on this document.
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__root.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__root.output"
+    ```
+
+## See also
+
+- [is_discarded](is_discarded.md) - return whether the last parse failed
+- [materialize](../basic_json_view/materialize.md) - build the `BasicJsonType` value of a subtree
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/shrink_to_fit.md

@@ -0,0 +1,58 @@
+# <small>nlohmann::basic_json_document::</small>shrink_to_fit
+
+```cpp
+void shrink_to_fit();
+```
+
+Releases capacity that is no longer needed, both of the node index and of the buffer for decoded strings (strings that
+contained escape sequences), e.g. after [`read()`](read.md) replaced a large document with a much smaller one. Like
+`#!cpp std::vector::shrink_to_fit()`, this is a non-binding request: the library may keep more capacity than strictly
+necessary.
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to the document.
+
+## Exceptions
+
+May throw `#!cpp std::bad_alloc` if the reallocation fails; on exception, the document is unchanged.
+
+## Complexity
+
+Linear in [`node_count()`](node_count.md) plus the length of the decoded strings.
+
+## Notes
+
+!!! warning "Invalidates views"
+
+    Unlike moving the document, `shrink_to_fit()` **invalidates every view taken from this document before the
+    call**, including a previously obtained [`root()`](root.md): the node index is moved into a new, smaller
+    allocation, and the old one is freed. Take a fresh view from [`root()`](root.md) after calling this function.
+
+This is unlike `#!cpp std::vector::shrink_to_fit()`, which promises nothing about validity but in practice often
+leaves iterators alone when it did not need to reallocate; here, an implementation that avoids a reallocation when
+possible would be an internal optimization only, not a guarantee to rely on.
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__shrink_to_fit.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__shrink_to_fit.output"
+    ```
+
+## See also
+
+- [node_count](node_count.md) - the number of index entries
+- [memory_usage](memory_usage.md) - the number of bytes held by the document
+- [root](root.md) - the view of the root value
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/source.md

@@ -0,0 +1,48 @@
+# <small>nlohmann::basic_json_document::</small>source
+
+```cpp
+view_type::string_view_t source() const noexcept;
+```
+
+Returns the parsed text, whether it is borrowed from the caller or owned by the document.
+
+## Return value
+
+A `#!cpp string_view_t` (`#!cpp std::string_view` on C++17 and newer) over the parsed text, or an empty one if the
+document is [discarded](is_discarded.md).
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+For a borrowed document, `source()` points directly into the caller's buffer, so it is only valid while that buffer
+is; see [`owns_source`](owns_source.md).
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_document__source.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__source.output"
+    ```
+
+## See also
+
+- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
+- [source_offset](../basic_json_view/source_offset.md) - byte offset of a value in the source text
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/basic_json_view.md

@@ -0,0 +1,51 @@
+# <small>nlohmann::basic_json_view::</small>basic_json_view
+
+```cpp
+basic_json_view() noexcept = default;
+```
+
+Creates an invalid (discarded) view: [`type()`](type.md) is `#!cpp value_t::discarded`,
+[`is_discarded()`](is_discarded.md) is `#!cpp true`, and `#!cpp explicit operator bool()` is `#!cpp false`.
+
+This is the only constructor a caller can use directly. Every other view is obtained from a
+[`basic_json_document`](../basic_json_document/index.md), via [`root()`](../basic_json_document/root.md) or (once
+element access is added) from navigating into a container.
+
+## Exception safety
+
+No-throw guarantee: this constructor never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+`basic_json_view` is trivially copyable (it holds two pointers), so a default-constructed view can be used as a
+placeholder for "no value yet" and later be assigned a real view.
+
+## Examples
+
+??? example
+
+    The example below shows the default constructor and that a `basic_json_view` is a small, copyable handle.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__basic_json_view.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__basic_json_view.output"
+    ```
+
+## See also
+
+- [is_discarded](is_discarded.md) - return whether the view is invalid
+- [operator bool](operator_bool.md) - return whether the view refers to a value
+- [root](../basic_json_document/root.md) - the view of a document's root value
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/empty.md

@@ -0,0 +1,61 @@
+# <small>nlohmann::basic_json_view::</small>empty
+
+```cpp
+bool empty() const noexcept;
+```
+
+Checks whether [`size()`](size.md) is `0`, as [`BasicJsonType::empty()`](../basic_json/empty.md) would for the same
+value.
+
+## Return value
+
+The return value depends on the type and is defined as follows:
+
+| Value type          | return value    |
+|----------------------|-----------------|
+| null                  | `#!cpp true`     |
+| discarded             | `#!cpp true`     |
+| boolean               | `#!cpp false`    |
+| string                | `#!cpp false`    |
+| number                | `#!cpp false`    |
+| object                | `#!cpp object_t::empty()` |
+| array                 | `#!cpp array_t::empty()`  |
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+As for [`BasicJsonType::empty()`](../basic_json/empty.md), this does not return whether a string value is empty -- it
+is `#!cpp false` for any string, regardless of its length.
+
+## Examples
+
+??? example
+
+    The example below uses [`size()`](size.md) and `empty()` to decide whether a parsed message is worth acting on,
+    without materializing it into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__size_empty.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__size_empty.output"
+    ```
+
+## See also
+
+- [size](size.md) - return the number of elements
+- [`BasicJsonType::empty`](../basic_json/empty.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/index.md

@@ -0,0 +1,82 @@
+# <small>nlohmann::</small>basic_json_view
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+template<typename BasicJsonType>
+class basic_json_view;
+```
+
+A read-only handle to one value of a [`basic_json_document`](../basic_json_document/index.md): two pointers (a pointer
+to the document and a pointer into its index), trivially copyable. A view is valid as long as
+
+- the document is alive,
+- the document has not been re-parsed with [`read()`](../basic_json_document/read.md) (or
+  [`parse()`](../basic_json_document/parse.md) into it) or shrunk with
+  [`shrink_to_fit()`](../basic_json_document/shrink_to_fit.md) since the view was taken, and
+- if the document borrows its source text, that text is still alive.
+
+Moving the document itself does not invalidate its views: the index is heap-allocated independently of the
+`basic_json_document` object.
+
+`basic_json_view` provides the read-only part of the `BasicJsonType` interface: the type-inspection functions, and
+[`materialize()`](materialize.md) to build the `BasicJsonType` value of a subtree on demand. It does not (yet) provide
+element access, iteration, `get<T>()`, JSON Pointer support, `dump()`, or comparison.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](../basic_json/index.md), matching the
+    [`basic_json_document`](../basic_json_document/index.md) the view was taken from.
+
+## Specializations
+
+- [**json_view**](../json_view.md) - views of a [`json_document`](../json_document.md)
+- [**ordered_json_view**](../ordered_json_view.md) - views of an [`ordered_json_document`](../ordered_json_document.md)
+
+## Member types
+
+- **value_t** - the JSON type enumeration, see [`basic_json::value_t`](../basic_json/value_t.md)
+- **string_t**, **number_integer_t**, **number_unsigned_t**, **number_float_t**, **json_pointer** - the corresponding
+  member types of `BasicJsonType`
+- **size_type** - `#!cpp std::size_t`
+- **string_view_t** - `#!cpp std::string_view` on C++17 and newer, a minimal internal substitute otherwise
+
+## Member functions
+
+- [(constructor)](basic_json_view.md)
+
+### Object inspection
+
+- [**type**](type.md) - return the type of the value
+- [**is_null**](is_null.md) - return whether the value is null
+- [**is_boolean**](is_boolean.md) - return whether the value is a boolean
+- [**is_number**](is_number.md) - return whether the value is a number
+- [**is_number_integer**](is_number_integer.md) - return whether the value is an integer number
+- [**is_number_unsigned**](is_number_unsigned.md) - return whether the value is an unsigned integer number
+- [**is_number_float**](is_number_float.md) - return whether the value is a floating-point number
+- [**is_string**](is_string.md) - return whether the value is a string
+- [**is_array**](is_array.md) - return whether the value is an array
+- [**is_object**](is_object.md) - return whether the value is an object
+- [**is_binary**](is_binary.md) - return whether the value is a binary array (always `#!cpp false`)
+- [**is_primitive**](is_primitive.md) - return whether the type is primitive
+- [**is_structured**](is_structured.md) - return whether the type is structured
+- [**is_discarded**](is_discarded.md) - return whether the view is invalid
+- [**operator bool**](operator_bool.md) - return whether the view refers to a value
+
+### Capacity
+
+- [**size**](size.md) - return the number of elements
+- [**empty**](empty.md) - return whether the value has no elements
+
+### Conversion
+
+- [**materialize**](materialize.md) - build the `BasicJsonType` value of this subtree
+
+### Source access
+
+- [**source_offset**](source_offset.md) - byte offset of this value in the document's source text
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_array.md

@@ -0,0 +1,46 @@
+# <small>nlohmann::basic_json_view::</small>is_array
+
+```cpp
+bool is_array() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is an array.
+
+## Return value
+
+`#!cpp true` if the type is an array, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_structured](is_structured.md) - return whether the type is structured
+- [size](size.md), [empty](empty.md) - the number of elements, and whether there are none
+- [`BasicJsonType::is_array`](../basic_json/is_array.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_binary.md

@@ -0,0 +1,46 @@
+# <small>nlohmann::basic_json_view::</small>is_binary
+
+```cpp
+bool is_binary() const noexcept;
+```
+
+This function always returns `#!cpp false`: a JSON text has no binary values, so a view can never refer to one. The
+function exists for interface parity with [`BasicJsonType::is_binary`](../basic_json/is_binary.md).
+
+## Return value
+
+`#!cpp false`, always.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [type](type.md) - return the type of the value
+- [`BasicJsonType::is_binary`](../basic_json/is_binary.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_boolean.md

@@ -0,0 +1,45 @@
+# <small>nlohmann::basic_json_view::</small>is_boolean
+
+```cpp
+bool is_boolean() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is a boolean.
+
+## Return value
+
+`#!cpp true` if the type is a boolean, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [type](type.md) - return the type of the value
+- [`BasicJsonType::is_boolean`](../basic_json/is_boolean.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_discarded.md

@@ -0,0 +1,55 @@
+# <small>nlohmann::basic_json_view::</small>is_discarded
+
+```cpp
+bool is_discarded() const noexcept;
+```
+
+Returns whether this view is invalid, i.e. does not refer to a value. This is the case for a default-constructed
+view (see [(constructor)](basic_json_view.md)), and for [`root()`](../basic_json_document/root.md) of a document
+that is itself [discarded](../basic_json_document/is_discarded.md) -- in particular, the root of a failed
+[`parse()`](../basic_json_document/parse.md) with `allow_exceptions` set to `#!cpp false`.
+
+## Return value
+
+`#!cpp true` if the view is discarded, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+`#!cpp v.is_discarded()` and `#!cpp !static_cast<bool>(v)` are equivalent; use whichever reads better at the call
+site.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [operator bool](operator_bool.md) - return whether the view refers to a value
+- [(constructor)](basic_json_view.md) - the default constructor creates a discarded view
+- [is_discarded (basic_json_document)](../basic_json_document/is_discarded.md) - return whether the last parse failed
+- [`BasicJsonType::is_discarded`](../basic_json/is_discarded.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_null.md

@@ -0,0 +1,45 @@
+# <small>nlohmann::basic_json_view::</small>is_null
+
+```cpp
+bool is_null() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is `#!json null`.
+
+## Return value
+
+`#!cpp true` if the type is `#!json null`, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [type](type.md) - return the type of the value
+- [`BasicJsonType::is_null`](../basic_json/is_null.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_number.md

@@ -0,0 +1,47 @@
+# <small>nlohmann::basic_json_view::</small>is_number
+
+```cpp
+bool is_number() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is a number, i.e. an integer, unsigned integer, or floating-point value. It is defined as `#!cpp is_number_integer() || is_number_float()`.
+
+## Return value
+
+`#!cpp true` if the type is a number, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_number_integer](is_number_integer.md) - return whether the value is an integer or unsigned integer number
+- [is_number_unsigned](is_number_unsigned.md) - return whether the value is an unsigned integer number
+- [is_number_float](is_number_float.md) - return whether the value is a floating-point number
+- [`BasicJsonType::is_number`](../basic_json/is_number.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_number_float.md

@@ -0,0 +1,51 @@
+# <small>nlohmann::basic_json_view::</small>is_number_float
+
+```cpp
+bool is_number_float() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is a floating-point number.
+
+## Return value
+
+`#!cpp true` if the type is `#!cpp value_t::number_float`, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+As for [`BasicJsonType::parse`](../basic_json/parse.md), an integer literal that does not fit into the 64-bit
+integer type is classified as a floating-point number, so `is_number_float()` can be `#!cpp true` even for an
+integer-looking token in the source text.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_number](is_number.md) - return whether the value is a number
+- [`BasicJsonType::is_number_float`](../basic_json/is_number_float.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_number_integer.md

@@ -0,0 +1,51 @@
+# <small>nlohmann::basic_json_view::</small>is_number_integer
+
+```cpp
+bool is_number_integer() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is an integer or unsigned integer number.
+
+## Return value
+
+`#!cpp true` if the type is `#!cpp value_t::number_integer` or `#!cpp value_t::number_unsigned`, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+As for [`BasicJsonType::is_number_integer`](../basic_json/is_number_integer.md), this includes unsigned integer
+values; use [`is_number_unsigned`](is_number_unsigned.md) to test for those specifically.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_number](is_number.md) - return whether the value is a number
+- [is_number_unsigned](is_number_unsigned.md) - return whether the value is an unsigned integer number
+- [`BasicJsonType::is_number_integer`](../basic_json/is_number_integer.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_number_unsigned.md

@@ -0,0 +1,45 @@
+# <small>nlohmann::basic_json_view::</small>is_number_unsigned
+
+```cpp
+bool is_number_unsigned() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is an unsigned integer number.
+
+## Return value
+
+`#!cpp true` if the type is `#!cpp value_t::number_unsigned`, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_number_integer](is_number_integer.md) - return whether the value is an integer or unsigned integer number
+- [`BasicJsonType::is_number_unsigned`](../basic_json/is_number_unsigned.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_object.md

@@ -0,0 +1,46 @@
+# <small>nlohmann::basic_json_view::</small>is_object
+
+```cpp
+bool is_object() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is an object.
+
+## Return value
+
+`#!cpp true` if the type is an object, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_structured](is_structured.md) - return whether the type is structured
+- [size](size.md), [empty](empty.md) - the number of elements, and whether there are none
+- [`BasicJsonType::is_object`](../basic_json/is_object.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_primitive.md

@@ -0,0 +1,46 @@
+# <small>nlohmann::basic_json_view::</small>is_primitive
+
+```cpp
+bool is_primitive() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is primitive, i.e. `#!json null`, a boolean, a number, or a string. It is defined as `#!cpp is_null() || is_string() || is_boolean() || is_number()`.
+
+## Return value
+
+`#!cpp true` if the type is primitive, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_structured](is_structured.md) - return whether the type is structured (the complement of this function, for a
+  non-discarded view)
+- [`BasicJsonType::is_primitive`](../basic_json/is_primitive.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_string.md

@@ -0,0 +1,45 @@
+# <small>nlohmann::basic_json_view::</small>is_string
+
+```cpp
+bool is_string() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is a string.
+
+## Return value
+
+`#!cpp true` if the type is a string, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [source_offset](source_offset.md) - byte offset of this value in the document's source text
+- [`BasicJsonType::is_string`](../basic_json/is_string.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/is_structured.md

@@ -0,0 +1,46 @@
+# <small>nlohmann::basic_json_view::</small>is_structured
+
+```cpp
+bool is_structured() const noexcept;
+```
+
+This function returns `#!cpp true` if and only if the value is structured, i.e. an array or an object. It is defined as `#!cpp is_array() || is_object()`.
+
+## Return value
+
+`#!cpp true` if the type is structured, `#!cpp false` otherwise.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_primitive](is_primitive.md) - return whether the type is primitive
+- [size](size.md), [empty](empty.md) - the number of elements, and whether there are none
+- [`BasicJsonType::is_structured`](../basic_json/is_structured.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/materialize.md

@@ -0,0 +1,69 @@
+# <small>nlohmann::basic_json_view::</small>materialize
+
+```cpp
+BasicJsonType materialize() const;
+```
+
+Builds the `BasicJsonType` value of this subtree: the value [`BasicJsonType::parse()`](../basic_json/parse.md) would
+have produced for the same source text, allocated for the first time by this call.
+
+## Return value
+
+The `BasicJsonType` value of this subtree, or a discarded `BasicJsonType` value (`#!cpp BasicJsonType(value_t::discarded)`)
+if the view is [discarded](is_discarded.md).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to the view or the document it refers to (nothing
+about either is mutated by this function).
+
+## Exceptions
+
+May throw `#!cpp std::bad_alloc` (via `BasicJsonType`'s allocator) if constructing the result fails.
+
+## Complexity
+
+Linear in the size of the subtree.
+
+## Notes
+
+`materialize()` replays the subtree through the same SAX builder [`BasicJsonType::parse()`](../basic_json/parse.md)
+uses internally, so the result matches it exactly -- including, for an object, that a repeated key keeps only its
+last value. The replay is iterative, so it is not limited by the call stack the way a naive recursive conversion
+would be; the JSON nesting depth is limited only by available memory, as for `BasicJsonType::parse()` itself.
+
+Unlike parsing with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) enabled, the values
+produced by `materialize()` do not carry source positions: there is no lexer run during the replay to record them.
+
+Calling `materialize()` on the same view repeatedly builds a new, independent `BasicJsonType` value each time; it
+never caches the result.
+
+## Examples
+
+??? example
+
+    The example below skips messages that are not useful -- a discarded value, or an empty array -- using only
+    [`is_array()`](is_array.md) and [`empty()`](empty.md), and calls `materialize()` only for the messages that are
+    actually used, so no `BasicJsonType` value (and none of its per-element allocations) is ever built for the
+    skipped ones.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__materialize.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__materialize.output"
+    ```
+
+## See also
+
+- [root](../basic_json_document/root.md) - the view of a document's root value
+- [`BasicJsonType::parse`](../basic_json/parse.md) - build a `BasicJsonType` value directly from a JSON text
+- [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - source positions on parsed values (not
+  produced by `materialize()`)
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/operator_bool.md

@@ -0,0 +1,46 @@
+# <small>nlohmann::basic_json_view::</small>operator bool
+
+```cpp
+explicit operator bool() const noexcept;
+```
+
+Returns whether this view refers to a value, i.e. the negation of [`is_discarded()`](is_discarded.md). Being
+`#!cpp explicit`, this conversion is only considered in a boolean context (`#!cpp if (v)`, `#!cpp !v`, `#!cpp v &&
+...`), not for implicit conversions to other types.
+
+## Return value
+
+`#!cpp true` if the view refers to a value, `#!cpp false` if it is [discarded](is_discarded.md).
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_discarded](is_discarded.md) - return whether the view is invalid
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/size.md

@@ -0,0 +1,60 @@
+# <small>nlohmann::basic_json_view::</small>size
+
+```cpp
+size_type size() const noexcept;
+```
+
+Returns the number of elements, as [`BasicJsonType::size()`](../basic_json/size.md) would for the same value.
+
+## Return value
+
+The return value depends on the type and is defined as follows:
+
+| Value type          | return value                |
+|----------------------|-----------------------------|
+| null                  | `0`                          |
+| discarded             | `0`                          |
+| boolean               | `1`                          |
+| string                | `1`                          |
+| number                | `1`                          |
+| object                | number of key/value pairs    |
+| array                 | number of elements           |
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant: for an object or array, the element count is stored in the index, not counted on demand.
+
+## Notes
+
+As for [`BasicJsonType::size()`](../basic_json/size.md), this does not return the length of a string value -- it is
+`1` for a string, regardless of its length.
+
+## Examples
+
+??? example
+
+    The example below uses `size()` and [`empty()`](empty.md) to decide whether a parsed message is worth acting on,
+    without materializing it into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__size_empty.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__size_empty.output"
+    ```
+
+## See also
+
+- [empty](empty.md) - return whether the value has no elements
+- [`BasicJsonType::size`](../basic_json/size.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/source_offset.md

@@ -0,0 +1,55 @@
+# <small>nlohmann::basic_json_view::</small>source_offset
+
+```cpp
+std::size_t source_offset() const noexcept;
+```
+
+Returns the byte offset of this value in the document's [`source()`](../basic_json_document/source.md) text, without
+materializing anything.
+
+## Return value
+
+- For a string with no escapes, a number, `#!json true`/`#!json false`/`#!json null`, an array, or an object: the
+  byte offset of the first byte of the value's token (for a string: the first byte after the opening quote) in
+  [`source()`](../basic_json_document/source.md).
+- `#!cpp static_cast<std::size_t>(-1)` for a [discarded](is_discarded.md) view, and for a string that contains
+  escapes -- such a string was decoded once into the document's own buffer, so there is no single byte range in
+  `source()` left to point at.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+This is a raw offset, not a length: the API does not (yet) expose how many bytes the token occupies in the source
+text, so `source_offset()` alone is enough to report *where* a value came from (for an error message, for syntax
+highlighting, ...) but not to slice its exact text back out of [`source()`](../basic_json_document/source.md) for a
+string, whose token length is not the same as its decoded [`size()`](size.md).
+
+## Examples
+
+??? example
+
+    ```cpp
+    --8<-- "examples/basic_json_view__source_offset.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__source_offset.output"
+    ```
+
+## See also
+
+- [source](../basic_json_document/source.md) - the parsed text
+- [is_string](is_string.md) - return whether the value is a string
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/type.md

@@ -0,0 +1,53 @@
+# <small>nlohmann::basic_json_view::</small>type
+
+```cpp
+value_t type() const noexcept;
+```
+
+Returns the type of the value this view refers to, as a value from the [`value_t`](../basic_json/value_t.md)
+enumeration -- the same enumeration [`BasicJsonType::type()`](../basic_json/type.md) uses.
+
+## Return value
+
+The type of the value; `#!cpp value_t::discarded` for a [discarded](is_discarded.md) view.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+Unlike [`BasicJsonType::type()`](../basic_json/type.md), this function can never return `#!cpp value_t::binary`: a
+JSON text has no binary values, so `type()` only distinguishes the eight ordinary JSON value types (plus
+`#!cpp discarded`).
+
+## Examples
+
+??? example
+
+    The example below classifies several parsed documents by the type of their root value, without materializing any
+    of them into a `BasicJsonType` value.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__type_predicates.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__type_predicates.output"
+    ```
+
+## See also
+
+- [is_null](is_null.md), [is_boolean](is_boolean.md), [is_number](is_number.md), [is_string](is_string.md),
+  [is_array](is_array.md), [is_object](is_object.md) - type-specific predicates built on `type()`
+- [`BasicJsonType::type`](../basic_json/type.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/json_document.md

@@ -0,0 +1,35 @@
+# <small>nlohmann::</small>json_document
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+using json_document = basic_json_document<json>;
+```
+
+This type is a [`basic_json_document`](basic_json_document/index.md) of the default [`json`](json.md)
+specialization.
+
+## Examples
+
+??? example
+
+    The example below demonstrates how to use the type `nlohmann::json_document`.
+
+    ```cpp
+    --8<-- "examples/json_document.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/json_document.output"
+    ```
+
+## See also
+
+- [json_view](json_view.md) - a view of a value of a `json_document`
+- [ordered_json_document](ordered_json_document.md) - the corresponding document for `ordered_json`
+
+## Version history
+
+Since version 3.13.0.

docs/mkdocs/docs/api/json_view.md

@@ -0,0 +1,34 @@
+# <small>nlohmann::</small>json_view
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+using json_view = basic_json_view<json>;
+```
+
+This type is a [`basic_json_view`](basic_json_view/index.md) of a value of a [`json_document`](json_document.md).
+
+## Examples
+
+??? example
+
+    The example below demonstrates how to use the type `nlohmann::json_view`.
+
+    ```cpp
+    --8<-- "examples/json_view.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/json_view.output"
+    ```
+
+## See also
+
+- [json_document](json_document.md) - the document type this view refers into
+- [ordered_json_view](ordered_json_view.md) - the corresponding view for `ordered_json_document`
+
+## Version history
+
+Since version 3.13.0.

docs/mkdocs/docs/api/ordered_json_document.md

@@ -0,0 +1,38 @@
+# <small>nlohmann::</small>ordered_json_document
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+using ordered_json_document = basic_json_document<ordered_json>;
+```
+
+This type is a [`basic_json_document`](basic_json_document/index.md) of the [`ordered_json`](ordered_json.md)
+specialization: [`materialize()`](basic_json_view/materialize.md) on one of its views preserves the insertion order
+of object keys, instead of sorting them like [`json_document`](json_document.md) does.
+
+## Examples
+
+??? example
+
+    The example below demonstrates how `ordered_json_document` preserves the insertion order of object keys when
+    materializing.
+
+    ```cpp
+    --8<-- "examples/ordered_json_document.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/ordered_json_document.output"
+    ```
+
+## See also
+
+- [ordered_json_view](ordered_json_view.md) - a view of a value of an `ordered_json_document`
+- [json_document](json_document.md) - the corresponding document for the default `json` specialization
+- [Object Order](../features/object_order.md)
+
+## Version history
+
+Since version 3.13.0.

docs/mkdocs/docs/api/ordered_json_view.md

@@ -0,0 +1,35 @@
+# <small>nlohmann::</small>ordered_json_view
+
+<small>Defined in header `<nlohmann/json_view.hpp>`</small>
+
+```cpp
+using ordered_json_view = basic_json_view<ordered_json>;
+```
+
+This type is a [`basic_json_view`](basic_json_view/index.md) of a value of an
+[`ordered_json_document`](ordered_json_document.md).
+
+## Examples
+
+??? example
+
+    The example below demonstrates how to use the type `nlohmann::ordered_json_view`.
+
+    ```cpp
+    --8<-- "examples/ordered_json_view.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/ordered_json_view.output"
+    ```
+
+## See also
+
+- [ordered_json_document](ordered_json_document.md) - the document type this view refers into
+- [json_view](json_view.md) - the corresponding view for `json_document`
+
+## Version history
+
+Since version 3.13.0.

docs/mkdocs/docs/examples/basic_json_document__accept.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // accept() behaves exactly like basic_json::accept(): the same inputs are
+    // accepted or rejected, with the same ignore_comments/ignore_trailing_commas
+    // options
+    std::cout << json_document::accept(R"({"a": 1})") << '\n';
+    std::cout << json_document::accept(R"({"a": 1,})") << '\n'; // trailing comma: rejected by default
+    std::cout << json_document::accept(R"({"a": 1,})", false, true) << '\n'; // ignore_trailing_commas
+
+    std::cout << (json_document::accept(R"({"a": 1})") == nlohmann::json::accept(R"({"a": 1})")) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__accept.output

@@ -0,0 +1,4 @@
+true
+false
+true
+true

docs/mkdocs/docs/examples/basic_json_document__basic_json_document.cpp

@@ -0,0 +1,23 @@
+#include <iostream>
+#include <utility>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // the default constructor creates an empty (discarded) document
+    json_document empty;
+    std::cout << empty.is_discarded() << '\n';
+
+    // json_document is move-only: parse() itself returns by value (moved out),
+    // and a document can be moved again, e.g. into a container
+    json_document doc = json_document::parse(R"({"a": 1})");
+    json_document moved = std::move(doc);
+    std::cout << moved.root().is_object() << '\n';
+
+    // copying is disabled at compile time:
+    // json_document another = moved; // does not compile
+}

docs/mkdocs/docs/examples/basic_json_document__basic_json_document.output

@@ -0,0 +1,2 @@
+true
+true

docs/mkdocs/docs/examples/basic_json_document__is_discarded.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // with allow_exceptions == false, a parse error produces a discarded
+    // document instead of throwing -- exactly like basic_json::parse()
+    json_document doc = json_document::parse(R"({"a": )", /* allow_exceptions */ false);
+    std::cout << doc.is_discarded() << '\n';
+    std::cout << doc.root().is_discarded() << '\n';
+
+    // a successful parse is never discarded
+    json_document ok = json_document::parse(R"({"a": 1})", false);
+    std::cout << ok.is_discarded() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__is_discarded.output

@@ -0,0 +1,3 @@
+true
+true
+false

docs/mkdocs/docs/examples/basic_json_document__memory_usage.cpp

@@ -0,0 +1,28 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // long enough that copying it needs a real (heap) allocation, so the
+    // comparison below does not depend on the standard library's small
+    // string optimization threshold
+    const std::string text = std::string(200, ' ') + "[1, 2, 3, 4, 5]";
+
+    // memory_usage() is not portable across platforms/allocators/compilers, so
+    // compare it relatively instead of printing the raw byte count
+    json_document borrowed = json_document::parse(text);
+    json_document owned = json_document::parse_copy(text);
+
+    // the owned document additionally stores its own copy of the source text
+    std::cout << (owned.memory_usage() > borrowed.memory_usage()) << '\n';
+
+    // a document with more values needs a larger index
+    json_document small = json_document::parse(std::string("[1]"));
+    json_document large = json_document::parse(std::string("[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"));
+    std::cout << (large.memory_usage() > small.memory_usage()) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__memory_usage.output

@@ -0,0 +1,2 @@
+true
+true

docs/mkdocs/docs/examples/basic_json_document__node_count.cpp

@@ -0,0 +1,15 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    // node_count() is the size of the flat index: one 16-byte node per value,
+    // plus one per object key (values and keys are all the index stores)
+    json_document scalar = json_document::parse("42");
+    std::cout << scalar.node_count() << '\n';
+
+    json_document doc = json_document::parse(R"({"a": 1, "b": [1, 2]})");
+    std::cout << doc.node_count() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__node_count.output

@@ -0,0 +1,2 @@
+1
+7

docs/mkdocs/docs/examples/basic_json_document__owns_source.cpp

@@ -0,0 +1,24 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    std::string text = R"({"a": 1})";
+
+    // borrowed: the document only points into `text`; `text` must outlive it
+    json_document borrowed = json_document::parse(text);
+    std::cout << borrowed.owns_source() << '\n';
+
+    // owned: parse_copy() always takes its own copy
+    json_document copied = json_document::parse_copy(text);
+    std::cout << copied.owns_source() << '\n';
+
+    // owned: an rvalue std::string is moved in, not copied, but still owned
+    json_document moved_in = json_document::parse(std::string(text));
+    std::cout << moved_in.owns_source() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__owns_source.output

@@ -0,0 +1,3 @@
+false
+true
+true

docs/mkdocs/docs/examples/basic_json_document__parse.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json.hpp>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // an lvalue std::string is BORROWED: the document only stores a pointer
+    // into `text`, so `text` must outlive `borrowed`
+    std::string text = R"({"count": 3})";
+    json_document borrowed = json_document::parse(text);
+    std::cout << borrowed.owns_source() << '\n'; // false
+
+    // an rvalue std::string is MOVED into the document -- no copy of the text
+    json_document owned = json_document::parse(std::string(R"({"count": 3})"));
+    std::cout << owned.owns_source() << '\n'; // true
+
+    // errors are identical to basic_json::parse: same exception id, message,
+    // and position, because the library parser runs on the same bytes on a
+    // failing input
+    try
+    {
+        static_cast<void>(json_document::parse(R"({"count": )"));
+    }
+    catch (const nlohmann::json::parse_error& e)
+    {
+        std::cout << e.id << '\n';
+    }
+}

docs/mkdocs/docs/examples/basic_json_document__parse.output

@@ -0,0 +1,3 @@
+false
+true
+101

docs/mkdocs/docs/examples/basic_json_document__parse_copy.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+json_document parse_from_temporary_buffer()
+{
+    char buffer[] = R"({"a": 1})";
+    // parse() would borrow `buffer`, which is about to go out of scope;
+    // parse_copy() takes its own copy instead, so the returned document does
+    // not depend on `buffer` afterward
+    return json_document::parse_copy(buffer);
+}
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    json_document doc = parse_from_temporary_buffer();
+    std::cout << doc.owns_source() << '\n';
+    std::cout << doc.root().is_object() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__parse_copy.output

@@ -0,0 +1,2 @@
+true
+true

docs/mkdocs/docs/examples/basic_json_document__parse_iterator_pair.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+#include <vector>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // a JSON value embedded in a larger, non-null-terminated buffer (e.g. a
+    // slice received over the network)
+    std::vector<char> buffer = {'[', '1', ',', '2', ']', 'j', 'u', 'n', 'k'};
+
+    // a pointer pair is BORROWED, exactly like a byte container lvalue: the
+    // document points into the buffer. (From C++20 on, std::vector<char>
+    // iterators are borrowed as well; before, they are copied.)
+    const char* first = buffer.data();
+    json_document doc = json_document::parse(first, first + 5);
+    std::cout << doc.root().is_array() << ' ' << doc.root().size() << '\n';
+    std::cout << doc.owns_source() << '\n'; // false: borrowed
+}

docs/mkdocs/docs/examples/basic_json_document__parse_iterator_pair.output

@@ -0,0 +1,2 @@
+true 2
+false

docs/mkdocs/docs/examples/basic_json_document__read.cpp

@@ -0,0 +1,31 @@
+#include <iostream>
+#include <string>
+#include <vector>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    std::vector<std::string> messages =
+    {
+        R"({"id": 1})", R"({"id": 2, "tag": "x"})", R"({"id": 3})"
+    };
+
+    // parse into the same document over and over: its node index and decode
+    // buffer are reused instead of being freed and reallocated for each message
+    json_document doc;
+    std::size_t total = 0;
+    for (const auto& msg : messages)
+    {
+        doc.read(msg);
+        total += doc.root().size();
+    }
+    std::cout << total << '\n';
+
+    // read() can also change what kind of input is owned/borrowed between calls
+    doc.read(std::string(R"({"owned": true})"));
+    std::cout << doc.owns_source() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__read.output

@@ -0,0 +1,2 @@
+4
+true

docs/mkdocs/docs/examples/basic_json_document__root.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    json_document doc = json_document::parse(R"({"greeting": "hi"})");
+    std::cout << doc.root().is_object() << '\n';
+
+    // root() is a cheap handle, not a copy: repeated calls observe the same value
+    std::cout << (doc.root().type() == doc.root().type()) << '\n';
+
+    // the root of a failed parse (allow_exceptions == false) is discarded
+    json_document failed = json_document::parse("{", false);
+    std::cout << failed.root().is_discarded() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__root.output

@@ -0,0 +1,3 @@
+true
+true
+true

docs/mkdocs/docs/examples/basic_json_document__shrink_to_fit.cpp

@@ -0,0 +1,44 @@
+#include <iostream>
+#include <sstream>
+#include <string>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // build a large array (many nodes), then read a small one into the same
+    // document: the index grown for the large input is still allocated
+    std::ostringstream big;
+    big << '[';
+    for (int i = 0; i < 500; ++i)
+    {
+        if (i != 0)
+        {
+            big << ',';
+        }
+        big << i;
+    }
+    big << ']';
+
+    json_document doc;
+    doc.read(big.str());
+    const std::size_t big_nodes = doc.node_count();
+
+    doc.read(std::string("[1]"));
+    std::cout << (doc.node_count() < big_nodes) << '\n'; // far fewer live nodes now
+    const std::size_t before = doc.memory_usage();
+
+    // shrink_to_fit() moves the index into a block sized for what is actually
+    // used. This INVALIDATES every view taken from this document before the
+    // call (they point into the old, now-freed block) -- take fresh ones from
+    // root() afterward.
+    doc.shrink_to_fit();
+    const std::size_t after = doc.memory_usage();
+    std::cout << (after <= before) << '\n';
+
+    // a freshly taken view is valid and correct
+    std::cout << doc.root().is_array() << ' ' << doc.root().size() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__shrink_to_fit.output

@@ -0,0 +1,3 @@
+true
+true
+true 1

docs/mkdocs/docs/examples/basic_json_document__source.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    std::string text = R"({"a": 1})";
+    json_document doc = json_document::parse(text);
+
+    // source() is the parsed text, whether borrowed or owned
+    std::cout << (doc.source().size() == text.size()) << '\n';
+    std::cout << std::string(doc.source().data(), doc.source().size()) << '\n';
+
+    // for a borrowed document, source() points right into the caller's buffer
+    std::cout << (doc.source().data() == text.data()) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__source.output

@@ -0,0 +1,3 @@
+true
+{"a": 1}
+true

docs/mkdocs/docs/examples/basic_json_view__basic_json_view.cpp

@@ -0,0 +1,17 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // the default constructor is the only public one: it creates an invalid
+    // (discarded) view, useful as a "no value yet" placeholder
+    nlohmann::json_view v;
+    std::cout << static_cast<bool>(v) << ' ' << v.is_discarded() << '\n';
+
+    // views are trivially copyable handles (two pointers); the document owns
+    // the actual data
+    nlohmann::json_view copy = v;
+    std::cout << static_cast<bool>(copy) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__basic_json_view.output

@@ -0,0 +1,2 @@
+false true
+false

docs/mkdocs/docs/examples/basic_json_view__materialize.cpp

@@ -0,0 +1,33 @@
+#include <array>
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    // three incoming messages; skip the ones that are not useful without ever
+    // building a nlohmann::json value for them
+    json_document heartbeat = json_document::parse("null");
+    json_document empty_batch = json_document::parse("[]");
+    json_document batch = json_document::parse(R"([{"id": 1}, {"id": 2}, {"id": 3}])");
+    std::array<const json_document*, 3> messages = {{&heartbeat, &empty_batch, &batch}};
+
+    for (const json_document* d : messages)
+    {
+        // is_array()/empty() only look at the flat index: a discarded
+        // heartbeat or an empty batch is never turned into a nlohmann::json
+        // value, so no per-element allocation happens for them
+        if (!d->root().is_array() || d->root().empty())
+        {
+            std::cout << "skipped\n";
+            continue;
+        }
+
+        // materialize() replays the subtree through the same SAX builder
+        // basic_json::parse() uses, so the result is exactly what
+        // basic_json::parse() would have produced for the same text
+        nlohmann::json value = d->root().materialize();
+        std::cout << value.dump() << '\n';
+    }
+}

docs/mkdocs/docs/examples/basic_json_view__materialize.output

@@ -0,0 +1,3 @@
+skipped
+skipped
+[{"id":1},{"id":2},{"id":3}]

docs/mkdocs/docs/examples/basic_json_view__size_empty.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // decide whether a batch is worth processing before building any
+    // nlohmann::json value for it
+    json_document batch = json_document::parse(R"([1, 2, 3, 4, 5])");
+    json_document empty_batch = json_document::parse("[]");
+
+    std::cout << batch.root().empty() << ' ' << batch.root().size() << '\n';
+    std::cout << empty_batch.root().empty() << ' ' << empty_batch.root().size() << '\n';
+
+    // as for basic_json: null has size 0, every other scalar has size 1
+    json_document n = json_document::parse("null");
+    json_document s = json_document::parse(R"("hi")");
+    std::cout << n.root().size() << ' ' << s.root().size() << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__size_empty.output

@@ -0,0 +1,3 @@
+false 5
+true 0
+0 1

docs/mkdocs/docs/examples/basic_json_view__source_offset.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <string>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // source_offset() points into source(): useful to report *where* in the
+    // original text a value came from (error messages, syntax highlighting,
+    // forwarding a sub-range verbatim, ...) without materializing it
+    json_document doc = json_document::parse(R"(  123)");
+    auto v = doc.root();
+    std::cout << v.source_offset() << ' '
+              << std::string(doc.source().data() + v.source_offset(), 3) << '\n';
+
+    // a string without escapes also stays in the source text
+    json_document plain = json_document::parse(R"("ab")");
+    std::cout << plain.source()[plain.root().source_offset()] << '\n';
+
+    // a string with escapes is decoded once into the document's own buffer, so
+    // there is no single byte range in source() to point at: source_offset()
+    // returns the "not applicable" sentinel
+    json_document escaped = json_document::parse(R"("a\nb")");
+    std::cout << (escaped.root().source_offset() == static_cast<std::size_t>(-1)) << '\n';
+
+    // a discarded view -- default-constructed, or the root of a failed parse
+    // with allow_exceptions == false -- has no offset either
+    json_document failed = json_document::parse("not json", false);
+    std::cout << (failed.root().source_offset() == static_cast<std::size_t>(-1)) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__source_offset.output

@@ -0,0 +1,4 @@
+2 123
+a
+true
+true

docs/mkdocs/docs/examples/basic_json_view__type_predicates.cpp

@@ -0,0 +1,43 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // several incoming messages, one json_document per message. type() and
+    // is_*() only look at the flat index built by parse(); no nlohmann::json
+    // tree exists yet, and none is built unless materialize() is called
+    json_document d_null = json_document::parse("null");
+    json_document d_bool = json_document::parse("true");
+    json_document d_int = json_document::parse("-42");
+    json_document d_unsigned = json_document::parse("42");
+    json_document d_float = json_document::parse("4.2");
+    json_document d_string = json_document::parse(R"("hi")");
+    json_document d_array = json_document::parse("[1, 2, 3]");
+    json_document d_object = json_document::parse(R"({"a": 1})");
+
+    std::cout << d_null.root().is_null() << '\n';
+    std::cout << d_bool.root().is_boolean() << '\n';
+    std::cout << d_int.root().is_number() << ' ' << d_int.root().is_number_integer() << '\n';
+    std::cout << d_unsigned.root().is_number_unsigned() << '\n';
+    std::cout << d_float.root().is_number_float() << '\n';
+    std::cout << d_string.root().is_string() << '\n';
+    std::cout << d_array.root().is_array() << ' ' << d_array.root().is_structured() << '\n';
+    std::cout << d_object.root().is_object() << ' ' << d_object.root().is_primitive() << '\n';
+
+    // JSON text can never produce a binary value: is_binary() is always false
+    std::cout << d_array.root().is_binary() << '\n';
+
+    // a default-constructed view, and the root of a document that failed to
+    // parse without exceptions, are both discarded
+    nlohmann::json_view invalid;
+    json_document failed = json_document::parse("not json", /* allow_exceptions */ false);
+    std::cout << static_cast<bool>(invalid) << ' ' << invalid.is_discarded() << '\n';
+    std::cout << static_cast<bool>(failed.root()) << ' ' << failed.root().is_discarded() << '\n';
+
+    // type() returns the same value_t enumeration as basic_json::type()
+    std::cout << (d_object.root().type() == nlohmann::json::value_t::object) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__type_predicates.output

@@ -0,0 +1,12 @@
+true
+true
+true true
+true
+true
+true
+true true
+true false
+false
+false true
+false true
+true

docs/mkdocs/docs/examples/json_document.cpp

@@ -0,0 +1,16 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // json_document is basic_json_document<nlohmann::json>: same value types
+    // and containers as the ordinary json specialization
+    json_document doc = json_document::parse(R"({"pi": 3.14, "numbers": [1, 2, 3]})");
+
+    std::cout << doc.root().is_object() << '\n';
+    std::cout << doc.root().materialize().dump() << '\n';
+}

docs/mkdocs/docs/examples/json_document.output

@@ -0,0 +1,2 @@
+true
+{"numbers":[1,2,3],"pi":3.14}

docs/mkdocs/docs/examples/json_view.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // json_view is basic_json_view<nlohmann::json>: a read-only handle
+    // returned by json_document::root()
+    nlohmann::json_document doc = nlohmann::json_document::parse("[1, 2, 3]");
+    nlohmann::json_view v = doc.root();
+
+    std::cout << v.is_array() << ' ' << v.size() << '\n';
+}

docs/mkdocs/docs/examples/json_view.output

@@ -0,0 +1 @@
+true 3

docs/mkdocs/docs/examples/json_view_ownership.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <string>
+#include <utility>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+
+int main()
+{
+    std::cout << std::boolalpha;
+
+    // BORROWED: doc only points into `text`; `text` must outlive `doc`
+    std::string text = R"({"a": 1})";
+    json_document doc = json_document::parse(text);
+    std::cout << doc.owns_source() << '\n'; // false
+
+    // a view is valid as long as the document is alive, has not been
+    // re-parsed (read()) or shrunk (shrink_to_fit()), and -- if borrowed --
+    // the source text is alive
+    nlohmann::json_view v = doc.root();
+    std::cout << v.is_object() << '\n';
+
+    // re-parsing the SAME document invalidates views taken before the call;
+    // `v` above must not be used after this line
+    doc.read(R"([1, 2, 3])");
+    v = doc.root(); // take a fresh view instead
+    std::cout << v.is_array() << '\n';
+
+    // moving the document does not invalidate views: the node index is
+    // heap-allocated and does not move with the document object
+    json_document moved = std::move(doc);
+    std::cout << v.is_array() << '\n';
+}

docs/mkdocs/docs/examples/json_view_ownership.output

@@ -0,0 +1,4 @@
+false
+true
+true
+true

docs/mkdocs/docs/examples/ordered_json_document.cpp

@@ -0,0 +1,13 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using ordered_json_document = nlohmann::ordered_json_document;
+
+int main()
+{
+    // ordered_json_document is basic_json_document<nlohmann::ordered_json>:
+    // materialize() preserves the insertion (source) order of object keys,
+    // instead of sorting them like json_document does
+    ordered_json_document doc = ordered_json_document::parse(R"({"z": 1, "a": 2, "m": 3})");
+    std::cout << doc.root().materialize().dump() << '\n';
+}

docs/mkdocs/docs/examples/ordered_json_document.output

@@ -0,0 +1 @@
+{"z":1,"a":2,"m":3}

docs/mkdocs/docs/examples/ordered_json_view.cpp

@@ -0,0 +1,10 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+int main()
+{
+    nlohmann::ordered_json_document doc = nlohmann::ordered_json_document::parse(R"({"z": 1, "a": 2})");
+    nlohmann::ordered_json_view v = doc.root();
+
+    std::cout << std::boolalpha << v.is_object() << ' ' << v.size() << '\n';
+}

docs/mkdocs/docs/examples/ordered_json_view.output

@@ -0,0 +1 @@
+true 2