| Defined in header <algorithm>
|
||
| (1) | ||
template< class InputIt, class T > InputIt find( InputIt first, InputIt last, const T& value ); |
(constexpr since C++20) (until C++26) |
|
| template< class InputIt, class T = typename std::iterator_traits <InputIt>::value_type > constexpr InputIt find( InputIt first, InputIt last, const T& value ); |
(since C++26) | |
| (2) | ||
| template< class ExecutionPolicy, class ForwardIt, class T > ForwardIt find( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, const T& value ); |
(since C++17) (until C++26) |
|
| template< class ExecutionPolicy, class ForwardIt, class T = typename std::iterator_traits <ForwardIt>::value_type > ForwardIt find( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, const T& value ); |
(since C++26) | |
template< class InputIt, class UnaryPred > InputIt find_if( InputIt first, InputIt last, UnaryPred p ); |
(3) | (constexpr since C++20) |
| template< class ExecutionPolicy, class ForwardIt, class UnaryPred > ForwardIt find_if( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, UnaryPred p ); |
(4) | (since C++17) |
template< class InputIt, class UnaryPred > InputIt find_if_not( InputIt first, InputIt last, UnaryPred q ); |
(5) | (since C++11) (constexpr since C++20) |
| template< class ExecutionPolicy, class ForwardIt, class UnaryPred > ForwardIt find_if_not( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, UnaryPred q ); |
(6) | (since C++17) |
Returns an iterator to the first element in the range [first, last) that satisfies specific criteria (or last if there is no such iterator).
find searches for an element equal to value (using operator==).find_if searches for an element for which predicate p returns true.find_if_not searches for an element for which predicate q returns false.policy.|
|
(until C++20) |
|
|
(since C++20) |
Parameters
| first, last | - | the range of elements to examine |
| value | - | value to compare the elements to |
| policy | - | the execution policy to use |
| p | - | unary predicate which returns true for the required element. The expression |
| q | - | unary predicate which returns false for the required element. The expression |
| Type requirements | ||
InputIt must meet the requirements of LegacyInputIterator.
| ||
ForwardIt must meet the requirements of LegacyForwardIterator.
| ||
UnaryPredicate must meet the requirements of Predicate.
| ||
Return value
The first iterator it in the range [first, last) satisfying the following condition or last if there is no such iterator:
*it == value is true.p(*it) is true.q(*it) is false.Complexity
Given N as std::distance(first, last):
value using operator==.p.q.Exceptions
The overloads with a template parameter named ExecutionPolicy report errors as follows:
- If execution of a function invoked as part of the algorithm throws an exception and
ExecutionPolicyis one of the standard policies, std::terminate is called. For any otherExecutionPolicy, the behavior is implementation-defined. - If the algorithm fails to allocate memory, std::bad_alloc is thrown.
Possible implementation
| find |
|---|
|
| find_if |
|
| find_if_not |
|
Notes
If C++11 is not available, an equivalent to std::find_if_not is to use std::find_if with the negated predicate.
|
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_algorithm_default_value_type |
202403 |
(C++26) | List-initialization for algorithms (1,2) |
Example
The following example finds numbers in given sequences.
#include <algorithm>
#include <array>
#include <cassert>
#include <complex>
#include <initializer_list>
#include <iostream>
#include <vector>
bool is_even(int i)
{
return i % 2 == 0;
}
void example_contains()
{
const auto haystack = {1, 2, 3, 4};
for (const int needle : {3, 5})
if (std::find(haystack.begin(), haystack.end(), needle) == haystack.end())
std::cout << "haystack does not contain " << needle << '\n';
else
std::cout << "haystack contains " << needle << '\n';
}
void example_predicate()
{
for (const auto& haystack : {std::array{3, 1, 4}, {1, 3, 5}})
{
const auto it = std::find_if(haystack.begin(), haystack.end(), is_even);
if (it != haystack.end())
std::cout << "haystack contains an even number " << *it << '\n';
else
std::cout << "haystack does not contain even numbers\n";
}
}
void example_list_init()
{
std::vector<std::complex<double>> haystack{{4.0, 2.0}};
#ifdef __cpp_lib_algorithm_default_value_type
// T gets deduced making list-initialization possible
const auto it = std::find(haystack.begin(), haystack.end(), {4.0, 2.0});
#else
const auto it = std::find(haystack.begin(), haystack.end(), std::complex{4.0, 2.0});
#endif
assert(it == haystack.begin());
}
int main()
{
example_contains();
example_predicate();
example_list_init();
}haystack contains 3
haystack does not contain 5
haystack contains an even number 4
haystack does not contain even numbersDefect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 283 | C++98 | T was required to be EqualityComparable, butthe value type of InputIt might not be T
|
removed the requirement |
See also
| finds the first two adjacent items that are equal (or satisfy a given predicate) (function template) | |
| finds the last sequence of elements in a certain range (function template) | |
| searches for any one of a set of elements (function template) | |
| finds the first position where two ranges differ (function template) | |
| searches for the first occurrence of a range of elements (function template) | |
| (C++20)(C++20)(C++20) |
finds the first element satisfying specific criteria (algorithm function object) |
Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.