deploy: 2aecd86b37

api/basic_json/parser_callback_t.md

@@ -102,6 +102,15 @@ called:
 Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
 the latter case, it is skipped completely, or replaced by `null` if it is the top-level value.
 
+## Notes
+
+For a `parse_event_t::key` event, `parsed` holds the decoded object name, with the same guarantees as the `val`
+parameter of [`json_sax::key`](../json_sax/key.md#notes): all escape sequences are decoded and `\uXXXX` escapes are
+stored as UTF-8, so different spellings of the same name yield identical strings; the name is validated completely
+before the callback is called, so a name with an invalid escape sequence or ill-formed UTF-8 causes a parse error and
+no `key` event; no Unicode normalization or case conversion is applied; and a name that occurs several times in the
+same object yields one `key` event per occurrence.
+
 ## Examples
 
 ??? example "Example: skip an object key while parsing"

api/basic_json/parser_callback_t/index.md

@@ -40,6 +40,10 @@ Discarding a value (i.e., returning `false`) has different effects depending on
 
 Whether the JSON value which called the function during parsing should be kept (`true`) or not (`false`). In the latter case, it is skipped completely, or replaced by `null` if it is the top-level value.
 
+## Notes
+
+For a `parse_event_t::key` event, `parsed` holds the decoded object name, with the same guarantees as the `val` parameter of [`json_sax::key`](https://json.nlohmann.me/api/json_sax/key/#notes): all escape sequences are decoded and `\uXXXX` escapes are stored as UTF-8, so different spellings of the same name yield identical strings; the name is validated completely before the callback is called, so a name with an invalid escape sequence or ill-formed UTF-8 causes a parse error and no `key` event; no Unicode normalization or case conversion is applied; and a name that occurs several times in the same object yields one `key` event per occurrence.
+
 ## Examples
 
 Example: skip an object key while parsing

api/json_sax/key.md

@@ -19,6 +19,23 @@ Whether parsing should proceed.
 
 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`](../../home/exceptions.md#parse-errors), 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. For CBOR, MessagePack, UBJSON, and BSON, `val` holds
+the bytes stored in the input, and [`sax_parse`](../basic_json/sax_parse.md) passes them unchanged, without checking them
+for valid UTF-8. BON8 encodes characters itself, so an ill-formed name is a parse error and `key` is not called for it.
+
 ## Examples
 
 ??? example
@@ -213,3 +230,7 @@ It is safe to move the passed object key value.
 ## Version history
 
 - Added in version 3.2.0.
+- The behavior described in the notes above (decoded names, validation before `key` is called, no normalization, `key`
+  before the `:` check, one call per duplicate, bytes of binary formats passed unchanged) is the same in all versions
+  from 3.2.0 on, and for the `key` event of a [parser callback](../basic_json/parser_callback_t.md) from 3.0.0 on. BSON
+  is only supported from version 3.4.0, and BON8 only from version 3.13.0.

api/json_sax/key/index.md

@@ -18,6 +18,16 @@ Whether parsing should proceed.
 
 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 `"/"` and `"\/"`, or `"\u00e9"` and `"\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`](https://json.nlohmann.me/home/exceptions/#parse-errors), 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. For CBOR, MessagePack, UBJSON, and BSON, `val` holds the bytes stored in the input, and [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md) passes them unchanged, without checking them for valid UTF-8. BON8 encodes characters itself, so an ill-formed name is a parse error and `key` is not called for it.
+
 ## Examples
 
 Example
@@ -210,3 +220,4 @@ result: false
 ## Version history
 
 - Added in version 3.2.0.
+- The behavior described in the notes above (decoded names, validation before `key` is called, no normalization, `key` before the `:` check, one call per duplicate, bytes of binary formats passed unchanged) is the same in all versions from 3.2.0 on, and for the `key` event of a [parser callback](https://json.nlohmann.me/api/basic_json/parser_callback_t/index.md) from 3.0.0 on. BSON is only supported from version 3.4.0, and BON8 only from version 3.13.0 unreleased.

features/parsing/sax_interface.md

@@ -64,6 +64,9 @@ bool parse_error(std::size_t position, const std::string& last_token, const json
 
 The return value of each function determines whether parsing should proceed.
 
+Object keys are passed to `key` decoded and validated: escape sequences are already resolved, so different spellings of
+the same name yield the same string. See [`key`](../../api/json_sax/key.md#notes) for the exact guarantees.
+
 ## Stepping through the events
 
 The events for a small input, step by step, and what two different handlers do with them. Press *Play* or step with *Next*:

features/parsing/sax_interface/index.md

@@ -64,6 +64,8 @@ bool parse_error(std::size_t position, const std::string& last_token, const json
 
 The return value of each function determines whether parsing should proceed.
 
+Object keys are passed to `key` decoded and validated: escape sequences are already resolved, so different spellings of the same name yield the same string. See [`key`](https://json.nlohmann.me/api/json_sax/key/#notes) for the exact guarantees.
+
 ## Stepping through the events
 
 The events for a small input, step by step, and what two different handlers do with them. Press *Play* or step with *Next*:

home/releases/v3.4.0/index.md

@@ -19,3 +19,4 @@ Feature release. All changes are backward-compatible.
 **Changed:**
 
 - [`basic_json::dump`](https://json.nlohmann.me/api/basic_json/dump/index.md): Error handlers added in version 3.4.0.
+- [`json_sax::key`](https://json.nlohmann.me/api/json_sax/key/index.md): BSON is only supported from version 3.4.0, and BON8 only from version 3.13.0 unreleased.