added examples

doc/examples/at_json_pointer.cpp

@@ -0,0 +1,35 @@
+#include <json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON value
+    json j =
+    {
+        {"number", 1}, {"string", "foo"}, {"array", {1, 2}}
+    };
+
+    // read-only access
+
+    // output element with JSON pointer "/number"
+    std::cout << j.at("/number"_json_pointer) << '\n';
+    // output element with JSON pointer "/string"
+    std::cout << j.at("/string"_json_pointer) << '\n';
+    // output element with JSON pointer "/array"
+    std::cout << j.at("/array"_json_pointer) << '\n';
+    // output element with JSON pointer "/array/1"
+    std::cout << j.at("/array/1"_json_pointer) << '\n';
+
+    // writing access
+
+    // change the string
+    j.at("/string"_json_pointer) = "bar";
+    // output the changed string
+    std::cout << j["string"] << '\n';
+
+    // change an array element
+    j.at("/array/1"_json_pointer) = 21;
+    // output the changed array
+    std::cout << j["array"] << '\n';
+}

doc/examples/at_json_pointer.link

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

doc/examples/at_json_pointer.output

@@ -0,0 +1,6 @@
+1
+"foo"
+[1,2]
+2
+"bar"
+[1,21]

doc/examples/at_json_pointer_const.cpp

@@ -0,0 +1,23 @@
+#include <json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON value
+    json j =
+    {
+        {"number", 1}, {"string", "foo"}, {"array", {1, 2}}
+    };
+
+    // read-only access
+
+    // output element with JSON pointer "/number"
+    std::cout << j.at("/number"_json_pointer) << '\n';
+    // output element with JSON pointer "/string"
+    std::cout << j.at("/string"_json_pointer) << '\n';
+    // output element with JSON pointer "/array"
+    std::cout << j.at("/array"_json_pointer) << '\n';
+    // output element with JSON pointer "/array/1"
+    std::cout << j.at("/array/1"_json_pointer) << '\n';
+}

doc/examples/at_json_pointer_const.link

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

doc/examples/at_json_pointer_const.output

@@ -0,0 +1,4 @@
+1
+"foo"
+[1,2]
+2

src/json.hpp

@@ -3616,9 +3616,9 @@ class basic_json
 
     @param[in] ptr  a JSON pointer
 
-    @return reference to the JSON value pointed to by @a ptr
+    @return reference to the element pointed to by @a ptr
 
-    @complexity Linear in the length of the JSON pointer.
+    @complexity Constant.
 
     @throw std::out_of_range      if the JSON pointer can not be resolved
     @throw std::domain_error      if an array index begins with '0'
@@ -3641,18 +3641,17 @@ class basic_json
     value; no `null` values are created. In particular, the the special value
     `-` yields an exception.
 
-    @param[in] ptr  a JSON pointer
+    @param[in] ptr  JSON pointer to the desired element
 
-    @return reference to the JSON value pointed to by @a ptr
+    @return const reference to the element pointed to by @a ptr
 
-    @complexity Linear in the length of the JSON pointer.
+    @complexity Constant.
 
     @throw std::out_of_range      if the JSON pointer can not be resolved
     @throw std::domain_error      if an array index begins with '0'
     @throw std::invalid_argument  if an array index was not a number
 
-    @liveexample{The behavior is shown in the example.,
+    @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
-    operatorjson_pointer_const}
 
     @since version 2.0.0
     */
@@ -3664,9 +3663,20 @@ class basic_json
     /*!
     @brief access specified element via JSON Pointer
 
-    Returns a reference to the element at with specified JSON pointer @a ptr.
+    Returns a reference to the element at with specified JSON pointer @a ptr,
+    with bounds checking.
 
-    @param ptr  JSON pointer to the desired element
+    @param[in] ptr  JSON pointer to the desired element
+
+    @return reference to the element pointed to by @a ptr
+
+    @complexity Constant.
+
+    @throw std::out_of_range      if the JSON pointer can not be resolved
+    @throw std::domain_error      if an array index begins with '0'
+    @throw std::invalid_argument  if an array index was not a number
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer}
 
     @since version 2.0.0
     */
@@ -3676,7 +3686,24 @@ class basic_json
     }
 
     /*!
-    @copydoc basic_json::at(const json_pointer&)
+    @brief access specified element via JSON Pointer
+
+    Returns a const reference to the element at with specified JSON pointer
+    @a ptr, with bounds checking.
+
+    @param[in] ptr  JSON pointer to the desired element
+
+    @return reference to the element pointed to by @a ptr
+
+    @complexity Constant.
+
+    @throw std::out_of_range      if the JSON pointer can not be resolved
+    @throw std::domain_error      if an array index begins with '0'
+    @throw std::invalid_argument  if an array index was not a number
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer_const}
+
+    @since version 2.0.0
     */
     const_reference at(const json_pointer& ptr) const
     {

src/json.hpp.re2c

@@ -3616,9 +3616,9 @@ class basic_json
 
     @param[in] ptr  a JSON pointer
 
-    @return reference to the JSON value pointed to by @a ptr
+    @return reference to the element pointed to by @a ptr
 
-    @complexity Linear in the length of the JSON pointer.
+    @complexity Constant.
 
     @throw std::out_of_range      if the JSON pointer can not be resolved
     @throw std::domain_error      if an array index begins with '0'
@@ -3641,18 +3641,17 @@ class basic_json
     value; no `null` values are created. In particular, the the special value
     `-` yields an exception.
 
-    @param[in] ptr  a JSON pointer
+    @param[in] ptr  JSON pointer to the desired element
 
-    @return reference to the JSON value pointed to by @a ptr
+    @return const reference to the element pointed to by @a ptr
 
-    @complexity Linear in the length of the JSON pointer.
+    @complexity Constant.
 
     @throw std::out_of_range      if the JSON pointer can not be resolved
     @throw std::domain_error      if an array index begins with '0'
     @throw std::invalid_argument  if an array index was not a number
 
-    @liveexample{The behavior is shown in the example.,
+    @liveexample{The behavior is shown in the example.,operatorjson_pointer_const}
-    operatorjson_pointer_const}
 
     @since version 2.0.0
     */
@@ -3664,9 +3663,20 @@ class basic_json
     /*!
     @brief access specified element via JSON Pointer
 
-    Returns a reference to the element at with specified JSON pointer @a ptr.
+    Returns a reference to the element at with specified JSON pointer @a ptr,
+    with bounds checking.
 
-    @param ptr  JSON pointer to the desired element
+    @param[in] ptr  JSON pointer to the desired element
+
+    @return reference to the element pointed to by @a ptr
+
+    @complexity Constant.
+
+    @throw std::out_of_range      if the JSON pointer can not be resolved
+    @throw std::domain_error      if an array index begins with '0'
+    @throw std::invalid_argument  if an array index was not a number
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer}
 
     @since version 2.0.0
     */
@@ -3676,7 +3686,24 @@ class basic_json
     }
 
     /*!
-    @copydoc basic_json::at(const json_pointer&)
+    @brief access specified element via JSON Pointer
+
+    Returns a const reference to the element at with specified JSON pointer
+    @a ptr, with bounds checking.
+
+    @param[in] ptr  JSON pointer to the desired element
+
+    @return reference to the element pointed to by @a ptr
+
+    @complexity Constant.
+
+    @throw std::out_of_range      if the JSON pointer can not be resolved
+    @throw std::domain_error      if an array index begins with '0'
+    @throw std::invalid_argument  if an array index was not a number
+
+    @liveexample{The behavior is shown in the example.,at_json_pointer_const}
+
+    @since version 2.0.0
     */
     const_reference at(const json_pointer& ptr) const
     {