Defined in header
template<classInputIt,classT>InputItfind(InputItfirst,InputItlast,constT&value); (1)(constexpr since C++20)
(until C++26)template<classInputIt,classT=typenamestd::iterator_traits<InputIt>::value_type>constexprInputItfind(InputItfirst,InputItlast,constT&value);(since C++26)template<classInputIt,classUnaryPred>InputItfind_if(InputItfirst,InputItlast,UnaryPredp); (2)(constexpr since C++20)template<classInputIt,classUnaryPred>InputItfind_if_not(InputItfirst,InputItlast,UnaryPredq); (3)(since C++11)
(constexpr since C++20)template<classExecutionPolicy,classForwardIt,classT>ForwardItfind(ExecutionPolicy&&policy,ForwardItfirst,ForwardItlast,constT&value); (4)(since C++17)
(until C++26)template<classExecutionPolicy,classForwardIt,classT=typenamestd::iterator_traits<ForwardIt>::value_type>ForwardItfind(ExecutionPolicy&&policy,ForwardItfirst,ForwardItlast,constT&value);(since C++26)template<classExecutionPolicy,classForwardIt,classUnaryPred>ForwardItfind_if(ExecutionPolicy&&policy,ForwardItfirst,ForwardItlast,UnaryPredp); (5) (since C++17)template<classExecutionPolicy,classForwardIt,classUnaryPred>ForwardItfind_if_not(ExecutionPolicy&&policy,ForwardItfirst,ForwardItlast,UnaryPredq); (6) (since C++17)Returns an iterator to the first element in the source range [first, last) that satisfies specific criteria (or last if there is no such iterator).
1)find searches for the first element equal to value (using operator==).
2)find_if searches for the first element for which predicate p returns true.
3)find_if_not searches for the first element for which predicate q returns false.
4-6) Same as (1-3), but executed according to policy.
These overloads participate in overload resolution only if the value of the following expression is true:
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
(until C++20)std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
(since C++20)Parameters
first, last - the pair of iterators defining the source
value - value to compare the elements to p - unary predicate which returns true for the required element. The expression p(v) must be convertible to bool for every argument v of type (possibly const) VT, where VT is the value type of InputIt, regardless of
, and must not modify v. Thus, a parameter type of VT&is not allowed, nor is VT unless for VT a move is equivalent to a copy(since C++11).
q - unary predicate which returns false for the required element. The expression q(v) must be convertible to bool for every argument v of type (possibly const) VT, where VT is the value type of InputIt, regardless of
, and must not modify v. Thus, a parameter type of VT&is not allowed, nor is VT unless for VT a move is equivalent to a copy(since C++11).
policy - the
to use Type requirements -InputIt must meet the requirements of
. -ForwardIt must meet the requirements of
. -UnaryPredicate must meet the requirements of
. Return value
The first iterator it in the source range satisfying the following condition or last if there is no such iterator:
1,4)*it==value is true.
2,5)p(*it) is true.
3,6)q(*it) is false.
Complexity
Given N as std::distance(first,last):
1) At most N comparisons with value using operator==.
2) At most N applications of p.
3) At most N applications of q.
4)𝓞(N) comparisons with value using operator==.
5)𝓞(N) applications of p.
6)𝓞(N) applications of q.
Exceptions
4-6) During the execution process:
If the temporary memory resources required for parallelization are not available,
is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for
,
is invoked).
Possible implementation
template<classInputIt,classT=typenamestd::iterator_traits<InputIt>::value_type>constexprInputItfind(InputItfirst,InputItlast,constT&value){for(;first!=last;++first)if(*first==value)returnfirst;returnlast;}
template<classInputIt,classUnaryPred>constexprInputItfind_if(InputItfirst,InputItlast,UnaryPredp){for(;first!=last;++first)if(p(*first))returnfirst;returnlast;}
template<classInputIt,classUnaryPred>constexprInputItfind_if_not(InputItfirst,InputItlast,UnaryPredq){for(;first!=last;++first)if(!q(*first))returnfirst;returnlast;}Notes
If C++11 is not available, an equivalent to std::find_if_not is to use std::find_if with the negated predicate.
template<classInputIt,classUnaryPred>InputItfind_if_not(InputItfirst,InputItlast,UnaryPredq){returnstd::find_if(first,last,std::not1(q));}
macroValueStdFeature
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Example
The following example finds numbers in given sequences.
Run this code
#include<algorithm>#include<array>#include<cassert>#include<complex>#include<initializer_list>#include<iostream>#include<vector>boolis_even(inti){returni%2==0;}voidexample_contains(){constautohaystack={1,2,3,4};for(constintneedle:{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';}voidexample_predicate(){for(constauto&haystack:{std::array{3,1,4},{1,3,5}}){constautoit=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";}}voidexample_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 possibleconstautoit=std::find(haystack.begin(),haystack.end(),{4.0,2.0});#elseconstautoit=std::find(haystack.begin(),haystack.end(),std::complex{4.0,2.0});#endifassert(it==haystack.begin());}intmain(){example_contains();example_predicate();example_list_init();}Output:
haystack contains 3 haystack does not contain 5 haystack contains an even number 4 haystack does not contain even numbers Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 T was required to be
, but
the value type of InputIt might not be Tremoved the requirement See also
ranges::findranges::find_ifranges::find_if_not
(C++20)(C++20)(C++20)
finds the first element satisfying specific criteria
(algorithm function object)
finds the first two adjacent items that are equal (or satisfy a given predicate)
(function template & algorithm function object)
(C++20)
finds the last sequence of elements in a certain range
(function template & algorithm function object)
(C++20)
searches for any one of a set of elements
(function template & algorithm function object)
(C++20)
finds the first position where two ranges differ
(function template & algorithm function object)
(C++20)
searches for the first occurrence of a range of elements
(function template & algorithm function object)
(C++20)