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 == *(i1).
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, *(i1)) is true. [1]
Definition
Defined in the standard header algorithm, and in the nonstandard
backwardcompatibility header algo.h.
Requirements on types
For the first version:
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.
See also
Binary Predicate, unique, remove_copy, remove_copy_if,
adjacent_find
Copyright ©
1999 Silicon Graphics, Inc. All Rights Reserved.
TrademarkInformation
webmaster@www.sgi.com