External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

🔥 consolidate documentation

Browse Source
This commit is contained in:
Niels Lohmann 2021-10-13 21:44:34 +02:00
parent 13d4e6bcf9
commit 0b02eb0dfb
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
5 changed files with 77 additions and 716 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/mkdocs/docs/api/basic_json/crend.md
View File

@ -1,4 +1,4 @@
# basic_json::rend # basic_json::crend
```cpp ```cpp
const_reverse_iterator crend() const noexcept; const_reverse_iterator crend() const noexcept;

4
doc/mkdocs/docs/api/basic_json/find.md
View File

@ -54,6 +54,10 @@ This method always returns `end()` when executed on a JSON type that is not an o
--8<-- "examples/find__key_type.output" --8<-- "examples/find__key_type.output"
``` ```
## See also
- [contains](contains.md) checks whether a key exists
## Version history ## Version history
- Added in version 1.0.0. - Added in version 1.0.0.

3
doc/mkdocs/docs/api/basic_json/items.md
View File

@ -86,7 +86,8 @@ When iterating over an array, `key()` will return the index of the element as st
## Version history ## Version history
- Added in version 3.0.0. - Added `iterator_wrapper` in version 3.0.0.
- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
- Added structured binding support in version 3.5.0. - Added structured binding support in version 3.5.0.
!!! note !!! note

392
include/nlohmann/json.hpp
View File

@ -3054,30 +3054,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// @name lookup /// @name lookup
/// @{ /// @{
/*! /// @brief find an element in a JSON object
@brief find an element in a JSON object /// @sa https://json.nlohmann.me/api/basic_json/find/
Finds an element in a JSON object with key equivalent to @a key. If the
element is not found or the JSON value is not an object, end() is
returned.
@note This method always returns @ref end() when executed on a JSON type
that is not an object.
@param[in] key key value of the element to search for.
@return Iterator to an element with key equivalent to @a key. If no such
element is found or the JSON value is not an object, past-the-end (see
@ref end()) iterator is returned.
@complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how `find()` is used.,find__key_type}
@sa see @ref contains(KeyT&&) const -- checks whether a key exists
@since version 1.0.0
*/
template<typename KeyT> template<typename KeyT>
iterator find(KeyT&& key) iterator find(KeyT&& key)
{ {
@ -3091,10 +3069,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief find an element in a JSON object
@brief find an element in a JSON object /// @sa https://json.nlohmann.me/api/basic_json/find/
@copydoc find(KeyT&&)
*/
template<typename KeyT> template<typename KeyT>
const_iterator find(KeyT&& key) const const_iterator find(KeyT&& key) const
{ {
@ -3143,30 +3119,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// @name iterators /// @name iterators
/// @{ /// @{
/*! /// @brief returns an iterator to the first element
@brief returns an iterator to the first element /// @sa https://json.nlohmann.me/api/basic_json/begin/
Returns an iterator to the first element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return iterator to the first element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
@liveexample{The following code shows an example for `begin()`.,begin}
@sa see @ref cbegin() -- returns a const iterator to the beginning
@sa see @ref end() -- returns an iterator to the end
@sa see @ref cend() -- returns a const iterator to the end
@since version 1.0.0
*/
iterator begin() noexcept iterator begin() noexcept
{ {
iterator result(this); iterator result(this);
@ -3174,39 +3128,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to the first element
@copydoc basic_json::cbegin() /// @sa https://json.nlohmann.me/api/basic_json/begin/
*/
const_iterator begin() const noexcept const_iterator begin() const noexcept
{ {
return cbegin(); return cbegin();
} }
/*! /// @brief returns a const iterator to the first element
@brief returns a const iterator to the first element /// @sa https://json.nlohmann.me/api/basic_json/cbegin/
Returns a const iterator to the first element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return const iterator to the first element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
@liveexample{The following code shows an example for `cbegin()`.,cbegin}
@sa see @ref begin() -- returns an iterator to the beginning
@sa see @ref end() -- returns an iterator to the end
@sa see @ref cend() -- returns a const iterator to the end
@since version 1.0.0
*/
const_iterator cbegin() const noexcept const_iterator cbegin() const noexcept
{ {
const_iterator result(this); const_iterator result(this);
@ -3214,30 +3144,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to one past the last element
@brief returns an iterator to one past the last element /// @sa https://json.nlohmann.me/api/basic_json/end/
Returns an iterator to one past the last element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return iterator one past the last element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
@liveexample{The following code shows an example for `end()`.,end}
@sa see @ref cend() -- returns a const iterator to the end
@sa see @ref begin() -- returns an iterator to the beginning
@sa see @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0
*/
iterator end() noexcept iterator end() noexcept
{ {
iterator result(this); iterator result(this);
@ -3245,39 +3153,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to one past the last element
@copydoc basic_json::cend() /// @sa https://json.nlohmann.me/api/basic_json/end/
*/
const_iterator end() const noexcept const_iterator end() const noexcept
{ {
return cend(); return cend();
} }
/*! /// @brief returns an iterator to one past the last element
@brief returns a const iterator to one past the last element /// @sa https://json.nlohmann.me/api/basic_json/cend/
Returns a const iterator to one past the last element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return const iterator one past the last element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).end()`.
@liveexample{The following code shows an example for `cend()`.,cend}
@sa see @ref end() -- returns an iterator to the end
@sa see @ref begin() -- returns an iterator to the beginning
@sa see @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0
*/
const_iterator cend() const noexcept const_iterator cend() const noexcept
{ {
const_iterator result(this); const_iterator result(this);
@ -3285,132 +3169,43 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to the reverse-beginning
@brief returns an iterator to the reverse-beginning /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
Returns an iterator to the reverse-beginning; that is, the last element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `reverse_iterator(end())`.
@liveexample{The following code shows an example for `rbegin()`.,rbegin}
@sa see @ref crbegin() -- returns a const reverse iterator to the beginning
@sa see @ref rend() -- returns a reverse iterator to the end
@sa see @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0
*/
reverse_iterator rbegin() noexcept reverse_iterator rbegin() noexcept
{ {
return reverse_iterator(end()); return reverse_iterator(end());
} }
/*! /// @brief returns an iterator to the reverse-beginning
@copydoc basic_json::crbegin() /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
*/
const_reverse_iterator rbegin() const noexcept const_reverse_iterator rbegin() const noexcept
{ {
return crbegin(); return crbegin();
} }
/*! /// @brief returns an iterator to the reverse-end
@brief returns an iterator to the reverse-end /// @sa https://json.nlohmann.me/api/basic_json/rend/
Returns an iterator to the reverse-end; that is, one before the first
element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `reverse_iterator(begin())`.
@liveexample{The following code shows an example for `rend()`.,rend}
@sa see @ref crend() -- returns a const reverse iterator to the end
@sa see @ref rbegin() -- returns a reverse iterator to the beginning
@sa see @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0
*/
reverse_iterator rend() noexcept reverse_iterator rend() noexcept
{ {
return reverse_iterator(begin()); return reverse_iterator(begin());
} }
/*! /// @brief returns an iterator to the reverse-end
@copydoc basic_json::crend() /// @sa https://json.nlohmann.me/api/basic_json/rend/
*/
const_reverse_iterator rend() const noexcept const_reverse_iterator rend() const noexcept
{ {
return crend(); return crend();
} }
/*! /// @brief returns a const reverse iterator to the last element
@brief returns a const reverse iterator to the last element /// @sa https://json.nlohmann.me/api/basic_json/crbegin/
Returns a const iterator to the reverse-beginning; that is, the last
element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
@liveexample{The following code shows an example for `crbegin()`.,crbegin}
@sa see @ref rbegin() -- returns a reverse iterator to the beginning
@sa see @ref rend() -- returns a reverse iterator to the end
@sa see @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0
*/
const_reverse_iterator crbegin() const noexcept const_reverse_iterator crbegin() const noexcept
{ {
return const_reverse_iterator(cend()); return const_reverse_iterator(cend());
} }
/*! /// @brief returns a const reverse iterator to one before the first
@brief returns a const reverse iterator to one before the first /// @sa https://json.nlohmann.me/api/basic_json/crend/
Returns a const reverse iterator to the reverse-end; that is, one before
the first element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
@liveexample{The following code shows an example for `crend()`.,crend}
@sa see @ref rend() -- returns a reverse iterator to the end
@sa see @ref rbegin() -- returns a reverse iterator to the beginning
@sa see @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0
*/
const_reverse_iterator crend() const noexcept const_reverse_iterator crend() const noexcept
{ {
return const_reverse_iterator(cbegin()); return const_reverse_iterator(cbegin());
@ -3419,59 +3214,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
public: public:
/*! /*!
@brief wrapper to access iterator member functions in range-based for @brief wrapper to access iterator member functions in range-based for
@sa https://json.nlohmann.me/api/basic_json/items/
This function allows to access @ref iterator::key() and @ref @deprecated This function is deprecated since 3.1.0 and will be removed in
iterator::value() during range-based for loops. In these loops, a version 4.0.0 of the library. Please use @ref items() instead;
reference to the JSON values is returned, so there is no access to the
underlying iterator.
For loop without iterator_wrapper:
@code{cpp}
for (auto it = j_object.begin(); it != j_object.end(); ++it)
{
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}
@endcode
Range-based for loop without iterator proxy:
@code{cpp}
for (auto it : j_object)
{
// "it" is of type json::reference and has no key() member
std::cout << "value: " << it << '\n';
}
@endcode
Range-based for loop with iterator proxy:
@code{cpp}
for (auto it : json::iterator_wrapper(j_object))
{
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}
@endcode
@note When iterating over an array, `key()` will return the index of the
element as string (see example).
@param[in] ref reference to a JSON value
@return iteration proxy object wrapping @a ref with an interface to use in
range-based for loops
@liveexample{The following code shows how the wrapper is used,iterator_wrapper}
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@note The name of this function is not yet final and may change in the
future.
@deprecated This stream operator is deprecated and will be removed in
future 4.0.0 of the library. Please use @ref items() instead;
that is, replace `json::iterator_wrapper(j)` with `j.items()`. that is, replace `json::iterator_wrapper(j)` with `j.items()`.
*/ */
JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items()) JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items())
@ -3489,82 +3234,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return ref.items(); return ref.items();
} }
/*! /// @brief helper to access iterator member functions in range-based for
@brief helper to access iterator member functions in range-based for /// @sa https://json.nlohmann.me/api/basic_json/items/
This function allows to access @ref iterator::key() and @ref
iterator::value() during range-based for loops. In these loops, a
reference to the JSON values is returned, so there is no access to the
underlying iterator.
For loop without `items()` function:
@code{cpp}
for (auto it = j_object.begin(); it != j_object.end(); ++it)
{
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}
@endcode
Range-based for loop without `items()` function:
@code{cpp}
for (auto it : j_object)
{
// "it" is of type json::reference and has no key() member
std::cout << "value: " << it << '\n';
}
@endcode
Range-based for loop with `items()` function:
@code{cpp}
for (auto& el : j_object.items())
{
std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
}
@endcode
The `items()` function also allows to use
[structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding)
(C++17):
@code{cpp}
for (auto& [key, val] : j_object.items())
{
std::cout << "key: " << key << ", value:" << val << '\n';
}
@endcode
@note When iterating over an array, `key()` will return the index of the
element as string (see example). For primitive types (e.g., numbers),
`key()` returns an empty string.
@warning Using `items()` on temporary objects is dangerous. Make sure the
object's lifetime exeeds the iteration. See
<https://github.com/nlohmann/json/issues/2040> for more
information.
@return iteration proxy object wrapping @a ref with an interface to use in
range-based for loops
@liveexample{The following code shows how the function is used.,items}
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 3.1.0, structured bindings support since 3.5.0.
*/
iteration_proxy<iterator> items() noexcept iteration_proxy<iterator> items() noexcept
{ {
return iteration_proxy<iterator>(*this); return iteration_proxy<iterator>(*this);
} }
/*! /// @brief helper to access iterator member functions in range-based for
@copydoc items() /// @sa https://json.nlohmann.me/api/basic_json/items/
*/
iteration_proxy<const_iterator> items() const noexcept iteration_proxy<const_iterator> items() const noexcept
{ {
return iteration_proxy<const_iterator>(*this); return iteration_proxy<const_iterator>(*this);

392
single_include/nlohmann/json.hpp
View File

@ -20541,30 +20541,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// @name lookup /// @name lookup
/// @{ /// @{
/*! /// @brief find an element in a JSON object
@brief find an element in a JSON object /// @sa https://json.nlohmann.me/api/basic_json/find/
Finds an element in a JSON object with key equivalent to @a key. If the
element is not found or the JSON value is not an object, end() is
returned.
@note This method always returns @ref end() when executed on a JSON type
that is not an object.
@param[in] key key value of the element to search for.
@return Iterator to an element with key equivalent to @a key. If no such
element is found or the JSON value is not an object, past-the-end (see
@ref end()) iterator is returned.
@complexity Logarithmic in the size of the JSON object.
@liveexample{The example shows how `find()` is used.,find__key_type}
@sa see @ref contains(KeyT&&) const -- checks whether a key exists
@since version 1.0.0
*/
template<typename KeyT> template<typename KeyT>
iterator find(KeyT&& key) iterator find(KeyT&& key)
{ {
@ -20578,10 +20556,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief find an element in a JSON object
@brief find an element in a JSON object /// @sa https://json.nlohmann.me/api/basic_json/find/
@copydoc find(KeyT&&)
*/
template<typename KeyT> template<typename KeyT>
const_iterator find(KeyT&& key) const const_iterator find(KeyT&& key) const
{ {
@ -20630,30 +20606,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
/// @name iterators /// @name iterators
/// @{ /// @{
/*! /// @brief returns an iterator to the first element
@brief returns an iterator to the first element /// @sa https://json.nlohmann.me/api/basic_json/begin/
Returns an iterator to the first element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return iterator to the first element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
@liveexample{The following code shows an example for `begin()`.,begin}
@sa see @ref cbegin() -- returns a const iterator to the beginning
@sa see @ref end() -- returns an iterator to the end
@sa see @ref cend() -- returns a const iterator to the end
@since version 1.0.0
*/
iterator begin() noexcept iterator begin() noexcept
{ {
iterator result(this); iterator result(this);
@ -20661,39 +20615,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to the first element
@copydoc basic_json::cbegin() /// @sa https://json.nlohmann.me/api/basic_json/begin/
*/
const_iterator begin() const noexcept const_iterator begin() const noexcept
{ {
return cbegin(); return cbegin();
} }
/*! /// @brief returns a const iterator to the first element
@brief returns a const iterator to the first element /// @sa https://json.nlohmann.me/api/basic_json/cbegin/
Returns a const iterator to the first element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return const iterator to the first element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).begin()`.
@liveexample{The following code shows an example for `cbegin()`.,cbegin}
@sa see @ref begin() -- returns an iterator to the beginning
@sa see @ref end() -- returns an iterator to the end
@sa see @ref cend() -- returns a const iterator to the end
@since version 1.0.0
*/
const_iterator cbegin() const noexcept const_iterator cbegin() const noexcept
{ {
const_iterator result(this); const_iterator result(this);
@ -20701,30 +20631,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to one past the last element
@brief returns an iterator to one past the last element /// @sa https://json.nlohmann.me/api/basic_json/end/
Returns an iterator to one past the last element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return iterator one past the last element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
@liveexample{The following code shows an example for `end()`.,end}
@sa see @ref cend() -- returns a const iterator to the end
@sa see @ref begin() -- returns an iterator to the beginning
@sa see @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0
*/
iterator end() noexcept iterator end() noexcept
{ {
iterator result(this); iterator result(this);
@ -20732,39 +20640,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to one past the last element
@copydoc basic_json::cend() /// @sa https://json.nlohmann.me/api/basic_json/end/
*/
const_iterator end() const noexcept const_iterator end() const noexcept
{ {
return cend(); return cend();
} }
/*! /// @brief returns an iterator to one past the last element
@brief returns a const iterator to one past the last element /// @sa https://json.nlohmann.me/api/basic_json/cend/
Returns a const iterator to one past the last element.
@image html range-begin-end.svg "Illustration from cppreference.com"
@return const iterator one past the last element
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[Container](https://en.cppreference.com/w/cpp/named_req/Container)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).end()`.
@liveexample{The following code shows an example for `cend()`.,cend}
@sa see @ref end() -- returns an iterator to the end
@sa see @ref begin() -- returns an iterator to the beginning
@sa see @ref cbegin() -- returns a const iterator to the beginning
@since version 1.0.0
*/
const_iterator cend() const noexcept const_iterator cend() const noexcept
{ {
const_iterator result(this); const_iterator result(this);
@ -20772,132 +20656,43 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return result; return result;
} }
/*! /// @brief returns an iterator to the reverse-beginning
@brief returns an iterator to the reverse-beginning /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
Returns an iterator to the reverse-beginning; that is, the last element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `reverse_iterator(end())`.
@liveexample{The following code shows an example for `rbegin()`.,rbegin}
@sa see @ref crbegin() -- returns a const reverse iterator to the beginning
@sa see @ref rend() -- returns a reverse iterator to the end
@sa see @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0
*/
reverse_iterator rbegin() noexcept reverse_iterator rbegin() noexcept
{ {
return reverse_iterator(end()); return reverse_iterator(end());
} }
/*! /// @brief returns an iterator to the reverse-beginning
@copydoc basic_json::crbegin() /// @sa https://json.nlohmann.me/api/basic_json/rbegin/
*/
const_reverse_iterator rbegin() const noexcept const_reverse_iterator rbegin() const noexcept
{ {
return crbegin(); return crbegin();
} }
/*! /// @brief returns an iterator to the reverse-end
@brief returns an iterator to the reverse-end /// @sa https://json.nlohmann.me/api/basic_json/rend/
Returns an iterator to the reverse-end; that is, one before the first
element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `reverse_iterator(begin())`.
@liveexample{The following code shows an example for `rend()`.,rend}
@sa see @ref crend() -- returns a const reverse iterator to the end
@sa see @ref rbegin() -- returns a reverse iterator to the beginning
@sa see @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0
*/
reverse_iterator rend() noexcept reverse_iterator rend() noexcept
{ {
return reverse_iterator(begin()); return reverse_iterator(begin());
} }
/*! /// @brief returns an iterator to the reverse-end
@copydoc basic_json::crend() /// @sa https://json.nlohmann.me/api/basic_json/rend/
*/
const_reverse_iterator rend() const noexcept const_reverse_iterator rend() const noexcept
{ {
return crend(); return crend();
} }
/*! /// @brief returns a const reverse iterator to the last element
@brief returns a const reverse iterator to the last element /// @sa https://json.nlohmann.me/api/basic_json/crbegin/
Returns a const iterator to the reverse-beginning; that is, the last
element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rbegin()`.
@liveexample{The following code shows an example for `crbegin()`.,crbegin}
@sa see @ref rbegin() -- returns a reverse iterator to the beginning
@sa see @ref rend() -- returns a reverse iterator to the end
@sa see @ref crend() -- returns a const reverse iterator to the end
@since version 1.0.0
*/
const_reverse_iterator crbegin() const noexcept const_reverse_iterator crbegin() const noexcept
{ {
return const_reverse_iterator(cend()); return const_reverse_iterator(cend());
} }
/*! /// @brief returns a const reverse iterator to one before the first
@brief returns a const reverse iterator to one before the first /// @sa https://json.nlohmann.me/api/basic_json/crend/
Returns a const reverse iterator to the reverse-end; that is, one before
the first element.
@image html range-rbegin-rend.svg "Illustration from cppreference.com"
@complexity Constant.
@requirement This function helps `basic_json` satisfying the
[ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)
requirements:
- The complexity is constant.
- Has the semantics of `const_cast<const basic_json&>(*this).rend()`.
@liveexample{The following code shows an example for `crend()`.,crend}
@sa see @ref rend() -- returns a reverse iterator to the end
@sa see @ref rbegin() -- returns a reverse iterator to the beginning
@sa see @ref crbegin() -- returns a const reverse iterator to the beginning
@since version 1.0.0
*/
const_reverse_iterator crend() const noexcept const_reverse_iterator crend() const noexcept
{ {
return const_reverse_iterator(cbegin()); return const_reverse_iterator(cbegin());
@ -20906,59 +20701,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
public: public:
/*! /*!
@brief wrapper to access iterator member functions in range-based for @brief wrapper to access iterator member functions in range-based for
@sa https://json.nlohmann.me/api/basic_json/items/
This function allows to access @ref iterator::key() and @ref @deprecated This function is deprecated since 3.1.0 and will be removed in
iterator::value() during range-based for loops. In these loops, a version 4.0.0 of the library. Please use @ref items() instead;
reference to the JSON values is returned, so there is no access to the
underlying iterator.
For loop without iterator_wrapper:
@code{cpp}
for (auto it = j_object.begin(); it != j_object.end(); ++it)
{
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}
@endcode
Range-based for loop without iterator proxy:
@code{cpp}
for (auto it : j_object)
{
// "it" is of type json::reference and has no key() member
std::cout << "value: " << it << '\n';
}
@endcode
Range-based for loop with iterator proxy:
@code{cpp}
for (auto it : json::iterator_wrapper(j_object))
{
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}
@endcode
@note When iterating over an array, `key()` will return the index of the
element as string (see example).
@param[in] ref reference to a JSON value
@return iteration proxy object wrapping @a ref with an interface to use in
range-based for loops
@liveexample{The following code shows how the wrapper is used,iterator_wrapper}
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@note The name of this function is not yet final and may change in the
future.
@deprecated This stream operator is deprecated and will be removed in
future 4.0.0 of the library. Please use @ref items() instead;
that is, replace `json::iterator_wrapper(j)` with `j.items()`. that is, replace `json::iterator_wrapper(j)` with `j.items()`.
*/ */
JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items()) JSON_HEDLEY_DEPRECATED_FOR(3.1.0, items())
@ -20976,82 +20721,15 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
return ref.items(); return ref.items();
} }
/*! /// @brief helper to access iterator member functions in range-based for
@brief helper to access iterator member functions in range-based for /// @sa https://json.nlohmann.me/api/basic_json/items/
This function allows to access @ref iterator::key() and @ref
iterator::value() during range-based for loops. In these loops, a
reference to the JSON values is returned, so there is no access to the
underlying iterator.
For loop without `items()` function:
@code{cpp}
for (auto it = j_object.begin(); it != j_object.end(); ++it)
{
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}
@endcode
Range-based for loop without `items()` function:
@code{cpp}
for (auto it : j_object)
{
// "it" is of type json::reference and has no key() member
std::cout << "value: " << it << '\n';
}
@endcode
Range-based for loop with `items()` function:
@code{cpp}
for (auto& el : j_object.items())
{
std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
}
@endcode
The `items()` function also allows to use
[structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding)
(C++17):
@code{cpp}
for (auto& [key, val] : j_object.items())
{
std::cout << "key: " << key << ", value:" << val << '\n';
}
@endcode
@note When iterating over an array, `key()` will return the index of the
element as string (see example). For primitive types (e.g., numbers),
`key()` returns an empty string.
@warning Using `items()` on temporary objects is dangerous. Make sure the
object's lifetime exeeds the iteration. See
<https://github.com/nlohmann/json/issues/2040> for more
information.
@return iteration proxy object wrapping @a ref with an interface to use in
range-based for loops
@liveexample{The following code shows how the function is used.,items}
@exceptionsafety Strong guarantee: if an exception is thrown, there are no
changes in the JSON value.
@complexity Constant.
@since version 3.1.0, structured bindings support since 3.5.0.
*/
iteration_proxy<iterator> items() noexcept iteration_proxy<iterator> items() noexcept
{ {
return iteration_proxy<iterator>(*this); return iteration_proxy<iterator>(*this);
} }
/*! /// @brief helper to access iterator member functions in range-based for
@copydoc items() /// @sa https://json.nlohmann.me/api/basic_json/items/
*/
iteration_proxy<const_iterator> items() const noexcept iteration_proxy<const_iterator> items() const noexcept
{ {
return iteration_proxy<const_iterator>(*this); return iteration_proxy<const_iterator>(*this);