[alg.binary.search] (original) (raw)

26 Algorithms library [algorithms]

26.8.4 Binary search [alg.binary.search]

26.8.4.1 General [alg.binary.search.general]

All of the algorithms in [alg.binary.search] are versions of binary search and assume that the sequence being searched is partitioned with respect to an expression formed by binding the search key to an argument of the comparison function.

They work on non-random access iterators minimizing the number of comparisons, which will be logarithmic for all types of iterators.

They are especially appropriate for random access iterators, because these algorithms do a logarithmic number of steps through the data structure.

For non-random access iterators they execute a linear number of steps.

26.8.4.2 lower_bound [lower.bound]

template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type> constexpr ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last,const T& value);template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type,class Compare> constexpr ForwardIterator lower_bound(ForwardIterator first, ForwardIterator last,const T& value, Compare comp);template<[forward_iterator](iterator.concept.forward#concept:forward%5Fiterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel%5Ffor "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S, class Proj = identity,class T = projected_value_t<I, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<I, Proj>> Comp = ranges::less> constexpr I ranges::lower_bound(I first, S last, const T& value, Comp comp = {}, Proj proj = {});template<[forward_range](range.refinements#concept:forward%5Frange "25.4.5 Other range refinements [range.refinements]") R, class Proj = identity,class T = projected_value_t<iterator_t<R>, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::lower_bound(R&& r, const T& value, Comp comp = {}, Proj proj = {});

Let comp be less{} andproj be identity{}for overloads with no parameters by those names.

Preconditions: The elements e of [first, last) are partitioned with respect to the expression

bool(invoke(comp, invoke(proj, e), value)).

Returns: The furthermost iterator i in the range [first, last] such that for every iterator j in the range [first, i),bool(invoke(comp, invoke(proj, *j), value)) is true.

Complexity: At most comparisons and projections.

26.8.4.3 upper_bound [upper.bound]

template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type> constexpr ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last,const T& value);template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type,class Compare> constexpr ForwardIterator upper_bound(ForwardIterator first, ForwardIterator last,const T& value, Compare comp);template<[forward_iterator](iterator.concept.forward#concept:forward%5Fiterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel%5Ffor "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S, class Proj = identity,class T = projected_value_t<I, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<I, Proj>> Comp = ranges::less> constexpr I ranges::upper_bound(I first, S last, const T& value, Comp comp = {}, Proj proj = {});template<[forward_range](range.refinements#concept:forward%5Frange "25.4.5 Other range refinements [range.refinements]") R, class Proj = identity,class T = projected_value_t<iterator_t<R>, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_iterator_t<R> ranges::upper_bound(R&& r, const T& value, Comp comp = {}, Proj proj = {});

Let comp be less{} andproj be identity{}for overloads with no parameters by those names.

Preconditions: The elements e of [first, last) are partitioned with respect to the expression

!bool(invoke(comp, value, invoke(proj, e))).

Returns: The furthermost iterator i in the range [first, last] such that for every iterator j in the range [first, i),!bool(invoke(comp, value, invoke(proj, *j))) is true.

Complexity: At most comparisons and projections.

26.8.4.4 equal_range [equal.range]

template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type> constexpr pair<ForwardIterator, ForwardIterator> equal_range(ForwardIterator first, ForwardIterator last, const T& value);template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type,class Compare> constexpr pair<ForwardIterator, ForwardIterator> equal_range(ForwardIterator first, ForwardIterator last, const T& value, Compare comp);template<[forward_iterator](iterator.concept.forward#concept:forward%5Fiterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel%5Ffor "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S, class Proj = identity,class T = projected_value_t<I, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<I, Proj>> Comp = ranges::less> constexpr subrange<I> ranges::equal_range(I first, S last, const T& value, Comp comp = {}, Proj proj = {});template<[forward_range](range.refinements#concept:forward%5Frange "25.4.5 Other range refinements [range.refinements]") R, class Proj = identity,class T = projected_value_t<iterator_t<R>, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr borrowed_subrange_t<R> ranges::equal_range(R&& r, const T& value, Comp comp = {}, Proj proj = {});

Let comp be less{} andproj be identity{}for overloads with no parameters by those names.

Preconditions: The elements e of [first, last) are partitioned with respect to the expressionsbool(invoke(comp, invoke(proj, e), value)) and!bool(invoke(comp, value, invoke(proj, e))).

Also, for all elements e of [first, last),bool(comp(e, value)) implies !bool(comp(​value, e))for the overloads in namespace std.

Returns:

Complexity: At most comparisons and projections.

26.8.4.5 binary_search [binary.search]

template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type> constexpr bool binary_search(ForwardIterator first, ForwardIterator last,const T& value);template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type,class Compare> constexpr bool binary_search(ForwardIterator first, ForwardIterator last,const T& value, Compare comp);template<[forward_iterator](iterator.concept.forward#concept:forward%5Fiterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel%5Ffor "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S, class Proj = identity,class T = projected_value_t<I, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<I, Proj>> Comp = ranges::less> constexpr bool ranges::binary_search(I first, S last, const T& value, Comp comp = {}, Proj proj = {});template<[forward_range](range.refinements#concept:forward%5Frange "25.4.5 Other range refinements [range.refinements]") R, class Proj = identity,class T = projected_value_t<iterator_t<R>, Proj>,[indirect_strict_weak_order](indirectcallable.indirectinvocable#concept:indirect%5Fstrict%5Fweak%5Forder "24.3.6.3 Indirect callables [indirectcallable.indirectinvocable]")<const T*, projected<iterator_t<R>, Proj>> Comp = ranges::less> constexpr bool ranges::binary_search(R&& r, const T& value, Comp comp = {}, Proj proj = {});

Let comp be less{} andproj be identity{}for overloads with no parameters by those names.

Preconditions: The elements e of [first, last) are partitioned with respect to the expressionsbool(invoke(comp, invoke(proj, e), value)) and!bool(invoke(comp, value, invoke(proj, e))).

Also, for all elements e of [first, last),bool(comp(e, value)) implies !bool(comp(​value, e))for the overloads in namespace std.

Returns: true if and only if for some iterator i in the range [first, last),!bool(invoke(comp, invoke(proj, *i), value)) && !bool(invoke(comp, value, invoke(proj, *i)))is true.

Complexity: At most comparisons and projections.