Difference between revisions of "cpp/algorithm/remove copy"

Latest revision as of 21:30, 20 May 2024

Defined in header `<algorithm>`
	(1)
template< class InputIt, class OutputIt, class T > OutputIt remove_copy( InputIt first, InputIt last, OutputIt d_first, const T& value );			(constexpr since C++20) (until C++26)
template< class InputIt, class OutputIt, class T = typename std::iterator_traits <InputIt>::value_type > constexpr OutputIt remove_copy( InputIt first, InputIt last, OutputIt d_first, const T& value );			(since C++26)
		(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 );				(since C++17) (until C++26)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class T = typename std::iterator_traits <ForwardIt1>::value_type > ForwardIt2 remove_copy( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first, const T& value );				(since C++26)
template< class InputIt, class OutputIt, class UnaryPred > OutputIt remove_copy_if( InputIt first, InputIt last, OutputIt d_first, UnaryPred p );			(3)	(constexpr since C++20)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class UnaryPred > ForwardIt2 remove_copy_if( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first, UnaryPred p );			(4)	(since C++17)

Copies elements from the range [first, last), to another range beginning at d_first, omitting the elements which satisfy specific criteria.

1) Ignores all elements that are equal to value (using operator==).

3) Ignores all elements for which predicate p returns true.

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

These overloads participate in overload resolution only if

std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true.	(until C++20)
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true.	(since C++20)

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.

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` must meet the requirements of LegacyInputIterator.
- `OutputIt` must meet the requirements of LegacyOutputIterator.
- `ForwardIt1, ForwardIt2` must meet the requirements of LegacyForwardIterator.
- `UnaryPred` must meet the requirements of Predicate.

[edit] Return value

Iterator to the element past the last element copied.

[edit] Complexity

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

1,2) Exactly

N

comparisons with value using operator==.

3,4) Exactly

N

applications of the predicate p.

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

[edit] 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.

[edit] Possible implementation

remove_copy (1)

template<class InputIt, class OutputIt,
         class T = typename std::iterator_traits<InputIt>::value_type>
constexpr 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;
}

remove_copy_if (3)

template<class InputIt, class OutputIt, class UnaryPred>
constexpr OutputIt remove_copy_if(InputIt first, InputIt last,
                                  OutputIt d_first, UnaryPred p)
{
    for (; first != last; ++first)
        if (!p(*first))
            *d_first++ = *first;
    return d_first;
}

[edit] Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_algorithm_default_value_type`	202403	(C++26)	List-initialization for algorithms (1,2)

[edit] Example

Run this code

#include <algorithm>
#include <complex>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <string>
#include <vector>
 
int main()
{
    // Erase the hash characters '#' on the fly.
    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";
 
    // Erase {1, 3} value on the fly.
    std::vector<std::complex<double>> nums{{2, 2}, {1, 3}, {4, 8}, {1, 3}};
    std::remove_copy(nums.begin(), nums.end(),
                     std::ostream_iterator<std::complex<double>>(std::cout),
    #ifdef __cpp_lib_algorithm_default_value_type
                     {1, 3}); // T gets deduced
    #else
                     std::complex<double>{1, 3});
    #endif
}

Output:

before: "#Return #Value #Optimization"
after:  "Return Value Optimization"
(2,2)(4,8)

[edit] Defect reports

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

DR	Applied to	Behavior as published	Correct behavior
LWG 779	C++98	`T` was required to be EqualityComparable, but the value type of `ForwardIt` is not always `T`	required d_first = first to be valid instead

[edit] See also

removeremove_if	removes elements satisfying specific criteria (function template) [edit]
copycopy_if (C++11)	copies a range of elements to a new location (function template) [edit]
partition_copy (C++11)	copies a range dividing the elements into two groups (function template) [edit]
ranges::remove_copyranges::remove_copy_if (C++20)(C++20)	copies a range of elements omitting those that satisfy specific criteria (niebloid)[edit]

@@ Line 1: / Line 1: @@
-{{cpp/title|remove_copy | remove_copy_if}}
+{{cpp/title|remove_copy|remove_copy_if}}
 {{cpp/algorithm/navbar}}
-{{ddcl list begin}}
+{{dcl begin}}
-{{ddcl list header | algorithm}}
+{{dcl header|algorithm}}
-{{ddcl list item | num=1 |
+{{dcl rev begin|num=1}}
-template< class InputIterator, class OutputIterator, class T >
+{{dcla|anchor=1|constexpr=c++20|until=c++26|
-OutputIterator remove_copy( InputIterator first,
+template< class InputIt, class OutputIt, class T >
-                            InputIterator last,
+OutputIt remove_copy( InputIt first, InputIt last,
-                            OutputIterator d_first,
+                      OutputIt d_first, const T& value );
-                            const T& value );
 }}
-{{ddcl list item | num=2 |
+{{dcl|since=c++26|1=
-template< class InputIterator, class OutputIterator, class UnaryPredicate >
+template< class InputIt, class OutputIt,
-OutputIterator remove_copy_if( InputIterator first,
+          class T = typename std::iterator_traits
-                               InputIterator last,
+                        <InputIt>::value_type >
-                               OutputIterator d_first,
+constexpr OutputIt remove_copy( InputIt first, InputIt last,
-                               UnaryPredicate p );
+                                OutputIt d_first, const T& value );
 }}
-{{ddcl list end}}
+{{dcl rev end}}
+{{dcl rev begin|num=2}}
+{{dcl|since=c++17|until=c++26|
+template< class ExecutionPolicy,
+          class ForwardIt1, class ForwardIt2, class T >
+ForwardIt2 remove_copy( ExecutionPolicy&& policy,
+                        ForwardIt1 first, ForwardIt1 last,
+                        ForwardIt2 d_first, const T& value );
+}}
+{{dcl|since=c++26|1=
+template< class ExecutionPolicy,
+          class ForwardIt1, class ForwardIt2,
+          class T = typename std::iterator_traits
+                        <ForwardIt1>::value_type >
+ForwardIt2 remove_copy( ExecutionPolicy&& policy,
+                        ForwardIt1 first, ForwardIt1 last,
+                        ForwardIt2 d_first, const T& value );
+}}
+{{dcl rev end}}
+{{dcla|num=3|notes={{mark constexpr since c++20}}|
+template< class InputIt, class OutputIt, class UnaryPred >
+OutputIt remove_copy_if( InputIt first, InputIt last,
+                         OutputIt d_first, UnaryPred p );
+}}
+{{dcl|num=4|since=c++17|
+template< class ExecutionPolicy,
+          class ForwardIt1, class ForwardIt2, class UnaryPred >
+ForwardIt2 remove_copy_if( ExecutionPolicy&& policy,
+                           ForwardIt1 first, ForwardIt1 last,
+                           ForwardIt2 d_first, UnaryPred p );
+}}
+{{dcl end}}
+Copies elements from the range {{range|first|last}}, to another range beginning at {{c|d_first}}, omitting the elements which satisfy specific criteria.
+@1@ Ignores all elements that are equal to {{c|value}} (using {{c/core|1=operator==}}).
+@3@ Ignores all elements for which predicate {{c|p}} returns {{c|true}}.
+@2,4@ Same as {{v|1,3}}, but executed according to {{c|policy}}.
+@@ {{cpp/algorithm/parallel overload precondition|plural=yes}}
+If {{rev inl|until=c++20|{{c|1=*d_first = *first}} is invalid}}{{rev inl|since=c++20|{{c|*first}} is not [[cpp/iterator#Types and writability|writable]] to {{c|d_first}}}}, the program is ill-formed.
-Copies elements from the range {{tt|[first, last)}}, to another range beginning at {{tt|d_first}}, omitting the elements which satisfy specific criteria. The first version ignores the elements that are equal to {{tt|value}}, the second version ignores the elements for which predicate {{tt|p}} returns {{c|true}}. Source and destination ranges cannot overlap.
+If source and destination ranges overlap, the behavior is undefined.
 ===Parameters===
-{{param list begin}}
+{{par begin}}
-{{param list item | first, last | the range of elements to copy}}
+{{par|first, last|the range of elements to copy}}
-{{param list item | d_first | the beginning of the destination range. }}
+{{par|d_first|the beginning of the destination range}}
-{{param list item | value | the value of the elements not to copy}}
+{{par|value|the value of the elements not to copy}}
-{{param list end}}
+{{par exec pol}}
+{{par hreq}}
+{{par req named|InputIt|InputIterator}}
+{{par req named|OutputIt|OutputIterator}}
+{{par req named|ForwardIt1, ForwardIt2|ForwardIterator}}
+{{par req named|UnaryPred|Predicate}}
+{{par end}}
 ===Return value===
+Iterator to the element past the last element copied.
-iterator to the element past the last element copied.
 ===Complexity===
+Given {{mathjax-or|\(\scriptsize N\)|N}} as {{c|std::distance(first, last)}}:
+@1,2@ Exactly {{mathjax-or|\(\scriptsize N\)|N}} comparisons with {{c|value}} using {{c/core|1=operator==}}.
+@3,4@ Exactly {{mathjax-or|\(\scriptsize N\)|N}} applications of the predicate {{c|p}}.
-Exactly {{tt|last - first}} applications of the predicate.
+For the overloads with an ExecutionPolicy, there may be a performance cost if {{tt|ForwardIt1}}'s {{tt|value_type}} is not {{named req|MoveConstructible}}.
+===Exceptions===
+{{cpp/algorithm/parallel exceptions reporting behavior|singular=no}}
 ===Possible implementation===
-{{eq fun | 1=
+{{eq impl|title1=remove_copy (1)|ver1=1|1=
-template<class InputIterator, class OutputIterator, class T>
+template<class InputIt, class OutputIt,
-OutputIterator remove_copy(InputIterator first,
+         class T = typename std::iterator_traits<InputIt>::value_type>
-                           InputIterator last,
+constexpr OutputIt remove_copy(InputIt first, InputIt last,
-                           OutputIterator d_first,
+                               OutputIt d_first, const T& value)
-                           const T& value)
 {
      for (; first != last; ++first)
-         if (!(*first == value)) {
+         if (!(*first == value))
              *d_first++ = *first;
-        }
-    }
      return d_first;
 }
- | 2=
+|title2=remove_copy_if (3)|ver2=3|2=
-template<class InputIterator, class OutputIterator, class UnaryPredicate>
+template<class InputIt, class OutputIt, class UnaryPred>
-OutputIterator remove_copy_if(InputIterator first,
+constexpr OutputIt remove_copy_if(InputIt first, InputIt last,
-                              InputIterator last,
+                                  OutputIt d_first, UnaryPred p)
-                              OutputIterator d_first,
-                              UnaryPredicate p)
 {
      for (; first != last; ++first)
-         if (!p(*first)) {
+         if (!p(*first))
              *d_first++ = *first;
-        }
-    }
      return d_first;
 }
 }}
+===Notes===
+{{feature test macro|__cpp_lib_algorithm_default_value_type|value=202403|std=C++26|[[cpp/language/list initialization|List-initialization]] for algorithms {{vl|1,2}}}}
 ===Example===
 {{example
- | The following code outputs a string while erasing the spaces on the fly.
+|code=
- | code=
 #include <algorithm>
+#include <complex>
+#include <iomanip>
+#include <iostream>
 #include <iterator>
 #include <string>
-#include <iostream>
+#include <vector>
 int main()
 {
-     std::string str = "Text with some   spaces";
+    // Erase the hash characters '#' on the fly.
-     std::cout << "before: " << str << "\n";
+     std::string str = "#Return #Value #Optimization";
+     std::cout << "before: " << std::quoted(str) << '\n';
-     std::cout << "after:  ";
+     std::cout << "after:  \"";
      std::remove_copy(str.begin(), str.end(),
-                      std::ostream_iterator<char>(std::cout), ' ');
+                      std::ostream_iterator<char>(std::cout), '#');
-     std::cout << '\n';
+     std::cout << "\"\n";
+    // Erase {1, 3} value on the fly.
+    std::vector<std::complex<double>> nums{<!---->{2, 2}, {1, 3}, {4, 8}, {1, 3}<!---->};
+    std::remove_copy(nums.begin(), nums.end(),
+                     std::ostream_iterator<std::complex<double>>(std::cout),
+    #ifdef __cpp_lib_algorithm_default_value_type
+                     {1, 3}); // T gets deduced
+    #else
+                     std::complex<double>{1, 3});
+    #endif
 }
- | output=
+|output=
-before: Text with some   spaces
+before: "#Return #Value #Optimization"
-after:  Textwithsomespaces
+after:  "Return Value Optimization"
+(2,2)(4,8)
 }}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=779|std=C++98|before={{tt|T}} was required to be {{named req|EqualityComparable}}, but<br>the value type of {{tt|ForwardIt}} is not always {{tt|T}}|after=required {{c|1=*d_first = *first}}<br>to be valid instead}}
+{{dr list end}}
 ===See also===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/algorithm/dcl list remove}}
+{{dsc inc|cpp/algorithm/dsc remove}}
-{{dcl list end}}
+{{dsc inc|cpp/algorithm/dsc copy}}
+{{dsc inc|cpp/algorithm/dsc partition_copy}}
+{{dsc inc|cpp/algorithm/ranges/dsc remove_copy}}
+{{dsc end}}
-[[ru:cpp/algorithm/remove copy]]
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions