]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
1 | # <small>nlohmann::basic_json::</small>is_discarded |
2 | ||
3 | ```cpp | |
4 | constexpr bool is_discarded() const noexcept; | |
5 | ``` | |
6 | ||
7 | This function returns `#!cpp true` for a JSON value if either: | |
8 | ||
9 | - the value was discarded during parsing with a callback function (see [`parser_callback_t`](parser_callback_t.md)), or | |
10 | - the value is the result of parsing invalid JSON with parameter `allow_exceptions` set to `#!cpp false`; see | |
11 | [`parse`](parse.md) for more information. | |
12 | ||
13 | ## Return value | |
14 | ||
15 | `#!cpp true` if type is discarded, `#!cpp false` otherwise. | |
16 | ||
17 | ## Exception safety | |
18 | ||
19 | No-throw guarantee: this member function never throws exceptions. | |
20 | ||
21 | ## Complexity | |
22 | ||
23 | Constant. | |
24 | ||
25 | ## Notes | |
26 | ||
27 | !!! note | |
28 | ||
29 | Discarded values are never compared equal with [`operator==`](operator_eq.md). That is, checking whether a JSON | |
30 | value `j` is discarded will only work via: | |
31 | ||
32 | ```cpp | |
33 | j.is_discarded() | |
34 | ``` | |
35 | ||
36 | because | |
37 | ||
38 | ```cpp | |
39 | j == json::value_t::discarded | |
40 | ``` | |
41 | ||
42 | will always be `#!cpp false`. | |
43 | ||
44 | !!! note | |
45 | ||
46 | When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing, | |
47 | then it is removed when it is part of a structured value. For instance, if the second value of an array is discared, | |
48 | instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level | |
49 | value is discarded, the return value of the `parse` call is discarded. | |
50 | ||
51 | This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur | |
52 | during parsing, but will be removed when inside a structured value or replaced by null in other cases. | |
53 | ||
54 | ## Examples | |
55 | ||
56 | ??? example | |
57 | ||
58 | The following code exemplifies `is_discarded()` for all JSON types. | |
59 | ||
60 | ```cpp | |
61 | --8<-- "examples/is_discarded.cpp" | |
62 | ``` | |
63 | ||
64 | Output: | |
65 | ||
66 | ```json | |
67 | --8<-- "examples/is_discarded.output" | |
68 | ``` | |
69 | ||
70 | ## Version history | |
71 | ||
72 | - Added in version 1.0.0. |