From eff06842f0dda8d9e2fd296e04f8fceae618c882 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 5 Nov 2021 21:43:46 +0100 Subject: [PATCH] :fire: consolidate documentation --- doc/mkdocs/docs/api/basic_json/index.md | 2 +- .../operator_literal_json_pointer.md | 6 +- doc/mkdocs/docs/api/json_pointer.md | 28 --- doc/mkdocs/docs/api/json_pointer/back.md | 39 +++ doc/mkdocs/docs/api/json_pointer/empty.md | 39 +++ doc/mkdocs/docs/api/json_pointer/index.md | 34 +++ .../docs/api/json_pointer/json_pointer.md | 40 +++ .../docs/api/json_pointer/operator_slash.md | 64 +++++ .../docs/api/json_pointer/operator_slasheq.md | 61 +++++ .../docs/api/json_pointer/operator_string.md | 24 ++ .../docs/api/json_pointer/parent_pointer.md | 35 +++ doc/mkdocs/docs/api/json_pointer/pop_back.md | 35 +++ doc/mkdocs/docs/api/json_pointer/push_back.md | 38 +++ doc/mkdocs/docs/api/json_pointer/to_string.md | 39 +++ doc/mkdocs/mkdocs.yml | 13 +- doc/mkdocs/scripts/check_strcuture.py | 4 + include/nlohmann/detail/json_pointer.hpp | 237 +++--------------- single_include/nlohmann/json.hpp | 237 +++--------------- 18 files changed, 542 insertions(+), 433 deletions(-) delete mode 100644 doc/mkdocs/docs/api/json_pointer.md create mode 100644 doc/mkdocs/docs/api/json_pointer/back.md create mode 100644 doc/mkdocs/docs/api/json_pointer/empty.md create mode 100644 doc/mkdocs/docs/api/json_pointer/index.md create mode 100644 doc/mkdocs/docs/api/json_pointer/json_pointer.md create mode 100644 doc/mkdocs/docs/api/json_pointer/operator_slash.md create mode 100644 doc/mkdocs/docs/api/json_pointer/operator_slasheq.md create mode 100644 doc/mkdocs/docs/api/json_pointer/operator_string.md create mode 100644 doc/mkdocs/docs/api/json_pointer/parent_pointer.md create mode 100644 doc/mkdocs/docs/api/json_pointer/pop_back.md create mode 100644 doc/mkdocs/docs/api/json_pointer/push_back.md create mode 100644 doc/mkdocs/docs/api/json_pointer/to_string.md diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index dbb585115..69133170d 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -88,7 +88,7 @@ The class satisfies the following concept requirements: - [**adl_serializer**](../adl_serializer) - the default serializer - [**value_t**](value_t.md) - the JSON type enumeration -- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation +- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation - [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags diff --git a/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md b/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md index 5ff9e0a9b..58f95e205 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md +++ b/doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md @@ -5,7 +5,7 @@ json_pointer operator "" _json_pointer(const char* s, std::size_t n); ``` This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer` -to a string literal and returns a [`json_pointer`](../json_pointer.md) object if no parse error occurred. +to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred. ## Parameters @@ -17,11 +17,11 @@ to a string literal and returns a [`json_pointer`](../json_pointer.md) object if ## Return value -[`json_pointer`](../json_pointer.md) value parsed from `s` +[`json_pointer`](../json_pointer/index.md) value parsed from `s` ## Exceptions -The function can throw anything that [`json_pointer::json_pointer`](../json_pointer.md) would throw. +The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw. ## Complexity diff --git a/doc/mkdocs/docs/api/json_pointer.md b/doc/mkdocs/docs/api/json_pointer.md deleted file mode 100644 index 69983ab89..000000000 --- a/doc/mkdocs/docs/api/json_pointer.md +++ /dev/null @@ -1,28 +0,0 @@ -# json_pointer - -```cpp -template -class json_pointer; -``` - -## Template parameters - -`BasicJsonType` -: a specialization of [`basic_json`](basic_json/index.md) - -## Member functions - -- (constructor) -- **to_string** - return a string representation of the JSON pointer -- **operator std::string**- return a string representation of the JSON pointer -- **operator/=** - append to the end of the JSON pointer -- **operator/** - create JSON Pointer by appending -- **parent_pointer** - returns the parent of this JSON pointer -- **pop_back** - remove last reference token -- **back** - return last reference token -- **push_back** - append an unescaped token at the end of the pointer -- **empty** - return whether pointer points to the root document - -## Version history - -Added in version 2.0.0. diff --git a/doc/mkdocs/docs/api/json_pointer/back.md b/doc/mkdocs/docs/api/json_pointer/back.md new file mode 100644 index 000000000..a16e98d96 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/back.md @@ -0,0 +1,39 @@ +# json_pointer::back + +```cpp +const std::string& back() const; +``` + +Return last reference token. + +## Return value + +Last reference token. + +## Exceptions + +Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent. + +## Complexity + +Constant. + +## Examples + +??? example + + The example shows the usage of `back`. + + ```cpp + --8<-- "examples/json_pointer__back.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__back.output" + ``` + +## Version history + +Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/empty.md b/doc/mkdocs/docs/api/json_pointer/empty.md new file mode 100644 index 000000000..4418e6859 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/empty.md @@ -0,0 +1,39 @@ +# json_pointer::empty + +```cpp +bool empty() const noexcept; +``` + +Return whether pointer points to the root document. + +## Return value + +`#!cpp true` iff the JSON pointer points to the root document. + +## Exception safety + +No-throw guarantee: this function never throws exceptions. + +## Complexity + +Constant. + +## Examples + +??? example + + The example shows the result of `empty` for different JSON Pointers. + + ```cpp + --8<-- "examples/json_pointer__empty.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__empty.output" + ``` + +## Version history + +Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/index.md b/doc/mkdocs/docs/api/json_pointer/index.md new file mode 100644 index 000000000..fd3d6b1a9 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/index.md @@ -0,0 +1,34 @@ +# json_pointer + +```cpp +template +class json_pointer; +``` + +JSON Pointer defines a string syntax for identifying a specific value within a JSON document. + +## Template parameters + +`BasicJsonType` +: a specialization of [`basic_json`](../basic_json/index.md) + +## Member functions + +- [(constructor)](json_pointer.md) +- [**to_string**](to_string.md) - return a string representation of the JSON pointer +- [**operator std::string**](operator_string.md) - return a string representation of the JSON pointer +- [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer +- [**operator/**](operator_slash.md) - create JSON Pointer by appending +- [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer +- [**pop_back**](pop_back.md) - remove last reference token +- [**back**](back.md) - return last reference token +- [**push_back**](push_back.md) - append an unescaped token at the end of the pointer +- [**empty**](empty.md) - return whether pointer points to the root document + +## See also + +[RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) + +## Version history + +Added in version 2.0.0. diff --git a/doc/mkdocs/docs/api/json_pointer/json_pointer.md b/doc/mkdocs/docs/api/json_pointer/json_pointer.md new file mode 100644 index 000000000..9d08f9c31 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/json_pointer.md @@ -0,0 +1,40 @@ +# json_pointer::json_pointer + +```cpp +explicit json_pointer(const std::string& s = ""); +``` + +Create a JSON pointer according to the syntax described in +[Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3). + +## Parameters + +`s` (in) +: string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value + +## Exceptions + +- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is + nonempty and does not begin with a slash (`/`); see example below. +- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON + pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below. + +## Examples + +??? example + + The example shows the construction several valid JSON pointers as well as the exceptional behavior. + + ```cpp + --8<-- "examples/json_pointer.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer.output" + ``` + +## Version history + +Added in version 2.0.0. diff --git a/doc/mkdocs/docs/api/json_pointer/operator_slash.md b/doc/mkdocs/docs/api/json_pointer/operator_slash.md new file mode 100644 index 000000000..504f66b63 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/operator_slash.md @@ -0,0 +1,64 @@ +# json_pointer::operator/ + +```cpp +// (1) +json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs); + +// (2) +json_pointer operator/(const json_pointer& lhs, std::string token); + +// (3) +json_pointer operator/(const json_pointer& lhs, std::size_t array_idx); +``` + +1. create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer +2. create a new JSON pointer by appending the unescaped token at the end of the JSON pointer +3. create a new JSON pointer by appending the array-index-token at the end of the JSON pointer + +## Parameters + +`lhs` (in) +: JSON pointer + +`rhs` (in) +: JSON pointer to append + +`token` (in) +: reference token to append + +`array_idx` (in) +: array index to append + +## Return value + +1. a new JSON pointer with `rhs` appended to `lhs` +2. a new JSON pointer with unescaped `token` appended to `lhs` +3. a new JSON pointer with `array_idx` appended to `lhs` + +## Complexity + +1. Linear in the length of `lhs` and `rhs`. +2. Linear in the length of `lhs`. +3. Linear in the length of `lhs`. + +## Examples + +??? example + + The example shows the usage of `operator/`. + + ```cpp + --8<-- "examples/json_pointer__operator_add_binary.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__operator_add_binary.output" + ``` + +## Version history + +1. Added in version 3.6.0. +2. Added in version 3.6.0. +3. Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md b/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md new file mode 100644 index 000000000..f92664193 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/operator_slasheq.md @@ -0,0 +1,61 @@ +# json_pointer::operator/= + +```cpp +// (1) +json_pointer& operator/=(const json_pointer& ptr); + +// (2) +json_pointer& operator/=(std::string token); + +// (3) +json_pointer& operator/=(std::size_t array_idx) +``` + +1. append another JSON pointer at the end of this JSON pointer +2. append an unescaped reference token at the end of this JSON pointer +3. append an array index at the end of this JSON pointer + +## Parameters + +`ptr` (in) +: JSON pointer to append + +`token` (in) +: reference token to append + +`array_idx` (in) +: array index to append + +## Return value + +1. JSON pointer with `ptr` appended +2. JSON pointer with `token` appended without escaping `token` +3. JSON pointer with `array_idx` appended + +## Complexity + +1. Linear in the length of `ptr`. +2. Amortized constant. +3. Amortized constant. + +## Examples + +??? example + + The example shows the usage of `operator/=`. + + ```cpp + --8<-- "examples/json_pointer__operator_add.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__operator_add.output" + ``` + +## Version history + +1. Added in version 3.6.0. +2. Added in version 3.6.0. +3. Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/operator_string.md b/doc/mkdocs/docs/api/json_pointer/operator_string.md new file mode 100644 index 000000000..881bff524 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/operator_string.md @@ -0,0 +1,24 @@ +# json_pointer::operator std::string + +```cpp +operator std::string() const +``` + +Return a string representation of the JSON pointer. + +## Return value + +A string representation of the JSON pointer + +## Possible implementation + +```cpp +operator std::string() const +{ + return to_string(); +} +``` + +## Version history + +Since version 2.0.0. diff --git a/doc/mkdocs/docs/api/json_pointer/parent_pointer.md b/doc/mkdocs/docs/api/json_pointer/parent_pointer.md new file mode 100644 index 000000000..1ec92c83b --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/parent_pointer.md @@ -0,0 +1,35 @@ +# json_pointer::parent_pointer + +```cpp +json_pointer parent_pointer() const; +``` + +Returns the parent of this JSON pointer. + +## Return value + +Parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned. + +## Complexity + +Linear in the length of the JSON pointer. + +## Examples + +??? example + + The example shows the result of `parent_pointer` for different JSON Pointers. + + ```cpp + --8<-- "examples/json_pointer__parent_pointer.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__parent_pointer.output" + ``` + +## Version history + +Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/pop_back.md b/doc/mkdocs/docs/api/json_pointer/pop_back.md new file mode 100644 index 000000000..9b570c501 --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/pop_back.md @@ -0,0 +1,35 @@ +# json_pointer::pop_back + +```cpp +void pop_back(); +``` + +Remove last reference token. + +## Exceptions + +Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent. + +## Complexity + +Constant. + +## Examples + +??? example + + The example shows the usage of `pop_back`. + + ```cpp + --8<-- "examples/json_pointer__pop_back.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__pop_back.output" + ``` + +## Version history + +Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/push_back.md b/doc/mkdocs/docs/api/json_pointer/push_back.md new file mode 100644 index 000000000..581ddd94d --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/push_back.md @@ -0,0 +1,38 @@ +# json_pointer::push_back + +```cpp +void push_back(const std::string& token); + +void push_back(std::string&& token); +``` + +Append an unescaped token at the end of the reference pointer. + +## Parameters + +`token` (in) +: token to add + +## Complexity + +Amortized constant. + +## Examples + +??? example + + The example shows the result of `push_back` for different JSON Pointers. + + ```cpp + --8<-- "examples/json_pointer__push_back.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__push_back.output" + ``` + +## Version history + +Added in version 3.6.0. diff --git a/doc/mkdocs/docs/api/json_pointer/to_string.md b/doc/mkdocs/docs/api/json_pointer/to_string.md new file mode 100644 index 000000000..6c802c74c --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer/to_string.md @@ -0,0 +1,39 @@ +# json_pointer::to_string + +```cpp +std::string to_string() const; +``` + +Return a string representation of the JSON pointer. + +## Return value + +A string representation of the JSON pointer + +## Notes + +For each JSON pointer `ptr`, it holds: + +```cpp +ptr == json_pointer(ptr.to_string()); +``` + +## Examples + +??? example + + The example shows the result of `to_string`. + + ```cpp + --8<-- "examples/json_pointer__to_string.cpp" + ``` + + Output: + + ```json + --8<-- "examples/json_pointer__to_string.output" + ``` + +## Version history + +Since version 2.0.0. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index d749e7688..4e265df9c 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -194,7 +194,18 @@ nav: - 'from_json': api/adl_serializer/from_json.md - 'to_json': api/adl_serializer/to_json.md - api/json.md - - api/json_pointer.md + - json_pointer: + - 'Overview': api/json_pointer/index.md + - '(Constructor)': api/json_pointer/json_pointer.md + - 'back': api/json_pointer/back.md + - 'empty': api/json_pointer/empty.md + - 'operator std::string': api/json_pointer/operator_string.md + - 'operator/': api/json_pointer/operator_slash.md + - 'operator/=': api/json_pointer/operator_slasheq.md + - 'parent_pointer': api/json_pointer/parent_pointer.md + - 'pop_back': api/json_pointer/pop_back.md + - 'push_back': api/json_pointer/push_back.md + - 'to_string': api/json_pointer/to_string.md - json_sax: - 'Overview': api/json_sax/index.md - 'binary': api/json_sax/binary.md diff --git a/doc/mkdocs/scripts/check_strcuture.py b/doc/mkdocs/scripts/check_strcuture.py index 83f6235fa..3b0f09d9e 100644 --- a/doc/mkdocs/scripts/check_strcuture.py +++ b/doc/mkdocs/scripts/check_strcuture.py @@ -41,6 +41,10 @@ def check_structure(): for lineno, line in enumerate(file_content.readlines()): line = line.strip() + # lines longer than 160 characters are bad (unless they are tables) + if len(line) > 160 and '|' not in line: + print(f'{file}:{lineno+1}: Error: line is too long ({len(line)} vs. 160 chars)!') + # check if headers are correct if line.startswith('## '): header = line.strip('## ') diff --git a/include/nlohmann/detail/json_pointer.hpp b/include/nlohmann/detail/json_pointer.hpp index d727ecc50..7483f8cd3 100644 --- a/include/nlohmann/detail/json_pointer.hpp +++ b/include/nlohmann/detail/json_pointer.hpp @@ -15,6 +15,9 @@ namespace nlohmann { + +/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document +/// @sa http://127.0.0.1:8000/api/json_pointer/ template class json_pointer { @@ -23,45 +26,14 @@ class json_pointer friend class basic_json; public: - /*! - @brief create JSON pointer - - Create a JSON pointer according to the syntax described in - [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3). - - @param[in] s string representing the JSON pointer; if omitted, the empty - string is assumed which references the whole JSON value - - @throw parse_error.107 if the given JSON pointer @a s is nonempty and does - not begin with a slash (`/`); see example below - - @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s is - not followed by `0` (representing `~`) or `1` (representing `/`); see - example below - - @liveexample{The example shows the construction several valid JSON pointers - as well as the exceptional behavior.,json_pointer} - - @since version 2.0.0 - */ + /// @brief create JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/json_pointer/ explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {} - /*! - @brief return a string representation of the JSON pointer - - @invariant For each JSON pointer `ptr`, it holds: - @code {.cpp} - ptr == json_pointer(ptr.to_string()); - @endcode - - @return a string representation of the JSON pointer - - @liveexample{The example shows the result of `to_string`.,json_pointer__to_string} - - @since version 2.0.0 - */ + /// @brief return a string representation of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/to_string/ std::string to_string() const { return std::accumulate(reference_tokens.begin(), reference_tokens.end(), @@ -72,28 +44,15 @@ class json_pointer }); } - /// @copydoc to_string() + /// @brief return a string representation of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_string/ operator std::string() const { return to_string(); } - /*! - @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 see @ref operator/=(std::string) to append a reference token - @sa see @ref operator/=(std::size_t) to append an array index - @sa see @ref operator/(const json_pointer&, const json_pointer&) for a binary operator - - @since version 3.6.0 - */ + /// @brief append another JSON pointer at the end of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/ json_pointer& operator/=(const json_pointer& ptr) { reference_tokens.insert(reference_tokens.end(), @@ -102,123 +61,45 @@ class json_pointer return *this; } - /*! - @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 see @ref operator/=(const json_pointer&) to append a JSON pointer - @sa see @ref operator/=(std::size_t) to append an array index - @sa see @ref operator/(const json_pointer&, std::size_t) for a binary operator - - @since version 3.6.0 - */ + /// @brief append an unescaped reference token at the end of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/ json_pointer& operator/=(std::string token) { push_back(std::move(token)); return *this; } - /*! - @brief append an array index at the end of this JSON pointer - - @param[in] array_idx array index to append - @return JSON pointer with @a array_idx appended - - @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} - - @complexity Amortized constant. - - @sa see @ref operator/=(const json_pointer&) to append a JSON pointer - @sa see @ref operator/=(std::string) to append a reference token - @sa see @ref operator/(const json_pointer&, std::string) for a binary operator - - @since version 3.6.0 - */ + /// @brief append an array index at the end of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/ json_pointer& operator/=(std::size_t array_idx) { return *this /= std::to_string(array_idx); } - /*! - @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 see @ref operator/=(const json_pointer&) to append a JSON pointer - - @since version 3.6.0 - */ + /// @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/ friend json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs) { 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 see @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) // NOLINT(performance-unnecessary-value-param) + /// @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/ + friend json_pointer operator/(const json_pointer& lhs, std::string token) // NOLINT(performance-unnecessary-value-param) { - return json_pointer(ptr) /= std::move(token); + return json_pointer(lhs) /= std::move(token); } - /*! - @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_idx array index - @return a new JSON pointer with @a array_idx 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 see @ref operator/=(std::size_t) to append an array index - - @since version 3.6.0 - */ - friend json_pointer operator/(const json_pointer& ptr, std::size_t array_idx) + /// @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/ + friend json_pointer operator/(const json_pointer& lhs, std::size_t array_idx) { - return json_pointer(ptr) /= array_idx; + return json_pointer(lhs) /= array_idx; } - /*! - @brief returns the parent of this JSON pointer - - @return parent of this JSON pointer; in case this JSON pointer is the root, - the root itself is returned - - @complexity Linear in the length of the JSON pointer. - - @liveexample{The example shows the result of `parent_pointer` for different - JSON Pointers.,json_pointer__parent_pointer} - - @since version 3.6.0 - */ + /// @brief returns the parent of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/parent_pointer/ json_pointer parent_pointer() const { if (empty()) @@ -231,19 +112,8 @@ class json_pointer return res; } - /*! - @brief remove last reference token - - @pre not `empty()` - - @liveexample{The example shows the usage of `pop_back`.,json_pointer__pop_back} - - @complexity Constant. - - @throw out_of_range.405 if JSON pointer has no parent - - @since version 3.6.0 - */ + /// @brief remove last reference token + /// @sa http://127.0.0.1:8000/api/json_pointer/pop_back/ void pop_back() { if (JSON_HEDLEY_UNLIKELY(empty())) @@ -254,20 +124,8 @@ class json_pointer reference_tokens.pop_back(); } - /*! - @brief return last reference token - - @pre not `empty()` - @return last reference token - - @liveexample{The example shows the usage of `back`.,json_pointer__back} - - @complexity Constant. - - @throw out_of_range.405 if JSON pointer has no parent - - @since version 3.6.0 - */ + /// @brief return last reference token + /// @sa http://127.0.0.1:8000/api/json_pointer/back/ const std::string& back() const { if (JSON_HEDLEY_UNLIKELY(empty())) @@ -278,43 +136,22 @@ class json_pointer return reference_tokens.back(); } - /*! - @brief append an unescaped token at the end of the reference pointer - - @param[in] token token to add - - @complexity Amortized constant. - - @liveexample{The example shows the result of `push_back` for different - JSON Pointers.,json_pointer__push_back} - - @since version 3.6.0 - */ + /// @brief append an unescaped token at the end of the reference pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/ void push_back(const std::string& token) { reference_tokens.push_back(token); } - /// @copydoc push_back(const std::string&) + /// @brief append an unescaped token at the end of the reference pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/ void push_back(std::string&& token) { reference_tokens.push_back(std::move(token)); } - /*! - @brief return whether pointer points to the root document - - @return true iff the JSON pointer points to the root document - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this function never throws exceptions. - - @liveexample{The example shows the result of `empty` for different JSON - Pointers.,json_pointer__empty} - - @since version 3.6.0 - */ + /// @brief return whether pointer points to the root document + /// @sa http://127.0.0.1:8000/api/json_pointer/empty/ bool empty() const noexcept { return reference_tokens.empty(); diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index f2b31e726..9d2866b9b 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -12369,6 +12369,9 @@ class json_reverse_iterator : public std::reverse_iterator namespace nlohmann { + +/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document +/// @sa http://127.0.0.1:8000/api/json_pointer/ template class json_pointer { @@ -12377,45 +12380,14 @@ class json_pointer friend class basic_json; public: - /*! - @brief create JSON pointer - - Create a JSON pointer according to the syntax described in - [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3). - - @param[in] s string representing the JSON pointer; if omitted, the empty - string is assumed which references the whole JSON value - - @throw parse_error.107 if the given JSON pointer @a s is nonempty and does - not begin with a slash (`/`); see example below - - @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s is - not followed by `0` (representing `~`) or `1` (representing `/`); see - example below - - @liveexample{The example shows the construction several valid JSON pointers - as well as the exceptional behavior.,json_pointer} - - @since version 2.0.0 - */ + /// @brief create JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/json_pointer/ explicit json_pointer(const std::string& s = "") : reference_tokens(split(s)) {} - /*! - @brief return a string representation of the JSON pointer - - @invariant For each JSON pointer `ptr`, it holds: - @code {.cpp} - ptr == json_pointer(ptr.to_string()); - @endcode - - @return a string representation of the JSON pointer - - @liveexample{The example shows the result of `to_string`.,json_pointer__to_string} - - @since version 2.0.0 - */ + /// @brief return a string representation of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/to_string/ std::string to_string() const { return std::accumulate(reference_tokens.begin(), reference_tokens.end(), @@ -12426,28 +12398,15 @@ class json_pointer }); } - /// @copydoc to_string() + /// @brief return a string representation of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_string/ operator std::string() const { return to_string(); } - /*! - @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 see @ref operator/=(std::string) to append a reference token - @sa see @ref operator/=(std::size_t) to append an array index - @sa see @ref operator/(const json_pointer&, const json_pointer&) for a binary operator - - @since version 3.6.0 - */ + /// @brief append another JSON pointer at the end of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/ json_pointer& operator/=(const json_pointer& ptr) { reference_tokens.insert(reference_tokens.end(), @@ -12456,123 +12415,45 @@ class json_pointer return *this; } - /*! - @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 see @ref operator/=(const json_pointer&) to append a JSON pointer - @sa see @ref operator/=(std::size_t) to append an array index - @sa see @ref operator/(const json_pointer&, std::size_t) for a binary operator - - @since version 3.6.0 - */ + /// @brief append an unescaped reference token at the end of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/ json_pointer& operator/=(std::string token) { push_back(std::move(token)); return *this; } - /*! - @brief append an array index at the end of this JSON pointer - - @param[in] array_idx array index to append - @return JSON pointer with @a array_idx appended - - @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add} - - @complexity Amortized constant. - - @sa see @ref operator/=(const json_pointer&) to append a JSON pointer - @sa see @ref operator/=(std::string) to append a reference token - @sa see @ref operator/(const json_pointer&, std::string) for a binary operator - - @since version 3.6.0 - */ + /// @brief append an array index at the end of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/ json_pointer& operator/=(std::size_t array_idx) { return *this /= std::to_string(array_idx); } - /*! - @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 see @ref operator/=(const json_pointer&) to append a JSON pointer - - @since version 3.6.0 - */ + /// @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/ friend json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs) { 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 see @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) // NOLINT(performance-unnecessary-value-param) + /// @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/ + friend json_pointer operator/(const json_pointer& lhs, std::string token) // NOLINT(performance-unnecessary-value-param) { - return json_pointer(ptr) /= std::move(token); + return json_pointer(lhs) /= std::move(token); } - /*! - @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_idx array index - @return a new JSON pointer with @a array_idx 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 see @ref operator/=(std::size_t) to append an array index - - @since version 3.6.0 - */ - friend json_pointer operator/(const json_pointer& ptr, std::size_t array_idx) + /// @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/ + friend json_pointer operator/(const json_pointer& lhs, std::size_t array_idx) { - return json_pointer(ptr) /= array_idx; + return json_pointer(lhs) /= array_idx; } - /*! - @brief returns the parent of this JSON pointer - - @return parent of this JSON pointer; in case this JSON pointer is the root, - the root itself is returned - - @complexity Linear in the length of the JSON pointer. - - @liveexample{The example shows the result of `parent_pointer` for different - JSON Pointers.,json_pointer__parent_pointer} - - @since version 3.6.0 - */ + /// @brief returns the parent of this JSON pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/parent_pointer/ json_pointer parent_pointer() const { if (empty()) @@ -12585,19 +12466,8 @@ class json_pointer return res; } - /*! - @brief remove last reference token - - @pre not `empty()` - - @liveexample{The example shows the usage of `pop_back`.,json_pointer__pop_back} - - @complexity Constant. - - @throw out_of_range.405 if JSON pointer has no parent - - @since version 3.6.0 - */ + /// @brief remove last reference token + /// @sa http://127.0.0.1:8000/api/json_pointer/pop_back/ void pop_back() { if (JSON_HEDLEY_UNLIKELY(empty())) @@ -12608,20 +12478,8 @@ class json_pointer reference_tokens.pop_back(); } - /*! - @brief return last reference token - - @pre not `empty()` - @return last reference token - - @liveexample{The example shows the usage of `back`.,json_pointer__back} - - @complexity Constant. - - @throw out_of_range.405 if JSON pointer has no parent - - @since version 3.6.0 - */ + /// @brief return last reference token + /// @sa http://127.0.0.1:8000/api/json_pointer/back/ const std::string& back() const { if (JSON_HEDLEY_UNLIKELY(empty())) @@ -12632,43 +12490,22 @@ class json_pointer return reference_tokens.back(); } - /*! - @brief append an unescaped token at the end of the reference pointer - - @param[in] token token to add - - @complexity Amortized constant. - - @liveexample{The example shows the result of `push_back` for different - JSON Pointers.,json_pointer__push_back} - - @since version 3.6.0 - */ + /// @brief append an unescaped token at the end of the reference pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/ void push_back(const std::string& token) { reference_tokens.push_back(token); } - /// @copydoc push_back(const std::string&) + /// @brief append an unescaped token at the end of the reference pointer + /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/ void push_back(std::string&& token) { reference_tokens.push_back(std::move(token)); } - /*! - @brief return whether pointer points to the root document - - @return true iff the JSON pointer points to the root document - - @complexity Constant. - - @exceptionsafety No-throw guarantee: this function never throws exceptions. - - @liveexample{The example shows the result of `empty` for different JSON - Pointers.,json_pointer__empty} - - @since version 3.6.0 - */ + /// @brief return whether pointer points to the root document + /// @sa http://127.0.0.1:8000/api/json_pointer/empty/ bool empty() const noexcept { return reference_tokens.empty();