📝 more documentation for the new exceptions

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';
+    }
 }

doc/examples/at_json_pointer.link

@@ -1 +1 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/NDSjglHZIjIZ0Uxg"><b>online</b></a>
+<a target="_blank" href="http://melpon.org/wandbox/permlink/Q6uMvBFm1yXUwb1d"><b>online</b></a>

doc/examples/at_json_pointer.output

@@ -4,3 +4,4 @@
 2
 "bar"
 [1,21]
+[json.exception.out_of_range.404] unresolved reference token 'foo'

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';
+    }
 }

doc/examples/at_json_pointer_const.link

@@ -1 +1 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/OuLYiMJ3pgyOHupb"><b>online</b></a>
+<a target="_blank" href="http://melpon.org/wandbox/permlink/hKv8e18tUvVJUt9e"><b>online</b></a>

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'

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';
+    }
 }

doc/examples/back.link

@@ -1 +1 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/nPVnBcHf8nrNpGOJ"><b>online</b></a>
+<a target="_blank" href="http://melpon.org/wandbox/permlink/CAv4NNr4D1FJhhUv"><b>online</b></a>

doc/examples/back.output

@@ -4,3 +4,4 @@ true
 2
 16
 "Hello, world"
+[json.exception.invalid_iterator.214] cannot get value

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.106 if an array index in the passed JSON pointer @a ptr
-    @throw parse_error.109   if an array index was not a number
+    begins with '0'
-    @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.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.106 if an array index in the passed JSON pointer @a ptr
-    @throw parse_error.109   if an array index was not a number
+    begins with '0'
-    @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.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}
 

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.106 if an array index in the passed JSON pointer @a ptr
-    @throw parse_error.109   if an array index was not a number
+    begins with '0'
-    @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.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.106 if an array index in the passed JSON pointer @a ptr
-    @throw parse_error.109   if an array index was not a number
+    begins with '0'
-    @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.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}