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=typenamestd::iterator_traits <InputIt>::value_type> | (since C++26) | |
| (2) | ||
template<class ExecutionPolicy,class ForwardIt,class T> ForwardIt find( ExecutionPolicy&& policy, | (since C++17) (until C++26) | |
template<class ExecutionPolicy, class ForwardIt,class T=typenamestd::iterator_traits | (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, | (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, | (6) | (since C++17) |
Returns an iterator to the first element in the range[first, last) that satisfies specific criteria (orlast if there is no such iterator).
find searches for an element equal tovalue (usingoperator==).find_if searches for an element for which predicatep returnstrue.find_if_not searches for an element for which predicateq returnsfalse.std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> istrue. | (until C++20) |
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> istrue. | (since C++20) |
Contents |
| first, last | - | the pair of iterators defining therange of elements to examine |
| value | - | value to compare the elements to |
| policy | - | theexecution policy to use |
| p | - | unary predicate which returns true for the required element. The expressionp(v) must be convertible tobool for every argument |
| q | - | unary predicate which returns false for the required element. The expressionq(v) must be convertible tobool for every argument |
| Type requirements | ||
-InputIt must meet the requirements ofLegacyInputIterator. | ||
-ForwardIt must meet the requirements ofLegacyForwardIterator. | ||
-UnaryPredicate must meet the requirements ofPredicate. | ||
The first iteratorit in therange[first, last) satisfying the following condition orlast if there is no such iterator:
Given\(\scriptsize N\)N asstd::distance(first, last):
operator==.The overloads with a template parameter namedExecutionPolicy report errors as follows:
ExecutionPolicy is one of thestandard policies,std::terminate is called. For any otherExecutionPolicy, the behavior is implementation-defined.| find (1) |
|---|
template<class InputIt,class T=typenamestd::iterator_traits<InputIt>::value_type>constexpr InputIt find(InputIt first, InputIt last,const T& value){for(; first!= last;++first)if(*first== value)return first; return last;} |
| find_if (3) |
template<class InputIt,class UnaryPred>constexpr InputIt find_if(InputIt first, InputIt last, UnaryPred p){for(; first!= last;++first)if(p(*first))return first; return last;} |
| find_if_not (5) |
template<class InputIt,class UnaryPred>constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPred q){for(; first!= last;++first)if(!q(*first))return first; return last;} |
If C++11 is not available, an equivalent tostd::find_if_not is to usestd::find_if with the negated predicate.
template<class InputIt,class UnaryPred>InputIt find_if_not(InputIt first, InputIt last, UnaryPred q){return std::find_if(first, last,std::not1(q));} |
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_algorithm_default_value_type | 202403 | (C++26) | List-initialization for algorithms(1,2) |
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(){constauto haystack={1,2,3,4}; for(constint needle:{3,5})if(std::find(haystack.begin(), haystack.end(), needle)== haystack.end())std::cout<<"haystack does not contain "<< needle<<'\n';elsestd::cout<<"haystack contains "<< needle<<'\n';} void example_predicate(){for(constauto& haystack:{std::array{3,1,4},{1,3,5}}){constauto it= std::find_if(haystack.begin(), haystack.end(), is_even);if(it!= haystack.end())std::cout<<"haystack contains an even number "<<*it<<'\n';elsestd::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 possibleconstauto it= std::find(haystack.begin(), haystack.end(),{4.0,2.0});#elseconstauto it= std::find(haystack.begin(), haystack.end(),std::complex{4.0,2.0});#endifassert(it== haystack.begin());} int main(){ example_contains(); example_predicate(); example_list_init();}
Output:
haystack contains 3haystack does not contain 5haystack contains an even number 4haystack does not contain even numbers
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 beEqualityComparable, butthe value type of InputIt might not beT | removed the requirement |
| finds the first two adjacent items that are equal (or satisfy a given predicate) (function template)[edit] | |
| finds the last sequence of elements in a certain range (function template)[edit] | |
| searches for any one of a set of elements (function template)[edit] | |
| finds the first position where two ranges differ (function template)[edit] | |
| searches for the first occurrence of a range of elements (function template)[edit] | |
(C++20)(C++20)(C++20) | finds the first element satisfying specific criteria (algorithm function object)[edit] |
