[alg.binary.search]

# 26 Algorithms library [[algorithms]](./#algorithms)

## 26.8 Sorting and related operations [[alg.sorting]](alg.sorting#alg.binary.search)

### 26.8.4 Binary search [alg.binary.search]

#### [26.8.4.1](#general) General [[alg.binary.search.general]](alg.binary.search.general)

[1](#general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9395)

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[.](#general-1.sentence-1)

They work on non-random access iterators minimizing the number of comparisons,
which will be logarithmic for all types of iterators[.](#general-1.sentence-2)

They are especially appropriate for random access iterators,
because these algorithms do a logarithmic number of steps
through the data structure[.](#general-1.sentence-3)

For non-random access iterators they execute a linear number of steps[.](#general-1.sentence-4)

#### [26.8.4.2](#lower.bound) lower_bound [[lower.bound]](lower.bound)

[🔗](#lib: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_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "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_strict_weak_order "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_range "25.4.6 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_strict_weak_order "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 = {});
`

[1](#lower.bound-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9436)

Let comp be less{} andproj be identity{} for overloads with no parameters by those names[.](#lower.bound-1.sentence-1)

[2](#lower.bound-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9441)

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

bool(invoke(comp, invoke(proj, e), value))[.](#lower.bound-2.sentence-2)

[3](#lower.bound-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9447)

*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[.](#lower.bound-3.sentence-1)

[4](#lower.bound-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9453)

*Complexity*: At most log2(last - first)+O(1) comparisons and projections[.](#lower.bound-4.sentence-1)

#### [26.8.4.3](#upper.bound) upper_bound [[upper.bound]](upper.bound)

[🔗](#lib: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_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "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_strict_weak_order "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_range "25.4.6 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_strict_weak_order "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 = {});
`

[1](#upper.bound-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9486)

Let comp be less{} andproj be identity{} for overloads with no parameters by those names[.](#upper.bound-1.sentence-1)

[2](#upper.bound-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9491)

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

!bool(invoke(comp, value, invoke(proj, e)))[.](#upper.bound-2.sentence-2)

[3](#upper.bound-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9497)

*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[.](#upper.bound-3.sentence-1)

[4](#upper.bound-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9503)

*Complexity*: At most log2(last - first)+O(1) comparisons and projections[.](#upper.bound-4.sentence-1)

#### [26.8.4.4](#equal.range) equal_range [[equal.range]](equal.range)

[🔗](#lib: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_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "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_strict_weak_order "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_range "25.4.6 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_strict_weak_order "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 = {});
`

[1](#equal.range-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9538)

Let comp be less{} andproj be identity{} for overloads with no parameters by those names[.](#equal.range-1.sentence-1)

[2](#equal.range-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9543)

*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)))[.](#equal.range-2.sentence-1)

Also, for all elements e of [first, last),bool(comp(e, value)) implies !bool(comp(​value, e)) for the overloads in namespace std[.](#equal.range-2.sentence-2)

[3](#equal.range-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9553)

*Returns*: 

- [(3.1)](#equal.range-3.1)

For the overloads in namespace std:{lower_bound(first, last, value, comp),
 upper_bound(first, last, value, comp)}

- [(3.2)](#equal.range-3.2)

For the overloads in namespace ranges:{ranges::lower_bound(first, last, value, comp, proj),
 ranges::upper_bound(first, last, value, comp, proj)}

[4](#equal.range-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9570)

*Complexity*: At most2∗log2(last - first)+O(1) comparisons and projections[.](#equal.range-4.sentence-1)

#### [26.8.4.5](#binary.search) binary_search [[binary.search]](binary.search)

[🔗](#lib: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_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "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_strict_weak_order "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_range "25.4.6 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_strict_weak_order "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 = {});
`

[1](#binary.search-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9605)

Let comp be less{} andproj be identity{} for overloads with no parameters by those names[.](#binary.search-1.sentence-1)

[2](#binary.search-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9610)

*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)))[.](#binary.search-2.sentence-1)

Also, for all elements e of [first, last),bool(comp(e, value)) implies !bool(comp(​value, e)) for the overloads in namespace std[.](#binary.search-2.sentence-2)

[3](#binary.search-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9620)

*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[.](#binary.search-3.sentence-1)

[4](#binary.search-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L9628)

*Complexity*: At most log2(last - first)+O(1) comparisons and projections[.](#binary.search-4.sentence-1)