deploy: 63c10a51fc

api/json_sax/index.md

@@ -7,6 +7,24 @@ struct json_sax;
 
 This class describes the SAX interface used by [sax_parse](https://json.nlohmann.me/api/basic_json/sax_parse/index.md). Each function is called in different situations while the input is parsed. The boolean return value informs the parser whether to continue processing the input.
 
+For instance, parsing the JSON text `{"a": [1, true]}` triggers the following callbacks, in order:
+
+```
+sequenceDiagram
+    participant P as Parser
+    participant H as SAX handler
+
+    P->>H: start_object(elements)
+    P->>H: key("a")
+    P->>H: start_array(elements)
+    P->>H: number_unsigned(1)
+    P->>H: boolean(true)
+    P->>H: end_array()
+    P->>H: end_object()
+```
+
+Note `elements` is passed as `std::numeric_limits<std::size_t>::max()` (i.e., "unknown") for JSON text input; only binary formats such as CBOR or MessagePack may report the actual number of elements in `start_object`/ `start_array`. Also note that `1` is reported via `number_unsigned` rather than `number_integer` because it has no leading `-` sign.
+
 ## Template parameters
 
 `BasicJsonType` : a specialization of [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md)