nlohmann::basic_json::items¶

iteration_proxy<iterator> items() noexcept;
iteration_proxy<const_iterator> items() const noexcept;

This function allows accessing iterator::key() and 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:

for (auto it = j_object.begin(); it != j_object.end(); ++it)
{
    std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
}

Range-based for loop without items() function:

for (auto it : j_object)
{
    // "it" is of type json::reference and has no key() member
    std::cout << "value: " << it << '\n';
}

Range-based for loop with items() function:

for (auto& el : j_object.items())
{
    std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
}

The items() function also allows using structured bindings (C++17):

for (auto& [key, val] : j_object.items())
{
    std::cout << "key: " << key << ", value:" << val << '\n';
}

Return value¶

iteration proxy object wrapping the current value with an interface to use in range-based for loops

Exception safety¶

Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

Complexity¶

Constant.

Notes¶

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.

Examples¶

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

using json = nlohmann::json;

int main()
{
    // create JSON values
    json j_object = {{"one", 1}, {"two", 2}};
    json j_array = {1, 2, 4, 8, 16};

    // example for an object
    for (auto& x : j_object.items())
    {
        std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
    }

    // example for an array
    for (auto& x : j_array.items())
    {
        std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
    }
}

key: one, value: 1
key: two, value: 2
key: 0, value: 1
key: 1, value: 2
key: 2, value: 4
key: 3, value: 8
key: 4, value: 16

Version history¶

• 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.