Defined in header
Call signature
template<std::forward_iteratorI,std::sentinel_for<I>S,classT,classProj=std::identity,std::indirect_strict_weak_order<constT*,std::projected<I,Proj>>Comp=ranges::less>constexprranges::subrange<I>equal_range(Ifirst,Slast,constT&value,Compcomp={},Projproj={}); (1)(since C++20)
(until C++26)template<std::forward_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT=std::projected_value_t<I,Proj>,std::indirect_strict_weak_order<constT*,std::projected<I,Proj>>Comp=ranges::less>constexprranges::subrange<I>equal_range(Ifirst,Slast,constT&value,Compcomp={},Projproj={});(since C++26)template<ranges::forward_rangeR,classT,classProj=std::identity,std::indirect_strict_weak_order<constT*,std::projected<ranges::iterator_t<R>,Proj>>Comp=ranges::less>constexprranges::borrowed_subrange_t<R>equal_range(R&&r,constT&value,Compcomp={},Projproj={}); (2)(since C++20)
(until C++26)template<ranges::forward_rangeR,classProj=std::identity,classT=std::projected_value_t<ranges::iterator_t<R>,Proj>,std::indirect_strict_weak_order<constT*,std::projected<ranges::iterator_t<R>,Proj>>Comp=ranges::less>constexprranges::borrowed_subrange_t<R>equal_range(R&&r,constT&value,Compcomp={},Projproj={});(since C++26)Searches for the range containing all elements (projected by proj) equivalent to value in the partitioned source range [first, last) or r. An element is considered equivalent to value if its projected value neither orders before nor orders after value with the comparator comp.
If the elements e of the source range are not partitioned with respect the following expressions at the same time, the behavior is undefined:
bool(std::invoke(comp,std::invoke(proj,e),value))
!bool(std::invoke(comp,value,std::invoke(proj,e)))
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 value to be compared with the (projected) elements comp - the comparator to be applied to the (projected) elements proj - the projection to be applied to the elements Return value
A subrange of the source range containing exactly all elements equivalent to value; the subrange is empty if no such element is found.
Complexity
Given N as ranges::distance(first,last) or ranges::distance(r):
1,2) At most 2log2(N)+𝓞(1) applications of comp and proj.
Notes
macroValueStdFeature
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Possible implementation
structequal_range_fn{template<std::forward_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT=std::projected_value_t<I,Proj>,std::indirect_strict_weak_order<constT*,std::projected<I,Proj>>Comp=ranges::less>constexprranges::subrange<I>operator()(Ifirst,Slast,constT&value,Compcomp={},Projproj={})const{returnranges::subrange(ranges::lower_bound(first,last,value,std::ref(comp),std::ref(proj)),ranges::upper_bound(first,last,value,std::ref(comp),std::ref(proj)));}template<ranges::forward_rangeR,classProj=std::identity,classT=std::projected_value_t<ranges::iterator_t<R>,Proj>,std::indirect_strict_weak_order<constT*,std::projected<ranges::iterator_t<R>,Proj>>Comp=ranges::less>constexprranges::borrowed_subrange_t<R>operator()(R&&r,constT&value,Compcomp={},Projproj={})const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),value,std::ref(comp),std::ref(proj));}};inlineconstexprequal_range_fnequal_range;Example
Run this code
#include<algorithm>#include<compare>#include<print>#include<vector>#include<utility>structS{intnumber{};charname{};// note: name is ignored by these comparison operatorsfriendbooloperator==(constSs1,constSs2){returns1.number==s2.number;}friendautooperator<=>(constSs1,constSs2){returns1.number<=>s2.number;}};template<>structstd::formatter<S>{constexprautoparse(auto&ctx){returnctx.begin();}template<classContext>Context::iteratorformat(constS&s,Context&ctx)const{returnstd::format_to(ctx.out(),"{{{}, '{}'}}",s.number,s.name);}};intmain(){// Note: not ordered, only partitioned w.r.t. S defined belowstd::vector<S>vec{{1,'A'},{2,'B'},{2,'C'},{2,'D'},{4,'D'},{4,'G'},{3,'F'}};constSvalue{2,'?'};namespaceranges=std::ranges;autoa=ranges::equal_range(vec,value);std::println("1. {}",a);autob=ranges::equal_range(vec.begin(),vec.end(),value);std::println("2. {}",b);autoc=ranges::equal_range(vec,'D',ranges::less{},&S::name);std::println("3. {}",c);autod=ranges::equal_range(vec.begin(),vec.end(),'D',ranges::less{},&S::name);std::println("4. {}",d);usingPairIntInt=std::pair<int,int>;std::vector<PairIntInt>nums{{1,0},{2,2},{2,1},{3,0},{3,1}};autocmp1=[](PairIntIntx,PairIntInty){returnx.first<y.first;};#ifdef __cpp_lib_algorithm_default_value_typeautop3=ranges::equal_range(nums,{2,0},cmp1);#elseautop3=ranges::equal_range(nums,PairIntInt{2,0},cmp1);#endifstd::println("5. {}",p3);}Output:
1. [{2, 'B'}, {2, 'C'}, {2, 'D'}] 2. [{2, 'B'}, {2, 'C'}, {2, 'D'}] 3. [{2, 'D'}, {4, 'D'}] 4. [{2, 'D'}, {4, 'D'}] 5. [(2, 2), (2, 1)] See also
finds the range of elements matching the given value using binary search
(function template)
(C++20)
finds the first element not less than the given value using binary search
(algorithm function object)
(C++20)
finds the first element greater than the given value using binary search
(algorithm function object)
(C++20)
determines if an element exists in a range using binary search
(algorithm function object)
(C++20)
divides a range of elements into two groups
(algorithm function object)
(C++20)
determines if two sets of elements are the same
(algorithm function object)