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