function template

std::replace

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

Replace value in range

Assigns new_value to all the elements in the range [first,last) that compare equal to old_value.

The function uses operator== to compare the individual elements to old_value.

The behavior of this function template is equivalent to:

template <class ForwardIterator, class T>
  void replace (ForwardIterator first, ForwardIterator last,
                const T& old_value, const T& new_value)
{
  while (first!=last) {
    if (*first == old_value) *first=new_value;
    ++first;
  }
}

Parameters

first, last: Forward iterators to the initial and final positions in a sequence of elements that support being compared and assigned a value of type T. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
old_value: Value to be replaced.
new_value: Replacement value.

Return value

none

Example

// replace algorithm example
#include <iostream>     // std::cout
#include <algorithm>    // std::replace
#include <vector>       // std::vector

int main () {
  int myints[] = { 10, 20, 30, 30, 20, 10, 10, 20 };
  std::vector<int> myvector (myints, myints+8);            // 10 20 30 30 20 10 10 20

  std::replace (myvector.begin(), myvector.end(), 20, 99); // 10 99 30 30 99 10 10 99

  std::cout << "myvector contains:";
  for (std::vector<int>::iterator it=myvector.begin(); it!=myvector.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}

Output:

myvector contains: 10 99 30 30 99 10 10 99

Complexity

Linear in the distance between first and last: Compares each element and assigns to those matching.

Data races

The objects in the range [first,last) are accessed and potentially modified.

Exceptions

Throws if any of the element comparisons, element assignments or operations on iterators throw.
Note that invalid arguments cause undefined behavior.