Namespaces
Variants

    std::replace, std::replace_if

    From cppreference.com
     
    C++
     
    Algorithm library
    Constrained algorithms and algorithms on ranges (C++20)
    Constrained algorithms, e.g. ranges::copy, ranges::sort, ...
    Execution policies (C++17)
    Non-modifying sequence operations
    Batch operations
    (C++17)
    Search operations
    (C++11)                (C++11)(C++11)

    Modifying sequence operations
    Copy operations
    (C++11)
    (C++11)
    (C++11)
    Swap operations
    Transformation operations
    Generation operations
    Removing operations
    Order-changing operations
    (until C++17)(C++11)
    (C++20)(C++20)
    Sampling operations
    (C++17)

    Sorting and related operations
    Partitioning operations
    Sorting operations
    Binary search operations
    (on partitioned ranges)
    Set operations (on sorted ranges)
    Merge operations (on sorted ranges)
    Heap operations
    Minimum/maximum operations
    (C++11)
    (C++17)
    Lexicographical comparison operations
    (C++20)
    Permutation operations
    C library
    Numeric operations
    Operations on uninitialized memory
     
    Defined in header <algorithm>
    (1)
    template< class ForwardIt, class T > void replace( ForwardIt first, ForwardIt last, const T& old_value, const T& new_value );
    		 (constexpr since C++20)
    (until C++26)
    template< class ForwardIt, class T = typename std::iterator_traits <ForwardIt>::value_type > constexpr void replace( ForwardIt first, ForwardIt last, const T& old_value, const T& new_value );
    		 (since C++26)
    (2)
    template< class ExecutionPolicy, class ForwardIt, class T > void replace( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, const T& old_value, const T& new_value );
    		 (since C++17)
    (until C++26)
    template< class ExecutionPolicy, class ForwardIt, class T = typename std::iterator_traits <ForwardIt>::value_type > void replace( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, const T& old_value, const T& new_value );
    		 (since C++26)
    (3)
    template< class ForwardIt, class UnaryPred, class T > void replace_if( ForwardIt first, ForwardIt last, UnaryPred p, const T& new_value );
    		 (constexpr since C++20)
    (until C++26)
    template< class ForwardIt, class UnaryPred, class T = typename std::iterator_traits <ForwardIt>::value_type> > constexpr void replace_if( ForwardIt first, ForwardIt last, UnaryPred p, const T& new_value );
    		 (since C++26)
    (4)
    template< class ExecutionPolicy, class ForwardIt, class UnaryPred, class T > void replace_if( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, UnaryPred p, const T& new_value );
    		 (since C++17)
    (until C++26)
    template< class ExecutionPolicy, class ForwardIt, class UnaryPred, class T = typename std::iterator_traits <ForwardIt>::value_type> > void replace_if( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, UnaryPred p, const T& new_value );
    		 (since C++26)
    See More

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

    1) Replaces all elements that are equal to old_value (using operator==).
    3) 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:

    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 *first = new_value is invalid(until C++20)new_value is not writable to first(since C++20), the program is ill-formed.

    Parameters

    first, last - the pair of iterators defining the range of elements to process
    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 ForwardIt, 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
    -
    ForwardIt must meet the requirements of LegacyForwardIterator.
    -
    UnaryPred must meet the requirements of Predicate.

    Complexity

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

    1,2) Exactly N comparisons using operator==.
    3,4) Exactly N applications of the predicate p.

    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.

    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).

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

    Possible implementation

    replace (1) 
    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;
}
    replace_if (3) 
    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;
}

    Example

    Run this code
    #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);
}

    Output: 

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

    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
    for replace), but the value type of ForwardIt is not
    always T and T is not always writable to ForwardIt     		required *first = new_value
    to be valid instead

    See also

    		 copies a range, replacing elements satisfying specific criteria with another value
    (function template) [edit]
    (C++20)(C++20)
    		 replaces all values satisfying specific criteria with another value
    (algorithm function object)[edit]