A.2.1. Algorithms to Find an Object

These algorithms search an input range for a specific value or sequence of values.

Each algorithm provides two overloaded versions. The first version uses equality (==) operator of the underlying type to compare elements; the second version compares elements using the user-supplied unaryPred or binaryPred.

Simple Find Algorithms

These algorithms look for specific values and require input iterators.

find(beg, end, val)
find_if(beg, end, unaryPred)
find_if_not(beg, end, unaryPred)
count(beg, end, val)
count_if(beg, end, unaryPred)

find returns an iterator to the first element in the input range equal to val. find_if returns an iterator to the first element for which unaryPred succeeds; find_if_not returns an iterator to the first element for which unaryPred is false. All three return end if no such element exists.

count returns a count of how many times val occurs; count_if counts elements for which unaryPred succeeds.

all_of(beg, end, unaryPred)
any_of(beg, end, unaryPred)
none_of(beg, end, unaryPred)

Returns a bool indicating whether the unaryPred succeeded for all of the elements, any element, or no element respectively. If the sequence is empty, any_of returns false; all_of and none_of return true.

Algorithms to Find One of Many Values

These algorithms require forward iterators. They look for a repeated elements in the input sequence.

adjacent_find(beg, end)
adjacent_find(beg, end, binaryPred)

Returns an iterator to the first adjacent pair of duplicate elements. Returns end if there are no adjacent duplicate elements.

search_n(beg, end, count, val)
search_n(beg, end, count, val, binaryPred)

Returns an iterator to the beginning of a subsequence of count equal elements. Returns end if no such subsequence exists.

Algorithms to Find Subsequences

With the exception of find_first_of, these algorithms require two pairs of forward iterators. find_first_of uses input iterators to denote its first sequence and forward iterators for its second. These algorithms search for subsequences rather than for a single element.

search(beg1, end1, beg2, end2)
search(beg1, end1, beg2, end2, binaryPred)

Returns an iterator to the first position in the input range at which the second range occurs as a subsequence. Returns end1 if the subsequence is not found.

find_first_of(beg1, end1, beg2, end2)
find_first_of(beg1, end1, beg2, end2, binaryPred)

Returns an iterator to the first occurrence in the first range of any element from the second range. Returns end1 if no match is found.

find_end(beg1, end1, beg2, end2)
find_end(beg1, end1, beg2, end2, binaryPred)

Like search, but returns an iterator to the last position in the input range at which the second range occurs as a subsequence. Returns end1 if the second subsequence is empty or is not found.