From 710f26f95c82d8a14a18d717671fe83688f681aa Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Tue, 19 Mar 2019 10:06:35 +0100 Subject: [PATCH] :memo: added documentation --- doc/examples/json_pointer__operator_add.cpp | 23 ++++ doc/examples/json_pointer__operator_add.link | 1 + .../json_pointer__operator_add.output | 4 + .../json_pointer__operator_add_binary.cpp | 19 +++ .../json_pointer__operator_add_binary.link | 1 + .../json_pointer__operator_add_binary.output | 3 + include/nlohmann/detail/json_pointer.hpp | 118 ++++++++++++++++-- single_include/nlohmann/json.hpp | 118 ++++++++++++++++-- 8 files changed, 269 insertions(+), 18 deletions(-) create mode 100644 doc/examples/json_pointer__operator_add.cpp create mode 100644 doc/examples/json_pointer__operator_add.link create mode 100644 doc/examples/json_pointer__operator_add.output create mode 100644 doc/examples/json_pointer__operator_add_binary.cpp create mode 100644 doc/examples/json_pointer__operator_add_binary.link create mode 100644 doc/examples/json_pointer__operator_add_binary.output diff --git a/doc/examples/json_pointer__operator_add.cpp b/doc/examples/json_pointer__operator_add.cpp new file mode 100644 index 000000000..7520feb22 --- /dev/null +++ b/doc/examples/json_pointer__operator_add.cpp @@ -0,0 +1,23 @@ +#include +#include + +using json = nlohmann::json; + +int main() +{ + // create a JSON pointer + json::json_pointer ptr("/foo"); + std::cout << ptr << '\n'; + + // apppend a JSON Pointer + ptr /= json::json_pointer("/bar/baz"); + std::cout << ptr << '\n'; + + // append a string + ptr /= "fob"; + std::cout << ptr << '\n'; + + // append an array index + ptr /= 42; + std::cout << ptr << std::endl; +} diff --git a/doc/examples/json_pointer__operator_add.link b/doc/examples/json_pointer__operator_add.link new file mode 100644 index 000000000..9fc510603 --- /dev/null +++ b/doc/examples/json_pointer__operator_add.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/json_pointer__operator_add.output b/doc/examples/json_pointer__operator_add.output new file mode 100644 index 000000000..ae13afe27 --- /dev/null +++ b/doc/examples/json_pointer__operator_add.output @@ -0,0 +1,4 @@ +"/foo" +"/foo/bar/baz" +"/foo/bar/baz/fob" +"/foo/bar/baz/fob/42" diff --git a/doc/examples/json_pointer__operator_add_binary.cpp b/doc/examples/json_pointer__operator_add_binary.cpp new file mode 100644 index 000000000..620763e14 --- /dev/null +++ b/doc/examples/json_pointer__operator_add_binary.cpp @@ -0,0 +1,19 @@ +#include +#include + +using json = nlohmann::json; + +int main() +{ + // create a JSON pointer + json::json_pointer ptr("/foo"); + + // apppend a JSON Pointer + std::cout << ptr / json::json_pointer("/bar/baz") << '\n'; + + // append a string + std::cout << ptr / "fob" << '\n'; + + // append an array index + std::cout << ptr / 42 << std::endl; +} diff --git a/doc/examples/json_pointer__operator_add_binary.link b/doc/examples/json_pointer__operator_add_binary.link new file mode 100644 index 000000000..dabccf5c6 --- /dev/null +++ b/doc/examples/json_pointer__operator_add_binary.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/json_pointer__operator_add_binary.output b/doc/examples/json_pointer__operator_add_binary.output new file mode 100644 index 000000000..7536042c0 --- /dev/null +++ b/doc/examples/json_pointer__operator_add_binary.output @@ -0,0 +1,3 @@ +"/foo/bar/baz" +"/foo/fob" +"/foo/42" diff --git a/include/nlohmann/detail/json_pointer.hpp b/include/nlohmann/detail/json_pointer.hpp index 154e8b71b..d4d6000a4 100644 --- a/include/nlohmann/detail/json_pointer.hpp +++ b/include/nlohmann/detail/json_pointer.hpp @@ -56,8 +56,7 @@ class json_pointer @return a string representation of the JSON pointer - @liveexample{The example shows the result of `to_string`., - json_pointer__to_string} + @liveexample{The example shows the result of `to_string`.,json_pointer__to_string} @since version 2.0.0 */ @@ -79,6 +78,19 @@ class json_pointer /*! @brief append another JSON pointer at the end of this JSON pointer + + @param[in] ptr JSON pointer to append + @return JSON pointer with @a ptr appended + + @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} + + @complexity Linear in the length of @a ptr. + + @sa @ref operator/=(std::string) to append a reference token + @sa @ref operator/=(std::size_t) to append an array index + @sa @ref operator/(const json_pointer&, const json_pointer&) for a binary operator + + @since version 3.6.0 */ json_pointer& operator/=(const json_pointer& ptr) { @@ -88,14 +100,44 @@ class json_pointer return *this; } - /// @copydoc push_back(std::string&&) + /*! + @brief append an unescaped reference token at the end of this JSON pointer + + @param[in] token reference token to append + @return JSON pointer with @a token appended without escaping @a token + + @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} + + @complexity Amortized constant. + + @sa @ref operator/=(const json_pointer&) to append a JSON pointer + @sa @ref operator/=(std::size_t) to append an array index + @sa @ref operator/(const json_pointer&, std::size_t) for a binary operator + + @since version 3.6.0 + */ json_pointer& operator/=(std::string token) { push_back(std::move(token)); return *this; } - /// @copydoc operator/=(std::string) + /*! + @brief append an array index at the end of this JSON pointer + + @param[in] array_index array index ot append + @return JSON pointer with @a array_index appended + + @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} + + @complexity Amortized constant. + + @sa @ref operator/=(const json_pointer&) to append a JSON pointer + @sa @ref operator/=(std::string) to append a reference token + @sa @ref operator/(const json_pointer&, std::string) for a binary operator + + @since version 3.6.0 + */ json_pointer& operator/=(std::size_t array_index) { return *this /= std::to_string(array_index); @@ -103,15 +145,39 @@ class json_pointer /*! @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer + + @param[in] lhs JSON pointer + @param[in] rhs JSON pointer + @return a new JSON pointer with @a rhs appended to @a lhs + + @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary} + + @complexity Linear in the length of @a lhs and @a rhs. + + @sa @ref operator/=(const json_pointer&) to append a JSON pointer + + @since version 3.6.0 */ - friend json_pointer operator/(const json_pointer& left_ptr, - const json_pointer& right_ptr) + friend json_pointer operator/(const json_pointer& lhs, + const json_pointer& rhs) { - return json_pointer(left_ptr) /= right_ptr; + return json_pointer(lhs) /= rhs; } /*! @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer + + @param[in] ptr JSON pointer + @param[in] token reference token + @return a new JSON pointer with unescaped @a token appended to @a ptr + + @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary} + + @complexity Linear in the length of @a ptr. + + @sa @ref operator/=(std::string) to append a reference token + + @since version 3.6.0 */ friend json_pointer operator/(const json_pointer& ptr, std::string token) { @@ -120,10 +186,22 @@ class json_pointer /*! @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer + + @param[in] ptr JSON pointer + @param[in] array_index array index + @return a new JSON pointer with @a array_index appended to @a ptr + + @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary} + + @complexity Linear in the length of @a ptr. + + @sa @ref operator/=(std::size_t) to append an array index + + @since version 3.6.0 */ - friend json_pointer operator/(const json_pointer& lhs, std::size_t array_index) + friend json_pointer operator/(const json_pointer& ptr, std::size_t array_index) { - return json_pointer(lhs) /= array_index; + return json_pointer(ptr) /= array_index; } /*! @@ -790,12 +868,34 @@ class json_pointer return result; } + /*! + @brief compares two JSON pointers for equality + + @param[in] lhs JSON pointer to compare + @param[in] rhs JSON pointer to compare + @return whether @a lhs is equal to @a rhs + + @complexity Linear in the length of the JSON pointer + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + */ friend bool operator==(json_pointer const& lhs, json_pointer const& rhs) noexcept { return lhs.reference_tokens == rhs.reference_tokens; } + /*! + @brief compares two JSON pointers for inequality + + @param[in] lhs JSON pointer to compare + @param[in] rhs JSON pointer to compare + @return whether @a lhs is not equal @a rhs + + @complexity Linear in the length of the JSON pointer + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + */ friend bool operator!=(json_pointer const& lhs, json_pointer const& rhs) noexcept { diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 7509df499..c96ddc4db 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -8466,8 +8466,7 @@ class json_pointer @return a string representation of the JSON pointer - @liveexample{The example shows the result of `to_string`., - json_pointer__to_string} + @liveexample{The example shows the result of `to_string`.,json_pointer__to_string} @since version 2.0.0 */ @@ -8489,6 +8488,19 @@ class json_pointer /*! @brief append another JSON pointer at the end of this JSON pointer + + @param[in] ptr JSON pointer to append + @return JSON pointer with @a ptr appended + + @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} + + @complexity Linear in the length of @a ptr. + + @sa @ref operator/=(std::string) to append a reference token + @sa @ref operator/=(std::size_t) to append an array index + @sa @ref operator/(const json_pointer&, const json_pointer&) for a binary operator + + @since version 3.6.0 */ json_pointer& operator/=(const json_pointer& ptr) { @@ -8498,14 +8510,44 @@ class json_pointer return *this; } - /// @copydoc push_back(std::string&&) + /*! + @brief append an unescaped reference token at the end of this JSON pointer + + @param[in] token reference token to append + @return JSON pointer with @a token appended without escaping @a token + + @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} + + @complexity Amortized constant. + + @sa @ref operator/=(const json_pointer&) to append a JSON pointer + @sa @ref operator/=(std::size_t) to append an array index + @sa @ref operator/(const json_pointer&, std::size_t) for a binary operator + + @since version 3.6.0 + */ json_pointer& operator/=(std::string token) { push_back(std::move(token)); return *this; } - /// @copydoc operator/=(std::string) + /*! + @brief append an array index at the end of this JSON pointer + + @param[in] array_index array index ot append + @return JSON pointer with @a array_index appended + + @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} + + @complexity Amortized constant. + + @sa @ref operator/=(const json_pointer&) to append a JSON pointer + @sa @ref operator/=(std::string) to append a reference token + @sa @ref operator/(const json_pointer&, std::string) for a binary operator + + @since version 3.6.0 + */ json_pointer& operator/=(std::size_t array_index) { return *this /= std::to_string(array_index); @@ -8513,15 +8555,39 @@ class json_pointer /*! @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer + + @param[in] lhs JSON pointer + @param[in] rhs JSON pointer + @return a new JSON pointer with @a rhs appended to @a lhs + + @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary} + + @complexity Linear in the length of @a lhs and @a rhs. + + @sa @ref operator/=(const json_pointer&) to append a JSON pointer + + @since version 3.6.0 */ - friend json_pointer operator/(const json_pointer& left_ptr, - const json_pointer& right_ptr) + friend json_pointer operator/(const json_pointer& lhs, + const json_pointer& rhs) { - return json_pointer(left_ptr) /= right_ptr; + return json_pointer(lhs) /= rhs; } /*! @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer + + @param[in] ptr JSON pointer + @param[in] token reference token + @return a new JSON pointer with unescaped @a token appended to @a ptr + + @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary} + + @complexity Linear in the length of @a ptr. + + @sa @ref operator/=(std::string) to append a reference token + + @since version 3.6.0 */ friend json_pointer operator/(const json_pointer& ptr, std::string token) { @@ -8530,10 +8596,22 @@ class json_pointer /*! @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer + + @param[in] ptr JSON pointer + @param[in] array_index array index + @return a new JSON pointer with @a array_index appended to @a ptr + + @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary} + + @complexity Linear in the length of @a ptr. + + @sa @ref operator/=(std::size_t) to append an array index + + @since version 3.6.0 */ - friend json_pointer operator/(const json_pointer& lhs, std::size_t array_index) + friend json_pointer operator/(const json_pointer& ptr, std::size_t array_index) { - return json_pointer(lhs) /= array_index; + return json_pointer(ptr) /= array_index; } /*! @@ -9200,12 +9278,34 @@ class json_pointer return result; } + /*! + @brief compares two JSON pointers for equality + + @param[in] lhs JSON pointer to compare + @param[in] rhs JSON pointer to compare + @return whether @a lhs is equal to @a rhs + + @complexity Linear in the length of the JSON pointer + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + */ friend bool operator==(json_pointer const& lhs, json_pointer const& rhs) noexcept { return lhs.reference_tokens == rhs.reference_tokens; } + /*! + @brief compares two JSON pointers for inequality + + @param[in] lhs JSON pointer to compare + @param[in] rhs JSON pointer to compare + @return whether @a lhs is not equal @a rhs + + @complexity Linear in the length of the JSON pointer + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + */ friend bool operator!=(json_pointer const& lhs, json_pointer const& rhs) noexcept {