equal

Test whether two ranges are equal

You're viewing an older version of this page (#5923). View the current version.

Definition

The equal() algorithm is defined in the standard header <algorithm> and in the nonstandard backward-compatibility header <algo.h>.

Interface

#include <algorithm>
template < class InputIterator1, class InputIterator2 >
   bool equal(
      InputIterator1 first1,
      InputIterator1 last1,
      InputIterator2 first2
      );
template < class InputIterator1,
           class InputIterator2,
           class BinaryPredicate >
   bool equal(
      InputIterator1 first1,
      InputIterator1 last1,
      InputIterator2 first2,
      BinaryPredicate comp
      );

Parameters:

Parameter	Description
first1	An input iterator addressing the position of the first element in the first range to be tested
last1	An input iterator addressing the position one past the final element in the first range to be tested
first2	An input iterator addressing the position of the first element in the second range to be tested
comp	User-defined predicate function object that defines the condition to be satisfied if two elements are to be taken as equivalent. A binary predicate takes two arguments and returns true when satisfied and false when not satisfied

Description

Compares two ranges element by element either for equality or equivalence in a sense specified by a binary predicate.

Return Value

The first version of equal returns true if and only if for every iterator i in [first1, last1), *i == *(first2 + (i - first1)).

The second version of equal returns true if and only if for every iterator i in [first1, last1), comp(*i, *(first2 + (i - first1))) is true.

Complexity

The time complexity of the algorithm is linear in the number of elements contained in the range, at most last1 - first1 comparisons.

References

http://msdn.microsoft.com/en-us

Example 1

Problem

This program illustrates the use of the STL equal() algorithm (default version) to test whether the integers in a range of integers in one vector are the same as the integers in another range in a different vector.

Workings

#include <iostream>
#include <vector>
#include <algorithm>

using namespace std;

int main()
{
  int a1[] = {4, 3, 7, 5, 6};
  vector<int> v1(a1, a1+5);
  cout <<"\nHere are the contents of v1:\n";
  for (vector<int>::size_type i=0; i<v1.size(); i++)
    cout <<v1.at(i)<<" ";

  int a2[] = {1, 2, 4, 3, 7, 5, 6, 8, 9, 10};
  vector<int> v2(a2, a2+10);
  cout <<"\nHere are the contents of v2:\n";
  for (vector<int>::size_type i=0; i<v2.size(); i++)
    cout <<v2.at(i)<<" ";

  cout <<"\nFirst we compare the sequence in v1 and the sequence "
         "starting\nat the beginning of v2, and ask whether they match.";
  if (equal(v1.begin(), v1.end(), v2.begin()))
    cout <<"\nYes, they match.";
  else
    cout <<"\nNo, they don't match.";

  cout <<"\nThen we compare the sequence in v1 with the sequence "
         "starting\nat the third value of v2, and ask whether they match.";
  if (equal(v1.begin(), v1.end(), v2.begin()+2))
    cout <<"\nYes, they match.";
  else
    cout <<"\nNo, they don't match.";

  return 0;
}

Solution

Output:

Here are the contents of v1:
4 3 7 5 6

Here are the contents of v2:
1 2 4 3 7 5 6 8 9 10

First we compare the sequence in v1 and the sequence starting
at the beginning of v2, and ask whether they match.
No, they don't match.

Then we compare the sequence in v1 with the sequence starting
at the third value of v2, and ask whether they match.
Yes, they match.

References

http://www.smu.ca/academic/science/compsci/

Example 2

Problem

The following example demonstrates both forms of equal().

The first call checks whether the elements have values with equal elements. The second call uses an auxiliary predicate function to check whether the elements of both collections have corresponding even and odd elements.

Workings

#include <iostream>
#include <vector>
#include <algorithm>

using namespace std;

int main()
{
  vector<int> coll1;
  list<int> coll2;

  INSERT_ELEMENTS(coll1,1,7);
  INSERT_ELEMENTS(coll2,3,9);

  PRINT_ELEMENTS(coll1,"coll1: ");
  PRINT_ELEMENTS(col12,"col12: ");
  
  //check whether both collections are equal
  if (equal (coll1. begin(), coll1. end(),  //first range
                             coll2.begin())) //second range
    cout <<"coll1 == col12"<<endl;
  else
    cout <<"coll1 != coll2"<<endl;

  //check for corresponding even and odd elements
  if (equal (coll1.begin(), coll1.end(),   //first range
                            coll2. begin(), //second range
                            bothEvenOrOdd)) //comparison criterion
    cout <<"even and odd elements correspond"<<endl;
  else 
    cout <<"even and odd elements do not correspond"<<endl;

  return 0;
}

Solution

Output:

coll1: 1 2 3 4 5 6 7
coll2: 3 4 5 6 7 8 9
coll1 != coll2
even and odd elements correspond

References

Nicolai M. Josuttis: "The C++ Standard Library"

Definition

Interface

Description

Return Value

Complexity

References

Example 1

Example 2

See Also