Binary search algorithms


Functions

template<typename ForwardIter, typename Type>
ForwardIter std::lower_bound (ForwardIter first, ForwardIter last, const Type &__val)
 Finds the first position in which val could be inserted without changing the ordering.
template<typename ForwardIter, typename Type, typename Compare>
ForwardIter std::lower_bound (ForwardIter first, ForwardIter last, const Type &__val, Compare comp)
 Finds the first position in which val could be inserted without changing the ordering.
template<typename ForwardIter, typename Type>
ForwardIter std::upper_bound (ForwardIter first, ForwardIter last, const Type &__val)
 Finds the last position in which val could be inserted without changing the ordering.
template<typename ForwardIter, typename Type, typename Compare>
ForwardIter std::upper_bound (ForwardIter first, ForwardIter last, const Type &__val, Compare comp)
 Finds the last position in which val could be inserted without changing the ordering.
template<typename ForwardIter, typename Type>
pair< ForwardIter, ForwardIter > std::equal_range (ForwardIter first, ForwardIter last, const Type &__val)
 Finds the largest subrange in which val could be inserted at any place in it without changing the ordering.
template<typename ForwardIter, typename Type, typename Compare>
pair< ForwardIter, ForwardIter > std::equal_range (ForwardIter first, ForwardIter last, const Type &__val, Compare comp)
 Finds the largest subrange in which val could be inserted at any place in it without changing the ordering.
template<typename ForwardIter, typename Type>
bool std::binary_search (ForwardIter first, ForwardIter last, const Type &__val)
 Determines whether an element exists in a range.
template<typename ForwardIter, typename Type, typename Compare>
bool std::binary_search (ForwardIter first, ForwardIter last, const Type &__val, Compare comp)
 Determines whether an element exists in a range.

Detailed Description

These algorithms are variations of a classic binary search. They 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

template<typename ForwardIter, typename Type, typename Compare>
bool binary_search ForwardIter  first,
ForwardIter  last,
const Type &  __val,
Compare  comp
 

Determines whether an element exists in a range.

Parameters:
first An iterator.
last Another iterator.
val The search term.
comp A functor to use for comparisons.
Returns:
True if val (or its equivelent) 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 3087 of file stl_algo.h.

References std::lower_bound().

template<typename ForwardIter, typename Type>
bool binary_search ForwardIter  first,
ForwardIter  last,
const Type &  __val
 

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 equivelent) 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 3056 of file stl_algo.h.

References std::lower_bound().

template<typename ForwardIter, typename Type, typename Compare>
pair<ForwardIter, ForwardIter> equal_range ForwardIter  first,
ForwardIter  last,
const Type &  __val,
Compare  comp
 

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 functor 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 3007 of file stl_algo.h.

References std::advance(), std::distance(), std::lower_bound(), and std::upper_bound().

template<typename ForwardIter, typename Type>
pair<ForwardIter, ForwardIter> equal_range ForwardIter  first,
ForwardIter  last,
const Type &  __val
 

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))
but does not actually call those functions.

Definition at line 2952 of file stl_algo.h.

References std::advance(), std::distance(), std::lower_bound(), and std::upper_bound().

template<typename ForwardIter, typename Type, typename Compare>
ForwardIter lower_bound ForwardIter  first,
ForwardIter  last,
const Type &  __val,
Compare  comp
 

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.
comp A functor to use for comparisons.
Returns:
An iterator pointing to the first element "not less than" val.
The comparison function should have the same effects on ordering as the function used for the initial sort.

Definition at line 2820 of file stl_algo.h.

References std::advance(), and std::distance().

template<typename ForwardIter, typename Type>
ForwardIter lower_bound ForwardIter  first,
ForwardIter  last,
const Type &  __val
 

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.

Definition at line 2772 of file stl_algo.h.

References std::advance(), and std::distance().

Referenced by std::binary_search(), and std::equal_range().

template<typename ForwardIter, typename Type, typename Compare>
ForwardIter upper_bound ForwardIter  first,
ForwardIter  last,
const Type &  __val,
Compare  comp
 

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 functor to use for comparisons.
Returns:
An iterator pointing to the first element greater than val.
The comparison function should have the same effects on ordering as the function used for the initial sort.

Definition at line 2905 of file stl_algo.h.

References std::advance(), and std::distance().

template<typename ForwardIter, typename Type>
ForwardIter upper_bound ForwardIter  first,
ForwardIter  last,
const Type &  __val
 

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.

Definition at line 2860 of file stl_algo.h.

References std::advance(), and std::distance().

Referenced by std::equal_range().


Generated on Thu Feb 10 23:23:44 2005 for libstdc++-v3 Source by  doxygen 1.4.0