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 key() is a string_view_t (for an array element, its index converted to a string, as for BasicJsonType::items()), and its 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 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 const auto (by value), not 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 key() and value(), see above) and whose begin()/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[].

Lifetime issues

Unlike BasicJsonType::items() (see #2040), calling items() on a temporary view is safe, for instance 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[] only ever sees the first one and materialize() -- like BasicJsonType::parse() -- keeps only the last.

#include <iostream>
#include <nlohmann/json_view.hpp>

using json_document = nlohmann::json_document;

int main()
{
    // a settings object whose source text records every update to a key as
    // a duplicate member. items() visits all of them, in document order, so
    // the update history is visible; operator[] only ever sees the first
    // one, and materialize() -- like basic_json::parse() -- keeps the last
    json_document updates = json_document::parse(R"({"retries": 1, "timeout": 30, "retries": 5})");
    const auto settings = updates.root();

    for (const auto& item : settings.items())
    {
        std::cout << item.key() << '=' << item.value().materialize().dump() << '\n';
    }

    std::cout << "first \"retries\" seen by operator[]: " << settings["retries"].materialize().dump() << '\n';
    std::cout << "last \"retries\" kept by materialize(): " << settings.materialize()["retries"].dump() << '\n';
}

Output:

retries=1
timeout=30
retries=5
first "retries" seen by operator[]: 1
last "retries" kept by materialize(): 5

Version history¶

Added in version 3.13.0 unreleased.