Skip to content

J
json
Unverified Commit 28dbe4e6 by Niels Lohmann
Options

📝 overworked documentation for the at functions

Added all possible exceptions to the examples of the at functions.
parent 89f60683
Showing with 302 additions and 99 deletions
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
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment