From 5e04a6a2ba8d7530320a883c63f3183e20aa8c21 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sun, 10 Oct 2021 15:32:59 +0200 Subject: [PATCH] :fire: consolidate documentation --- doc/mkdocs/docs/api/basic_json/back.md | 4 + doc/mkdocs/docs/api/basic_json/contains.md | 54 ++++++-- doc/mkdocs/docs/api/basic_json/front.md | 4 + include/nlohmann/json.hpp | 148 ++------------------- single_include/nlohmann/json.hpp | 148 ++------------------- 5 files changed, 82 insertions(+), 276 deletions(-) diff --git a/doc/mkdocs/docs/api/basic_json/back.md b/doc/mkdocs/docs/api/basic_json/back.md index 1484153ae..2acee240a 100644 --- a/doc/mkdocs/docs/api/basic_json/back.md +++ b/doc/mkdocs/docs/api/basic_json/back.md @@ -55,6 +55,10 @@ Constant. --8<-- "examples/back.output" ``` +## See also + +- [front](front.md) to access the first element + ## Version history - Added in version 1.0.0. diff --git a/doc/mkdocs/docs/api/basic_json/contains.md b/doc/mkdocs/docs/api/basic_json/contains.md index 1616f0c2d..23dacb47e 100644 --- a/doc/mkdocs/docs/api/basic_json/contains.md +++ b/doc/mkdocs/docs/api/basic_json/contains.md @@ -1,12 +1,17 @@ # basic_json::contains ```cpp +// (1) template bool contains(KeyT && key) const; + +// (2) +bool contains(const json_pointer& ptr) const ``` -Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the JSON -value is not an object, `#!cpp false` is returned. +1. Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the + JSON value is not an object, `#!cpp false` is returned. +2. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value. ## Template parameters @@ -17,27 +22,45 @@ value is not an object, `#!cpp false` is returned. `key` (in) : key value to check its existence. - + +`ptr` (in) +: JSON pointer to check its existence. + ## Return value -`#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value is -not an object, `#!cpp false` is returned. +1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value + is not an object, `#!cpp false` is returned. +2. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise. ## Exception safety Strong exception safety: if an exception occurs, the original value stays intact. +## Exceptions + +1. The function does not throw exceptions. +2. The function can throw the following exceptions: + - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with + `0`. + - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a + number. + ## Complexity Logarithmic in the size of the JSON object. ## Notes -This method always returns `#!cpp false` when executed on a JSON type that is not an object. +1. This method always returns `#!cpp false` when executed on a JSON type that is not an object. +2. This method can be executed on any JSON value type. + +!!! info "Postconditions" + + If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`. ## Example -??? example +??? example "Example (1) check with key" The example shows how `contains()` is used. @@ -51,6 +74,21 @@ This method always returns `#!cpp false` when executed on a JSON type that is no --8<-- "examples/contains.output" ``` +??? example "Example (1) check with JSON pointer" + + The example shows how `contains()` is used. + + ```cpp + --8<-- "examples/contains_json_pointer.cpp" + ``` + + Output: + + ```json + --8<-- "examples/contains_json_pointer.output" + ``` + ## Version history -- Added in version 3.6.0. +1. Added in version 3.6.0. +2. Added in version 3.7.0. diff --git a/doc/mkdocs/docs/api/basic_json/front.md b/doc/mkdocs/docs/api/basic_json/front.md index 55010fb85..af29def17 100644 --- a/doc/mkdocs/docs/api/basic_json/front.md +++ b/doc/mkdocs/docs/api/basic_json/front.md @@ -48,6 +48,10 @@ Constant. --8<-- "examples/front.output" ``` +## See also + +- [back](back.md) to access the last element + ## Version history - Added in version 1.0.0. diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 81227ccdf..f7c5dc4e3 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -3188,75 +3188,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return value(ptr, string_t(default_value)); } - /*! - @brief access the first element - - Returns a reference to the first element in the container. For a JSON - container `c`, the expression `c.front()` is equivalent to `*c.begin()`. - - @return In case of a structured type (array or object), a reference to the - first element is returned. In case of number, string, boolean, or binary - values, a reference to the value is returned. - - @complexity Constant. - - @pre The JSON value must not be `null` (would throw `std::out_of_range`) - or an empty array or object (undefined behavior, **guarded by - assertions**). - @post The JSON value remains unchanged. - - @throw invalid_iterator.214 when called on `null` value - - @liveexample{The following code shows an example for `front()`.,front} - - @sa see @ref back() -- access the last element - - @since version 1.0.0 - */ + /// @brief access the first element + /// @sa https://json.nlohmann.me/api/basic_json/front/ reference front() { return *begin(); } - /*! - @copydoc basic_json::front() - */ + /// @brief access the first element + /// @sa https://json.nlohmann.me/api/basic_json/front/ const_reference front() const { return *cbegin(); } - /*! - @brief access the last element - - Returns a reference to the last element in the container. For a JSON - container `c`, the expression `c.back()` is equivalent to - @code {.cpp} - auto tmp = c.end(); - --tmp; - return *tmp; - @endcode - - @return In case of a structured type (array or object), a reference to the - last element is returned. In case of number, string, boolean, or binary - values, a reference to the value is returned. - - @complexity Constant. - - @pre The JSON value must not be `null` (would throw `std::out_of_range`) - or an empty array or object (undefined behavior, **guarded by - assertions**). - @post The JSON value remains unchanged. - - @throw invalid_iterator.214 when called on a `null` value. See example - below. - - @liveexample{The following code shows an example for `back()`.,back} - - @sa see @ref front() -- access the first element - - @since version 1.0.0 - */ + /// @brief access the last element + /// @sa https://json.nlohmann.me/api/basic_json/back/ reference back() { auto tmp = end(); @@ -3264,9 +3211,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return *tmp; } - /*! - @copydoc basic_json::back() - */ + /// @brief access the last element + /// @sa https://json.nlohmann.me/api/basic_json/back/ const_reference back() const { auto tmp = cend(); @@ -3653,27 +3599,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return result; } - /*! - @brief returns the number of occurrences of a key in a JSON object - - Returns the number of elements with key @a key. If ObjectType is the - default `std::map` type, the return value will always be `0` (@a key was - not found) or `1` (@a key was found). - - @note This method always returns `0` when executed on a JSON type that is - not an object. - - @param[in] key key value of the element to count - - @return Number of elements with key @a key. If the JSON value is not an - object, the return value will be `0`. - - @complexity Logarithmic in the size of the JSON object. - - @liveexample{The example shows how `count()` is used.,count} - - @since version 1.0.0 - */ + /// @brief returns the number of occurrences of a key in a JSON object + /// @sa https://json.nlohmann.me/api/basic_json/count/ template size_type count(KeyT&& key) const { @@ -3681,31 +3608,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return is_object() ? m_value.object->count(std::forward(key)) : 0; } - /*! - @brief check the existence of an element in a JSON object - - Check whether an element exists in a JSON object with key equivalent to - @a key. If the element is not found or the JSON value is not an object, - false is returned. - - @note This method always returns false when executed on a JSON type - that is not an object. - - @param[in] key key value to check its existence. - - @return true if an element with specified @a key exists. If no such - element with such key is found or the JSON value is not an object, - false is returned. - - @complexity Logarithmic in the size of the JSON object. - - @liveexample{The following code shows an example for `contains()`.,contains} - - @sa see @ref find(KeyT&&) -- returns an iterator to an object element - @sa see @ref contains(const json_pointer&) const -- checks the existence for a JSON pointer - - @since version 3.6.0 - */ + /// @brief check the existence of an element in a JSON object + /// @sa https://json.nlohmann.me/api/basic_json/contains/ template < typename KeyT, typename std::enable_if < !std::is_same::type, json_pointer>::value, int >::type = 0 > bool contains(KeyT && key) const @@ -3713,32 +3617,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return is_object() && m_value.object->find(std::forward(key)) != m_value.object->end(); } - /*! - @brief check the existence of an element in a JSON object given a JSON pointer - - Check whether the given JSON pointer @a ptr can be resolved in the current - JSON value. - - @note This method can be executed on any JSON value type. - - @param[in] ptr JSON pointer to check its existence. - - @return true if the JSON pointer can be resolved to a stored value, false - otherwise. - - @post If `j.contains(ptr)` returns true, it is safe to call `j[ptr]`. - - @throw parse_error.106 if an array index begins with '0' - @throw parse_error.109 if an array index was not a number - - @complexity Logarithmic in the size of the JSON object. - - @liveexample{The following code shows an example for `contains()`.,contains_json_pointer} - - @sa see @ref contains(KeyT &&) const -- checks the existence of a key - - @since version 3.7.0 - */ + /// @brief check the existence of an element in a JSON object given a JSON pointer + /// @sa https://json.nlohmann.me/api/basic_json/contains/ bool contains(const json_pointer& ptr) const { return ptr.contains(this); diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 91765c7c8..c0c79c484 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -20675,75 +20675,22 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return value(ptr, string_t(default_value)); } - /*! - @brief access the first element - - Returns a reference to the first element in the container. For a JSON - container `c`, the expression `c.front()` is equivalent to `*c.begin()`. - - @return In case of a structured type (array or object), a reference to the - first element is returned. In case of number, string, boolean, or binary - values, a reference to the value is returned. - - @complexity Constant. - - @pre The JSON value must not be `null` (would throw `std::out_of_range`) - or an empty array or object (undefined behavior, **guarded by - assertions**). - @post The JSON value remains unchanged. - - @throw invalid_iterator.214 when called on `null` value - - @liveexample{The following code shows an example for `front()`.,front} - - @sa see @ref back() -- access the last element - - @since version 1.0.0 - */ + /// @brief access the first element + /// @sa https://json.nlohmann.me/api/basic_json/front/ reference front() { return *begin(); } - /*! - @copydoc basic_json::front() - */ + /// @brief access the first element + /// @sa https://json.nlohmann.me/api/basic_json/front/ const_reference front() const { return *cbegin(); } - /*! - @brief access the last element - - Returns a reference to the last element in the container. For a JSON - container `c`, the expression `c.back()` is equivalent to - @code {.cpp} - auto tmp = c.end(); - --tmp; - return *tmp; - @endcode - - @return In case of a structured type (array or object), a reference to the - last element is returned. In case of number, string, boolean, or binary - values, a reference to the value is returned. - - @complexity Constant. - - @pre The JSON value must not be `null` (would throw `std::out_of_range`) - or an empty array or object (undefined behavior, **guarded by - assertions**). - @post The JSON value remains unchanged. - - @throw invalid_iterator.214 when called on a `null` value. See example - below. - - @liveexample{The following code shows an example for `back()`.,back} - - @sa see @ref front() -- access the first element - - @since version 1.0.0 - */ + /// @brief access the last element + /// @sa https://json.nlohmann.me/api/basic_json/back/ reference back() { auto tmp = end(); @@ -20751,9 +20698,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return *tmp; } - /*! - @copydoc basic_json::back() - */ + /// @brief access the last element + /// @sa https://json.nlohmann.me/api/basic_json/back/ const_reference back() const { auto tmp = cend(); @@ -21140,27 +21086,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return result; } - /*! - @brief returns the number of occurrences of a key in a JSON object - - Returns the number of elements with key @a key. If ObjectType is the - default `std::map` type, the return value will always be `0` (@a key was - not found) or `1` (@a key was found). - - @note This method always returns `0` when executed on a JSON type that is - not an object. - - @param[in] key key value of the element to count - - @return Number of elements with key @a key. If the JSON value is not an - object, the return value will be `0`. - - @complexity Logarithmic in the size of the JSON object. - - @liveexample{The example shows how `count()` is used.,count} - - @since version 1.0.0 - */ + /// @brief returns the number of occurrences of a key in a JSON object + /// @sa https://json.nlohmann.me/api/basic_json/count/ template size_type count(KeyT&& key) const { @@ -21168,31 +21095,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return is_object() ? m_value.object->count(std::forward(key)) : 0; } - /*! - @brief check the existence of an element in a JSON object - - Check whether an element exists in a JSON object with key equivalent to - @a key. If the element is not found or the JSON value is not an object, - false is returned. - - @note This method always returns false when executed on a JSON type - that is not an object. - - @param[in] key key value to check its existence. - - @return true if an element with specified @a key exists. If no such - element with such key is found or the JSON value is not an object, - false is returned. - - @complexity Logarithmic in the size of the JSON object. - - @liveexample{The following code shows an example for `contains()`.,contains} - - @sa see @ref find(KeyT&&) -- returns an iterator to an object element - @sa see @ref contains(const json_pointer&) const -- checks the existence for a JSON pointer - - @since version 3.6.0 - */ + /// @brief check the existence of an element in a JSON object + /// @sa https://json.nlohmann.me/api/basic_json/contains/ template < typename KeyT, typename std::enable_if < !std::is_same::type, json_pointer>::value, int >::type = 0 > bool contains(KeyT && key) const @@ -21200,32 +21104,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return is_object() && m_value.object->find(std::forward(key)) != m_value.object->end(); } - /*! - @brief check the existence of an element in a JSON object given a JSON pointer - - Check whether the given JSON pointer @a ptr can be resolved in the current - JSON value. - - @note This method can be executed on any JSON value type. - - @param[in] ptr JSON pointer to check its existence. - - @return true if the JSON pointer can be resolved to a stored value, false - otherwise. - - @post If `j.contains(ptr)` returns true, it is safe to call `j[ptr]`. - - @throw parse_error.106 if an array index begins with '0' - @throw parse_error.109 if an array index was not a number - - @complexity Logarithmic in the size of the JSON object. - - @liveexample{The following code shows an example for `contains()`.,contains_json_pointer} - - @sa see @ref contains(KeyT &&) const -- checks the existence of a key - - @since version 3.7.0 - */ + /// @brief check the existence of an element in a JSON object given a JSON pointer + /// @sa https://json.nlohmann.me/api/basic_json/contains/ bool contains(const json_pointer& ptr) const { return ptr.contains(this);