json_view: exceptions name the path and the bytes of the value (#5974)

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

docs/mkdocs/docs/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
 

docs/mkdocs/docs/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
 

docs/mkdocs/docs/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
 

docs/mkdocs/docs/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
 

docs/mkdocs/docs/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
 

docs/mkdocs/docs/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
 

docs/mkdocs/docs/api/basic_json_view/operator[].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
 

docs/mkdocs/docs/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
 

docs/mkdocs/docs/features/json_view.md

@@ -134,9 +134,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
 
@@ -167,10 +179,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
@@ -357,14 +365,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.