mirror of
https://github.com/nlohmann/json.git
synced 2024-08-21 20:42:29 +02:00
📝 fix and extend documentation of discarded values
This commit is contained in:
parent
3be6ee3525
commit
b386f4de0b
36
doc/examples/parse__allow_exceptions.cpp
Normal file
36
doc/examples/parse__allow_exceptions.cpp
Normal file
|
@ -0,0 +1,36 @@
|
||||||
|
#include <iostream>
|
||||||
|
#include <nlohmann/json.hpp>
|
||||||
|
|
||||||
|
using json = nlohmann::json;
|
||||||
|
|
||||||
|
int main()
|
||||||
|
{
|
||||||
|
// an invalid JSON text
|
||||||
|
std::string text = R"(
|
||||||
|
{
|
||||||
|
"key": "value without closing quotes
|
||||||
|
}
|
||||||
|
)";
|
||||||
|
|
||||||
|
// parse with exceptions
|
||||||
|
try
|
||||||
|
{
|
||||||
|
json j = json::parse(text);
|
||||||
|
}
|
||||||
|
catch (json::parse_error& e)
|
||||||
|
{
|
||||||
|
std::cout << e.what() << std::endl;
|
||||||
|
}
|
||||||
|
|
||||||
|
// parse without exceptions
|
||||||
|
json j = json::parse(text, nullptr, false);
|
||||||
|
|
||||||
|
if (j.is_discarded())
|
||||||
|
{
|
||||||
|
std::cout << "the input is invalid JSON" << std::endl;
|
||||||
|
}
|
||||||
|
else
|
||||||
|
{
|
||||||
|
std::cout << "the input is valid JSON: " << j << std::endl;
|
||||||
|
}
|
||||||
|
}
|
|
@ -1,4 +1,4 @@
|
||||||
# basic_basic_json::exception
|
# basic_json::exception
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class exception : public std::exception;
|
class exception : public std::exception;
|
||||||
|
|
|
@ -52,7 +52,7 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
||||||
`value_t::discarded`.
|
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
|
||||||
|
|
||||||
## Exception safety
|
## Exception safety
|
||||||
|
|
||||||
|
|
|
@ -59,7 +59,7 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
||||||
`value_t::discarded`.
|
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
|
||||||
|
|
||||||
## Exception safety
|
## Exception safety
|
||||||
|
|
||||||
|
|
|
@ -52,7 +52,7 @@ Deserializes a given input to a JSON value using the MessagePack serialization f
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
||||||
`value_t::discarded`.
|
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
|
||||||
|
|
||||||
## Exception safety
|
## Exception safety
|
||||||
|
|
||||||
|
|
|
@ -52,7 +52,7 @@ Deserializes a given input to a JSON value using the UBJSON (Universal Binary JS
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
||||||
`value_t::discarded`.
|
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
|
||||||
|
|
||||||
## Exception safety
|
## Exception safety
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# basic_basic_json::invalid_iterator
|
# basic_json::invalid_iterator
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class invalid_iterator : public exception;
|
class invalid_iterator : public exception;
|
||||||
|
|
|
@ -4,8 +4,11 @@
|
||||||
constexpr bool is_discarded() const noexcept;
|
constexpr bool is_discarded() const noexcept;
|
||||||
```
|
```
|
||||||
|
|
||||||
This function returns true if and only if the JSON value was discarded during parsing with a callback function (see
|
This function returns `#!cpp true` for a JSON value if either:
|
||||||
[`parser_callback_t`](parser_callback_t.md)).
|
|
||||||
|
- the value was discarded during parsing with a callback function (see [`parser_callback_t`](parser_callback_t.md)), or
|
||||||
|
- the value is the result of parsing invalid JSON with parameter `allow_exceptions` set to `#!cpp false`; see
|
||||||
|
[`parse`](parse.md) for more information.
|
||||||
|
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
|
@ -21,6 +24,30 @@ Constant.
|
||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
|
||||||
|
Discarded values are never compared equal with [`operator==`](operator_eq.md). That is, checking whether a JSON
|
||||||
|
value `j` is discarded will only work via:
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
j.is_discarded()
|
||||||
|
```
|
||||||
|
|
||||||
|
because
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
j == json::value_t::discarded
|
||||||
|
```
|
||||||
|
|
||||||
|
will always be `#!cpp false`.
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
|
||||||
|
When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
|
||||||
|
then it is removed when it is part of a structured value. For instance, if the second value of an array is discared,
|
||||||
|
instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level
|
||||||
|
value is discarded, the return value of the `parse` call is discarded.
|
||||||
|
|
||||||
This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
|
This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
|
||||||
during parsing, but will be removed when inside a structured value or replaced by null in other cases.
|
during parsing, but will be removed when inside a structured value or replaced by null in other cases.
|
||||||
|
|
||||||
|
|
|
@ -12,11 +12,10 @@ bool operator==(ScalarType lhs, const const_reference rhs) noexcept;
|
||||||
|
|
||||||
Compares two JSON values for equality according to the following rules:
|
Compares two JSON values for equality according to the following rules:
|
||||||
|
|
||||||
- Two JSON values are equal if (1) they are from the same type and (2) their stored values are the same according to
|
- Two JSON values are equal if (1) they are not discarded, (2) they are from the same type, and (3) their stored values
|
||||||
their respective `operator==`.
|
are the same according to their respective `operator==`.
|
||||||
- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
|
- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
|
||||||
treated as unequal.
|
treated as unequal.
|
||||||
- Two JSON null values are equal.
|
|
||||||
|
|
||||||
## Template parameters
|
## Template parameters
|
||||||
|
|
||||||
|
@ -45,10 +44,18 @@ Linear.
|
||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
- Floating-point inside JSON values numbers are compared with `json::number_float_t::operator==` which is
|
!!! note
|
||||||
`double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative
|
|
||||||
[comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
|
- NaN values never compare equal to themselves or to other NaN values.
|
||||||
could be used, for instance
|
- JSON `#!cpp null` values are all equal.
|
||||||
|
- Discarded values never compare equal to themselves.
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
|
||||||
|
Floating-point numbers inside JSON values numbers are compared with `json::number_float_t::operator==` which is
|
||||||
|
`double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative
|
||||||
|
[comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
|
||||||
|
could be used, for instance
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
|
template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
|
||||||
|
@ -78,8 +85,6 @@ Linear.
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- NaN values never compare equal to themselves or to other NaN values.
|
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
??? example
|
??? example
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# basic_basic_json::other_error
|
# basic_json::other_error
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class other_error : public exception;
|
class other_error : public exception;
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# basic_basic_json::out_of_range
|
# basic_json::out_of_range
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class out_of_range : public exception;
|
class out_of_range : public exception;
|
||||||
|
|
|
@ -61,7 +61,7 @@ static basic_json parse(IteratorType first, IteratorType last,
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
Deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
Deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
|
||||||
`value_t::discarded`.
|
`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
|
||||||
|
|
||||||
## Exception safety
|
## Exception safety
|
||||||
|
|
||||||
|
@ -79,7 +79,7 @@ super-linear complexity.
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
??? example
|
??? example "Parsing from a charater array"
|
||||||
|
|
||||||
The example below demonstrates the `parse()` function reading from an array.
|
The example below demonstrates the `parse()` function reading from an array.
|
||||||
|
|
||||||
|
@ -93,7 +93,7 @@ super-linear complexity.
|
||||||
--8<-- "examples/parse__array__parser_callback_t.output"
|
--8<-- "examples/parse__array__parser_callback_t.output"
|
||||||
```
|
```
|
||||||
|
|
||||||
??? example
|
??? example "Parsing from a string"
|
||||||
|
|
||||||
The example below demonstrates the `parse()` function with and without callback function.
|
The example below demonstrates the `parse()` function with and without callback function.
|
||||||
|
|
||||||
|
@ -107,7 +107,7 @@ super-linear complexity.
|
||||||
--8<-- "examples/parse__string__parser_callback_t.output"
|
--8<-- "examples/parse__string__parser_callback_t.output"
|
||||||
```
|
```
|
||||||
|
|
||||||
??? example
|
??? example "Parsing from an input stream"
|
||||||
|
|
||||||
The example below demonstrates the `parse()` function with and without callback function.
|
The example below demonstrates the `parse()` function with and without callback function.
|
||||||
|
|
||||||
|
@ -121,7 +121,7 @@ super-linear complexity.
|
||||||
--8<-- "examples/parse__istream__parser_callback_t.output"
|
--8<-- "examples/parse__istream__parser_callback_t.output"
|
||||||
```
|
```
|
||||||
|
|
||||||
??? example
|
??? example "Parsing from a contiguous container"
|
||||||
|
|
||||||
The example below demonstrates the `parse()` function reading from a contiguous container.
|
The example below demonstrates the `parse()` function reading from a contiguous container.
|
||||||
|
|
||||||
|
@ -135,6 +135,20 @@ super-linear complexity.
|
||||||
--8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
|
--8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
??? example "Effect of `allow_exceptions` parameter"
|
||||||
|
|
||||||
|
The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
--8<-- "examples/parse__allow_exceptions.cpp"
|
||||||
|
```
|
||||||
|
|
||||||
|
Output:
|
||||||
|
|
||||||
|
```json
|
||||||
|
--8<-- "examples/parse__allow_exceptions.output"
|
||||||
|
```
|
||||||
|
|
||||||
## Version history
|
## Version history
|
||||||
|
|
||||||
- Added in version 1.0.0.
|
- Added in version 1.0.0.
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# basic_basic_json::parse_error
|
# basic_json::parse_error
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class parse_error : public exception;
|
class parse_error : public exception;
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# basic_basic_json::type_error
|
# basic_json::type_error
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class type_error : public exception;
|
class type_error : public exception;
|
||||||
|
|
Loading…
Reference in a new issue