Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Algorithms

The std::replace and std::replace_if algorithms

Reference for C++ std::replace, replace_if, replace_copy and replace_copy_if: substitute values in place or into a new range, with predicates.

std::replace overwrites every element equal to an old value with a new value, in place. std::replace_if does the same for every element a predicate accepts. Both visit the whole range once and never change its size.

If you want to keep the source unchanged, use std::replace_copy or std::replace_copy_if: they read one range and write the (possibly substituted) elements to an output iterator.

C++
std::replace(v.begin(), v.end(), -1, 0);   // every -1 becomes 0

Try it

C++ Replacing values in place

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Copying while replacing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
template<class ForwardIt, class T>
void replace(ForwardIt first, ForwardIt last, const T& old_value, const T& new_value);

template<class ForwardIt, class Pred, class T>
void replace_if(ForwardIt first, ForwardIt last, Pred pred, const T& new_value);

template<class InputIt, class OutputIt, class T>
OutputIt replace_copy(InputIt first, InputIt last, OutputIt out,
                      const T& old_value, const T& new_value);

template<class InputIt, class OutputIt, class Pred, class T>
OutputIt replace_copy_if(InputIt first, InputIt last, OutputIt out,
                         Pred pred, const T& new_value);
Name Description
first, last The half-open range [first, last).
old_value Elements equal to it (by ==) are replaced.
new_value The value assigned in their place.
pred Returns true for elements to replace. Note: in replace_if the predicate comes before the new value.
out Destination for the _copy versions.

Returns: replace and replace_if return nothing (before C++20 ranges). The _copy versions return the output iterator one past the last element written. std::ranges::replace returns the end iterator.

Errors / undefined behavior: the _copy versions require that the output range does not overlap the input range.

Usage notes

  • Argument order differs: replace(first, last, old, new) but replace_if(first, last, pred, new). Mixing them up is a frequent compile error.
  • Complexity: exactly last - first comparisons or predicate calls.
  • Same type: old_value and new_value are both of type T. A call like replace(v.begin(), v.end(), 0, 1.5) is a compile error or a narrowing surprise, so pass matching types.
  • Associative containers: elements of std::set and keys of std::map are const, so you cannot replace them. Erase and insert instead.
  • Strings: for substitution of substrings rather than single characters you need std::string::replace or a manual loop; std::replace only maps one element to one element.
  • No size change: if you need to drop elements, use std::remove. To transform every element to something computed, use std::transform.
  • Ranges: std::ranges::replace and replace_if (C++20) take a range and an optional projection. The projection is applied only to the value that is compared; the new value is assigned to the whole element.