Defined in header
Call signature
template<std::input_iteratorI,std::sentinel_for<I>S,classT,classProj=std::identity>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT*>constexprIfind(Ifirst,Slast,constT&value,Projproj={}); (1)(since C++20)
(until C++26)template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT=std::projected_value_t<I,Proj>>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT*>constexprIfind(Ifirst,Slast,constT&value,Projproj={});(since C++26)template<ranges::input_rangeR,classT,classProj=std::identity>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT*>constexprranges::borrowed_iterator_t<R>find(R&&r,constT&value,Projproj={}); (2)(since C++20)
(until C++26)template<ranges::input_rangeR,classProj=std::identity,classT=std::projected_value_t<ranges::iterator_t<R>,Proj>>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT*>constexprranges::borrowed_iterator_t<R>find(R&&r,constT&value,Projproj={});(since C++26)template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>constexprIfind_if(Ifirst,Slast,Predpred,Projproj={}); (3)(since C++20)template<ranges::input_rangeR,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>constexprranges::borrowed_iterator_t<R>find_if(R&&r,Predpred,Projproj={}); (4) (since C++20)template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>constexprIfind_if_not(Ifirst,Slast,Predpred,Projproj={}); (5)(since C++20)template<ranges::input_rangeR,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>constexprranges::borrowed_iterator_t<R>find_if_not(R&&r,Predpred,Projproj={}); (6) (since C++20)template</*execution-policy*/Ep,std::random_access_iteratorI,std::sized_sentinel_for<I>S,classProj=std::identity,classT=std::projected_value_t<I,Proj>>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT*>Ifind(Ep&&policy,Ifirst,Slast,constT&value,Projproj={}); (7) (since C++26)template</*execution-policy*/Ep,/*sized-random-access-range*/R,classProj=std::identity,classT=std::projected_value_t<ranges::iterator_t<R>,Proj>>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT*>ranges::borrowed_iterator_t<R>find(Ep&&policy,R&&r,constT&value,Projproj={}); (8) (since C++26)template</*execution-policy*/Ep,std::random_access_iteratorI,std::sized_sentinel_for<I>S,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>Ifind_if(Ep&&policy,Ifirst,Slast,Predpred,Projproj={}); (9) (since C++26)template</*execution-policy*/Ep,/*sized-random-access-range*/R,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>ranges::borrowed_iterator_t<R>find_if(Ep&&policy,R&&r,Predpred,Projproj={}); (10) (since C++26)template</*execution-policy*/Ep,std::random_access_iteratorI,std::sized_sentinel_for<I>S,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>Ifind_if_not(Ep&&policy,Ifirst,Slast,Predpred,Projproj={}); (11) (since C++26)template</*execution-policy*/Ep,/*sized-random-access-range*/R,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>ranges::borrowed_iterator_t<R>find_if_not(Ep&&policy,R&&r,Predpred,Projproj={}); (12) (since C++26)For the definition of /*execution-policy*/, see
; for the definition of /*sized-random-access-range*/, see
.
Search for the first element (projected by proj) in the source range [first, last) or r that satisfies specific criteria:
1,2)find searches for the first element equal to the target value value.
3,4)find_if searches for the first element for which predicate pred returns true.
5,6)find_if_not searches for the first element for which predicate pred returns false.
7-12) Same as (1-6), but executed according to policy.
The function-like entities described on this page are
(informally known as niebloids), that is:
Explicit template argument lists cannot be specified when calling any of them.
None of them are visible to
.
When any of them are found by
as the name to the left of the function-call operator,
is inhibited.
Parameters
first, last - the iterator-sentinel pair defining the source
r - the source range value - the target value pred - the predicate to be applied to the (projected) elements proj - the projection to be applied to the elements policy - the
to use Return value
Iterator to the first element satisfying the condition.
If no such element is found, returns ranges::next(first,last) (or ranges::next(ranges::begin(r),ranges::end(r)) for range overloads).
Complexity
Given N as ranges::distance(first,last) or ranges::distance(r):
1,2) At most N comparisons and applications of proj.
3-6) At most N applications of pred and proj.
7,8)𝓞(N) comparisons and applications of proj.
9-12)𝓞(N) applications of pred and proj.
Exceptions
7-12) 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).
Notes
macroValueStdFeature
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Possible implementation
structfind_fn{template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT=std::projected_value_t<I,Proj>>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT*>constexprIoperator()(Ifirst,Slast,constT&value,Projproj={})const{for(;first!=last;++first)if(std::invoke(proj,*first)==value)returnfirst;returnfirst;}template<ranges::input_rangeR,classT,classProj=std::identity>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT*>constexprranges::borrowed_iterator_t<R>operator()(R&&r,constT&value,Projproj={})const{return(*this)(ranges::begin(r),ranges::end(r),value,std::ref(proj));}template<ranges::forward_rangeR,classT,classProj=std::identity>requiresstd::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT*>constexprranges::borrowed_iterator_t<R>operator()(R&&r,constT&value,Projproj={})const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),value,std::ref(proj));}};inlineconstexprfind_fnfind;
structfind_if_fn{template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>constexprIoperator()(Ifirst,Slast,Predpred,Projproj={})const{for(;first!=last;++first)if(std::invoke(pred,std::invoke(proj,*first)))returnfirst;returnfirst;}template<ranges::input_rangeR,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>constexprranges::borrowed_iterator_t<R>operator()(R&&r,Predpred,Projproj={})const{return(*this)(ranges::begin(r),ranges::end(r),std::ref(pred),std::ref(proj));}template<ranges::forward_rangeR,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>constexprranges::borrowed_iterator_t<R>operator()(R&&r,Predpred,Projproj={})const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),std::ref(pred),std::ref(proj));}};inlineconstexprfind_if_fnfind_if;
structfind_if_not_fn{template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>constexprIoperator()(Ifirst,Slast,Predpred,Projproj={})const{for(;first!=last;++first)if(!std::invoke(pred,std::invoke(proj,*first)))returnfirst;returnfirst;}template<ranges::input_rangeR,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>constexprranges::borrowed_iterator_t<R>operator()(R&&r,Predpred,Projproj={})const{return(*this)(ranges::begin(r),ranges::end(r),std::ref(pred),std::ref(proj));}template<ranges::forward_rangeR,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>constexprranges::borrowed_iterator_t<R>operator()(R&&r,Predpred,Projproj={})const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),std::ref(pred),std::ref(proj));}};inlineconstexprfind_if_not_fnfind_if_not;Example
Run this code
#include<algorithm>#include<cassert>#include<complex>#include<format>#include<iostream>#include<iterator>#include<string>#include<vector>voidprojector_example(){structfolk_info{unsigneduid;std::stringname,position;};std::vector<folk_info>folks{{0,"Ana","dev"},{1,"Bob","devops"},{2,"Eve","ops"}};constautowho{"Eve"};if(autoit=std::ranges::find(folks,who,&folk_info::name);it!=folks.end())std::cout<<std::format("Profile:\n"" UID: {}\n"" Name: {}\n"" Position: {}\n\n",it->uid,it->name,it->position);}intmain(){namespaceranges=std::ranges;projector_example();constintn1=3;constintn2=5;constautov={4,1,3,2};if(ranges::find(v,n1)!=v.end())std::cout<<"v contains: "<<n1<<'\n';elsestd::cout<<"v does not contain: "<<n1<<'\n';if(ranges::find(v.begin(),v.end(),n2)!=v.end())std::cout<<"v contains: "<<n2<<'\n';elsestd::cout<<"v does not contain: "<<n2<<'\n';autois_even=[](intx){returnx%2==0;};if(autoresult=ranges::find_if(v.begin(),v.end(),is_even);result!=v.end())std::cout<<"First even element in v: "<<*result<<'\n';elsestd::cout<<"No even elements in v\n";if(autoresult=ranges::find_if_not(v,is_even);result!=v.end())std::cout<<"First odd element in v: "<<*result<<'\n';elsestd::cout<<"No odd elements in v\n";autodivides_13=[](intx){returnx%13==0;};if(autoresult=ranges::find_if(v,divides_13);result!=v.end())std::cout<<"First element divisible by 13 in v: "<<*result<<'\n';elsestd::cout<<"No elements in v are divisible by 13\n";if(autoresult=ranges::find_if_not(v.begin(),v.end(),divides_13);result!=v.end())std::cout<<"First element indivisible by 13 in v: "<<*result<<'\n';elsestd::cout<<"All elements in v are divisible by 13\n";std::vector<std::complex<double>>nums{{4,2}};#ifdef __cpp_lib_algorithm_default_value_type// T gets deduced in (2) making list-initialization possibleconstautoit=ranges::find(nums,{4,2});#elseconstautoit=ranges::find(nums,std::complex<double>{4,2});#endifassert(it==nums.begin());}Output:
Profile: UID: 2 Name: Eve Position: ops v contains: 3 v does not contain: 5 First even element in v: 4 First odd element in v: 1 No elements in v are divisible by 13 First element indivisible by 13 in v: 4 See also
(C++11)
finds the first element satisfying specific criteria
(function template)
(C++20)
finds the first two adjacent items that are equal (or satisfy a given predicate)
(algorithm function object)
(C++20)
finds the last sequence of elements in a certain range
(algorithm function object)
(C++20)
searches for any one of a set of elements
(algorithm function object)
(C++20)
finds the first position where two ranges differ
(algorithm function object)
(C++20)
searches for the first occurrence of a range of elements
(algorithm function object)