json/docs/mkdocs/docs/api/macros/json_diagnostic_positions.md

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. In addition, parse(), accept(), and sax_parse() no longer use the faster path for input in one block of memory, so parsing a string or a buffer is slower than without the macro.

If JSON_DIAGNOSTICS is also set, the message contains the path and the byte range, such as (/1) (bytes 4-8). An exception about the root value has no path and only the range, such as (bytes 0-4).

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 diagnostics
• materialize() - 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.