unique_copy


Category: algorithms	Component type: function

Prototype

Unique_copy is an overloaded name; there are actually two unique_copy functions.

template <class InputIterator, class OutputIterator>
OutputIterator unique_copy(InputIterator first, InputIterator last,
                           OutputIterator result);

template <class InputIterator, class OutputIterator, class BinaryPredicate>
OutputIterator unique_copy(InputIterator first, InputIterator last,
                           OutputIterator result,
                           BinaryPredicate binary_pred);

Description

Unique_copy copies elements from the range [first, last) to a range beginning with result, except that in a consecutive group of duplicate elements only the first one is copied. The return value is the end of the range to which the elements are copied. This behavior is similar to the Unix filter uniq.

The reason there are two different versions of unique_copy is that there are two different definitions of what it means for a consecutive group of elements to be duplicates. In the first version, the test is simple equality: the elements in a range [f, l) are duplicates if, for every iterator i in the range, either i == f or else *i == *(i-1). In the second, the test is an arbitrary Binary Predicate binary_pred: the elements in [f, l) are duplicates if, for every iterator i in the range, either i == f or else binary_pred(*i, *(i-1)) is true. [1]

Definition

Defined in the standard header algorithm, and in the nonstandard backward-compatibility header algo.h.

Requirements on types

For the first version:

InputIterator is a model of Input Iterator.
InputIterator's value type is Equality Comparable.
OutputIterator is a model of Output Iterator.
InputIterator's value type is convertible to a type in OutputIterator's set of value types.

For the second version:

InputIterator is a model of Input Iterator.
BinaryPredicate is a model of Binary Predicate. [2]
InputIterator's value type is convertible to first argument type and to BinaryPredicate's second argument type.
OutputIterator is a model of Output Iterator.
InputIterator's value type is convertible to a type in OutputIterator's set of value types.

Preconditions

[first, last) is a valid range.
There is enough space to hold all of the elements being copied. More formally, if there are n elements in the range [first, last) after duplicates are removed from consecutive groups, then [result, result + n) must be a valid range.

Complexity

Linear. Exactly last - first applications of operator== (in the case of the first version of unique) or of binary_pred (in the case of the second version), and at most last - first assignments.

Example

Print all of the numbers in an array, but only print the first one in a consecutive group of identical numbers.

const int A[] = {2, 7, 7, 7, 1, 1, 8, 8, 8, 2, 8, 8};
unique_copy(A, A + sizeof(A) / sizeof(int), 
            ostream_iterator<int>(cout, " "));
// The output is "2 7 1 8 2 8".

Notes

[1] Strictly speaking, the first version of unique_copy is redundant: you can achieve the same functionality by using an object of class equal_to as the Binary Predicate argument. The first version is provided strictly for the sake of convenience: testing for equality is an important special case.

[2] BinaryPredicate is not required to be an equivalence relation. You should be cautious, though, about using unique_copy with a Binary Predicate that is not an equivalence relation: you could easily get unexpected results.