amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-10-29 09:05:42 +00:00

Files

T

Niels Lohmann cf8b7c8b8d Document the contract of object keys passed to json_sax::key and key callbacks

Describe what the name passed to json_sax::key and to a parser callback
for parse_event_t::key holds when parsing JSON text: escapes are decoded
to UTF-8, different spellings of a name yield identical strings, the name
is validated before the call (invalid escapes or UTF-8 give a parse error
and no key event), no normalization or case conversion is applied, the
event precedes the ':' check, and duplicate names are reported once per
occurrence. Also note that sax_parse passes binary-format keys unchanged.

See discussion #5955.

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

2026-10-28 20:29:43 +01:00

2.0 KiB

Raw Blame History

nlohmann::json_sax::key

virtual bool key(string_t& val) = 0;

An object key was read.

Parameters

val (in): object key

Return value

Whether parsing should proceed.

Notes

It is safe to move the passed object key value.

When parsing JSON text, val is the decoded object name, not its spelling in the input:

All escape sequences (\", \\, \/, \b, \f, \n, \r, \t, \uXXXX, and surrogate pairs) are decoded, and \uXXXX escapes are stored as UTF-8. Different spellings of the same name, such as #!json "/" and #!json "\/", or #!json "\u00e9" and #!json "\u00E9", yield identical strings. An escaped \u0000 yields an embedded NUL byte.
The name is scanned and validated completely before key is called. If it contains an invalid escape sequence, an unpaired surrogate, a control character, or ill-formed UTF-8, the parse fails with a parse_error, and key is not called for it.
No Unicode normalization or case conversion is applied: names that differ in any byte are different strings.
key is called before the following : is read, so a parse error may still follow for the same member.
A name that occurs several times in the same object is passed once per occurrence.

For the binary formats, object keys contain no escape sequences: val holds the bytes stored in the input. sax_parse passes them unchanged, without checking them for valid UTF-8.

Examples

??? example

The example below shows how the SAX interface is used.

```cpp
--8<-- "examples/sax_parse.cpp"
```

Output:

```json
--8<-- "examples/sax_parse.output"
```

Version history

Added in version 3.2.0.

2.0 KiB Raw Blame History