5a9f59a688
- API pages for operator[], at, front, back, find, contains, count, begin, end, cbegin, cend, items, and type_name of basic_json_view, linked both ways with the basic_json pages - the feature page and size() describe document order and duplicate keys - the examples show when the view helps: reading a few fields of a large text, probing optional members, and members in source order Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.0 KiB
nlohmann::basic_json_view::items
/* unspecified */ items() const noexcept;
Returns a range of item values -- (key, value) pairs -- for use in range-based for loops.
The key of an array element is its index, converted to a string, as for
BasicJsonType::items().
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 item 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,
contains, and count, which resolve to the first member with a given key. See the
Notes on duplicate keys of operator[].
!!! danger "Lifetime issues"
As for `BasicJsonType::items()`, calling `items()` on a temporary view (or a temporary document) is dangerous:
the range refers back to the document, so the document must outlive the loop. See
[#2040](https://github.com/nlohmann/json/issues/2040) for the `BasicJsonType` background.
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.