26 Algorithms library [algorithms]

26.7 Mutating sequence operations [alg.modifying.operations]

26.7.5 Replace [alg.replace]

template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type>
  constexpr void replace(ForwardIterator first, ForwardIterator last,
                         const T& old_value, const T& new_value);
template<class ExecutionPolicy, class ForwardIterator,
         class T = iterator_traits<ForwardIterator>::value_type>
  void replace(ExecutionPolicy&& exec,
               ForwardIterator first, ForwardIterator last,
               const T& old_value, const T& new_value);

template<class ForwardIterator, class Predicate,
         class T = iterator_traits<ForwardIterator>::value_type>
  constexpr void replace_if(ForwardIterator first, ForwardIterator last,
                            Predicate pred, const T& new_value);
template<class ExecutionPolicy, class ForwardIterator, class Predicate,
         class T = iterator_traits<ForwardIterator>::value_type>
  void replace_if(ExecutionPolicy&& exec,
                  ForwardIterator first, ForwardIterator last,
                  Predicate pred, const T& new_value);

template<input_iterator I, sentinel_for<I> S, class Proj = identity,
         class T1 = projected_value_t<I, Proj>, class T2 = T1>
  requires indirectly_writable<I, const T2&> &&
           indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T1*>
  constexpr I
    ranges::replace(I first, S last, const T1& old_value, const T2& new_value, Proj proj = {});
template<input_range R, class Proj = identity,
         class T1 = projected_value_t<iterator_t<R>, Proj>, class T2 = T1>
  requires indirectly_writable<iterator_t<R>, const T2&> &&
           indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T1*>
  constexpr borrowed_iterator_t<R>
    ranges::replace(R&& r, const T1& old_value, const T2& new_value, Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         class Proj = identity, class T1 = projected_value_t<I, Proj>, class T2 = T1>
  requires indirectly_writable<I, const T2&> &&
           indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T1*>
  I ranges::replace(Ep&& exec, I first, S last,
                    const T1& old_value, const T2& new_value, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, class Proj = identity,
         class T1 = projected_value_t<iterator_t<R>, Proj>, class T2 = T1>
  requires indirectly_writable<iterator_t<R>, const T2&> &&
            indirect_binary_predicate<ranges::equal_to,
                                      projected<iterator_t<R>, Proj>, const T1*>
  borrowed_iterator_t<R>
    ranges::replace(Ep&& exec, R&& r, const T1& old_value, const T2& new_value,
                    Proj proj = {});

template<input_iterator I, sentinel_for<I> S, class Proj = identity,
         class T = projected_value_t<I, Proj>,
         indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_writable<I, const T&>
  constexpr I ranges::replace_if(I first, S last, Pred pred, const T& new_value, Proj proj = {});
template<input_range R, class Proj = identity, class T = projected_value_t<iterator_t<R>, Proj>,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_writable<iterator_t<R>, const T&>
  constexpr borrowed_iterator_t<R>
    ranges::replace_if(R&& r, Pred pred, const T& new_value, Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         class Proj = identity, class T = projected_value_t<I, Proj>,
         indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_writable<I, const T&>
  I ranges::replace_if(Ep&& exec, I first, S last, Pred pred,
                       const T& new_value, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, class Proj = identity,
         class T = projected_value_t<iterator_t<R>, Proj>,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_writable<iterator_t<R>, const T&>
  borrowed_iterator_t<R>
    ranges::replace_if(Ep&& exec, R&& r, Pred pred, const T& new_value, Proj proj = {});

Let E(i) be

(1.1)
bool(*i == old_value) for replace;
(1.2)
bool(pred(*i)) for replace_if;
(1.3)
bool(invoke(proj, *i) == old_value) for ranges::replace;
(1.4)
bool(invoke(pred, invoke(proj, *i))) for ranges::replace_if.

Mandates: new_value is writable ([iterator.requirements.general]) to first.

Effects: Substitutes elements referred by the iterator i in the range [first, last) with new_value, when E(i) 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);

template<input_iterator I, sentinel_for<I> S, class O,
         class Proj = identity, class T1 = projected_value_t<I, Proj>, class T2 = iter_value_t<O>>
  requires indirectly_copyable<I, O> &&
           indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T1*> &&
           output_iterator<O, const T2&>
  constexpr ranges::replace_copy_result<I, O>
    ranges::replace_copy(I first, S last, O result, const T1& old_value, const T2& new_value,
                         Proj proj = {});
template<input_range R, class O, class Proj = identity,
         class T1 = projected_value_t<iterator_t<R>, Proj>, class T2 = iter_value_t<O>>
  requires indirectly_copyable<iterator_t<R>, O> &&
           indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T1*>
           && output_iterator<O, const T2&>
  constexpr ranges::replace_copy_result<borrowed_iterator_t<R>, O>
    ranges::replace_copy(R&& r, O result, const T1& old_value, const T2& new_value,
                         Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         random_access_iterator O, sized_sentinel_for<O> OutS,
         class Proj = identity,
         class T1 = projected_value_t<I, Proj>, class T2 = iter_value_t<O>>
  requires indirectly_copyable<I, O> &&
           indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T1*> &&
           indirectly_writable<O, const T2&>
  ranges::replace_copy_result<I, O>
    ranges::replace_copy(Ep&& exec, I first, S last, O result, OutS result_last,
                         const T1& old_value, const T2& new_value, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, sized-random-access-range OutR,
         class Proj = identity, class T1 = projected_value_t<iterator_t<R>, Proj>,
         class T2 = range_value_t<OutR>>
  requires indirectly_copyable<iterator_t<R>, iterator_t<OutR>> &&
           indirect_binary_predicate<ranges::equal_to,
                                      projected<iterator_t<R>, Proj>, const T1*> &&
           indirectly_writable<iterator_t<OutR>, const T2&>
  ranges::replace_copy_result<borrowed_iterator_t<R>, borrowed_iterator_t<OutR>>
    ranges::replace_copy(Ep&& exec, R&& r, OutR&& result_r, const T1& old_value,
                         const T2& new_value, Proj proj = {});

template<input_iterator I, sentinel_for<I> S,class O, class T = iter_value_t<O>,
         class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_copyable<I, O> && output_iterator<O, const T&>
  constexpr ranges::replace_copy_if_result<I, O>
    ranges::replace_copy_if(I first, S last, O result, Pred pred, const T& new_value,
                            Proj proj = {});
template<input_range R, class O, class T = iter_value_t<O>, class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_copyable<iterator_t<R>, O> && output_iterator<O, const T&>
  constexpr ranges::replace_copy_if_result<borrowed_iterator_t<R>, O>
    ranges::replace_copy_if(R&& r, O result, Pred pred, const T& new_value,
                            Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         random_access_iterator O, sized_sentinel_for<O> OutS, class T = iter_value_t<O>,
         class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_copyable<I, O> && indirectly_writable<O, const T&>
  ranges::replace_copy_if_result<I, O>
    ranges::replace_copy_if(Ep&& exec, I first, S last, O result, OutS result_last,
                            Pred pred, const T& new_value, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, sized-random-access-range OutR,
         class T = range_value_t<OutR>, class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_copyable<iterator_t<R>, iterator_t<OutR>> &&
           indirectly_writable<OutR, const T&>
  ranges::replace_copy_if_result<borrowed_iterator_t<R>, borrowed_iterator_t<OutR>>
    ranges::replace_copy_if(Ep&& exec, R&& r, OutR&& result_r, Pred pred, const T& new_value,
                            Proj proj = {});

Let E(i) be

(6.1)
bool(*(first + (i - result)) == old_value) for replace_copy;
(6.2)
bool(pred(*(first + (i - result)))) for replace_copy_if;
(6.3)
bool(invoke(proj, *(first + (i - result))) == old_value) for ranges::replace_copy;
(6.4)
bool(invoke(pred, invoke(proj, *(first + (i - result))))) for ranges::replace_copy_if.

Let:

(7.1)
result_last be result + (last - first) for the overloads with no parameter result_last or result_r;
(7.2)
N be min(last - first, result_last - result).

Mandates: The results of the expressions *first and new_value are writable ([iterator.requirements.general]) to result.

Preconditions: The ranges [first, last) and [result, result + N) do not overlap.

Effects: Assigns through every iterator i in the range [result, result + N) a new corresponding value

(10.1)
new_value if E(i) is true or
(10.2)
*(first + (i - result)) otherwise.

Returns:

(11.1)
result + N for the overloads in namespace std.
(11.2)
{first + N, result + N} for the overloads in namespace ranges.

Complexity: Exactly N applications of the corresponding predicate and any projection.