Niels Lohmann
7b755737b4
From gregmarr's review of #5622: - count() counts every member with the key, so count(key) > 1 detects duplicate keys; it was contains() as 0/1 before. - get_to() passes types that get<T>() does not convert directly to from_json with the existing value, as basic_json::get_to() does, so that a from_json which sets only the fields present keeps the others. - array_index() checks the empty token and "-" first; the results are unchanged. - Docs: no "if an exception is thrown" where a view never changes anything; the borrowed source must also stay unmodified; items() on a temporary view is safe; back()/front() notes shortened; the basic_json see-also entries say how the view's results can differ. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.1 KiB
nlohmann::basic_json_view::items
/* unspecified */ items() const noexcept;
Returns a range of items -- (key, value) pairs -- for use in range-based for loops. An item's #!cpp key() is a
#!cpp string_view_t (for an array element, its index converted to a string, as for
BasicJsonType::items()), and its #!cpp value() is a basic_json_view of the element.
The returned type is not part of the public API and may change between versions; use a range-based for loop (see the
example), or #!cpp decltype(v.items()) if you need to name it.
for (const auto& item : v.items())
{
std::cout << "key: " << item.key() << ", value: " << item.value() << '\n';
}
On C++17, item also supports structured bindings:
for (const auto [key, value] : v.items())
{
std::cout << "key: " << key << ", value: " << value << '\n';
}
Note the #!cpp const auto (by value), not #!cpp const auto&: unlike BasicJsonType::items(), whose elements are
references into an existing object, a view's item is produced on the fly for each step of the iteration, so there
is nothing for a reference to bind to.
Return value
A range whose iterators dereference to an item (with #!cpp key() and #!cpp value(), see above) and whose
#!cpp begin()/#!cpp end() are equivalent to basic_json_view::begin()/end(), in document order.
Exception safety
No-throw guarantee: this function never throws exceptions.
Complexity
Constant.
Notes
As for begin()/end(), items() visits every member of an object, including all
occurrences of a duplicate key -- unlike operator[], at, find,
and contains, which resolve to the first member with a given key. See the
Notes on duplicate keys of operator[].
!!! danger "Lifetime issues"
Unlike `BasicJsonType::items()` (see [#2040](https://github.com/nlohmann/json/issues/2040)), calling `items()` on
a temporary view is safe, for instance `#!cpp for (auto item : v["a"].items())`: the returned range holds a copy
of the view. What must outlive the loop is the document and, for a borrowed document, the source buffer.
Examples
??? example
The example below shows a settings object whose source text records every update to a key as a duplicate
member, in the order they happened. `items()` walks all of them, so the update history is visible, while
[`operator[]`](operator[].md) only ever sees the *first* one and [`materialize()`](materialize.md) -- like
[`BasicJsonType::parse()`](../basic_json/parse.md) -- keeps only the *last*.
```cpp
--8<-- "examples/basic_json_view__items.cpp"
```
Output:
```json
--8<-- "examples/basic_json_view__items.output"
```
See also
- begin, end - the iterators
items()is built on BasicJsonType::items- the corresponding function ofbasic_json
Version history
- Added in version 3.13.0.