Document that read() must not be given a view of the document itself (#6086)

* Document that read() must not be given a view of the document itself

basic_json_document::read() releases the previous text, the decoded
strings and the edits before it parses its input. An input that points
into them (source(), get_string(), number_token(), or a string of an
edited document) is read after its memory was cleared or freed.

A guard that copies such input costs about 1 ns per read() (5 % of a
read of a 7-byte input), which this API exists to avoid, so state the
precondition in read.md, lifetime.md and the pages of the views that
hand out such strings instead, and show how to copy the string first.

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

* Assert in debug builds that read() is not given its own text

read() releases the document's text, decoded strings, owned image and
edits before it parses, so an input that points into them is read after
release. Without NDEBUG, read() now asserts that a borrowed input, a
copied contiguous input and (before C++17) a string_ref input are not
held by the document: its owned text, its decoded strings, an owned
image, and the current buffer of edited strings. Release builds keep
the documented precondition without a check, which would cost 2-4.5 %
per read() of a small message.

JSON_ASSERT is undefined at the end of json.hpp, so the view uses
assert() through a new internal NLOHMANN_VIEW_ASSERT.

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

---------

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

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

@@ -111,8 +111,9 @@ points apply to every edit:
   the end, and, with [`number_format::source`](../basic_json_view/number_format.md), keeps the spelling of every
   number that was not itself edited — see [Editing a document](../../features/json_view/editing.md) for
   why this matters.
-- [`read()`](read.md) discards all edits, [`shrink_to_fit()`](shrink_to_fit.md) does not move the node index once
-  there are edits, and [`memory_usage()`](memory_usage.md) includes the memory edits use.
+- [`read()`](read.md) discards all edits (so its `input` must not be a string obtained from this document),
+  [`shrink_to_fit()`](shrink_to_fit.md) does not move the node index once there are edits, and
+  [`memory_usage()`](memory_usage.md) includes the memory edits use.
   [`source_offset()`](../basic_json_view/source_offset.md) of a value introduced by an edit is
   `#!cpp static_cast<std::size_t>(-1)`, the same value it reports for a decoded string.
 

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

@@ -46,6 +46,34 @@ Linear in the length of the input.
 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.
 
+!!! warning "`input` must not point into the document itself"
+
+    `read()` releases the document's previous text, its decoded strings, and (for an editable document) its edits
+    *before* it parses `input`. An `input` that is, or points into, any of them violates a precondition: it may seem to
+    work, parse empty or garbled text, be reported by a sanitizer, or read freed memory (undefined behavior).
+
+    This applies to every `string_view` obtained from the document whose characters live in memory that `read()`
+    releases:
+
+    - [`source()`](source.md) of a document that owns its text;
+    - [`get_string()`](../basic_json_view/get_string.md) (also as `get<string_view_t>()` or a `string_view` member of a
+      decoded struct) of a string with escapes, of a string of a document that owns its text, and of an edited string;
+    - [`number_token()`](../basic_json_view/number_token.md) of a number of a document that owns its text, and of a
+      number written by an edit;
+    - the key of an object member (`key()`) if it has escapes, was written by an edit, or the document owns its text.
+
+    It does not apply to a text that the caller owns and the document borrows, nor to the strings, keys, and tokens that
+    are read from such a text unchanged, nor to the decoded strings of a borrowed [image](load.md), which live in the
+    caller's image: `read()` never touches them. To parse JSON that a document holds in a string of its own (for
+    example, JSON embedded in a string value), copy the string first, for example with
+    `#!cpp std::string inner(doc.root()["payload"].get_string()); doc.read(inner);`.
+
+    A debug build (one without `NDEBUG`) checks this with `assert()`: an `input` in the document's text, decoded
+    strings, or image, or in the most recent buffer of strings written by edits, ends the program. (Strings written
+    by earlier edits are not covered.) A release build does not check, to keep the cost of reusing a document at a
+    minimum. The check uses `assert()` directly, not [`JSON_ASSERT`](../macros/json_assert.md), which `json.hpp`
+    undefines at its end.
+
 `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. An input that is copied (see the table in
 [`parse()`](parse.md#notes)) is written into the document's previous owned copy, reusing its memory; a moved-in

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

@@ -24,6 +24,9 @@ Constant.
 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).
 
+The text of a document that owns it must not be passed to [`read()`](read.md) of the same document: `read()` releases
+an owned text before it parses its input. Copy it first. (A borrowed text belongs to the caller and is not affected.)
+
 ## Examples
 
 ??? example