std::remove_copy() algorithm

od C++20

// (1)
template< class InputIt, class OutputIt, class T >
constexpr OutputIt remove_copy( InputIt first, InputIt last,
                      OutputIt d_first, const T& value );

// (2)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class T >
ForwardIt2 remove_copy( ExecutionPolicy&& policy,
                        ForwardIt1 first, ForwardIt1 last,
                        ForwardIt2 d_first, const T& value );

od C++17

// (1)
template< class InputIt, class OutputIt, class T >
OutputIt remove_copy( InputIt first, InputIt last,
                      OutputIt d_first, const T& value );

// (2)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class T >
ForwardIt2 remove_copy( ExecutionPolicy&& policy,
                        ForwardIt1 first, ForwardIt1 last,
                        ForwardIt2 d_first, const T& value );

do C++17

// (1)
template< class InputIt, class OutputIt, class T >
OutputIt remove_copy( InputIt first, InputIt last,
                      OutputIt d_first, const T& value );

• (1) Copies elements from the range [first; last), to another range beginning at d_first, omitting the elements equal to value.

• (2) Same as (1), but executed according to policy.

  Overload Resolution

  These overloads participate in overload resolution only if std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>  (do C++20) std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>  (od C++20) is true.

Undefined Behaviour

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

Parameters

first last	The range of elements to copy.
d_first	The beginning of the destination range.
value	The value of the elements not to copy.
policy	The execution policy to use. See execution policy for details.

Type requirements

InputIt	LegacyInputIterator
OutputIt	LegacyOutputIterator
ForwardIt1 ForwardIt2	LegacyForwardIterator

od C++20

*first

Must be writable to d_first.

do C++20

*first must be writable to d_first.

Return value

Iterator to the element past the last element copied.

Complexity

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

Exactly N comparisons with value using operator==.

important

For the overloads with an ExecutionPolicy, there may be a performance cost if ForwardIt1's value_type is not MoveConstructible.

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

remove_copy (1)

template<class InputIt, class OutputIt, class T>
OutputIt remove_copy(InputIt first, InputIt last, OutputIt d_first, const T& value)
{
    for (; first != last; ++first)
        if (!(*first == value))
            *d_first++ = *first;
    return d_first;
}

Examples

Main.cpp

#include <algorithm>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <string>

int main()
{
    std::string str = "#Return #Value #Optimization";
    std::cout << "before: " << std::quoted(str) << '\n';

    std::cout << "after:  \"";
    std::remove_copy(str.begin(), str.end(),
                     std::ostream_iterator<char>(std::cout), '#');
    std::cout << "\"\n";
}

Output

before: "#Return #Value #Optimization"
after:  "Return Value Optimization"