Niels Lohmann
52b72b5684
- Make the iterator range illustrations legible in dark mode (prefers-color-scheme rules inside the SVGs). - Add a "Byte layout" section with a color-coded byte table to each binary format page (BJData, BON8, BSON, CBOR, MessagePack, UBJSON), and highlight the smallest size per file in the comparison table. - Add "See also" sections to the overview pages that lacked one. - Split the release notes into one page per release, grouped by minor version on the overview page, with an "API changes" section per release generated from the API pages' version histories (hooks/api_changes.py). - Fact-check the release notes and version histories against the release tags and correct wrong or misleading entries (e.g., json_serializer 2.1.0, merge_patch 3.1.0, items, count, operator[], to_bjdata, std::string_view key support). Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.5 KiB
3.5 KiB
nlohmann::basic_json::find
// (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;
- 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. - See 1. This overload is only available if
KeyTypeis comparable with#!cpp typename object_t::key_typeand#!cpp typename object_comparator_t::is_transparentdenotes a type. - Deleted: this overload is only available if
Tis an integral type and is declared as deleted, so that a call with an integerkey(for example,#!cpp j.find(0)) fails to compile. Otherwise, the integer literal0would 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_pointerthat is comparable withstring_tusingobject_comparator_t. 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::stringfor the object key. To access an array element instead, useat,operator[], or compare againstsize.
Examples
??? example "Example: (1) find object element by key"
The example shows how `find()` is used.
```cpp
--8<-- "examples/find__object_t_key_type.cpp"
```
Output:
```json
--8<-- "examples/find__object_t_key_type.output"
```
??? example "Example: (2) find object element by key using string_view"
The example shows how `find()` is used.
```cpp
--8<-- "examples/find__keytype.c++17.cpp"
```
Output:
```json
--8<-- "examples/find__keytype.c++17.output"
```
See also
- count returns the number of occurrences of a key
- contains checks whether a key exists
- basic_json_view::find - the same lookup on a zero-copy view (a duplicate key resolves
to the first member, whereas
parse()keeps the last)
Version history
- Added in version 3.11.0.
- Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Support for keys convertible to
std::string_viewadded in version 3.13.0, consistently across the lookup functions. - 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.