mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 13:10:33 +00:00
Documentation change (#3672)
Co-authored-by: Florian Albrechtskirchinger <falbrechtskirchinger@gmail.com>
This commit is contained in:
co-authored by
Florian Albrechtskirchinger
parent
9e1a7c85e3
commit
7b6cf5918b
@@ -1,6 +1,10 @@
|
||||
# Parsing and Exceptions
|
||||
|
||||
When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
|
||||
When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown.
|
||||
This exception contains the position in the input where the error occurred, together with a diagnostic message and the
|
||||
last read input token. The exceptions page contains a
|
||||
[list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted
|
||||
input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
|
||||
|
||||
```cpp
|
||||
json j;
|
||||
@@ -19,7 +23,9 @@ In case exceptions are undesired or not supported by the environment, there are
|
||||
|
||||
## Switch off exceptions
|
||||
|
||||
The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`).
|
||||
The `parse()` function accepts a `#!cpp bool` parameter `allow_exceptions` which controls whether an exception is
|
||||
thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned
|
||||
(`#!cpp false`).
|
||||
|
||||
```cpp
|
||||
json j = json::parse(my_input, nullptr, false);
|
||||
@@ -33,7 +39,8 @@ Note there is no diagnostic information available in this scenario.
|
||||
|
||||
## Use accept() function
|
||||
|
||||
Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON.
|
||||
Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating
|
||||
whether the input is valid JSON.
|
||||
|
||||
```cpp
|
||||
if (!json::accept(my_input))
|
||||
|
||||
@@ -2,9 +2,10 @@
|
||||
|
||||
## Overview
|
||||
|
||||
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events
|
||||
(passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the
|
||||
callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
|
||||
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is
|
||||
called on certain events (passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and
|
||||
context JSON value `parsed`. The return value of the callback function is a boolean indicating whether the element that
|
||||
emitted the callback shall be kept or not.
|
||||
|
||||
The type of the callback function is:
|
||||
|
||||
@@ -17,8 +18,8 @@ using parser_callback_t =
|
||||
|
||||
## Callback event types
|
||||
|
||||
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
|
||||
of the parameters `depth`, `event`, and `parsed`.
|
||||
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
|
||||
table describes the values of the parameters `depth`, `event`, and `parsed`.
|
||||
|
||||
| parameter `event` | description | parameter `depth` | parameter `parsed` |
|
||||
|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
|
||||
@@ -59,10 +60,13 @@ of the parameters `depth`, `event`, and `parsed`.
|
||||
|
||||
## Return value
|
||||
|
||||
Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called:
|
||||
Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which the function
|
||||
was called:
|
||||
|
||||
- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read.
|
||||
- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the top-level element is skipped.
|
||||
- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
|
||||
read.
|
||||
- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the
|
||||
top-level element is skipped.
|
||||
|
||||
??? example
|
||||
|
||||
|
||||
Reference in New Issue
Block a user