From 3113a52a7d148d7ad9567cf9d67fa67960beb3f1 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 23 Dec 2017 18:38:18 +0100 Subject: [PATCH] :memo: added exception 403 to documentation of at (#888) The at function throws json::out_of_range.403 when a nonexistent object key is provided (just like the usual at function). This was not documented and users could assume json::out_of_range.404 would be thrown instead. - Updated documentation. - Added example code. --- doc/examples/at_json_pointer.cpp | 11 +++++++++++ doc/examples/at_json_pointer.link | 2 +- doc/examples/at_json_pointer.output | 1 + doc/examples/at_json_pointer_const.cpp | 11 +++++++++++ doc/examples/at_json_pointer_const.link | 2 +- doc/examples/at_json_pointer_const.output | 1 + doc/index.md | 6 ++++++ src/json.hpp | 7 ++++++- 8 files changed, 38 insertions(+), 3 deletions(-) diff --git a/doc/examples/at_json_pointer.cpp b/doc/examples/at_json_pointer.cpp index 80ed6c15..f43b1bcc 100644 --- a/doc/examples/at_json_pointer.cpp +++ b/doc/examples/at_json_pointer.cpp @@ -79,6 +79,17 @@ int main() std::cout << e.what() << '\n'; } + // out_of_range.403 + try + { + // try to use a JSON pointer to an nonexistent object key + json::const_reference ref = j.at("/foo"_json_pointer); + } + catch (json::out_of_range& e) + { + std::cout << e.what() << '\n'; + } + // out_of_range.404 try { diff --git a/doc/examples/at_json_pointer.link b/doc/examples/at_json_pointer.link index 61a4410a..99ebf019 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 505792f2..1d29893e 100644 --- a/doc/examples/at_json_pointer.output +++ b/doc/examples/at_json_pointer.output @@ -8,4 +8,5 @@ [json.exception.parse_error.109] parse error: array index 'one' is not a number [json.exception.out_of_range.401] array index 4 is out of range [json.exception.out_of_range.402] array index '-' (2) is out of range +[json.exception.out_of_range.403] key 'foo' not found [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 1496aa5a..8009e95f 100644 --- a/doc/examples/at_json_pointer_const.cpp +++ b/doc/examples/at_json_pointer_const.cpp @@ -55,6 +55,17 @@ int main() std::cout << e.what() << '\n'; } + // out_of_range.403 + try + { + // try to use a JSON pointer to an nonexistent object key + json::const_reference ref = j.at("/foo"_json_pointer); + } + catch (json::out_of_range& e) + { + std::cout << e.what() << '\n'; + } + // out_of_range.404 try { diff --git a/doc/examples/at_json_pointer_const.link b/doc/examples/at_json_pointer_const.link index 31e0bb08..9011b99b 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 b3361f04..aaf8f187 100644 --- a/doc/examples/at_json_pointer_const.output +++ b/doc/examples/at_json_pointer_const.output @@ -5,4 +5,5 @@ [json.exception.parse_error.109] parse error: array index 'one' is not a number [json.exception.out_of_range.401] array index 4 is out of range [json.exception.out_of_range.402] array index '-' (2) is out of range +[json.exception.out_of_range.403] key 'foo' not found [json.exception.out_of_range.404] unresolved reference token 'foo' diff --git a/doc/index.md b/doc/index.md index 3c23b3a9..122e8e6d 100644 --- a/doc/index.md +++ b/doc/index.md @@ -28,6 +28,12 @@ These pages contain the API documentation of JSON for Modern C++, a C++11 header - @link nlohmann::basic_json::get_ref get_ref @endlink -- get a value reference - @link nlohmann::basic_json::operator ValueType() const operator ValueType @endlink -- get a value (implicit conversion) - @link nlohmann::basic_json::value value @endlink -- get a value from an object and return default value if key is not present + - exceptions + - @link nlohmann::basic_json::parse_error parse_error @endlink for exceptions indicating a parse error + - @link nlohmann::basic_json::invalid_iterator invalid_iterator @endlink for exceptions indicating errors with iterators + - @link nlohmann::basic_json::type_error type_error @endlink for exceptions indicating executing a member function with a wrong type + - @link nlohmann::basic_json::out_of_range out_of_range @endlink for exceptions indicating access out of the defined range + - @link nlohmann::basic_json::other_error other_error @endlink for exceptions indicating other library errors - lexicographical comparison operators - serialization - deserialization diff --git a/src/json.hpp b/src/json.hpp index 1f7e8dca..ae363ba7 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -456,7 +456,6 @@ Exceptions have ids 5xx. name / id | example message | description ------------------------------ | --------------- | ------------------------- json.exception.other_error.501 | unsuccessful: {"op":"test","path":"/baz", "value":"bar"} | A JSON Patch operation 'test' failed. The unsuccessful operation is also printed. -json.exception.other_error.502 | invalid object size for conversion | Some conversions to user-defined types impose constraints on the object size (e.g. std::pair) @sa @ref exception for the base class of the library exceptions @sa @ref parse_error for exceptions indicating a parse error @@ -13721,6 +13720,9 @@ class basic_json pointer @a ptr. As `at` provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See example below. + @throw out_of_range.403 if the JSON pointer describes a key of an object + which cannot be found. See example below. + @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved. See example below. @@ -13761,6 +13763,9 @@ class basic_json pointer @a ptr. As `at` provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See example below. + @throw out_of_range.403 if the JSON pointer describes a key of an object + which cannot be found. See example below. + @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved. See example below.