std::search_n

equality (1)	template <class ForwardIterator, class Size, class T> ForwardIterator search_n (ForwardIterator first, ForwardIterator last, Size count, const T& val);
predicate (2)	template <class ForwardIterator, class Size, class T, class BinaryPredicate> ForwardIterator search_n ( ForwardIterator first, ForwardIterator last, Size count, const T& val, BinaryPredicate pred );

equality (1)

template <class ForwardIterator, class Size, class T>   ForwardIterator search_n (ForwardIterator first, ForwardIterator last,                             Size count, const T& val);

predicate (2)

template <class ForwardIterator, class Size, class T, class BinaryPredicate>   ForwardIterator search_n ( ForwardIterator first, ForwardIterator last,                              Size count, const T& val, BinaryPredicate pred );

Search range for elements

Searches the range [first,last) for a sequence of count elements, each comparing equal to val (or for which pred returns true).

The function returns an iterator to the first of such elements, or last if no such sequence is found.

The behavior of this function template is equivalent to:

template<class ForwardIterator, class Size, class T>
  ForwardIterator search_n (ForwardIterator first, ForwardIterator last,
                            Size count, const T& val)
{
  ForwardIterator it, limit;
  Size i;

  limit=first; std::advance(limit,std::distance(first,last)-count);

  while (first!=limit)
  {
    it = first; i=0;
    while (*it==val)       // or: while (pred(*it,val)) for the pred version
      { ++it; if (++i==count) return first; }
    ++first;
  }
  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.
count: Minimum number of successive elements to match.
Size shall be (convertible to) an integral type.
val: Individual value to be compared, or to be used as argument for pred (in the second version).
for the first version, T shall be a type supporting comparisons with the elements pointed by InputIterator using operator== (with the elements as left-hand size operands, and val as right-hand side).
pred: Binary function that accepts two arguments (one element from the sequence as first, and val as second), and returns a value convertible to bool. The value returned indicates whether the element is considered a 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 sequence.
If no such sequence is found, the function returns last.

Example

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

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

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

  std::vector<int>::iterator it;

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

  if (it!=myvector.end())
    std::cout << "two 30s found at position " << (it-myvector.begin()) << '\n';
  else
    std::cout << "match not found\n";

  // using predicate comparison:
  it = std::search_n (myvector.begin(), myvector.end(), 2, 10, mypredicate);

  if (it!=myvector.end())
    std::cout << "two 10s found at position " << int(it-myvector.begin()) << '\n';
  else
    std::cout << "match not found\n";

  return 0;
}

Output:

Two 30s found at position 2
Two 10s found at position 5

Complexity

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

Data races

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

Exceptions

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