Skip to main content

std::remove_copy() algorithm

// (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 );
  • (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>>  (until C++20) std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>  (since 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

InputItLegacyInputIterator
OutputItLegacyOutputIterator
ForwardIt1
ForwardIt2
LegacyForwardIterator
*firstMust 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"
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.

std::remove_copy() algorithm

// (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 );
  • (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>>  (until C++20) std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>  (since 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

InputItLegacyInputIterator
OutputItLegacyOutputIterator
ForwardIt1
ForwardIt2
LegacyForwardIterator
*firstMust 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"
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.