📝 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

-<a target="_blank" href="http://melpon.org/wandbox/permlink/WtZ49NXtkzcLAx37"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/8ldtT0NOhidn0fOA"><b>online</b></a>
\ No newline at end of file

doc/examples/at__object_t_key_type.output

 "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

-<a target="_blank" href="http://melpon.org/wandbox/permlink/AsC3grSJ7UngjKwF"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/nfmFWMaJJHFJ7eVK"><b>online</b></a>
\ No newline at end of file

doc/examples/at__object_t_key_type_const.output

 "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

-<a target="_blank" href="http://melpon.org/wandbox/permlink/EU0DspVPybW5cJDH"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/8UnQY256zGX2Lx6d"><b>online</b></a>
\ No newline at end of file

doc/examples/at__size_type.output

 "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

-<a target="_blank" href="http://melpon.org/wandbox/permlink/L70DHUpUzdDQtLgZ"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/U1fv6LY7xZOAuSBs"><b>online</b></a>
\ No newline at end of file

doc/examples/at__size_type_const.output

 "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
+    {
+        // 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
     {
-        auto ref = j.at("/number/foo"_json_pointer);
+        // 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

-<a target="_blank" href="http://melpon.org/wandbox/permlink/Q6uMvBFm1yXUwb1d"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/Fy2xBfZMols2DUQC"><b>online</b></a>
\ No newline at end of file

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

-<a target="_blank" href="http://melpon.org/wandbox/permlink/hKv8e18tUvVJUt9e"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/WxhV3mL9YX8FJonk"><b>online</b></a>
\ No newline at end of file

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'

src/json.hpp

@@ -3723,16 +3723,20 @@ class basic_json
     @return reference to the element at index @a idx
 
     @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense.
+    calling `at` with an index makes no sense. See example below.
     @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`; see example below.
+    that is, `idx >= size()`. See example below.
 
-    @complexity Constant.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `at()`.,at__size_type}
+    @complexity Constant.
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__size_type}
     */
     reference at(size_type idx)
     {
@@ -3766,16 +3770,20 @@ class basic_json
     @return const reference to the element at index @a idx
 
     @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense.
+    calling `at` with an index makes no sense. See example below.
     @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`; see example below.
+    that is, `idx >= size()`. See example below.
 
-    @complexity Constant.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how array elements can be read using
-    `at()`.,at__size_type_const}
+    @complexity Constant.
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__size_type_const}
     */
     const_reference at(size_type idx) const
     {
@@ -3809,20 +3817,24 @@ class basic_json
     @return reference to the element at key @a key
 
     @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense.
+    calling `at` with a key makes no sense. See example below.
     @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`; see example below.
+    that is, `find(key) == end()`. See example below.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how object elements can be read and
-    written using `at()`.,at__object_t_key_type}
+    @complexity Logarithmic in the size of the container.
 
     @sa @ref operator[](const typename object_t::key_type&) for unchecked
     access by reference
     @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__object_t_key_type}
     */
     reference at(const typename object_t::key_type& key)
     {
@@ -3856,20 +3868,24 @@ class basic_json
     @return const reference to the element at key @a key
 
     @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense.
+    calling `at` with a key makes no sense. See example below.
     @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`; see example below.
+    that is, `find(key) == end()`. See example below.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how object elements can be read using
-    `at()`.,at__object_t_key_type_const}
+    @complexity Logarithmic in the size of the container.
 
     @sa @ref operator[](const typename object_t::key_type&) for unchecked
     access by reference
     @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__object_t_key_type_const}
     */
     const_reference at(const typename object_t::key_type& key) const
     {
@@ -12791,24 +12807,30 @@ basic_json_parser_74:
 
     @return reference to the element pointed to by @a ptr
 
-    @complexity Constant.
-
     @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
-    begins with '0'
+    begins with '0'. See example below.
 
     @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
-    is not a number
+    is not a number. See example below.
 
-    @throw out_of_range.402 if the array index `-` is used in the passed JSON
+    @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
+    is out of range. See example below.
+
+    @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.
+    implicitly inserted), the index '-' is always invalid. See example below.
+
+    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
+    See example below.
 
-    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved;
-    see example below.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The behavior is shown in the example.,at_json_pointer}
+    @complexity Constant.
 
     @since version 2.0.0
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer}
     */
     reference at(const json_pointer& ptr)
     {
@@ -12825,24 +12847,30 @@ basic_json_parser_74:
 
     @return reference to the element pointed to by @a ptr
 
-    @complexity Constant.
-
     @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
-    begins with '0'
+    begins with '0'. See example below.
 
     @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
-    is not a number
+    is not a number. See example below.
+
+    @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
+    is out of range. See example below.
 
-    @throw out_of_range.402 if the array index `-` is used in the passed JSON
+    @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.
+    implicitly inserted), the index '-' is always invalid. See example below.
 
-    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved;
-    see example below.
+    @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}
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
+
+    @complexity Constant.
 
     @since version 2.0.0
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer_const}
     */
     const_reference at(const json_pointer& ptr) const
     {

src/json.hpp.re2c

@@ -3723,16 +3723,20 @@ class basic_json
     @return reference to the element at index @a idx
 
     @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense.
+    calling `at` with an index makes no sense. See example below.
     @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`; see example below.
+    that is, `idx >= size()`. See example below.
 
-    @complexity Constant.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how array elements can be read and
-    written using `at()`.,at__size_type}
+    @complexity Constant.
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__size_type}
     */
     reference at(size_type idx)
     {
@@ -3766,16 +3770,20 @@ class basic_json
     @return const reference to the element at index @a idx
 
     @throw type_error.304 if the JSON value is not an array; in this case,
-    calling `at` with an index makes no sense.
+    calling `at` with an index makes no sense. See example below.
     @throw out_of_range.401 if the index @a idx is out of range of the array;
-    that is, `idx >= size()`; see example below.
+    that is, `idx >= size()`. See example below.
 
-    @complexity Constant.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how array elements can be read using
-    `at()`.,at__size_type_const}
+    @complexity Constant.
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how array elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__size_type_const}
     */
     const_reference at(size_type idx) const
     {
@@ -3809,20 +3817,24 @@ class basic_json
     @return reference to the element at key @a key
 
     @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense.
+    calling `at` with a key makes no sense. See example below.
     @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`; see example below.
+    that is, `find(key) == end()`. See example below.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how object elements can be read and
-    written using `at()`.,at__object_t_key_type}
+    @complexity Logarithmic in the size of the container.
 
     @sa @ref operator[](const typename object_t::key_type&) for unchecked
     access by reference
     @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read and
+    written using `at()`. It also demonstrates the different exceptions that
+    can be thrown.,at__object_t_key_type}
     */
     reference at(const typename object_t::key_type& key)
     {
@@ -3856,20 +3868,24 @@ class basic_json
     @return const reference to the element at key @a key
 
     @throw type_error.304 if the JSON value is not an object; in this case,
-    calling `at` with a key makes no sense.
+    calling `at` with a key makes no sense. See example below.
     @throw out_of_range.403 if the key @a key is is not stored in the object;
-    that is, `find(key) == end()`; see example below.
+    that is, `find(key) == end()`. See example below.
 
-    @complexity Logarithmic in the size of the container.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The example below shows how object elements can be read using
-    `at()`.,at__object_t_key_type_const}
+    @complexity Logarithmic in the size of the container.
 
     @sa @ref operator[](const typename object_t::key_type&) for unchecked
     access by reference
     @sa @ref value() for access by value with a default value
 
     @since version 1.0.0
+
+    @liveexample{The example below shows how object elements can be read using
+    `at()`. It also demonstrates the different exceptions that can be thrown.,
+    at__object_t_key_type_const}
     */
     const_reference at(const typename object_t::key_type& key) const
     {
@@ -11824,24 +11840,30 @@ class basic_json
 
     @return reference to the element pointed to by @a ptr
 
-    @complexity Constant.
-
     @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
-    begins with '0'
+    begins with '0'. See example below.
 
     @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
-    is not a number
+    is not a number. See example below.
 
-    @throw out_of_range.402 if the array index `-` is used in the passed JSON
+    @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
+    is out of range. See example below.
+
+    @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.
+    implicitly inserted), the index '-' is always invalid. See example below.
+
+    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved.
+    See example below.
 
-    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved;
-    see example below.
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
 
-    @liveexample{The behavior is shown in the example.,at_json_pointer}
+    @complexity Constant.
 
     @since version 2.0.0
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer}
     */
     reference at(const json_pointer& ptr)
     {
@@ -11858,24 +11880,30 @@ class basic_json
 
     @return reference to the element pointed to by @a ptr
 
-    @complexity Constant.
-
     @throw parse_error.106 if an array index in the passed JSON pointer @a ptr
-    begins with '0'
+    begins with '0'. See example below.
 
     @throw parse_error.109 if an array index in the passed JSON pointer @a ptr
-    is not a number
+    is not a number. See example below.
+
+    @throw out_of_range.401 if an array index in the passed JSON pointer @a ptr
+    is out of range. See example below.
 
-    @throw out_of_range.402 if the array index `-` is used in the passed JSON
+    @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.
+    implicitly inserted), the index '-' is always invalid. See example below.
 
-    @throw out_of_range.404 if the JSON pointer @a ptr can not be resolved;
-    see example below.
+    @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}
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
+
+    @complexity Constant.
 
     @since version 2.0.0
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer_const}
     */
     const_reference at(const json_pointer& ptr) const
     {