std::adjacent_find

equality (1)	template <class ForwardIterator> ForwardIterator adjacent_find (ForwardIterator first, ForwardIterator last);
predicate (2)	template <class ForwardIterator, class BinaryPredicate> ForwardIterator adjacent_find (ForwardIterator first, ForwardIterator last, BinaryPredicate pred);

equality (1)

template <class ForwardIterator>   ForwardIterator adjacent_find (ForwardIterator first, ForwardIterator last);

predicate (2)

template <class ForwardIterator, class BinaryPredicate>   ForwardIterator adjacent_find (ForwardIterator first, ForwardIterator last,                                  BinaryPredicate pred);

Find equal adjacent elements in range

Searches the range [first,last) for the first occurrence of two consecutive elements that match, and returns an iterator to the first of these two elements, or last if no such pair is found.

Two elements match if they compare equal using operator== (or using pred, in version (2)).

The behavior of this function template is equivalent to:

template <class ForwardIterator>
   ForwardIterator adjacent_find (ForwardIterator first, ForwardIterator last)
{
  if (first != last)
  {
    ForwardIterator next=first; ++next;
    while (next != last) {
      if (*first == *next)     // or: if (pred(*first,*next)), for version (2)
        return first;
      ++first; ++next;
    }
  }
  return last;
}

Parameters

first, last: Forward iterators to the initial and final positions of the searched sequence. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
pred: Binary function that accepts two elements as arguments, and returns a value convertible to bool. The returned value indicates whether the elements are considered to match in the context of this function.
The function shall not modify any of its arguments.
This can either be a function pointer or a function object.

Return value

An iterator to the first element of the first pair of matching consecutive elements in the range [first,last).
If no such pair is found, the function returns last.

Example

// adjacent_find example
#include <iostream>     // std::cout
#include <algorithm>    // std::adjacent_find
#include <vector>       // std::vector

bool myfunction (int i, int j) {
  return (i==j);
}

int main () {
  int myints[] = {5,20,5,30,30,20,10,10,20};
  std::vector<int> myvector (myints,myints+8);
  std::vector<int>::iterator it;

  // using default comparison:
  it = std::adjacent_find (myvector.begin(), myvector.end());

  if (it!=myvector.end())
    std::cout << "the first pair of repeated elements are: " << *it << '\n';

  //using predicate comparison:
  it = std::adjacent_find (++it, myvector.end(), myfunction);

  if (it!=myvector.end())
    std::cout << "the second pair of repeated elements are: " << *it << '\n';

  return 0;
}

Output:

the first pair of repeated elements are: 30
the second pair of repeated elements are: 10

Complexity

Up to linear in the distance between first and last: Compares elements until a match is found.

Data races

Some (or all) of the objects in the range [first,last) are accessed (once at most).

Exceptions

Throws if any element comparison (or pred) throws or if any of the operations on iterators throws.
Note that invalid arguments cause undefined behavior.