std::equal

equality (1)	template <class InputIterator1, class InputIterator2> bool equal (InputIterator1 first1, InputIterator1 last1, InputIterator2 first2);
predicate (2)	template <class InputIterator1, class InputIterator2, class BinaryPredicate> bool equal (InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, BinaryPredicate pred);

equality (1)

template <class InputIterator1, class InputIterator2>  bool equal (InputIterator1 first1, InputIterator1 last1,              InputIterator2 first2);

predicate (2)

template <class InputIterator1, class InputIterator2, class BinaryPredicate>  bool equal (InputIterator1 first1, InputIterator1 last1,              InputIterator2 first2, BinaryPredicate pred);

Test whether the elements in two ranges are equal

Compares the elements in the range [first1,last1) with those in the range beginning at first2, and returns true if all of the elements in both ranges match.

The elements are compared using operator== (or pred, in version (2)).

The behavior of this function template is equivalent to:

template <class InputIterator1, class InputIterator2>
  bool equal ( InputIterator1 first1, InputIterator1 last1, InputIterator2 first2 )
{
  while (first1!=last1) {
    if (!(*first1 == *first2))   // or: if (!pred(*first1,*first2)), for version 2
      return false;
    ++first1; ++first2;
  }
  return true;
}

Parameters

first1, last1: Input iterators to the initial and final positions of the first sequence. The range used is [first1,last1), which contains all the elements between first1 and last1, including the element pointed by first1 but not the element pointed by last1.
first2: Input iterator to the initial position of the second sequence. The comparison includes up to as many elements of this sequence as those in the range [first1,last1).
pred: Binary function that accepts two elements as argument (one of each of the two sequences, in the same order), and returns a value convertible to bool. The value returned 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

true if all the elements in the range [first1,last1) compare equal to those of the range starting at first2, and false otherwise.

Example

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

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

int main () {
  int myints[] = {20,40,60,80,100};               //   myints: 20 40 60 80 100
  std::vector<int>myvector (myints,myints+5);     // myvector: 20 40 60 80 100

  // using default comparison:
  if ( std::equal (myvector.begin(), myvector.end(), myints) )
    std::cout << "The contents of both sequences are equal.\n";
  else
    std::cout << "The contents of both sequences differ.\n";

  myvector[3]=81;                                 // myvector: 20 40 60 81 100

  // using predicate comparison:
  if ( std::equal (myvector.begin(), myvector.end(), myints, mypredicate) )
    std::cout << "The contents of both sequences are equal.\n";
  else
    std::cout << "The contents of both sequences differ.\n";

  return 0;
}

Output:

The contents of both sequences are equal.
The contents of both sequence differ.

Complexity

Up to linear in the distance between first1 and last1: Compares elements until a mismatch is found.

Data races

Some (or all) of the objects in both ranges 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.