24 Algorithms library [algorithms]

24.6 Mutating sequence operations [alg.modifying.operations]

24.6.5 Replace [alg.replace]

template<class ForwardIterator, class T> constexpr void replace(ForwardIterator first, ForwardIterator last, const T& old_value, const T& new_value); template<class ExecutionPolicy, class ForwardIterator, class T> void replace(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, const T& old_value, const T& new_value); template<class ForwardIterator, class Predicate, class T> constexpr void replace_if(ForwardIterator first, ForwardIterator last, Predicate pred, const T& new_value); template<class ExecutionPolicy, class ForwardIterator, class Predicate, class T> void replace_if(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last, Predicate pred, const T& new_value); namespace ranges { template<InputIterator I, Sentinel<I> S, class T1, class T2, class Proj = identity> requires Writable<I, const T2&> && IndirectRelation<ranges::equal_to<>, projected<I, Proj>, const T1*> constexpr I replace(I first, S last, const T1& old_value, const T2& new_value, Proj proj = {}); template<InputRange R, class T1, class T2, class Proj = identity> requires Writable<iterator_t<R>, const T2&> && IndirectRelation<ranges::equal_to<>, projected<iterator_t<R>, Proj>, const T1*> constexpr safe_iterator_t<R> replace(R&& r, const T1& old_value, const T2& new_value, Proj proj = {}); template<InputIterator I, Sentinel<I> S, class T, class Proj = identity, IndirectUnaryPredicate<projected<I, Proj>> Pred> requires Writable<I, const T&> constexpr I replace_if(I first, S last, Pred pred, const T& new_value, Proj proj = {}); template<InputRange R, class T, class Proj = identity, IndirectUnaryPredicate<projected<iterator_t<R>, Proj>> Pred> requires Writable<iterator_t<R>, const T&> constexpr safe_iterator_t<R> replace_if(R&& r, Pred pred, const T& new_value, Proj proj = {}); }
Let E be
  • bool(*i == old_­value) for replace,
  • bool(pred(*i)) for replace_­if,
  • bool(invoke(proj, *i) == old_­value) for ranges::replace, or
  • bool(invoke(pred, invoke(proj, *i))) for ranges::replace_­if.
Requires: The expression *first = new_­value shall be valid.
Effects: Substitutes elements referred by the iterator i in the range [first, last) with new_­value, when E is true.
Returns: last for the overloads in namespace ranges.
Complexity: Exactly last - first applications of the corresponding predicate and any projection.
template<class InputIterator, class OutputIterator, class T> constexpr OutputIterator replace_copy(InputIterator first, InputIterator last, OutputIterator result, const T& old_value, const T& new_value); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class T> ForwardIterator2 replace_copy(ExecutionPolicy&& exec, ForwardIterator1 first, ForwardIterator1 last, ForwardIterator2 result, const T& old_value, const T& new_value); template<class InputIterator, class OutputIterator, class Predicate, class T> constexpr OutputIterator replace_copy_if(InputIterator first, InputIterator last, OutputIterator result, Predicate pred, const T& new_value); template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class Predicate, class T> ForwardIterator2 replace_copy_if(ExecutionPolicy&& exec, ForwardIterator1 first, ForwardIterator1 last, ForwardIterator2 result, Predicate pred, const T& new_value); namespace ranges { template<InputIterator I, Sentinel<I> S, class T1, class T2, OutputIterator<const T2&> O, class Proj = identity> requires IndirectlyCopyable<I, O> && IndirectRelation<ranges::equal_to<>, projected<I, Proj>, const T1*> constexpr replace_copy_result<I, O> replace_copy(I first, S last, O result, const T1& old_value, const T2& new_value, Proj proj = {}); template<InputRange R, class T1, class T2, OutputIterator<const T2&> O, class Proj = identity> requires IndirectlyCopyable<iterator_t<R>, O> && IndirectRelation<ranges::equal_to<>, projected<iterator_t<R>, Proj>, const T1*> constexpr replace_copy_result<safe_iterator_t<R>, O> replace_copy(R&& r, O result, const T1& old_value, const T2& new_value, Proj proj = {}); template<InputIterator I, Sentinel<I> S, class T, OutputIterator<const T&> O, class Proj = identity, IndirectUnaryPredicate<projected<I, Proj>> Pred> requires IndirectlyCopyable<I, O> constexpr replace_copy_if_result<I, O> replace_copy_if(I first, S last, O result, Pred pred, const T& new_value, Proj proj = {}); template<InputRange R, class T, OutputIterator<const T&> O, class Proj = identity, IndirectUnaryPredicate<projected<iterator_t<R>, Proj>> Pred> requires IndirectlyCopyable<iterator_t<R>, O> constexpr replace_copy_if_result<safe_iterator_t<R>, O> replace_copy_if(R&& r, O result, Pred pred, const T& new_value, Proj proj = {}); }
Let E be
  • bool(*(first + (i - result)) == old_­value) for replace_­copy,
  • bool(pred(*(first + (i - result)))) for replace_­copy_­if,
  • bool(invoke(proj, *(first + (i - result))) == old_­value) for ranges::replace_­copy,
  • bool(invoke(pred, invoke(proj, *(first + (i - result))))) for ranges::replace_­copy_­if.
Requires: The results of the expressions *first and new_­value shall be writable ([iterator.requirements.general]) to the result output iterator.
The ranges [first, last) and [result, result + (last - first)) shall not overlap.
Effects: Assigns to every iterator i in the range [result, result + (last - first)) either new_­value or *(first + (i - result)) depending on whether E holds.
Returns:
  • result + (last - first) for the overloads in namespace std, or
  • {last, result + (last - first)} for the overloads in namespace ranges.
Complexity: Exactly last - first applications of the corresponding predicate and any projection.