diff --git a/doc/examples/at__object_t_key_type b/doc/examples/at__object_t_key_type deleted file mode 100755 index 03f48e68..00000000 Binary files a/doc/examples/at__object_t_key_type and /dev/null differ diff --git a/doc/examples/at__object_t_key_type.cpp b/doc/examples/at__object_t_key_type.cpp index a66bd9a3..7797418f 100644 --- a/doc/examples/at__object_t_key_type.cpp +++ b/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) diff --git a/doc/examples/at__object_t_key_type.link b/doc/examples/at__object_t_key_type.link index 1cb99d46..8874783b 100644 --- a/doc/examples/at__object_t_key_type.link +++ b/doc/examples/at__object_t_key_type.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/at__object_t_key_type.output b/doc/examples/at__object_t_key_type.output index 654b9eb6..b544b729 100644 --- a/doc/examples/at__object_t_key_type.output +++ b/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 diff --git a/doc/examples/at__object_t_key_type_const.cpp b/doc/examples/at__object_t_key_type_const.cpp index 99eb6f01..f6042404 100644 --- a/doc/examples/at__object_t_key_type_const.cpp +++ b/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) diff --git a/doc/examples/at__object_t_key_type_const.link b/doc/examples/at__object_t_key_type_const.link index a07dbd59..cd8594e6 100644 --- a/doc/examples/at__object_t_key_type_const.link +++ b/doc/examples/at__object_t_key_type_const.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/at__object_t_key_type_const.output b/doc/examples/at__object_t_key_type_const.output index b3dd11d3..40ca3f09 100644 --- a/doc/examples/at__object_t_key_type_const.output +++ b/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 diff --git a/doc/examples/at__size_type.cpp b/doc/examples/at__size_type.cpp index 07e363ab..28def1dd 100644 --- a/doc/examples/at__size_type.cpp +++ b/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) diff --git a/doc/examples/at__size_type.link b/doc/examples/at__size_type.link index 78ec0ca0..cba0fa00 100644 --- a/doc/examples/at__size_type.link +++ b/doc/examples/at__size_type.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/at__size_type.output b/doc/examples/at__size_type.output index 4f0c9e54..54026436 100644 --- a/doc/examples/at__size_type.output +++ b/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 diff --git a/doc/examples/at__size_type_const.cpp b/doc/examples/at__size_type_const.cpp index 88d28be6..213d22fd 100644 --- a/doc/examples/at__size_type_const.cpp +++ b/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'; } diff --git a/doc/examples/at__size_type_const.link b/doc/examples/at__size_type_const.link index c703c5d9..ce3647ac 100644 --- a/doc/examples/at__size_type_const.link +++ b/doc/examples/at__size_type_const.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/at__size_type_const.output b/doc/examples/at__size_type_const.output index e52b6cc0..8135a27a 100644 --- a/doc/examples/at__size_type_const.output +++ b/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 diff --git a/doc/examples/at_json_pointer.cpp b/doc/examples/at_json_pointer.cpp index 6d1617e6..3ef91282 100644 --- a/doc/examples/at_json_pointer.cpp +++ b/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) { diff --git a/doc/examples/at_json_pointer.link b/doc/examples/at_json_pointer.link index 45402303..c8563ec2 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 a45737ad..505792f2 100644 --- a/doc/examples/at_json_pointer.output +++ b/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' diff --git a/doc/examples/at_json_pointer_const.cpp b/doc/examples/at_json_pointer_const.cpp index dab1b39c..a1d065f2 100644 --- a/doc/examples/at_json_pointer_const.cpp +++ b/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) { diff --git a/doc/examples/at_json_pointer_const.link b/doc/examples/at_json_pointer_const.link index 70e7cf86..f421faf4 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 21712e86..b3361f04 100644 --- a/doc/examples/at_json_pointer_const.output +++ b/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' diff --git a/src/json.hpp b/src/json.hpp index 605d6aa5..7f31377f 100644 --- a/src/json.hpp +++ b/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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Constant. - @liveexample{The example below shows how array elements can be read and - written using `at()`.,at__size_type} - @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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Constant. - @liveexample{The example below shows how array elements can be read using - `at()`.,at__size_type_const} - @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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Logarithmic in the size of the container. - @liveexample{The example below shows how object elements can be read and - written using `at()`.,at__object_t_key_type} - @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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Logarithmic in the size of the container. - @liveexample{The example below shows how object elements can be read using - `at()`.,at__object_t_key_type_const} - @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. - @liveexample{The behavior is shown in the example.,at_json_pointer} + @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} */ 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.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. - @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 { diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 2bd2fd76..48111521 100644 --- a/src/json.hpp.re2c +++ b/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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Constant. - @liveexample{The example below shows how array elements can be read and - written using `at()`.,at__size_type} - @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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Constant. - @liveexample{The example below shows how array elements can be read using - `at()`.,at__size_type_const} - @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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Logarithmic in the size of the container. - @liveexample{The example below shows how object elements can be read and - written using `at()`.,at__object_t_key_type} - @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. + + @exceptionsafety Strong guarantee: if an exception is thrown, there are no + changes in the JSON value. @complexity Logarithmic in the size of the container. - @liveexample{The example below shows how object elements can be read using - `at()`.,at__object_t_key_type_const} - @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. - @liveexample{The behavior is shown in the example.,at_json_pointer} + @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} */ 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.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. - @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 {