📝 added documentation

This commit is contained in:
Niels Lohmann 2019-03-19 10:06:35 +01:00
parent b224c52376
commit 710f26f95c
No known key found for this signature in database
GPG key ID: 7F3CEA63AE251B69
8 changed files with 269 additions and 18 deletions

View file

@ -0,0 +1,23 @@
#include <iostream>
#include <nlohmann/json.hpp>
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;
}

View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/9GFummh9iBAkOFiL"><b>online</b></a>

View file

@ -0,0 +1,4 @@
"/foo"
"/foo/bar/baz"
"/foo/bar/baz/fob"
"/foo/bar/baz/fob/42"

View file

@ -0,0 +1,19 @@
#include <iostream>
#include <nlohmann/json.hpp>
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;
}

View file

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

View file

@ -0,0 +1,3 @@
"/foo/bar/baz"
"/foo/fob"
"/foo/42"

View file

@ -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
{

View file

@ -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
{