docs: cross-reference json_view and json_document for 3.13.0 (#5892)

* docs: cross-reference json_view and json_document for 3.13.0

Document the new zero-copy document/view API across the docs: add a
"Documents and views" section to the basic_json API hub linking to all
specializations, point parsing/conversion/modifying pages to the view-based
alternatives, add document/view sections to feature pages, update the
landing page to mention json_view.hpp/json_literals.hpp, and cross-link
debugging/exceptions.

Also document wide-string inputs (and ill-formed UTF-16/32 rejection),
add parse/accept examples for wide strings, fix related doc gaps, and
align features/parsing and FAQ with the added support.

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

* docs: fix article before std::istream in FAQ

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

* docs: clarify document inputs, decoding, get<T>() and editing

Address review comments: say which inputs are borrowed and that a wide
string pointer is an extra input, which values are decoded during parsing,
that get<T>() reads only built-in types directly, all forms of set() and
that the document's insert() is array-only, and how to store wide strings.

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

* docs: integers are converted while parsing a document

Also say "They accept every input" in basic_json_document::parse.

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

---------

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

docs/mkdocs/docs/features/conversions.md

@@ -38,6 +38,18 @@ which avoids repeating it:
     --8<-- "examples/get_to.output"
     ```
 
+!!! info "Getting values out of a document or a view"
+
+    A [view](../api/basic_json_view/index.md) offers the same `get<T>()` conversion. For the built-in types (booleans,
+    numbers, strings, `#!cpp std::vector`, `#!cpp std::map`, ...) it reads the value straight from the document's
+    index, without building a `basic_json` value first; user-defined types with a `from_json()` are converted from a
+    `basic_json` value, see the [list](../api/basic_json_view/get.md). Two conversions never copy at all:
+    [`get_string()`](../api/basic_json_view/get_string.md) returns a string as a view into the source text, and
+    [`number_token()`](../api/basic_json_view/number_token.md) returns a number exactly as it was written. Every other
+    type is obtained from a subtree that is built on demand with
+    [`materialize()`](../api/basic_json_view/materialize.md). See
+    [Zero-copy JSON views](json_view.md#getting-values-out-without-copying).
+
 The library already knows how to convert to and from the scalar types and the STL containers (such as
 `#!cpp std::vector`, `#!cpp std::map`, `#!cpp std::array`, `#!cpp std::optional`, and many more). Converting a JSON
 object back to a `#!cpp std::map` or a JSON array back to a `#!cpp std::vector` therefore works without any extra code:
@@ -234,3 +246,4 @@ The conversions above are built in for standard types. To make the same syntax w
 - [`get_ref`](../api/basic_json/get_ref.md) / [`get_ptr`](../api/basic_json/get_ptr.md) - access the stored value without copying
 - [Arbitrary types conversions](arbitrary_types.md) - support your own types
 - [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) - toggle implicit conversions
+- [Zero-copy JSON views](json_view.md) - get values out of a document or a view

docs/mkdocs/docs/features/creating_values.md

@@ -1,7 +1,9 @@
 # Creating JSON values
 
 There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text
-instead, see [parsing](parsing/index.md).
+instead, see [parsing](parsing/index.md). A JSON text can also be parsed into a
+[document](../api/basic_json_document/index.md) and read through a [view](../api/basic_json_view/index.md) instead of
+into a value; see [Zero-copy JSON views](json_view.md).
 
 ## From C++ values
 
@@ -101,3 +103,4 @@ string `#!json "42"`.
 - [`operator""_json`](../api/operator_literal_json.md) - the `_json` literal
 - [Converting values](conversions.md) - which C++ types can be used
 - [Parsing](parsing/index.md) - create a value from JSON text
+- [Zero-copy JSON views](json_view.md) - create a document and a view from JSON text instead of a value

docs/mkdocs/docs/features/macros.md

@@ -287,6 +287,23 @@ external dependency and is not defined by default.
 
 See [full documentation of `JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md).
 
+## `JSON_VIEW_NO_SIMD`
+
+When defined, the parser of [`basic_json_document`](../api/basic_json_document/index.md)
+(`<nlohmann/json_view.hpp>`) uses only portable C++ to scan strings, instead of vector instructions (SSE2 on x86-64,
+NEON on AArch64). The same input is accepted or rejected either way; only the speed differs. It is not defined by
+default.
+
+See [full documentation of `JSON_VIEW_NO_SIMD`](../api/macros/json_view_no_simd.md).
+
+## `JSON_VIEW_USE_SSSE3`
+
+When defined on x86-64, the parser of [`basic_json_document`](../api/basic_json_document/index.md)
+(`<nlohmann/json_view.hpp>`) validates non-ASCII text in strings with SSSE3 without asking the CPU first. It is not
+defined by default.
+
+See [full documentation of `JSON_VIEW_USE_SSSE3`](../api/macros/json_view_use_ssse3.md).
+
 ## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)`
 
 The library defines 12 macros to simplify the serialization/deserialization of types. See the page on

docs/mkdocs/docs/features/modifying_values.md

@@ -85,6 +85,18 @@ json a = {1, 2, 3, 4};
 a.erase(1);             // [1,3,4]  (erase by index)
 ```
 
+## Editing a document
+
+The operations above work on a `basic_json` value. A JSON text that was parsed into a
+[document](json_view.md#editing-a-document) can also be changed in place, without building a `basic_json` tree for the
+parts that are not touched: [`set`](../api/basic_json_document/set.md) replaces a value, adds or replaces an object
+member, or replaces an array element (also through a JSON pointer),
+[`push_back`](../api/basic_json_document/push_back.md) appends to an array,
+[`insert`](../api/basic_json_document/insert.md) inserts into an array (unlike `basic_json::insert`, it has no object
+overload; members are added with `set`), and [`erase`](../api/basic_json_document/erase.md) removes a member or an
+element. These functions are available on the
+editable document types, such as [`json_editable_document`](../api/json_editable_document.md).
+
 ## See also
 
 - [`push_back`](../api/basic_json/push_back.md) / [`emplace_back`](../api/basic_json/emplace_back.md) - append to an array
@@ -93,3 +105,4 @@ a.erase(1);             // [1,3,4]  (erase by index)
 - [`merge_patch`](../api/basic_json/merge_patch.md) - apply an RFC 7396 merge patch
 - [`erase`](../api/basic_json/erase.md) / [`clear`](../api/basic_json/clear.md) - remove elements
 - [JSON Patch and Diff](json_patch.md) and [JSON Merge Patch](merge_patch.md) - structured modifications
+- [Editing a document](json_view.md#editing-a-document) - change a parsed document in place

docs/mkdocs/docs/features/parsing/index.md

@@ -18,6 +18,7 @@ flowchart LR
 The [`parse`](../../api/basic_json/parse.md) function reads a JSON value from an input. The input can be
 
 - a string (`#!cpp std::string`, C string, or string literal),
+- a wide string (`#!cpp std::u16string`, `#!cpp std::u32string`, or `#!cpp std::wstring`, or a wide string literal),
 - a `#!cpp std::istream` (e.g., an `#!cpp std::ifstream` reading from a file),
 - a `#!cpp FILE*` pointer,
 - a pair of iterators over a contiguous range (e.g., a `#!cpp std::vector<std::uint8_t>`), or
@@ -32,12 +33,18 @@ std::ifstream f("example.json");
 json data = json::parse(f);
 ```
 
-The input must be encoded in UTF-8; other encodings are not supported. A single input may contain only one JSON value.
+The input must be encoded in UTF-8; other encodings are not supported. The exception is wide-character input, which
+is read as UTF-16 or UTF-32 -- depending on the character type -- and converted to UTF-8; see the
+[`parse`](../../api/basic_json/parse.md) page for an example. A single input may contain only one JSON value.
 Inputs consisting of multiple values separated by newlines are handled by the [JSON Lines](json_lines.md) format.
 
 By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the `parse`
 function — see [comments](../comments.md) and [trailing commas](../trailing_commas.md).
 
+[`basic_json_document::parse`](../../api/basic_json_document/parse.md) accepts the same inputs with the same options,
+but keeps the result in a document rather than in a `basic_json` value; see
+[Documents and views](#documents-and-views) below.
+
 ## Strictness and trailing data
 
 [`parse`](../../api/basic_json/parse.md) reads a single JSON value and requires the whole input to be consumed: any
@@ -98,6 +105,26 @@ The library offers two parsing models:
 You can influence a DOM parse without switching to the SAX interface by passing a
 [parser callback](parser_callbacks.md), which is called during parsing and can, for example, discard parts of the input.
 
+## Documents and views
+
+A third model sits between DOM and SAX: [`basic_json_document::parse`](../../api/basic_json_document/parse.md) parses
+the input into a document that keeps the text and a flat index of the values in it, and
+[`basic_json_view`](../../api/basic_json_view/index.md) gives read-only access to the values through that index.
+The whole input is validated during parsing, but only integers and strings that contain escape sequences are converted
+right away (the strings into a buffer owned by the document). Floating-point numbers and all other strings stay in the
+source text and are only converted when they are read, which is faster and uses less memory than building a tree of `basic_json` values when only parts
+of the document are needed. A document can also be
+modified in place, and it can be saved and loaded again without parsing it.
+
+```cpp
+#include <nlohmann/json_view.hpp>
+
+json_document doc = json_document::parse(R"({"happy": true, "pi": 3.141})");
+std::cout << doc.root()["happy"].get<bool>() << '\n';
+```
+
+See [Zero-copy JSON views](../json_view.md) for the concept and the trade-offs.
+
 ## Exceptions
 
 When the input is not valid JSON, the `parse` function throws an exception by default. If exceptions are undesired or
@@ -108,6 +135,7 @@ options.
 ## See also
 
 - [`parse`](../../api/basic_json/parse.md) - deserialize from a compatible input
+- [`basic_json_document::parse`](../../api/basic_json_document/parse.md) - deserialize into a document instead of a value
 - [`accept`](../../api/basic_json/accept.md) - check if the input is valid JSON
 - [`sax_parse`](../../api/basic_json/sax_parse.md) - generate SAX events
 - [JSON Lines](json_lines.md) - parse newline-delimited JSON
@@ -115,3 +143,4 @@ options.
 - [SAX interface](sax_interface.md) - implement a custom SAX handler
 - [parsing and exceptions](parse_exceptions.md) - control error handling
 - [parsing untrusted input](untrusted_input.md) - what to consider when parsing input from untrusted sources
+- [Zero-copy JSON views](../json_view.md) - parse into a document and read it through a view

docs/mkdocs/docs/features/parsing/untrusted_input.md

@@ -81,6 +81,9 @@ Invalid UTF-8 is rejected while parsing, not just while serializing:
 
 - In JSON text, an ill-formed UTF-8 byte in a string is a
   [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) ("invalid string: ill-formed UTF-8 byte").
+- In UTF-16 or UTF-32 input, an ill-formed sequence is a
+  [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) as well: a lone surrogate, a high surrogate
+  that is not followed by its low surrogate, and a code point above `U+10FFFF` are all rejected.
 - In a binary format, a string that is not valid UTF-8 is a
   [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113).