Niels Lohmann
4c130c33d9
With JSON_DIAGNOSTIC_POSITIONS, materialize() now gives every value the start_pos()/end_pos() that basic_json::parse() would give it, so exceptions about materialized values name the same bytes (#5864). - json_sax_dom_parser takes the lexer type as a defaulted template parameter; materialize() passes position_source, which reports the positions it derives from the index. diagnostic_positions treats npos as "no position" and keeps ranges all-or-nothing. - Strings with escapes keep the offset of their opening quote plus one in `next` (only with the macro); materialize() scans from there to the closing quote. The end of an array or object is found by scanning from the end of its last element over whitespace, comments and a trailing comma. - In editable documents, values written by edits, arrays and objects whose elements changed, and containers whose last element has no position get none. Images keep the flag is_new, and load() checks that `next` of a string is within the text. Nothing changes on the parse path without the macro. The view's own exceptions still carry no byte range, so the tests that compare them with those of materialized values skip it under the macro, as they skip the path under JSON_DIAGNOSTICS. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
5.2 KiB
JSON_DIAGNOSTIC_POSITIONS
#define JSON_DIAGNOSTIC_POSITIONS /* value */
This macro enables position diagnostics for generated JSON objects.
When enabled, two new member functions start_pos() and
end_pos() are added to basic_json values. If the value was
created by calling theparse function, then these functions allow querying the byte positions
of the value in the input it was parsed from. In case the value was constructed by other means, std::string::npos is
returned.
start_pos() returns the position of the first character of a given value in the original
JSON string, while end_pos() returns the position of the character following the last
character. For objects and arrays, the first and last characters correspond to the opening or closing braces/brackets,
respectively. For primitive values, the first and last character represents the opening and closing quotes (strings) or
the first and last character of the field's numerical or predefined value (true, false, null), respectively.
| JSON type | return value start_pos() |
return value end_pos() |
|---|---|---|
| object | position of the opening { |
position after the closing } |
| array | position of the opening [ |
position after the closing ] |
| string | position of the opening " |
position after the closing " |
| number | position of the first character | position after the last character |
| boolean | position of t for true and f for false |
position after e |
| null | position of n |
position after l |
Given the above, end_pos()-start_pos() for a JSON
value provides the length of the parsed JSON string for that value, including the opening or closing braces, brackets,
or quotes.
Note that enabling this macro increases the size of every JSON value by two std::size_t fields and adds slight runtime
overhead to parsing, copying JSON value objects, and the generation of error messages for exceptions. It also causes
these values to be reported in those error messages.
Default definition
The default value is 0 (position diagnostics are switched off).
#define JSON_DIAGNOSTIC_POSITIONS 0
When the macro is not defined, the library will define it to its default value.
Notes
!!! note "CMake option"
Diagnostic positions can also be controlled with the CMake option
[`JSON_Diagnostic_Positions`](../../integration/cmake.md#json_diagnostic_positions) (`OFF` by default)
which defines `JSON_DIAGNOSTIC_POSITIONS` accordingly.
!!! note "Availability"
Diagnostic positions are only available if the value was created by the [`parse`](../basic_json/parse.md) function.
The [`sax_parse`](../basic_json/sax_parse.md) function or all other means to create a JSON value **do not** set the
diagnostic positions and [`start_pos()`](../basic_json/start_pos.md) and [`end_pos()`](../basic_json/end_pos.md)
will only return `std::string::npos` for these values.
!!! warning "Invalidation"
The returned positions are only valid as long as the JSON value is not changed. The positions are *not* updated
when the JSON value is changed.
Examples
??? example "Example: retrieving positions"
```cpp
--8<-- "examples/diagnostic_positions.cpp"
```
Output:
```
--8<-- "examples/diagnostic_positions.output"
```
The output shows the start/end positions of all the objects and fields in the JSON string.
??? example "Example: using only diagnostic positions in exceptions"
```cpp
--8<-- "examples/diagnostic_positions_exception.cpp"
```
Output:
```
--8<-- "examples/diagnostic_positions_exception.output"
```
The output shows the exception with start/end positions only.
??? example "Example: using extended diagnostics with positions enabled in exceptions"
```cpp
--8<-- "examples/diagnostics_extended_positions.cpp"
```
Output:
```
--8<-- "examples/diagnostics_extended_positions.output"
```
The output shows the exception with diagnostic path info and start/end positions.
See also
- :simple-cmake: JSON_Diagnostic_Positions - CMake option to control the macro
JSON_DIAGNOSTICS- macro to control extended diagnosticsmaterialize()- values of a JSON view, with the same positions- Parsing and Exceptions - handling parse errors and locating them in the input
Version history
- Added in version 3.12.0.