From 0f6b8aa7181aabb51ef71c80b64e12016e7667ae Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Wed, 8 Mar 2017 23:30:38 +0100
Subject: [PATCH] :memo: more documentation for the new exceptions
---
doc/examples/at_json_pointer.cpp | 10 +++++++
doc/examples/at_json_pointer.link | 2 +-
doc/examples/at_json_pointer.output | 1 +
doc/examples/at_json_pointer_const.cpp | 10 +++++++
doc/examples/at_json_pointer_const.link | 2 +-
doc/examples/at_json_pointer_const.output | 1 +
doc/examples/back.cpp | 13 +++++++--
doc/examples/back.link | 2 +-
doc/examples/back.output | 1 +
src/json.hpp | 35 +++++++++++++++++------
src/json.hpp.re2c | 35 +++++++++++++++++------
11 files changed, 89 insertions(+), 23 deletions(-)
diff --git a/doc/examples/at_json_pointer.cpp b/doc/examples/at_json_pointer.cpp
index 0665e608..6d1617e6 100644
--- a/doc/examples/at_json_pointer.cpp
+++ b/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';
+ }
}
diff --git a/doc/examples/at_json_pointer.link b/doc/examples/at_json_pointer.link
index 7a7efa26..45402303 100644
--- a/doc/examples/at_json_pointer.link
+++ b/doc/examples/at_json_pointer.link
@@ -1 +1 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/NDSjglHZIjIZ0Uxg"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/Q6uMvBFm1yXUwb1d"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/at_json_pointer.output b/doc/examples/at_json_pointer.output
index 11913c72..a45737ad 100644
--- a/doc/examples/at_json_pointer.output
+++ b/doc/examples/at_json_pointer.output
@@ -4,3 +4,4 @@
2
"bar"
[1,21]
+[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 e3cfc515..dab1b39c 100644
--- a/doc/examples/at_json_pointer_const.cpp
+++ b/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';
+ }
}
diff --git a/doc/examples/at_json_pointer_const.link b/doc/examples/at_json_pointer_const.link
index 9057e0b2..70e7cf86 100644
--- a/doc/examples/at_json_pointer_const.link
+++ b/doc/examples/at_json_pointer_const.link
@@ -1 +1 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/OuLYiMJ3pgyOHupb"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/hKv8e18tUvVJUt9e"><b>online</b></a>
\ 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 7b9306bb..21712e86 100644
--- a/doc/examples/at_json_pointer_const.output
+++ b/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'
diff --git a/doc/examples/back.cpp b/doc/examples/back.cpp
index 70516e58..45f9483c 100644
--- a/doc/examples/back.cpp
+++ b/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';
+ }
}
diff --git a/doc/examples/back.link b/doc/examples/back.link
index 0b009780..15b1102b 100644
--- a/doc/examples/back.link
+++ b/doc/examples/back.link
@@ -1 +1 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/nPVnBcHf8nrNpGOJ"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="http://melpon.org/wandbox/permlink/CAv4NNr4D1FJhhUv"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/back.output b/doc/examples/back.output
index 159ba0fc..2990dbf0 100644
--- a/doc/examples/back.output
+++ b/doc/examples/back.output
@@ -4,3 +4,4 @@ true
2
16
"Hello, world"
+[json.exception.invalid_iterator.214] cannot get value
diff --git a/src/json.hpp b/src/json.hpp
index 9fb7690f..5a3e6c3a 100644
--- a/src/json.hpp
+++ b/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.109 if an array index was not a number
- @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.106 if an array index in the passed JSON pointer @a ptr
+ begins with '0'
+
+ @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.109 if an array index was not a number
- @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.106 if an array index in the passed JSON pointer @a ptr
+ begins with '0'
+
+ @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}
diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c
index 22e12841..289e3f10 100644
--- a/src/json.hpp.re2c
+++ b/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.109 if an array index was not a number
- @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.106 if an array index in the passed JSON pointer @a ptr
+ begins with '0'
+
+ @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.109 if an array index was not a number
- @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.106 if an array index in the passed JSON pointer @a ptr
+ begins with '0'
+
+ @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}