nlohmann::basic_json_view::find¶

iterator find(string_view_t key) const;
iterator find(const char* key) const;
iterator find(const string_t& key) const;

Finds a member with key key -- the first one, should the key occur more than once (see Notes on duplicate keys). If the value is not an object, or no member has this key, end() is returned.

Parameters¶

key (in): key value of the element to search for

Return value¶

An iterator to the member with key key, or end() if there is none or the value is not an object.

Exception safety¶

No-throw guarantee: this function never throws exceptions.

Complexity¶

Linear in the number of members: as for ordered_json, members are compared one after another, in document order, stopping at the first match. Each comparison first checks the key's length -- already known from the index, without reading the key bytes -- before comparing its content. Objects with 128 or more members get a hash index of their keys while parsing, so that a lookup in them takes constant time on average.

Notes¶

Duplicate keys: the first member wins

If the source text repeats a key, this resolves to the first member with it, not to the last one that materialize() and parse() keep. See the Notes on duplicate keys of operator[] and Duplicate keys for the reasons and for how to get the last value.

Unlike BasicJsonType::find, which always returns end() for a non-object type, this also does so for a discarded view -- there is no separate "invalid" iterator to return.

Examples¶

Example

The example below scans a batch of events for those that carry an optional user_id field, using find() instead of operator[] (which would throw for the events that are not objects at all) or contains() followed by a second lookup. Events without a match are never materialized.

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

using json_document = nlohmann::json_document;

int main()
{
    // a batch of incoming events; only some carry a "user_id" -- find()
    // locates it without throwing for the events that turn out to not be
    // objects, and without materializing an event that does not match
    json_document batch = json_document::parse(R"(
      [
        {"type": "click", "user_id": 42},
        {"type": "ping"},
        {"type": "click", "user_id": 7}
      ]
    )");

    const auto events = batch.root();
    for (std::size_t i = 0; i < events.size(); ++i)
    {
        const auto event = events[i];
        const auto it = event.find("user_id");
        if (it != event.end())
        {
            std::cout << "user " << it->materialize().dump() << '\n';
        }
    }
}

Output:

user 42
user 7

Version history¶

Added in version 3.13.0 unreleased.