Defined in header
template<classInputIt,classOutputIt,classT>OutputItreplace_copy(InputItfirst,InputItlast,OutputItd_first,constT&old_value,constT&new_value); (1)(constexpr since C++20)template<classInputIt,classOutputIt,classUnaryPred,classT>OutputItreplace_copy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredp,constT&new_value); (2)(constexpr since C++20)
(until C++26)template<classInputIt,classOutputIt,classUnaryPred,classT=typenamestd::iterator_traits<OutputIt>::value_type>constexprOutputItreplace_copy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredp,constT&new_value);(since C++26)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classT>ForwardIt2replace_copy(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,constT&old_value,constT&new_value); (3) (since C++17)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classUnaryPred,classT>ForwardIt2replace_copy_if(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,UnaryPredp,constT&new_value); (4)(since C++17)
(until C++26)template<classExecutionPolicy,classForwardIt1,classForwardIt2,classUnaryPred,classT=typenamestd::iterator_traits<ForwardIt2>::value_type>ForwardIt2replace_copy_if(ExecutionPolicy&&policy,ForwardIt1first,ForwardIt1last,ForwardIt2d_first,UnaryPredp,constT&new_value);(since C++26)Copies the elements from the source range [first, last) to the destination range d_first, while replacing all elements satisfying specific criteria with new_value.
1)replace_copy replaces all elements that are equal to old_value (using operator==).
2)replace_copy_if replaces 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 any of the results of the expressions *first and new_value is not
to d_first, 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 old_value - the value of elements to replace p - unary predicate which returns true if the element value should be replaced. 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).
new_value - the value to use as replacement 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
. Return value
The past-the-end iterator of the destination range.
Complexity
Given N as std::distance(first,last):
1) Exactly N comparisons using operator==.
2) Exactly N applications of the predicate p.
3)𝓞(N) comparisons 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
macroValueStdFeature
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Possible implementation
template<classInputIt,classOutputIt,classT>OutputItreplace_copy(InputItfirst,InputItlast,OutputItd_first,constT&old_value,constT&new_value){for(;first!=last;++first)*d_first++=(*first==old_value)?new_value:*first;returnd_first;}
template<classInputIt,classOutputIt,classUnaryPred,classT=typenamestd::iterator_traits<ForwardIt>::value_type>OutputItreplace_copy_if(InputItfirst,InputItlast,OutputItd_first,UnaryPredp,constT&new_value){for(;first!=last;++first)*d_first++=p(*first)?new_value:*first;returnd_first;}Example
Run this code
#include<algorithm>#include<complex>#include<iostream>#include<vector>voidprintln(constauto&seq){for(constauto&e:seq)std::cout<<e<<' ';std::cout<<'\n';}intmain(){std::vector<short>src{3,1,4,1,5,9,2,6,5};println(src);std::vector<int>dst(src.size());std::replace_copy_if(src.cbegin(),src.cend(),dst.begin(),[](shortn){returnn>5;},0);println(dst);std::vector<std::complex<double>>src2{{1,3},{2,4},{3,5}},dst2(src2.size());println(src2);#ifdef __cpp_lib_algorithm_default_value_typestd::replace_copy_if(src2.cbegin(),src2.cend(),dst2.begin(),[](std::complex<double>z){returnstd::abs(z)<5;},{4,2});// Possible, since the T is deduced.#elsestd::replace_copy_if(src2.cbegin(),src2.cend(),dst2.begin(),[](std::complex<double>z){returnstd::abs(z)<5;},std::complex<double>{4,2});#endifprintln(dst2);}Output:
3 1 4 1 5 9 2 6 5 3 1 4 1 5 0 2 0 5 (1,3) (2,4) (3,5) (4,2) (4,2) (3,5) 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
(and
for
replace_copy), but the value type of InputIt is not always Tremoved the requirement
C++98 replace_copy_if only required InputIt to
meet the requirements of
corrected to
The actual defect in the C++ standard is that the template parameter InputIterator was misspecified as Iterator. This affects the type requirements because the C++ standard states that for the function templates in the algorithms library, the template type parameters whose name ends with Iterator imply the type requirements of the corresponding iterator categories.
See also