26 Algorithms library [algorithms]

26.8 Sorting and related operations [alg.sorting]

26.8.4 Binary search [alg.binary.search]

26.8.4.1 General [alg.binary.search.general]

1
#
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 I, sentinel_for<I> S, class Proj = identity, class T = projected_value_t<I, Proj>, indirect_strict_weak_order<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 R, class Proj = identity, class T = projected_value_t<iterator_t<R>, Proj>, indirect_strict_weak_order<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
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expression
bool(invoke(comp, invoke(proj, e), value)).
3
#
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.
4
#
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 I, sentinel_for<I> S, class Proj = identity, class T = projected_value_t<I, Proj>, indirect_strict_weak_order<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 R, class Proj = identity, class T = projected_value_t<iterator_t<R>, Proj>, indirect_strict_weak_order<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
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expression
!bool(invoke(comp, value, invoke(proj, e))).
3
#
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.
4
#
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 I, sentinel_for<I> S, class Proj = identity, class T = projected_value_t<I, Proj>, indirect_strict_weak_order<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 R, class Proj = identity, class T = projected_value_t<iterator_t<R>, Proj>, indirect_strict_weak_order<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
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expressions bool(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.
3
#
Returns:
  • (3.1)
    For the overloads in namespace std: {lower_bound(first, last, value, comp), upper_bound(first, last, value, comp)}
  • (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
#
Complexity: At most comparisons and projections.

26.8.4.5 binary_search [binary.search]

1
#
Let comp be less{} and proj be identity{} for overloads with no parameters by those names.
2
#
Preconditions: The elements e of [first, last) are partitioned with respect to the expressions bool(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.
3
#
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.
4
#
Complexity: At most comparisons and projections.