std::replace, std::replace_if - cppreference.com (original) (raw)

| Defined in header | | | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------- | | (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) |

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

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

Contents

• 1 Parameters
• 2 Complexity
• 3 Exceptions
• 4 Notes
• 5 Possible implementation
• 6 Example
• 7 Defect reports
• 8 See also

[edit] Parameters

[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:

• 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

[edit] Example

#include #include #include #include #include   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(), std::placeholders::_1, 5), 55); println(s);   std::array<std::complex, 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{1, 3}, std::complex{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)

[edit] Defect reports

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

[edit] See also