std::replace, std::replace_if

Replaces all elements in the range [first, last) with new_value if they satisfy specific criteria.

If *first = new_value is invalid(until C++20)new_value is not writable to first(since C++20), the program is ill-formed.

[edit] Parameters

[edit] Complexity

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

[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] Notes

Because the algorithm takes old_value and new_value by reference, it can have unexpected behavior if either is a reference to an element of the range [first, last).

[edit] Possible implementation

template<class ForwardIt,
 class T = typename std::iterator_traits <ForwardIt>::value_type>
void replace(ForwardIt first, ForwardIt last,
 const T& old_value, const T& new_value)
{
 for (; first != last; ++first)
 if (*first == old_value)
 *first = new_value;
}

template<class ForwardIt, class UnaryPred,
 class T = typename std::iterator_traits <ForwardIt>::value_type>
void replace_if(ForwardIt first, ForwardIt last,
 UnaryPred p, const T& new_value)
{
 for (; first != last; ++first)
 if (p(*first))
 *first = new_value;
}

[edit] Example

#include <algorithm>
#include <array>
#include <complex>
#include <functional>
#include <iostream>
 
void println(const auto& seq)
{
 for (const auto& e : seq)
 std::cout << e << ' ';
 std::cout << '\n';
}
 
int main()
{
 std::array <int, 10> s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3};
 
 // Replace all occurrences of 8 with 88.
 std::replace(s.begin(), s.end(), 8, 88);
 println(s);
 
 // Replace all values less than 5 with 55.
 std::replace_if(s.begin(), s.end(), 
 std::bind (std::less <int>(), std::placeholders::_1, 5), 55);
 println(s);
 
 std::array <std::complex <double>, 2> nums{{{1, 3}, {1, 3}}};
 #ifdef __cpp_lib_algorithm_default_value_type
 std::replace(nums.begin(), nums.end(), {1, 3}, {4, 2});
 #else
 std::replace(nums.begin(), nums.end(), std::complex <double>{1, 3},
 std::complex <double>{4, 2});
 #endif
 println(nums);
}

5 7 4 2 88 6 1 9 0 3
5 7 55 55 88 6 55 9 55 55
(4,2), (4,2)

[edit] Defect reports

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

[edit] See also