std:: unique_copy

Copies the elements from the range [ first , last ) , to another range beginning at d_first in such a way that there are no consecutive equal elements. Only the first element of each group of equal elements is copied.

If * d_first = * first is invalid (until C++20) * first is not writable to d_first (since C++20) , the program is ill-formed.

If source and destination ranges overlap, the behavior is undefined.

Given T as the value type of InputIt , if overload (1) or (3) does not satisfy all of the following conditions, the behavior is undefined:

• T is both CopyConstructible and CopyAssignable .
• All following conditions are satisfied:

• OutputIt meets the requirements of LegacyForwardIterator .
• The value type of OutputIt is also T .
• T is CopyAssignable .

Parameters

Return value

Output iterator to the element past the last written element.

Complexity

Given \(\scriptsize N\) N as std:: distance ( first, last ) :

For overloads (2,4) , there may be a performance cost if the value type of ForwardIt1 is not both CopyConstructible and CopyAssignable .

Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

• If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard policies , std::terminate is called. For any other ExecutionPolicy , the behavior is implementation-defined.
• If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation

See also the implementations in libstdc++ and libc++ .

Notes

If InputIt satisfies LegacyForwardIterator , this function rereads the input in order to detect duplicates.

Otherwise, if OutputIt satisfies LegacyForwardIterator , and the value type of InputIt is the same as that of OutputIt , this function compare * d_first to * first .

Otherwise, this function compares * first to a local element copy.

Example

#include <algorithm>
#include <iostream>
#include <iterator>
#include <string>
 
int main()
{
    std::string s1 {"A string with mmmany letters!"};
    std::cout << "Before: " << s1 << '\n';
 
    std::string s2;
    std::unique_copy(s1.begin(), s1.end(), std::back_inserter(s2),
                     [](char c1, char c2) { return c1 == 'm' && 'm' == c2; });
 
    std::cout << "After:  " << s2 << '\n';
}

Before: A string with mmmany letters!
After:  A string with many letters!

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also