Defined in header
template<classInputIt,classOutputIt,classT>OutputItremove_copy(InputItfirst,InputItlast,OutputItd_first,constT&value); (1)(constexpr since C++20)
(until C++26)template<classInputIt,classOutputIt,classT=typenamestd::iterator_traits<InputIt>::value_type>constexprOutputItremove_copy(InputItfirst,InputItlast,OutputItd_first,constT&value);(since C++26)template<classInputIt,classOutputIt,classUnaryPred>OutputItremove_copy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredp); (2)(constexpr since C++20)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classT>ForwardIt2remove_copy(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,constT&value); (3)(since C++17)
(until C++26)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classT=typenamestd::iterator_traits<ForwardIt1>::value_type>ForwardIt2remove_copy(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,constT&value);(since C++26)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classUnaryPred>ForwardIt2remove_copy_if(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,UnaryPredp); (4) (since C++17)Copies elements from the source range [first, last) to the destination range beginning at d_first, ignoring the elements which satisfy specific criteria.
1)remove_copy ignores all elements that are equal to value (using operator==).
2)remove_copy_if ignores all elements for which predicate p returns true.
3,4) Same as (1,2), but executed according to policy.
These overloads participate in overload resolution only if the value of the following expression is true:
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)If *d_first=*first is invalid(until C++20)*first is not
to d_first(since C++20), the program is ill-formed.
If the source and destination ranges overlap, the behavior is undefined.
Parameters
first, last - the pair of iterators defining the source
d_first - the beginning of the destination range value - the value of the elements not to copy p - unary predicate which returns true if the element should not be copied. The expression p(v) must be convertible to bool for every argument v of type (possibly const) VT, where VT is the value type of InputIt, regardless of
, and must not modify v. Thus, a parameter type of VT&is not allowed, nor is VT unless for VT a move is equivalent to a copy(since C++11).
policy - the
to use Type requirements -InputIt must meet the requirements of
. -OutputIt must meet the requirements of
. -ForwardIt1, ForwardIt2 must meet the requirements of
. -UnaryPred must meet the requirements of
. Return value
The past-the-end iterator of the destination range.
Complexity
Given N as std::distance(first,last):
1) Exactly N comparisons with value using operator==.
2) Exactly N applications of the predicate p.
3)𝓞(N) comparisons with value using operator==.
4)𝓞(N) applications of the predicate p.
Exceptions
3,4) During the execution process:
If the temporary memory resources required for parallelization are not available,
is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for
,
is invoked).
Notes
For parallel algorithm overloads, there may be a performance cost if ForwardIt1's value type is not
.
macroValueStdFeature
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Possible implementation
template<classInputIt,classOutputIt,classT=typenamestd::iterator_traits<InputIt>::value_type>constexprOutputItremove_copy(InputItfirst,InputItlast,OutputItd_first,constT&value){for(;first!=last;++first)if(!(*first==value))*d_first++=*first;returnd_first;}
template<classInputIt,classOutputIt,classUnaryPred>constexprOutputItremove_copy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredp){for(;first!=last;++first)if(!p(*first))*d_first++=*first;returnd_first;}Example
Run this code
#include<algorithm>#include<complex>#include<iomanip>#include<iostream>#include<iterator>#include<string>#include<vector>intmain(){// Erase the hash characters '#' on the fly.std::stringstr="#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#elsestd::complex<double>{1,3});#endif}Output:
before: "#Return #Value #Optimization" after: "Return Value Optimization" (2,2)(4,8) Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 T was required to be
, but
the value type of InputIt is not always Trequired *d_first=*first
to be valid instead See also
ranges::remove_copyranges::remove_copy_if
(C++20)(C++20)
copies a range of elements omitting those that satisfy specific criteria
(algorithm function object)
removes elements satisfying specific criteria
(function template & algorithm function object)
ranges::removeranges::remove_if
(C++20)(C++20)
(C++11)
copies a range of elements to a new location
(function template & algorithm function object)
(C++20)(C++20)
(C++11)
copies a range dividing the elements into two groups
(function template & algorithm function object)
(C++20)