📝 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

@@ -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
     {

doc/examples/at_json_pointer.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/mlj2WqOtwBidvuJx"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/3RO0naQeY3cWXNAz"><b>online</b></a>

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'

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
     {

doc/examples/at_json_pointer_const.link

@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/vHKlyYl9DwaUO9UN"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/LwtGNqrGgjcWey3P"><b>online</b></a>

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'

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