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.
std::replace(v.begin(), v.end(), -1, 0); // every -1 becomes 0
Try it
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.
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
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)butreplace_if(first, last, pred, new). Mixing them up is a frequent compile error. - Complexity: exactly
last - firstcomparisons or predicate calls. - Same type:
old_valueandnew_valueare both of typeT. A call likereplace(v.begin(), v.end(), 0, 1.5)is a compile error or a narrowing surprise, so pass matching types. - Associative containers: elements of
std::setand keys ofstd::mapare const, so you cannot replace them. Erase and insert instead. - Strings: for substitution of substrings rather than single characters you need
std::string::replaceor a manual loop;std::replaceonly 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, usestd::transform. - Ranges:
std::ranges::replaceandreplace_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.