Apache C++ Standard Library Reference Guide

## equal()

Library: Algorithms

    Function

- Local Index
- Summary
- Synopsis
- Description
- Complexity
- Example
- Standards Conformance

### Local Index

No Entries

### Summary

Algorithm that compares two ranges of values for equality

### Synopsis

    #include <algorithm>

    namespace std {
      template <class InputIterator1, class InputIterator2>
      bool equal(InputIterator1 start1, InputIterator1 finish1,
                 InputIterator2 start2);

     template <class InputIterator1, class InputIterator2,
               class BinaryPredicate>
     bool equal(InputIterator1 start1, InputIterator1 finish1,
                InputIterator2 start2, BinaryPredicate
                binary_pred);
    }

### Description

The `equal()` algorithm does a pairwise comparison of all of the elements in one range with all of the elements in another range to see if they match. The first version of `equal()` uses `operator==()` as the comparison function, and the second version allows you to specify a binary predicate as the comparison function. The first version returns `true` if all of the corresponding elements are equal to each other. The second version of `equal()` returns `true` if for each pair of elements in the two ranges, the result of applying the binary predicate is true. In other words, `equal()` returns `true` if both of the following are true:

- There are at least as many elements in the second range as in the first

- For every iterator `i` in the range `[start1, finish1)` the following corresponding conditions hold:

`*i == *(start2 + (i - start1))`

or

`binary_pred(*i, *(start2 + (i - start1))) == true`

If one of these conditions is not true, `equal()` returns `false`.

This algorithm assumes that all iterators in the range `[start2, start2 + (finish1 - start1)]` are dereferenceable.

### Complexity

`equal()` performs at most `finish1 - start1` comparisons or applications of the predicate.

### Example

    //
    // equal.cpp
    //

    #include <algorithm>    // equal
    #include <functional>
    #include <iostream>
    #include <vector>

    int main ()
    {
        // Typedef for convenience.
        typedef std::vector<int, std::allocator<int> > vector;

        typedef std::ostream_iterator <vector::value_type, char,
                                 std::char_traits<char> > os_iter;

        const vector::value_type a1[] = { 1, 2, 3, 4 };
        const vector::value_type a2[] = { 1, 2, 4, 3 };

        // Set up two vectors.
        const vector v1(a1, a1 + sizeof a1 / sizeof *a1);
        const vector v2(a2, a2 + sizeof a2 / sizeof *a2);

        // Check for equality.
        bool same = std::equal(v1.begin(), v1.end(),
                               v2.begin());

        same = same && std::equal(v1.begin(), v1.end(),
                 v2.begin(), std::equal_to<vector::value_type>());

        // Output the sequences.
        std::cout << "{ ";
        std::copy(v1.begin(), v1.end(), os_iter(std::cout, " "));

        std::cout << "} == { ";
        std::copy(v2.begin(), v2.end(), os_iter(std::cout, " "));

        // Output the result.
        std::cout << "} --> " << std::boolalpha
                  << same << std::endl;

        return 0;
    }

    Program Output

    { 1 2 3 4 } == { 1 2 4 3 } --> false

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 25.1.8