Skip to content

Commit e00484f

Browse files
authored
📝 update sax_parse documentation (#4878)
1 parent c5cc4fa commit e00484f

File tree

2 files changed

+15
-3
lines changed

2 files changed

+15
-3
lines changed

docs/mkdocs/docs/api/basic_json/sax_parse.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,10 +51,10 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
5151
## Parameters
5252
5353
`i` (in)
54-
: Input to parse from.
54+
: Input to parse from
5555
5656
`sax` (in)
57-
: SAX event listener
57+
: SAX event listener (must not be null)
5858
5959
`format` (in)
6060
: the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default), see
@@ -83,6 +83,17 @@ return value of the last processed SAX event
8383
8484
## Exception safety
8585
86+
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
87+
88+
## Exceptions
89+
90+
- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
91+
empty input like a null `FILE*` or `char*` pointer.
92+
- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if `to_unicode` fails or surrogate
93+
error.
94+
- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if `to_unicode` fails.
95+
- Throws [`other_error.502`](../../home/exceptions.md#jsonexceptionother_error502) if `sax` is a null pointer.
96+
8697
## Complexity
8798
8899
Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX
@@ -114,6 +125,7 @@ A UTF-8 byte order mark is silently ignored.
114125
- Added in version 3.2.0.
115126
- Ignoring comments via `ignore_comments` added in version 3.9.0.
116127
- Added `ignore_trailing_commas` in version 3.12.1.
128+
- Added `json.exception.other_error.502` exception in version 3.12.1.
117129
118130
!!! warning "Deprecation"
119131

docs/mkdocs/docs/home/exceptions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -903,7 +903,7 @@ A JSON Patch operation 'test' failed. The unsuccessful operation is also printed
903903

904904
### json.exception.other_error.502
905905

906-
This exception occurs when a null pointer is passed as SAX handler in [sax_parse](../api/basic_json/sax_parse.md) function.
906+
This exception is thrown when a null pointer is passed as SAX event listener to the [sax_parse](../api/basic_json/sax_parse.md) function.
907907

908908
!!! failure "Example message"
909909

0 commit comments

Comments
 (0)