Niels Lohmann
7b755737b4
From gregmarr's review of #5622: - count() counts every member with the key, so count(key) > 1 detects duplicate keys; it was contains() as 0/1 before. - get_to() passes types that get<T>() does not convert directly to from_json with the existing value, as basic_json::get_to() does, so that a from_json which sets only the fields present keeps the others. - array_index() checks the empty token and "-" first; the results are unchanged. - Docs: no "if an exception is thrown" where a view never changes anything; the borrowed source must also stay unmodified; items() on a temporary view is safe; back()/front() notes shortened; the basic_json see-also entries say how the view's results can differ. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.6 KiB
3.6 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. Fixed in version 3.13.0 to
consistently accept
std::string_view-convertible keys, as already supported byoperator[],at,value, and other 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.