deploy: ddc34f546a

api/basic_json_document/accept.md

@@ -13,9 +13,15 @@ function never throws an exception for invalid input, and the returned `#!cpp bo
 is returned.
 
 The result is the same as that of `BasicJsonType::accept()` by design; the difference is how the check is made. This
-function runs the document's index builder (and discards the index), while `BasicJsonType::accept()` runs the SAX
-parser with a handler that ignores every event. Use this one if you go on to parse the same input with
-[`parse()`](parse.md) anyway, so that both use the same code; either is fine for a plain yes/no answer.
+function runs the document's builder, which checks the text as [`parse()`](parse.md) does, while
+`BasicJsonType::accept()` runs the SAX parser with a handler that ignores every event. Use this one if you go on to
+parse the same input with [`parse()`](parse.md) anyway, so that both use the same code; either is fine for a plain
+yes/no answer.
+
+When both `ignore_comments` and `ignore_trailing_commas` are `#!cpp false` (the default), the builder writes no index.
+With either option set, it builds the index as [`parse()`](parse.md) does and discards it: the result is the same, only
+the time differs. (Neither option needs the index; the variant that skips it exists only for the default options to
+keep the code size down.)
 
 ## Template parameters
 

api/basic_json_document/accept/index.md

@@ -9,7 +9,9 @@ static bool accept(InputType&& input,
 
 Checks whether the input is valid JSON, accepting and rejecting exactly what [`BasicJsonType::accept()`](https://json.nlohmann.me/api/basic_json/accept/index.md) does, with the same options. Unlike [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md), this function never throws an exception for invalid input, and the returned `bool` is the only result — no document is returned.
 
-The result is the same as that of `BasicJsonType::accept()` by design; the difference is how the check is made. This function runs the document's index builder (and discards the index), while `BasicJsonType::accept()` runs the SAX parser with a handler that ignores every event. Use this one if you go on to parse the same input with [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) anyway, so that both use the same code; either is fine for a plain yes/no answer.
+The result is the same as that of `BasicJsonType::accept()` by design; the difference is how the check is made. This function runs the document's builder, which checks the text as [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) does, while `BasicJsonType::accept()` runs the SAX parser with a handler that ignores every event. Use this one if you go on to parse the same input with [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) anyway, so that both use the same code; either is fine for a plain yes/no answer.
+
+When both `ignore_comments` and `ignore_trailing_commas` are `false` (the default), the builder writes no index. With either option set, it builds the index as [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) does and discards it: the result is the same, only the time differs. (Neither option needs the index; the variant that skips it exists only for the default options to keep the code size down.)
 
 ## Template parameters
 

api/basic_json_view/at.md

@@ -68,9 +68,10 @@ Strong guarantee: there are no changes to the view or the document it refers to.
     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if `ptr` cannot be resolved
       because a reference token is used on a primitive value.
 
-None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) these exceptions name the JSON
+Pointer path of the value within the document, and with
+[`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) its bytes in the source text (when
+[`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/at/index.md

@@ -53,7 +53,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
    - Throws [`out_of_range.403`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range403) if a reference token names an object member that does not exist.
    - Throws [`out_of_range.404`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range404) if `ptr` cannot be resolved because a reference token is used on a primitive value.
 
-None of these exceptions carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) these exceptions name the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

api/basic_json_view/back.md

@@ -20,9 +20,9 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 Throws [`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) if the view is
 [null](is_null.md) or [discarded](is_discarded.md), or if it is an empty array or object.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) the exception names the JSON Pointer
+path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md)
+its bytes in the source text (when [`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/back/index.md

@@ -18,7 +18,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 
 Throws [`invalid_iterator.214`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator214) if the view is [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) or [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md), or if it is an empty array or object.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) the exception names the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

api/basic_json_view/front.md

@@ -20,9 +20,9 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 Throws [`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) if the view is
 [null](is_null.md) or [discarded](is_discarded.md), or if it is an empty array or object.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) the exception names the JSON Pointer
+path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md)
+its bytes in the source text (when [`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/front/index.md

@@ -18,7 +18,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 
 Throws [`invalid_iterator.214`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator214) if the view is [null](https://json.nlohmann.me/api/basic_json_view/is_null/index.md) or [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md), or if it is an empty array or object.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) the exception names the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

api/basic_json_view/get.md

@@ -80,14 +80,13 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 - For every other `T`: whatever [`materialize().get<T>()`](../basic_json/get.md) throws — typically `type_error.302`,
   or whatever a user-provided `from_json()` throws.
 
-None of the exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four
-bullets above) carry a
-[`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no `BasicJsonType` value to point at. An
-exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real
-`BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled.
-That path is relative to the root of the view's subtree, because `materialize()` builds only the subtree (with parent
-pointers): it is empty if the failing value is the subtree's root itself, and it never is the path within the whole
-document.
+The exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four bullets
+above) carry the context of those of `BasicJsonType`: with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) the
+JSON Pointer path of the value within the document, and with
+[`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) its bytes in the source text. An exception
+thrown while converting through `materialize()` (the last bullet) is thrown by the materialized `BasicJsonType` value
+instead: its path is relative to the root of the view's subtree, because `materialize()` builds only the subtree
+(with parent pointers), so it is empty if the failing value is the subtree's root itself.
 
 ## Complexity
 

api/basic_json_view/get/index.md

@@ -47,7 +47,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 - For a `T` whose `from_json()` reads the view: whatever that `from_json()` throws; for the library's conversions and the macros, the same exceptions with the same messages as [`BasicJsonType::get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) of the same value.
 - For every other `T`: whatever [`materialize().get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) throws — typically `type_error.302`, or whatever a user-provided `from_json()` throws.
 
-None of the exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four bullets above) carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at. An exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real `BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled. That path is relative to the root of the view's subtree, because `materialize()` builds only the subtree (with parent pointers): it is empty if the failing value is the subtree's root itself, and it never is the path within the whole document.
+The exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four bullets above) carry the context of those of `BasicJsonType`: with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text. An exception thrown while converting through `materialize()` (the last bullet) is thrown by the materialized `BasicJsonType` value instead: its path is relative to the root of the view's subtree, because `materialize()` builds only the subtree (with parent pointers), so it is empty if the failing value is the subtree's root itself.
 
 ## Complexity
 

api/basic_json_view/get_string.md

@@ -22,9 +22,9 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value is not a string; example:
 `"type must be string, but is array"`.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) the exception names the JSON Pointer
+path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md)
+its bytes in the source text (when [`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/get_string/index.md

@@ -18,7 +18,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 
 Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if the value is not a string; example: `"type must be string, but is array"`.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) the exception names the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

api/basic_json_view/number_token.md

@@ -22,9 +22,9 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value is not a number; example:
 `"type must be number, but is string"`.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) the exception names the JSON Pointer
+path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md)
+its bytes in the source text (when [`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/number_token/index.md

@@ -18,7 +18,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 
 Throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if the value is not a number; example: `"type must be number, but is string"`.
 
-This exception does not carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) the exception names the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

api/basic_json_view/operator%5B%5D.md

@@ -73,9 +73,10 @@ Strong guarantee: there are no changes to the view or the document it refers to.
     - [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in `ptr` is not a
       number.
 
-None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) these exceptions name the JSON
+Pointer path of the value within the document, and with
+[`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) its bytes in the source text (when
+[`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/operator[]/index.md

@@ -47,7 +47,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
    - [`parse_error.106`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error106) if an array index in `ptr` begins with `'0'`.
    - [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) if an array index in `ptr` is not a number.
 
-None of these exceptions carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) these exceptions name the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

api/basic_json_view/value.md

@@ -61,9 +61,10 @@ Strong guarantee: there are no changes to the view or the document it refers to.
    `default_value` instead of throwing, exactly as [`BasicJsonType::value`](../basic_json/value.md) catches
    `out_of_range` and returns `default_value`.
 
-None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
-`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
-`JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) these exceptions name the JSON
+Pointer path of the value within the document, and with
+[`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) its bytes in the source text (when
+[`materialize()`](materialize.md) sets them).
 
 ## Complexity
 

api/basic_json_view/value/index.md

@@ -43,7 +43,7 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 1. Throws [`type_error.306`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error306) if the value is not an object — the same exception, with the same message, that [`BasicJsonType::value`](https://json.nlohmann.me/api/basic_json/value/index.md) throws for the same call. If a member with key `key` is found, throws whatever converting it to `T` throws (typically [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302), with the same message [`BasicJsonType::value`](https://json.nlohmann.me/api/basic_json/value/index.md) throws for the same mismatch); a missing member never throws.
 1. Throws [`type_error.306`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error306) if this value — not the value `ptr` resolves to — is neither an object nor an array. Throws [`parse_error.106`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error106) or [`parse_error.109`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error109) if `ptr` contains a malformed array index. If `ptr` resolves to a value, throws whatever converting it to `T` throws. Every other way `ptr` can fail to resolve — a missing key, an out-of-range or "`-`" array index, an unresolvable token on a primitive — yields `default_value` instead of throwing, exactly as [`BasicJsonType::value`](https://json.nlohmann.me/api/basic_json/value/index.md) catches `out_of_range` and returns `default_value`.
 
-None of these exceptions carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with `JSON_DIAGNOSTICS` enabled.
+As for `BasicJsonType`, with [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) these exceptions name the JSON Pointer path of the value within the document, and with [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) its bytes in the source text (when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) sets them).
 
 ## Complexity
 

features/json_view.md

@@ -432,9 +432,21 @@ document: `#!cpp auto v = json_document::parse(text).root();` does not compile.
 - **Macros.** [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md) and
   [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md)/[`JSON_THROW_USER`](../api/macros/json_throw_user.md)
   behave the same way they do for `<nlohmann/json.hpp>`. These are the macros that change what the parser accepts or
-  how it reports errors. The others either do not apply ([`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md)
-  needs parent pointers in `basic_json` values) or only affect the values `materialize()` produces, through
-  `BasicJsonType`.
+  how it reports errors. Two more macros add context to the exceptions of views, as they do for those of
+  `#!cpp basic_json`:
+
+    - With [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md), an exception names the JSON Pointer path of the
+      value within the document.
+    - With [`JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md), an exception names the bytes of
+      the value in the source text.
+
+    A view has neither parent pointers nor stored positions, so both are found from the document's index when the
+    exception is thrown. This takes time linear in the size of the document. One exception has neither:
+    `key()` of an iterator over an array or a primitive value
+    ([`invalid_iterator.207`](../home/exceptions.md#jsonexceptioninvalid_iterator207)), because a view's iterator does
+    not know the value it iterates over.
+
+    The other macros only affect the values `materialize()` produces, through `BasicJsonType`.
 
 ## What is different
 
@@ -465,10 +477,6 @@ document: `#!cpp auto v = json_document::parse(text).root();` does not compile.
   [`at`](../api/basic_json_view/at.md) throws for every missing value.
 - **Duplicate keys: lookups find the first member, `parse()` keeps the last.** See [Duplicate keys](#duplicate-keys)
   below.
-- **No [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) path.** Exceptions thrown by `basic_json_view`'s own
-  element access and lookup functions never carry the JSON Pointer path `JSON_DIAGNOSTICS` would otherwise add: the
-  view has no `basic_json` value to point at, so the exception is created without one, regardless of how
-  `BasicJsonType` was built.
 - **Ordering comparisons are not provided** by `basic_json_view` — there is no `#!cpp operator<`.
   [`operator==`](../api/basic_json_view/operator_eq.md) and [`operator!=`](../api/basic_json_view/operator_ne.md) are
   provided, though: two views, or a view and a `BasicJsonType` value, compare equal exactly when
@@ -551,6 +559,34 @@ Two conversions never copy at all:
 
 Both results are only valid as long as the view — and, for a string with no escapes, the borrowed source text — is.
 
+### `string_view` members
+
+A struct whose member is a `#!cpp std::string_view` (C++17) can be decoded from a view with the
+`NLOHMANN_DEFINE_TYPE_*` macros, and the member is not copied either: for a string without escape sequences it points
+into the document's source text, and for a string with escape sequences into the document's buffer of decoded strings.
+The member is valid as long as the document is alive and, for a document that
+[borrows its source text](#ownership-and-lifetime) (as [`parse()`](../api/basic_json_document/parse.md) does for
+an lvalue `#!cpp std::string`, a `#!cpp std::string_view`, or a C string), as long as that text is.
+
+```cpp
+struct record
+{
+    std::string_view name;
+    int count;
+    NLOHMANN_DEFINE_TYPE_INTRUSIVE(record, name, count)
+};
+
+const std::string text = R"({"name": "widget", "count": 3})";
+const json_document doc = json_document::parse(text);  // borrows text
+const record r = doc.root().get<record>();             // r.name points into text, valid while text and doc are
+```
+
+!!! warning "Decoding into a `string_view` from a `json` value dangles at once"
+
+    The same struct also compiles with `#!cpp json::parse(text).get<record>()`, but there `name` points into the
+    temporary `json` value, which is destroyed at the end of the statement. Use a named
+    [`json_document`](../api/json_document.md), as above, to decode such a struct.
+
 ## Writing generic code
 
 A view's type names its `BasicJsonType` and its [`view_mode`](../api/view_mode.md):
@@ -627,14 +663,10 @@ Its body may only use what views and `basic_json` have in common: the type check
 a view does not have; such a type is converted through `materialize()`. A `from_json()` for `json` only is
 converted through `materialize()` as well.
 
-Two things differ when a `from_json()` reads the view:
-
-- **Duplicate keys.** Members looked up by name (`at()`, `value()`, ... and thus the macros) find the **first** member
-  with a repeated key, see [Duplicate keys](#duplicate-keys); `#!cpp materialize().get<T>()` would see the last one.
-  Containers built from an object, such as `#!cpp std::map`, keep the **last** value either way, as
-  [`parse()`](../api/basic_json/parse.md) does.
-- **[`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md).** Exceptions thrown by the view carry no path to the
-  value.
+One thing differs when a `from_json()` reads the view: members looked up by name (`at()`, `value()`, ... and thus
+the macros) find the **first** member with a repeated key, see [Duplicate keys](#duplicate-keys);
+`#!cpp materialize().get<T>()` would see the last one. Containers built from an object, such as `#!cpp std::map`,
+keep the **last** value either way, as [`parse()`](../api/basic_json/parse.md) does.
 
 `to_json()` is unaffected: it writes `basic_json` values, never views.
 

features/json_view/index.md

@@ -121,9 +121,19 @@ true
 ## What is the same as `parse()`
 
 - **Accept/reject.** [`accept()`](https://json.nlohmann.me/api/basic_json_document/accept/index.md) and [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) accept and reject exactly the same inputs as [`basic_json::accept()`](https://json.nlohmann.me/api/basic_json/accept/index.md)/[`basic_json::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md), with the same `ignore_comments` and `ignore_trailing_commas` options.
+
 - **Errors.** A failing parse throws the same exception — the same id, message, and position — because on failure the library's own parser is run on the same bytes to produce the diagnostic. Valid input never pays for this, and the replay builds no values: it costs about a lexing pass up to the error. `allow_exceptions == false` skips the replay and gives a [discarded](https://json.nlohmann.me/api/basic_json_document/is_discarded/index.md) document instead of throwing, just as it gives a discarded value for `basic_json::parse()`.
+
 - **Number classification.** An integer literal that does not fit into the 64-bit integer type becomes a floating-point value, exactly as it does for `basic_json::parse()`.
-- **Macros.** [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) and [`JSON_NOEXCEPTION`](https://json.nlohmann.me/api/macros/json_noexception/index.md)/[`JSON_THROW_USER`](https://json.nlohmann.me/api/macros/json_throw_user/index.md) behave the same way they do for `<nlohmann/json.hpp>`. These are the macros that change what the parser accepts or how it reports errors. The others either do not apply ([`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) needs parent pointers in `basic_json` values) or only affect the values `materialize()` produces, through `BasicJsonType`.
+
+- **Macros.** [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) and [`JSON_NOEXCEPTION`](https://json.nlohmann.me/api/macros/json_noexception/index.md)/[`JSON_THROW_USER`](https://json.nlohmann.me/api/macros/json_throw_user/index.md) behave the same way they do for `<nlohmann/json.hpp>`. These are the macros that change what the parser accepts or how it reports errors. Two more macros add context to the exceptions of views, as they do for those of `basic_json`:
+
+  - With [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md), an exception names the JSON Pointer path of the value within the document.
+  - With [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md), an exception names the bytes of the value in the source text.
+
+  A view has neither parent pointers nor stored positions, so both are found from the document's index when the exception is thrown. This takes time linear in the size of the document. One exception has neither: `key()` of an iterator over an array or a primitive value ([`invalid_iterator.207`](https://json.nlohmann.me/home/exceptions/#jsonexceptioninvalid_iterator207)), because a view's iterator does not know the value it iterates over.
+
+  The other macros only affect the values `materialize()` produces, through `BasicJsonType`.
 
 ## What is different
 
@@ -134,7 +144,6 @@ true
 - **Objects iterate in document order.** [`begin()`](https://json.nlohmann.me/api/basic_json_view/begin/index.md)/ [`end()`](https://json.nlohmann.me/api/basic_json_view/end/index.md) and [`items()`](https://json.nlohmann.me/api/basic_json_view/items/index.md) visit an object's members in the order they appear in the source text. `basic_json`'s default `object_t` is a `std::map`, which sorts by key, so iterating a [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md)d value can print members in a different order than iterating the view they came from.
 - **Chained access is safe.** [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) with a missing key, an index out of range, or an unresolvable JSON pointer returns a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) view, and `operator[]` on a discarded view returns a discarded view without throwing: `v["a"]["b"][0]` can be tested once at the end. Type errors on values that exist (a key on an array, an index on an object) still throw, and [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md) throws for every missing value.
 - **Duplicate keys: lookups find the first member, `parse()` keeps the last.** See [Duplicate keys](#duplicate-keys) below.
-- **No [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path.** Exceptions thrown by `basic_json_view`'s own element access and lookup functions never carry the JSON Pointer path `JSON_DIAGNOSTICS` would otherwise add: the view has no `basic_json` value to point at, so the exception is created without one, regardless of how `BasicJsonType` was built.
 - **Ordering comparisons are not provided** by `basic_json_view` — there is no `operator<`. [`operator==`](https://json.nlohmann.me/api/basic_json_view/operator_eq/index.md) and [`operator!=`](https://json.nlohmann.me/api/basic_json_view/operator_ne/index.md) are provided, though: two views, or a view and a `BasicJsonType` value, compare equal exactly when [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) or [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) would produce equal values for them, without ever building a tree to do it. For ordering, too, [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) is the way to get a value you can compare.
 
 ## Duplicate keys
@@ -178,6 +187,27 @@ Two conversions never copy at all:
 
 Both results are only valid as long as the view — and, for a string with no escapes, the borrowed source text — is.
 
+### `string_view` members
+
+A struct whose member is a `std::string_view` (C++17) can be decoded from a view with the `NLOHMANN_DEFINE_TYPE_*` macros, and the member is not copied either: for a string without escape sequences it points into the document's source text, and for a string with escape sequences into the document's buffer of decoded strings. The member is valid as long as the document is alive and, for a document that [borrows its source text](#ownership-and-lifetime) (as [`parse()`](https://json.nlohmann.me/api/basic_json_document/parse/index.md) does for an lvalue `std::string`, a `std::string_view`, or a C string), as long as that text is.
+
+```
+struct record
+{
+    std::string_view name;
+    int count;
+    NLOHMANN_DEFINE_TYPE_INTRUSIVE(record, name, count)
+};
+
+const std::string text = R"({"name": "widget", "count": 3})";
+const json_document doc = json_document::parse(text);  // borrows text
+const record r = doc.root().get<record>();             // r.name points into text, valid while text and doc are
+```
+
+Decoding into a `string_view` from a `json` value dangles at once
+
+The same struct also compiles with `json::parse(text).get<record>()`, but there `name` points into the temporary `json` value, which is destroyed at the end of the statement. Use a named [`json_document`](https://json.nlohmann.me/api/json_document/index.md), as above, to decode such a struct.
+
 ## Writing generic code
 
 A view's type names its `BasicJsonType` and its [`view_mode`](https://json.nlohmann.me/api/view_mode/index.md): [`json_view`](https://json.nlohmann.me/api/json_view/index.md) is `basic_json_view<json, view_mode::read_only>`, and [`json_editable_view`](https://json.nlohmann.me/api/json_editable_view/index.md) is `basic_json_view<json, view_mode::editable>`. These are different types. The only conversion between them turns a view of a read-only document into a view of an editable document of the same `BasicJsonType`, so a function written for one shortcut accepts few other views:
@@ -227,10 +257,7 @@ void from_json(const J& j, person& p)
 
 Its body may only use what views and `basic_json` have in common: the type checks, `at()`, `operator[]`, `contains()`, `value()`, `size()`, iteration and `items()`, and `get<T>()`/`get_to()`. An unconstrained `template<typename BasicJsonType> void from_json(const BasicJsonType& j, person& p)`, as in [arbitrary type conversions](https://json.nlohmann.me/features/arbitrary_types/index.md), is never called with a view, as it might use `basic_json` functions a view does not have; such a type is converted through `materialize()`. A `from_json()` for `json` only is converted through `materialize()` as well.
 
-Two things differ when a `from_json()` reads the view:
-
-- **Duplicate keys.** Members looked up by name (`at()`, `value()`, ... and thus the macros) find the **first** member with a repeated key, see [Duplicate keys](#duplicate-keys); `materialize().get<T>()` would see the last one. Containers built from an object, such as `std::map`, keep the **last** value either way, as [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) does.
-- **[`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md).** Exceptions thrown by the view carry no path to the value.
+One thing differs when a `from_json()` reads the view: members looked up by name (`at()`, `value()`, ... and thus the macros) find the **first** member with a repeated key, see [Duplicate keys](#duplicate-keys); `materialize().get<T>()` would see the last one. Containers built from an object, such as `std::map`, keep the **last** value either way, as [`parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) does.
 
 `to_json()` is unaffected: it writes `basic_json` values, never views.
 

home/debugging.md

@@ -10,6 +10,13 @@ at its root, a [Natvis](https://learn.microsoft.com/en-us/visualstudio/debugger/
 file that gives `json`/`ordered_json` values a friendly, key/value debugger view instead of showing raw internal
 fields, when debugging with the MSVC debug engine (`cppvsdbg`) in Visual Studio or VS Code.
 
+The file also has visualizers for `json_document` and `json_view` (and their `ordered_json`/editable variants). They
+show the value of the document or view, and its elements as an expandable list. Because a document is only a flat index
+into the source text, the strings of the direct elements are shown, but the elements of nested arrays and objects are
+shown as index nodes (their kind, size, and numbers; strings only by length). Arrays and objects that have been edited
+in a `json_editable_document` are not expanded. The visualizers read the internal layout of the MSVC STL (`std::array`,
+`std::unique_ptr`).
+
 The checked-in visualizers cover namespace variants with zero, one, or two ABI tags. Configurations with three or more
 ABI tags are not covered and may show raw internal fields instead. To generate a Natvis file for such a configuration:
 
@@ -29,7 +36,7 @@ ABI tags are not covered and may show raw internal fields instead. To generate a
 
 4. Use the generated file instead of `nlohmann_json.natvis`.
 
-`--abi-tags` can be repeated for several configurations, and `--all` generates every combination (about 60 MB for 12
+`--abi-tags` can be repeated for several configurations, and `--all` generates every combination (about 60 MB for 11
 ABI tags, doubling with each further tag). See
 [`tools/generate_natvis`](https://github.com/nlohmann/json/tree/develop/tools/generate_natvis) for all options.
 

home/debugging/index.md

@@ -6,6 +6,8 @@ This page collects the library's built-in debugger integrations and other debugg
 
 The repository ships [`nlohmann_json.natvis`](https://github.com/nlohmann/json/blob/develop/nlohmann_json.natvis) at its root, a [Natvis](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects) file that gives `json`/`ordered_json` values a friendly, key/value debugger view instead of showing raw internal fields, when debugging with the MSVC debug engine (`cppvsdbg`) in Visual Studio or VS Code.
 
+The file also has visualizers for `json_document` and `json_view` (and their `ordered_json`/editable variants). They show the value of the document or view, and its elements as an expandable list. Because a document is only a flat index into the source text, the strings of the direct elements are shown, but the elements of nested arrays and objects are shown as index nodes (their kind, size, and numbers; strings only by length). Arrays and objects that have been edited in a `json_editable_document` are not expanded. The visualizers read the internal layout of the MSVC STL (`std::array`, `std::unique_ptr`).
+
 The checked-in visualizers cover namespace variants with zero, one, or two ABI tags. Configurations with three or more ABI tags are not covered and may show raw internal fields instead. To generate a Natvis file for such a configuration:
 
 1. Check out the release tag of the library version you use.
@@ -24,7 +26,7 @@ The checked-in visualizers cover namespace variants with zero, one, or two ABI t
 
 1. Use the generated file instead of `nlohmann_json.natvis`.
 
-`--abi-tags` can be repeated for several configurations, and `--all` generates every combination (about 60 MB for 12 ABI tags, doubling with each further tag). See [`tools/generate_natvis`](https://github.com/nlohmann/json/tree/develop/tools/generate_natvis) for all options.
+`--abi-tags` can be repeated for several configurations, and `--all` generates every combination (about 60 MB for 11 ABI tags, doubling with each further tag). See [`tools/generate_natvis`](https://github.com/nlohmann/json/tree/develop/tools/generate_natvis) for all options.
 
 Debug engines that wrap LLDB instead of the MSVC debug engine (for example, `codelldb` in VS Code) only have partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the `.natvis` file present. Switching to `cppvsdbg` where available, or checking your debug extension's own Natvis support/version, are the next things to try if this happens. There is currently no bundled LLDB-native pretty-printer script in this repository.
 

home/license.md

@@ -22,8 +22,8 @@ The class contains a port of the shortest double-to-decimal conversion of [Żmij
 
 The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).
 
-The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, and its digit comparison for long numbers from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright © 2021 The fast_float authors
+The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, its digit comparison for long numbers, and its parsing of eight digits at a time from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright © 2021 The fast_float authors
 
 The view's parser (`<nlohmann/json_view.hpp>`) contains techniques and code adapted from [yyjson](https://github.com/ibireme/yyjson) by YaoYuan, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above): table-driven decoding of `\u` escapes and fixed-offset unrolled checks.
 
-The view's parser (`<nlohmann/json_view.hpp>`) validates non-ASCII strings with the vector UTF-8 check of [simdjson](https://github.com/simdjson/simdjson) by Daniel Lemire, Geoff Langdale, John Keiser, and contributors (its "lookup4" algorithm and tables, after J. Keiser and D. Lemire, "Validating UTF-8 In Less Than One Instruction Per Byte", 2021), which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here) and the Apache 2.0 License. Copyright &copy; 2018-2025 The simdjson authors
+The class's lexer and the view's parser (`<nlohmann/json_view.hpp>`) validate non-ASCII strings with the vector UTF-8 check of [simdjson](https://github.com/simdjson/simdjson) by Daniel Lemire, Geoff Langdale, John Keiser, and contributors (its "lookup4" algorithm and tables, after J. Keiser and D. Lemire, "Validating UTF-8 In Less Than One Instruction Per Byte", 2021), which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here) and the Apache 2.0 License. Copyright &copy; 2018-2025 The simdjson authors

home/license/index.md

@@ -20,8 +20,8 @@ The class contains a port of the shortest double-to-decimal conversion of [Żmij
 
 The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).
 
-The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, and its digit comparison for long numbers from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright © 2021 The fast_float authors
+The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, its digit comparison for long numbers, and its parsing of eight digits at a time from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright © 2021 The fast_float authors
 
 The view's parser (`<nlohmann/json_view.hpp>`) contains techniques and code adapted from [yyjson](https://github.com/ibireme/yyjson) by YaoYuan, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above): table-driven decoding of `\u` escapes and fixed-offset unrolled checks.
 
-The view's parser (`<nlohmann/json_view.hpp>`) validates non-ASCII strings with the vector UTF-8 check of [simdjson](https://github.com/simdjson/simdjson) by Daniel Lemire, Geoff Langdale, John Keiser, and contributors (its "lookup4" algorithm and tables, after J. Keiser and D. Lemire, "Validating UTF-8 In Less Than One Instruction Per Byte", 2021), which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here) and the Apache 2.0 License. Copyright © 2018-2025 The simdjson authors
+The class's lexer and the view's parser (`<nlohmann/json_view.hpp>`) validate non-ASCII strings with the vector UTF-8 check of [simdjson](https://github.com/simdjson/simdjson) by Daniel Lemire, Geoff Langdale, John Keiser, and contributors (its "lookup4" algorithm and tables, after J. Keiser and D. Lemire, "Validating UTF-8 In Less Than One Instruction Per Byte", 2021), which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here) and the Apache 2.0 License. Copyright © 2018-2025 The simdjson authors