📝 overworked documentation for the at functions

Added all possible exceptions to the examples of the at functions.

doc/examples/at__object_t_key_type.cpp

@@ -21,9 +21,23 @@ int main()
     // output changed array
     std::cout << object << '\n';
 
-    // try to write at a nonexisting key
+
+    // exception type_error.304
     try
     {
+        // use at() on a non-object type
+        json str = "I am a string";
+        str.at("the good") = "Another string";
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // exception out_of_range.401
+    try
+    {
+        // try to write at a nonexisting key
         object.at("the fast") = "il rapido";
     }
     catch (json::out_of_range& e)

doc/examples/at__object_t_key_type.link

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

doc/examples/at__object_t_key_type.output

@@ -1,3 +1,4 @@
 "il brutto"
 {"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
+[json.exception.type_error.304] cannot use at() with string
 [json.exception.out_of_range.403] key 'the fast' not found

doc/examples/at__object_t_key_type_const.cpp

@@ -15,9 +15,23 @@ int main()
     // output element with key "the ugly"
     std::cout << object.at("the ugly") << '\n';
 
-    // try to read from a nonexisting key
+
+    // exception type_error.304
     try
     {
+        // use at() on a non-object type
+        const json str = "I am a string";
+        std::cout << str.at("the good") << '\n';
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // exception out_of_range.401
+    try
+    {
+        // try to read from a nonexisting key
         std::cout << object.at("the fast") << '\n';
     }
     catch (json::out_of_range)

doc/examples/at__object_t_key_type_const.link

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

doc/examples/at__object_t_key_type_const.output

@@ -1,2 +1,3 @@
 "il brutto"
+[json.exception.type_error.304] cannot use at() with string
 out of range

doc/examples/at__size_type.cpp

@@ -16,9 +16,23 @@ int main()
     // output changed array
     std::cout << array << '\n';
 
-    // try to write beyond the array limit
+
+    // exception type_error.304
     try
     {
+        // use at() on a non-array type
+        json str = "I am a string";
+        str.at(0) = "Another string";
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // exception out_of_range.401
+    try
+    {
+        // try to write beyond the array limit
         array.at(5) = "sixth";
     }
     catch (json::out_of_range& e)

doc/examples/at__size_type.link

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

doc/examples/at__size_type.output

@@ -1,3 +1,4 @@
 "third"
 ["first","second","third","fourth"]
+[json.exception.type_error.304] cannot use at() with string
 [json.exception.out_of_range.401] array index 5 is out of range

doc/examples/at__size_type_const.cpp

@@ -5,17 +5,31 @@ using json = nlohmann::json;
 int main()
 {
     // create JSON array
-    json array = {"first", "2nd", "third", "fourth"};
+    const json array = {"first", "2nd", "third", "fourth"};
 
     // output element at index 2 (third element)
     std::cout << array.at(2) << '\n';
 
-    // try to read beyond the array limit
+
+    // exception type_error.304
     try
     {
+        // use at() on a non-array type
+        const json str = "I am a string";
+        std::cout << str.at(0) << '\n';
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // exception out_of_range.401
+    try
+    {
+        // try to read beyond the array limit
         std::cout << array.at(5) << '\n';
     }
-    catch (const json::out_of_range& e)
+    catch (json::out_of_range& e)
     {
         std::cout << e.what() << '\n';
     }

doc/examples/at__size_type_const.link

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

doc/examples/at__size_type_const.output

@@ -1,2 +1,3 @@
 "third"
+[json.exception.type_error.304] cannot use at() with string
 [json.exception.out_of_range.401] array index 5 is out of range

doc/examples/at_json_pointer.cpp

@@ -33,10 +33,56 @@ int main()
     // output the changed array
     std::cout << j["array"] << '\n';
 
-    // try to use an invalid JSON pointer
+
+    // out_of_range.106
     try
     {
-        auto ref = j.at("/number/foo"_json_pointer);
+        // try to use an array index with leading '0'
+        json::reference ref = j.at("/array/01"_json_pointer);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.109
+    try
+    {
+        // try to use an array index that is not a number
+        json::reference ref = j.at("/array/one"_json_pointer);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.401
+    try
+    {
+        // try to use a an invalid array index
+        json::reference ref = j.at("/array/4"_json_pointer);
+    }
+    catch (json::out_of_range& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.402
+    try
+    {
+        // try to use the array index '-'
+        json::reference ref = j.at("/array/-"_json_pointer);
+    }
+    catch (json::out_of_range& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.404
+    try
+    {
+        // try to use a JSON pointer that cannot be resolved
+        json::reference ref = j.at("/number/foo"_json_pointer);
     }
     catch (json::out_of_range& e)
     {

doc/examples/at_json_pointer.link

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

doc/examples/at_json_pointer.output

@@ -4,4 +4,8 @@
 2
 "bar"
 [1,21]
+[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'
+[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.404] unresolved reference token 'foo'

doc/examples/at_json_pointer_const.cpp

@@ -5,7 +5,7 @@ using json = nlohmann::json;
 int main()
 {
     // create a JSON value
-    json j =
+    const json j =
     {
         {"number", 1}, {"string", "foo"}, {"array", {1, 2}}
     };
@@ -21,10 +21,44 @@ int main()
     // output element with JSON pointer "/array/1"
     std::cout << j.at("/array/1"_json_pointer) << '\n';
 
-    // try to use an invalid JSON pointer
+    // out_of_range.109
     try
     {
-        auto ref = j.at("/number/foo"_json_pointer);
+        // try to use an array index that is not a number
+        json::const_reference ref = j.at("/array/one"_json_pointer);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.401
+    try
+    {
+        // try to use a an invalid array index
+        json::const_reference ref = j.at("/array/4"_json_pointer);
+    }
+    catch (json::out_of_range& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.402
+    try
+    {
+        // try to use the array index '-'
+        json::const_reference ref = j.at("/array/-"_json_pointer);
+    }
+    catch (json::out_of_range& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // out_of_range.404
+    try
+    {
+        // try to use a JSON pointer that cannot be resolved
+        json::const_reference ref = j.at("/number/foo"_json_pointer);
     }
     catch (json::out_of_range& e)
     {

doc/examples/at_json_pointer_const.link

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

doc/examples/at_json_pointer_const.output

@@ -2,4 +2,7 @@
 "foo"
 [1,2]
 2
+[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.404] unresolved reference token 'foo'