function template
<algorithm>

std::unique_copy

equality (1)
template <class InputIterator, class OutputIterator>
  OutputIterator unique_copy (InputIterator first, InputIterator last,
                              OutputIterator result);
predicate (2)
template <class InputIterator, class OutputIterator, class BinaryPredicate>
  OutputIterator unique_copy (InputIterator first, InputIterator last,
                              OutputIterator result, BinaryPredicate pred);
Copy range removing duplicates
Copies the elements in the range [first,last) to the range beginning at result, except consecutive duplicates (elements that compare equal to the element preceding).

Only the first element from every consecutive group of equivalent elements in the range [first,last) is copied.

The comparison between elements is performed by either applying operator==, or the template parameter pred (for the second version) between them.

The behavior of this function template is equivalent to:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
template <class InputIterator, class OutputIterator>
  OutputIterator unique_copy (InputIterator first, InputIterator last,
                              OutputIterator result)
{
  if (first==last) return result;

  *result = *first;
  while (++first != last) {
    typename iterator_traits<InputIterator>::value_type val = *first;
    if (!(*result == val))   // or: if (!pred(*result,val)) for version (2)
      *(++result)=val;
  }
  return ++result;
}


Parameters

first, last
Forward iterators to the initial and final positions in a sequence. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
If InputIterator is a single-pass iterator, the type it points to shall be copy-constructible and copy-assignable.
result
Output iterator to the initial position of the range where the resulting range of values is stored.
The pointed type shall support being assigned the value of an element in the range [first,last).
pred
Binary function that accepts two elements in the range as argument, and returns a value convertible to bool. The value returned indicates whether both arguments are considered equivalent (if true, they are equivalent and one of them is removed).
The function shall not modify any of its arguments.
This can either be a function pointer or a function object.

The ranges shall not overlap.

Return value

An iterator pointing to the end of the copied range, which contains no consecutive duplicates.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// unique_copy example
#include <iostream>     // std::cout
#include <algorithm>    // std::unique_copy, std::sort, std::distance
#include <vector>       // std::vector

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

int main () {
  int myints[] = {10,20,20,20,30,30,20,20,10};
  std::vector<int> myvector (9);                            // 0  0  0  0  0  0  0  0  0

  // using default comparison:
  std::vector<int>::iterator it;
  it=std::unique_copy (myints,myints+9,myvector.begin());   // 10 20 30 20 10 0  0  0  0
                                                            //                ^

  std::sort (myvector.begin(),it);                          // 10 10 20 20 30 0  0  0  0
                                                            //                ^

  // using predicate comparison:
  it=std::unique_copy (myvector.begin(), it, myvector.begin(), myfunction);
                                                            // 10 20 30 20 30 0  0  0  0
                                                            //          ^

  myvector.resize( std::distance(myvector.begin(),it) );    // 10 20 30

  // print out content:
  std::cout << "myvector contains:";
  for (it=myvector.begin(); it!=myvector.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}


Output:
myvector contains: 10 20 30

Complexity

Up to linear in the distance between first and last: Compares each pair of elements, and performs an assignment operation for those elements not matching.

Data races

The objects in the range [first,last) are accessed.
The objects in the range between result and the returned value are modified.

Exceptions

Throws if any of pred, the element comparisons, the element assignments or the operations on iterators throws.
Note that invalid arguments cause undefined behavior.

See also