From 0f6b8aa7181aabb51ef71c80b64e12016e7667ae Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 8 Mar 2017 23:30:38 +0100 Subject: [PATCH] :memo: more documentation for the new exceptions --- doc/examples/at_json_pointer.cpp | 10 +++++++ doc/examples/at_json_pointer.link | 2 +- doc/examples/at_json_pointer.output | 1 + doc/examples/at_json_pointer_const.cpp | 10 +++++++ doc/examples/at_json_pointer_const.link | 2 +- doc/examples/at_json_pointer_const.output | 1 + doc/examples/back.cpp | 13 +++++++-- doc/examples/back.link | 2 +- doc/examples/back.output | 1 + src/json.hpp | 35 +++++++++++++++++------ src/json.hpp.re2c | 35 +++++++++++++++++------ 11 files changed, 89 insertions(+), 23 deletions(-) diff --git a/doc/examples/at_json_pointer.cpp b/doc/examples/at_json_pointer.cpp index 0665e608..6d1617e6 100644 --- a/doc/examples/at_json_pointer.cpp +++ b/doc/examples/at_json_pointer.cpp @@ -32,4 +32,14 @@ int main() j.at("/array/1"_json_pointer) = 21; // output the changed array std::cout << j["array"] << '\n'; + + // try to use an invalid JSON pointer + try + { + auto ref = j.at("/number/foo"_json_pointer); + } + catch (json::out_of_range& e) + { + std::cout << e.what() << '\n'; + } } diff --git a/doc/examples/at_json_pointer.link b/doc/examples/at_json_pointer.link index 7a7efa26..45402303 100644 --- a/doc/examples/at_json_pointer.link +++ b/doc/examples/at_json_pointer.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/at_json_pointer.output b/doc/examples/at_json_pointer.output index 11913c72..a45737ad 100644 --- a/doc/examples/at_json_pointer.output +++ b/doc/examples/at_json_pointer.output @@ -4,3 +4,4 @@ 2 "bar" [1,21] +[json.exception.out_of_range.404] unresolved reference token 'foo' diff --git a/doc/examples/at_json_pointer_const.cpp b/doc/examples/at_json_pointer_const.cpp index e3cfc515..dab1b39c 100644 --- a/doc/examples/at_json_pointer_const.cpp +++ b/doc/examples/at_json_pointer_const.cpp @@ -20,4 +20,14 @@ int main() std::cout << j.at("/array"_json_pointer) << '\n'; // output element with JSON pointer "/array/1" std::cout << j.at("/array/1"_json_pointer) << '\n'; + + // try to use an invalid JSON pointer + try + { + auto ref = j.at("/number/foo"_json_pointer); + } + catch (json::out_of_range& e) + { + std::cout << e.what() << '\n'; + } } diff --git a/doc/examples/at_json_pointer_const.link b/doc/examples/at_json_pointer_const.link index 9057e0b2..70e7cf86 100644 --- a/doc/examples/at_json_pointer_const.link +++ b/doc/examples/at_json_pointer_const.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/at_json_pointer_const.output b/doc/examples/at_json_pointer_const.output index 7b9306bb..21712e86 100644 --- a/doc/examples/at_json_pointer_const.output +++ b/doc/examples/at_json_pointer_const.output @@ -2,3 +2,4 @@ "foo" [1,2] 2 +[json.exception.out_of_range.404] unresolved reference token 'foo' diff --git a/doc/examples/back.cpp b/doc/examples/back.cpp index 70516e58..45f9483c 100644 --- a/doc/examples/back.cpp +++ b/doc/examples/back.cpp @@ -5,7 +5,6 @@ using json = nlohmann::json; int main() { // create JSON values - json j_null; json j_boolean = true; json j_number_integer = 17; json j_number_float = 23.42; @@ -16,7 +15,6 @@ int main() json j_string = "Hello, world"; // call back() - //std::cout << j_null.back() << '\n'; // would throw std::cout << j_boolean.back() << '\n'; std::cout << j_number_integer.back() << '\n'; std::cout << j_number_float.back() << '\n'; @@ -25,4 +23,15 @@ int main() std::cout << j_array.back() << '\n'; //std::cout << j_array_empty.back() << '\n'; // undefined behavior std::cout << j_string.back() << '\n'; + + // back() called on a null value + try + { + json j_null; + j_null.back(); + } + catch (json::invalid_iterator& e) + { + std::cout << e.what() << '\n'; + } } diff --git a/doc/examples/back.link b/doc/examples/back.link index 0b009780..15b1102b 100644 --- a/doc/examples/back.link +++ b/doc/examples/back.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/back.output b/doc/examples/back.output index 159ba0fc..2990dbf0 100644 --- a/doc/examples/back.output +++ b/doc/examples/back.output @@ -4,3 +4,4 @@ true 2 16 "Hello, world" +[json.exception.invalid_iterator.214] cannot get value diff --git a/src/json.hpp b/src/json.hpp index 9fb7690f..5a3e6c3a 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -4411,7 +4411,8 @@ class basic_json assertions**). @post The JSON value remains unchanged. - @throw invalid_iterator.214 when called on `null` value. + @throw invalid_iterator.214 when called on a `null` value. See example + below. @liveexample{The following code shows an example for `back()`.,back} @@ -12769,10 +12770,18 @@ basic_json_parser_74: @complexity Constant. - @throw parse_error.106 if an array index begins with '0' - @throw parse_error.109 if an array index was not a number - @throw out_of_range.402 if the array index '-' is used - @throw out_of_range.404 if the JSON pointer can not be resolved + @throw parse_error.106 if an array index in the passed JSON pointer @a ptr + begins with '0' + + @throw parse_error.109 if an array index in the passed JSON pointer @a ptr + is not a number + + @throw out_of_range.402 if the array index `-` is used in the passed JSON + pointer @a ptr. As `at` provides checked access (and no elements are + implicitly inserted), the index `-` is always invalid. + + @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved; + see example below. @liveexample{The behavior is shown in the example.,at_json_pointer} @@ -12795,10 +12804,18 @@ basic_json_parser_74: @complexity Constant. - @throw parse_error.106 if an array index begins with '0' - @throw parse_error.109 if an array index was not a number - @throw out_of_range.402 if the array index '-' is used - @throw out_of_range.404 if the JSON pointer can not be resolved + @throw parse_error.106 if an array index in the passed JSON pointer @a ptr + begins with '0' + + @throw parse_error.109 if an array index in the passed JSON pointer @a ptr + is not a number + + @throw out_of_range.402 if the array index `-` is used in the passed JSON + pointer @a ptr. As `at` provides checked access (and no elements are + implicitly inserted), the index `-` is always invalid. + + @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved; + see example below. @liveexample{The behavior is shown in the example.,at_json_pointer_const} diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 22e12841..289e3f10 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -4411,7 +4411,8 @@ class basic_json assertions**). @post The JSON value remains unchanged. - @throw invalid_iterator.214 when called on `null` value. + @throw invalid_iterator.214 when called on a `null` value. See example + below. @liveexample{The following code shows an example for `back()`.,back} @@ -11802,10 +11803,18 @@ class basic_json @complexity Constant. - @throw parse_error.106 if an array index begins with '0' - @throw parse_error.109 if an array index was not a number - @throw out_of_range.402 if the array index '-' is used - @throw out_of_range.404 if the JSON pointer can not be resolved + @throw parse_error.106 if an array index in the passed JSON pointer @a ptr + begins with '0' + + @throw parse_error.109 if an array index in the passed JSON pointer @a ptr + is not a number + + @throw out_of_range.402 if the array index `-` is used in the passed JSON + pointer @a ptr. As `at` provides checked access (and no elements are + implicitly inserted), the index `-` is always invalid. + + @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved; + see example below. @liveexample{The behavior is shown in the example.,at_json_pointer} @@ -11828,10 +11837,18 @@ class basic_json @complexity Constant. - @throw parse_error.106 if an array index begins with '0' - @throw parse_error.109 if an array index was not a number - @throw out_of_range.402 if the array index '-' is used - @throw out_of_range.404 if the JSON pointer can not be resolved + @throw parse_error.106 if an array index in the passed JSON pointer @a ptr + begins with '0' + + @throw parse_error.109 if an array index in the passed JSON pointer @a ptr + is not a number + + @throw out_of_range.402 if the array index `-` is used in the passed JSON + pointer @a ptr. As `at` provides checked access (and no elements are + implicitly inserted), the index `-` is always invalid. + + @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved; + see example below. @liveexample{The behavior is shown in the example.,at_json_pointer_const}