diff --git a/doc/examples/at_json_pointer.cpp b/doc/examples/at_json_pointer.cpp new file mode 100644 index 00000000..0665e608 --- /dev/null +++ b/doc/examples/at_json_pointer.cpp @@ -0,0 +1,35 @@ +#include + +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'; +} diff --git a/doc/examples/at_json_pointer.link b/doc/examples/at_json_pointer.link new file mode 100644 index 00000000..5356294e --- /dev/null +++ b/doc/examples/at_json_pointer.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/at_json_pointer.output b/doc/examples/at_json_pointer.output new file mode 100644 index 00000000..11913c72 --- /dev/null +++ b/doc/examples/at_json_pointer.output @@ -0,0 +1,6 @@ +1 +"foo" +[1,2] +2 +"bar" +[1,21] diff --git a/doc/examples/at_json_pointer_const.cpp b/doc/examples/at_json_pointer_const.cpp new file mode 100644 index 00000000..e3cfc515 --- /dev/null +++ b/doc/examples/at_json_pointer_const.cpp @@ -0,0 +1,23 @@ +#include + +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'; +} diff --git a/doc/examples/at_json_pointer_const.link b/doc/examples/at_json_pointer_const.link new file mode 100644 index 00000000..905e60d3 --- /dev/null +++ b/doc/examples/at_json_pointer_const.link @@ -0,0 +1 @@ +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 new file mode 100644 index 00000000..7b9306bb --- /dev/null +++ b/doc/examples/at_json_pointer_const.output @@ -0,0 +1,4 @@ +1 +"foo" +[1,2] +2 diff --git a/src/json.hpp b/src/json.hpp index 5fdba140..ffa46067 100644 --- a/src/json.hpp +++ b/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., - operatorjson_pointer_const} + @liveexample{The behavior is shown in the example.,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 { diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 95a484f8..ced7ffba 100644 --- a/src/json.hpp.re2c +++ b/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., - operatorjson_pointer_const} + @liveexample{The behavior is shown in the example.,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 {