std::replace_copy, std::replace_copy_if - cppreference.com (original) (raw)

Defined in header
template< class InputIt, class OutputIt, class T > OutputIt replace_copy( InputIt first, InputIt last, OutputIt d_first, const T& old_value, const T& new_value ); (1) (constexpr since C++20)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class T >ForwardIt2 replace_copy ( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first, const T& old_value, const T& new_value ); (2) (since C++17)
(3)
template< class InputIt, class OutputIt, class UnaryPred, class T > OutputIt replace_copy_if ( InputIt first, InputIt last, OutputIt d_first, UnaryPred p, const T& new_value ); (constexpr since C++20) (until C++26)
template< class InputIt, class OutputIt, class UnaryPred, class T = typename std::iterator_traits <OutputIt>::value_type > constexpr OutputIt replace_copy_if ( InputIt first, InputIt last, OutputIt d_first, UnaryPred p, const T& new_value ); (since C++26)
(4)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class UnaryPred, class T >ForwardIt2 replace_copy_if ( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first, UnaryPred p, const T& new_value ); (since C++17) (until C++26)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class UnaryPred, class T = typename std::iterator_traits <ForwardIt2>::value_type >ForwardIt2 replace_copy_if ( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first, UnaryPred p, const T& new_value ); (since C++26)

Copies the elements from the range [first, last) to another range beginning at d_first, while replacing all elements satisfying specific criteria with new_value.

  1. Replaces all elements that are equal to old_value (using operator==).

  2. Replaces 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 all following conditions are satisfied:

If any of the results of the expressions *first and new_value is not writable to d_first, the program is ill-formed.

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

Contents

[edit] Parameters

first, last - the pair of iterators defining the source range of elements to copy
d_first - the beginning of the destination range
old_value - the value of elements to replace
policy - the execution policy to use
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 value category, 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
Type requirements
-InputIt must meet the requirements of LegacyInputIterator.
-OutputIt must meet the requirements of LegacyOutputIterator.
-ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator.

[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 \(\scriptsize N\)N comparisons using operator==.

3,4) Exactly \(\scriptsize N\)N applications of the predicate p.

[edit] Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

[edit] Possible implementation

replace_copy (1)
template<class InputIt, class OutputIt, class T> OutputIt replace_copy(InputIt first, InputIt last, OutputIt d_first, const T& old_value, const T& new_value) { for (; first != last; ++first) *d_first++ = (*first == old_value) ? new_value : *first; return d_first; }
replace_copy_if (3)
template<class InputIt, class OutputIt, class UnaryPred, class T = typename std::iterator_traits<ForwardIt>::value_type> OutputIt replace_copy_if(InputIt first, InputIt last, OutputIt d_first, UnaryPred p, const T& new_value) { for (; first != last; ++first) *d_first++ = p(*first) ? new_value : *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 (3,4)

[edit] Example

#include #include #include #include   void println(const auto& seq) { for (const auto& e : seq) std::cout << e << ' '; std::cout << '\n'; }   int main() { std::vector src{3, 1, 4, 1, 5, 9, 2, 6, 5}; println(src); std::vector dst(src.size()); std::replace_copy_if(src.cbegin(), src.cend(), dst.begin(), [](short n){ return n > 5; }, 0); println(dst);   std::vector<std::complex> src2{{1, 3}, {2, 4}, {3, 5}}, dst2(src2.size()); println(src2); #ifdef __cpp_lib_algorithm_default_value_type std::replace_copy_if(src2.cbegin(), src2.cend(), dst2.begin(), z){ return std::abs(z) < 5; }, {4, 2}); // Possible, since the T is deduced. #else std::replace_copy_if(src2.cbegin(), src2.cend(), dst2.begin(), z){ return std::abs(z) < 5; }, std::complex{4, 2}); #endif println(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)

[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 283 C++98 T was required to be CopyAssignable (and EqualityComparable forreplace_copy), but the value type of InputIt is not always T removed the requirement
LWG 337 C++98 replace_copy_if only required InputIt tomeet the requirements of LegacyIterator[1] corrected toLegacyInputIterator
  1. ↑ 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.

[edit] See also