| # <small>nlohmann::basic_json::</small>find | |
| ```cpp | |
| // (1) | |
| iterator find(const typename object_t::key_type& key); | |
| const_iterator find(const typename object_t::key_type& key) const; | |
| // (2) | |
| template<typename KeyType> | |
| iterator find(KeyType&& key); | |
| template<typename KeyType> | |
| const_iterator find(KeyType&& key) const; | |
| // (3) | |
| template<typename T> | |
| iterator find(T) = delete; | |
| template<typename T> | |
| const_iterator find(T) const = delete; | |
| ``` | |
| 1. Finds an element in a JSON object with a key equivalent to `key`. If the element is not found or the | |
| JSON value is not an object, `end()` is returned. | |
| 2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and | |
| `#!cpp typename object_comparator_t::is_transparent` denotes a type. | |
| 3. Deleted: this overload is only available if `T` is an integral type and is declared as deleted, so that a call with | |
| an integer `key` (for example, `#!cpp j.find(0)`) fails to compile. Otherwise, the integer literal `0` would convert to | |
| a null `#!cpp const char*` and, from there, to the key type, causing undefined behavior at runtime. | |
| ## Template parameters | |
| `KeyType` | |
| : A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with | |
| [`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md). | |
| This can also be a string view (C++17). | |
| ## Parameters | |
| `key` (in) | |
| : key value of the element to search for. | |
| ## Return value | |
| Iterator to an element with a key equivalent to `key`. If no such element is found or the JSON value is not an object, | |
| a past-the-end iterator (see `end()`) is returned. | |
| ## Exception safety | |
| Strong exception safety: if an exception occurs, the original value stays intact. | |
| ## Complexity | |
| Logarithmic in the size of the JSON object. | |
| ## Notes | |
| - This method always returns `end()` when executed on a JSON type that is not an object. | |
| - Calling this function with an integer argument (for example, `#!cpp find(0)`) does not compile: such an argument | |
| would otherwise implicitly convert to a null `#!cpp const char*` and, from there, cause undefined behavior when | |
| constructing a `#!cpp std::string` for the object key. To access an array element instead, use [`at`](at.md), | |
| [`operator[]`](operator%5B%5D.md), or compare against [`size`](size.md). | |
| ## Examples | |
| ??? example "Example: (1) find object element by key" | |
| The example shows how `find()` is used. | |
| ```cpp | |
| #include <iostream> | |
| #include <nlohmann/json.hpp> | |
| using json = nlohmann::json; | |
| int main() | |
| { | |
| // create a JSON object | |
| json j_object = {{"one", 1}, {"two", 2}}; | |
| // call find | |
| auto it_two = j_object.find("two"); | |
| auto it_three = j_object.find("three"); | |
| // print values | |
| std::cout << std::boolalpha; | |
| std::cout << "\"two\" was found: " << (it_two != j_object.end()) << '\n'; | |
| std::cout << "value at key \"two\": " << *it_two << '\n'; | |
| std::cout << "\"three\" was found: " << (it_three != j_object.end()) << '\n'; | |
| } | |
| ``` | |
| Output: | |
| ```json | |
| "two" was found: true | |
| value at key "two": 2 | |
| "three" was found: false | |
| ``` | |
| ??? example "Example: (2) find object element by key using string_view" | |
| The example shows how `find()` is used. | |
| ```cpp | |
| #include <iostream> | |
| #include <string_view> | |
| #include <nlohmann/json.hpp> | |
| using namespace std::string_view_literals; | |
| using json = nlohmann::json; | |
| int main() | |
| { | |
| // create a JSON object | |
| json j_object = {{"one", 1}, {"two", 2}}; | |
| // call find | |
| auto it_two = j_object.find("two"sv); | |
| auto it_three = j_object.find("three"sv); | |
| // print values | |
| std::cout << std::boolalpha; | |
| std::cout << "\"two\" was found: " << (it_two != j_object.end()) << '\n'; | |
| std::cout << "value at key \"two\": " << *it_two << '\n'; | |
| std::cout << "\"three\" was found: " << (it_three != j_object.end()) << '\n'; | |
| } | |
| ``` | |
| Output: | |
| ```json | |
| "two" was found: true | |
| value at key "two": 2 | |
| "three" was found: false | |
| ``` | |
| ## See also | |
| - [count](count.md) returns the number of occurrences of a key | |
| - [contains](contains.md) checks whether a key exists | |
| - [basic_json_view::find](../basic_json_view/find.md) - the same lookup on a zero-copy view (a duplicate key resolves | |
| to the first member, whereas `parse()` keeps the last) | |
| ## Version history | |
| 1. Added in version 3.11.0. | |
| 2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 to | |
| consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md), | |
| [`at`](at.md), [`value`](value.md), and other lookup functions. | |
| 3. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of | |
| causing undefined behavior at runtime. |