From b386f4de0bff06c994e1ea62964ee94d4d5d80bf Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 19 Aug 2020 20:26:06 +0200 Subject: [PATCH] :memo: fix and extend documentation of discarded values --- doc/examples/parse__allow_exceptions.cpp | 36 +++++++++++++++++++ doc/mkdocs/docs/api/basic_json/exception.md | 2 +- doc/mkdocs/docs/api/basic_json/from_bson.md | 2 +- doc/mkdocs/docs/api/basic_json/from_cbor.md | 2 +- .../docs/api/basic_json/from_msgpack.md | 2 +- doc/mkdocs/docs/api/basic_json/from_ubjson.md | 2 +- .../docs/api/basic_json/invalid_iterator.md | 2 +- .../docs/api/basic_json/is_discarded.md | 33 +++++++++++++++-- doc/mkdocs/docs/api/basic_json/operator_eq.md | 23 +++++++----- doc/mkdocs/docs/api/basic_json/other_error.md | 2 +- .../docs/api/basic_json/out_of_range.md | 2 +- doc/mkdocs/docs/api/basic_json/parse.md | 24 ++++++++++--- doc/mkdocs/docs/api/basic_json/parse_error.md | 2 +- doc/mkdocs/docs/api/basic_json/type_error.md | 2 +- 14 files changed, 109 insertions(+), 27 deletions(-) create mode 100644 doc/examples/parse__allow_exceptions.cpp diff --git a/doc/examples/parse__allow_exceptions.cpp b/doc/examples/parse__allow_exceptions.cpp new file mode 100644 index 000000000..82449a526 --- /dev/null +++ b/doc/examples/parse__allow_exceptions.cpp @@ -0,0 +1,36 @@ +#include +#include + +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; + } +} diff --git a/doc/mkdocs/docs/api/basic_json/exception.md b/doc/mkdocs/docs/api/basic_json/exception.md index d6609ee1f..deedae5a6 100644 --- a/doc/mkdocs/docs/api/basic_json/exception.md +++ b/doc/mkdocs/docs/api/basic_json/exception.md @@ -1,4 +1,4 @@ -# basic_basic_json::exception +# basic_json::exception ```cpp class exception : public std::exception; diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md index bf218cd91..6df74f39c 100644 --- a/doc/mkdocs/docs/api/basic_json/from_bson.md +++ b/doc/mkdocs/docs/api/basic_json/from_bson.md @@ -52,7 +52,7 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ ## Return value 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 diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md index 138229ad0..ec186fc2a 100644 --- a/doc/mkdocs/docs/api/basic_json/from_cbor.md +++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md @@ -59,7 +59,7 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object ## Return value 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 diff --git a/doc/mkdocs/docs/api/basic_json/from_msgpack.md b/doc/mkdocs/docs/api/basic_json/from_msgpack.md index 18649c14a..9f6852499 100644 --- a/doc/mkdocs/docs/api/basic_json/from_msgpack.md +++ b/doc/mkdocs/docs/api/basic_json/from_msgpack.md @@ -52,7 +52,7 @@ Deserializes a given input to a JSON value using the MessagePack serialization f ## Return value 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 diff --git a/doc/mkdocs/docs/api/basic_json/from_ubjson.md b/doc/mkdocs/docs/api/basic_json/from_ubjson.md index 91c22f058..f6213f293 100644 --- a/doc/mkdocs/docs/api/basic_json/from_ubjson.md +++ b/doc/mkdocs/docs/api/basic_json/from_ubjson.md @@ -52,7 +52,7 @@ Deserializes a given input to a JSON value using the UBJSON (Universal Binary JS ## Return value 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 diff --git a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md index 1a56c5281..b11b27dfc 100644 --- a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md +++ b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md @@ -1,4 +1,4 @@ -# basic_basic_json::invalid_iterator +# basic_json::invalid_iterator ```cpp class invalid_iterator : public exception; diff --git a/doc/mkdocs/docs/api/basic_json/is_discarded.md b/doc/mkdocs/docs/api/basic_json/is_discarded.md index d233e6c5b..b733f623c 100644 --- a/doc/mkdocs/docs/api/basic_json/is_discarded.md +++ b/doc/mkdocs/docs/api/basic_json/is_discarded.md @@ -4,9 +4,12 @@ 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 -[`parser_callback_t`](parser_callback_t.md)). - +This function returns `#!cpp true` for a JSON value if either: + +- 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 `#!cpp true` if type is discarded, `#!cpp false` otherwise. @@ -21,6 +24,30 @@ Constant. ## 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 during parsing, but will be removed when inside a structured value or replaced by null in other cases. diff --git a/doc/mkdocs/docs/api/basic_json/operator_eq.md b/doc/mkdocs/docs/api/basic_json/operator_eq.md index d087d99cc..34cf5537d 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_eq.md +++ b/doc/mkdocs/docs/api/basic_json/operator_eq.md @@ -12,11 +12,10 @@ bool operator==(ScalarType lhs, const const_reference rhs) noexcept; 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 - their respective `operator==`. +- Two JSON values are equal if (1) they are not discarded, (2) they are from the same type, and (3) their stored values + 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 treated as unequal. -- Two JSON null values are equal. ## Template parameters @@ -45,11 +44,19 @@ Linear. ## Notes -- Floating-point 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 +!!! note + - NaN values never compare equal to themselves or to other NaN values. + - 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 template::value, T>::type> inline bool is_same(T a, T b, T epsilon = std::numeric_limits::epsilon()) noexcept @@ -78,8 +85,6 @@ Linear. } ``` -- NaN values never compare equal to themselves or to other NaN values. - ## Example ??? example diff --git a/doc/mkdocs/docs/api/basic_json/other_error.md b/doc/mkdocs/docs/api/basic_json/other_error.md index fdaa29050..492b2d484 100644 --- a/doc/mkdocs/docs/api/basic_json/other_error.md +++ b/doc/mkdocs/docs/api/basic_json/other_error.md @@ -1,4 +1,4 @@ -# basic_basic_json::other_error +# basic_json::other_error ```cpp class other_error : public exception; diff --git a/doc/mkdocs/docs/api/basic_json/out_of_range.md b/doc/mkdocs/docs/api/basic_json/out_of_range.md index 18a8e95ab..47ead87c2 100644 --- a/doc/mkdocs/docs/api/basic_json/out_of_range.md +++ b/doc/mkdocs/docs/api/basic_json/out_of_range.md @@ -1,4 +1,4 @@ -# basic_basic_json::out_of_range +# basic_json::out_of_range ```cpp class out_of_range : public exception; diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md index 11e420d41..1f991b381 100644 --- a/doc/mkdocs/docs/api/basic_json/parse.md +++ b/doc/mkdocs/docs/api/basic_json/parse.md @@ -61,7 +61,7 @@ static basic_json parse(IteratorType first, IteratorType last, ## Return value 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 @@ -79,7 +79,7 @@ super-linear complexity. ## Examples -??? example +??? example "Parsing from a charater 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" ``` -??? example +??? example "Parsing from a string" 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" ``` -??? example +??? example "Parsing from an input stream" 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" ``` -??? example +??? example "Parsing 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" ``` +??? 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 - Added in version 1.0.0. diff --git a/doc/mkdocs/docs/api/basic_json/parse_error.md b/doc/mkdocs/docs/api/basic_json/parse_error.md index 305087ddb..de0ee4010 100644 --- a/doc/mkdocs/docs/api/basic_json/parse_error.md +++ b/doc/mkdocs/docs/api/basic_json/parse_error.md @@ -1,4 +1,4 @@ -# basic_basic_json::parse_error +# basic_json::parse_error ```cpp class parse_error : public exception; diff --git a/doc/mkdocs/docs/api/basic_json/type_error.md b/doc/mkdocs/docs/api/basic_json/type_error.md index 498fbd47b..ea0154e39 100644 --- a/doc/mkdocs/docs/api/basic_json/type_error.md +++ b/doc/mkdocs/docs/api/basic_json/type_error.md @@ -1,4 +1,4 @@ -# basic_basic_json::type_error +# basic_json::type_error ```cpp class type_error : public exception;