deploy: 4155e2938f

api/basic_json_view/find/index.md

@@ -0,0 +1,88 @@
+# 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](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/#notes)). If the value is not an object, or no member has this key, [`end()`](https://json.nlohmann.me/api/basic_json_view/end/index.md) 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()`](https://json.nlohmann.me/api/basic_json_view/end/index.md) 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`](https://json.nlohmann.me/api/ordered_json/index.md), 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()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) and `parse()` keep. See the [Notes on duplicate keys](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/#notes) of `operator[]` and [Duplicate keys](https://json.nlohmann.me/features/json_view/#duplicate-keys) for the reasons and for how to get the last value.
+
+Unlike [`BasicJsonType::find`](https://json.nlohmann.me/api/basic_json/find/index.md), which always returns `end()` for a non-object type, this also does so for a [discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) 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[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md) (which would throw for the events that are not objects at all) or [`contains()`](https://json.nlohmann.me/api/basic_json_view/contains/index.md) 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
+```
+
+## See also
+
+- [count](https://json.nlohmann.me/api/basic_json_view/count/index.md) - returns the number of occurrences of a key
+- [contains](https://json.nlohmann.me/api/basic_json_view/contains/index.md) - checks whether a key exists
+- [`BasicJsonType::find`](https://json.nlohmann.me/api/basic_json/find/index.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0 unreleased.