libstdc++: Binary Search

libstdc++

Binary Search
Algorithms » Sorting
Collaboration diagram for Binary Search:

## Functions
template<typename _ForwardIterator, typename _Tp>
constexpr bool | std::binary_search (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val)
template<typename _ForwardIterator, typename _Tp, typename _Compare>
constexpr bool | std::binary_search (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val, _Compare __comp)
template<typename _ForwardIterator, typename _Tp>
constexpr pair< _ForwardIterator, _ForwardIterator > | std::equal_range (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val)
template<typename _ForwardIterator, typename _Tp, typename _Compare>
constexpr pair< _ForwardIterator, _ForwardIterator > | std::equal_range (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val, _Compare __comp)
template<typename _ForwardIterator, typename _Tp>
constexpr _ForwardIterator | std::lower_bound (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val)
template<typename _ForwardIterator, typename _Tp, typename _Compare>
constexpr _ForwardIterator | std::lower_bound (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val, _Compare __comp)
template<typename _ForwardIterator, typename _Tp>
constexpr _ForwardIterator | std::upper_bound (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val)
template<typename _ForwardIterator, typename _Tp, typename _Compare>
constexpr _ForwardIterator | std::upper_bound (_ForwardIterator __first, _ForwardIterator __last, const _Tp &__val, _Compare __comp)

## Detailed Description

These algorithms are variations of a classic binary search, and all assume that the sequence being searched is already sorted.

The number of comparisons will be logarithmic (and as few as possible). The number of steps through the sequence will be logarithmic for random-access iterators (e.g., pointers), and linear otherwise.

The LWG has passed Defect Report 270, which notes: The proposed resolution reinterprets binary search. Instead of thinking about searching for a value in a sorted range, we view that as an important special case of a more general algorithm: searching for the partition point in a partitioned range. We also add a guarantee that the old wording did not: we ensure that the upper bound is no earlier than the lower bound, that the pair returned by equal_range is a valid range, and that the first part of that pair is the lower bound.

The actual effect of the first sentence is that a comparison functor passed by the user doesn't necessarily need to induce a strict weak ordering relation. Rather, it partitions the range.

## Function Documentation

## ◆ binary_search() [1/2]

template<typename _ForwardIterator, typename _Tp>

bool std::binary_search | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val )
| nodiscardconstexpr

Determines whether an element exists in a range.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.

Returns
  True if __val (or its equivalent) is in [__first, __last).

Note that this does not actually return an iterator to __val. For that, use std::find or a container's specialized find member functions.

Definition at line 2223 of file stl_algo.h.

## ◆ binary_search() [2/2]

template<typename _ForwardIterator, typename _Tp, typename _Compare>

bool std::binary_search | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val,
|  | _Compare | __comp )
| nodiscardconstexpr

Determines whether an element exists in a range.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.
  __comp | A function object to use for comparisons.

Returns
  True if __val (or its equivalent) is in [__first, __last).

Note that this does not actually return an iterator to __val. For that, use std::find or a container's specialized find member functions.

The comparison function should have the same effects on ordering as the function used for the initial sort.

Definition at line 2256 of file stl_algo.h.

## ◆ equal_range() [1/2]

template<typename _ForwardIterator, typename _Tp>

pair< _ForwardIterator, _ForwardIterator > std::equal_range | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val )
| inlinenodiscardconstexpr

Finds the largest subrange in which __val could be inserted at any place in it without changing the ordering.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.

Returns
  An pair of iterators defining the subrange.

This is equivalent to

std::make_pair(lower_bound(__first, __last, __val),
upper_bound(__first, __last, __val))
std::make_pair
constexpr pair< typename __decay_and_strip< _T1 >::__type, typename __decay_and_strip< _T2 >::__type > make_pair(_T1 &&__x, _T2 &&__y)
A convenience wrapper for creating a pair from two objects.
Definition stl_pair.h:1169

but does not actually call those functions.

Definition at line 2156 of file stl_algo.h.

## ◆ equal_range() [2/2]

template<typename _ForwardIterator, typename _Tp, typename _Compare>

pair< _ForwardIterator, _ForwardIterator > std::equal_range | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val,
|  | _Compare | __comp )
| inlinenodiscardconstexpr

Finds the largest subrange in which __val could be inserted at any place in it without changing the ordering.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.
  __comp | A function object to use for comparisons.

Returns
  An pair of iterators defining the subrange.

This is equivalent to

std::make_pair(lower_bound(__first, __last, __val, __comp),
upper_bound(__first, __last, __val, __comp))

but does not actually call those functions.

Definition at line 2192 of file stl_algo.h.

## ◆ lower_bound() [1/2]

template<typename _ForwardIterator, typename _Tp>

_ForwardIterator std::lower_bound | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val )
| inlinenodiscardconstexpr

Finds the first position in which val could be inserted without changing the ordering.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.

Returns
  An iterator pointing to the first element not less than val, or end() if every element is less than val.

Definition at line 1541 of file stl_algobase.h.

## ◆ lower_bound() [2/2]

template<typename _ForwardIterator, typename _Tp, typename _Compare>

_ForwardIterator std::lower_bound | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val,
|  | _Compare | __comp )
| inlinenodiscardconstexpr

Finds the first position in which __val could be inserted without changing the ordering.

Parameters

  __first | An iterator to the start of a sorted range.
  __last | A past-the-end iterator for the sorted range.
  __val | The search term.
  __comp | A function object to use for comparisons.

Returns
  An iterator pointing to the first element not less than __val, or __last if every element is less than __val.

The comparison function should have the same effects on ordering as the function used for the initial sort.

Definition at line 1995 of file stl_algo.h.

## ◆ upper_bound() [1/2]

template<typename _ForwardIterator, typename _Tp>

_ForwardIterator std::upper_bound | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val )
| inlinenodiscardconstexpr

Finds the last position in which __val could be inserted without changing the ordering.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.

Returns
  An iterator pointing to the first element greater than __val, or __last if no elements are greater than __val.

Definition at line 2053 of file stl_algo.h.

## ◆ upper_bound() [2/2]

template<typename _ForwardIterator, typename _Tp, typename _Compare>

_ForwardIterator std::upper_bound | ( | _ForwardIterator | __first,
|  | _ForwardIterator | __last,
|  | const _Tp & | __val,
|  | _Compare | __comp )
| inlinenodiscardconstexpr

Finds the last position in which __val could be inserted without changing the ordering.

Parameters

  __first | An iterator.
  __last | Another iterator.
  __val | The search term.
  __comp | A function object to use for comparisons.

Returns
  An iterator pointing to the first element greater than __val, or __last if no elements are greater than __val.

The comparison function should have the same effects on ordering as the function used for the initial sort.

Definition at line 2084 of file stl_algo.h.