Defined in header
Call signature
template<std::input_iteratorI,std::sentinel_for<I>S,classT1,classT2,classProj=std::identity>requiresstd::indirectly_writable<I,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT1*>constexprIreplace(Ifirst,Slast,constT1&old_value,constT2&new_value,Projproj={}); (1)(since C++20)
(until C++26)template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT1=std::projected_value_t<I,Proj>,classT2=std::iter_value_t<I>>requiresstd::indirectly_writable<I,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT1*>constexprIreplace(Ifirst,Slast,constT1&old_value,constT2&new_value,Projproj={});(since C++26)template<ranges::input_rangeR,classT1,classT2,classProj=std::identity>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT1*>constexprranges::borrowed_iterator_t<R>replace(R&&r,constT1&old_value,constT2&new_value,Projproj={}); (2)(since C++20)
(until C++26)template<ranges::input_rangeR,classProj=std::identity,classT1=std::projected_value_t<ranges::iterator_t<R>,Proj>,classT2=ranges::range_value_t<R>>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT1*>constexprranges::borrowed_iterator_t<R>replace(R&&r,constT1&old_value,constT2&new_value,Projproj={});(since C++26)template<std::input_iteratorI,std::sentinel_for<I>S,classT,classProj=std::identity,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>requiresstd::indirectly_writable<I,constT&>constexprIreplace_if(Ifirst,Slast,Predpred,constT&new_value,Projproj={}); (3)(since C++20)
(until C++26)template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT=std::iter_value_t<I>,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>requiresstd::indirectly_writable<I,constT&>constexprIreplace_if(Ifirst,Slast,Predpred,constT&new_value,Projproj={});(since C++26)template<ranges::input_rangeR,classT,classProj=std::identity,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT&>constexprranges::borrowed_iterator_t<R>replace_if(R&&r,Predpred,constT&new_value,Projproj={}); (4)(since C++20)
(until C++26)template<ranges::input_rangeR,classProj=std::identity,classT=ranges::range_value_t<R>,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT&>constexprranges::borrowed_iterator_t<R>replace_if(R&&r,Predpred,constT&new_value,Projproj={});(since C++26)template</*execution-policy*/Ep,std::random_access_iteratorI,std::sized_sentinel_for<I>S,classProj=std::identity,classT1=std::projected_value_t<I,Proj>,classT2=std::iter_value_t<I>>requiresstd::indirectly_writable<I,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT1*>Ireplace(Ep&&policy,Ifirst,Slast,constT1&old_value,constT2&new_value,Projproj={}); (5) (since C++26)template</*execution-policy*/Ep,/*sized-random-access-range*/R,classProj=std::identity,classT1=std::projected_value_t<ranges::iterator_t<R>,Proj>,classT2=ranges::range_value_t<R>>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT1*>ranges::borrowed_iterator_t<R>replace(Ep&&policy,R&&r,constT1&old_value,constT2&new_value,Projproj={}); (6) (since C++26)template</*execution-policy*/Ep,std::random_access_iteratorI,std::sized_sentinel_for<I>S,classProj=std::identity,classT=std::iter_value_t<I>,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>requiresstd::indirectly_writable<I,constT&>Ireplace_if(Ep&&policy,Ifirst,Slast,Predpred,constT&new_value,Projproj={}); (7) (since C++26)template</*execution-policy*/Ep,/*sized-random-access-range*/R,classProj=std::identity,classT=ranges::range_value_t<R>,std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT&>ranges::borrowed_iterator_t<R>replace_if(Ep&&policy,R&&r,Predpred,constT&new_value,Projproj={}); (8) (since C++26)For the definition of /*execution-policy*/, see
; for the definition of /*sized-random-access-range*/, see
.
Replaces the elements (projected by proj) in the target range [first, last) or r with new_value if they satisfy specific criteria.
1,2)replace replaces all elements that are equal to old_value (using operator==).
3,4)replace_if replaces all elements for which predicate pred returns true.
5-8) Same as (1-4), but executed according to policy.
If new_value is not
to first, the program is ill-formed.
The function-like entities described on this page are
(informally known as niebloids), that is:
Explicit template argument lists cannot be specified when calling any of them.
None of them are visible to
.
When any of them are found by
as the name to the left of the function-call operator,
is inhibited.
Parameters
first, last - the iterator-sentinel pair defining the target
r - the target range old_value - the value of elements to replace new_value - the value to use as a replacement pred - predicate to be applied to the projected elements proj - the projection to be applied to the elements policy - the
to use Return value
The past-the-end iterator of the target range.
Complexity
Given N as ranges::distance(first,last) or ranges::distance(r):
1,2) Exactly N comparisons using operator==, and exactly N applications of proj.
3,4) Exactly N applications of pred and proj.
5,6)𝓞(N) comparisons using operator==, and 𝓞(N) applications of proj.
7,8)𝓞(N) applications of pred and proj.
Exceptions
5-8) During the execution process:
If the temporary memory resources required for parallelization are not available,
is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for
,
is invoked).
Notes
Because the algorithm takes old_value and new_value by reference, it may have unexpected behavior if either is a reference to an element of the target range.
macroValueStdFeature
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Possible implementation
structreplace_fn{template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT1=std::projected_value_t<I,Proj>,classT2=T1>requiresstd::indirectly_writable<I,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<I,Proj>,constT1*>constexprIoperator()(Ifirst,Slast,constT1&old_value,constT2&new_value,Projproj={})const{for(;first!=last;++first)if(old_value==std::invoke(proj,*first))*first=new_value;returnfirst;}template<ranges::input_rangeR,classProj=std::identityclassT1=std::projected_value_t<ranges::iterator_t<R>,Proj>,classT2=T1>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT1*>constexprranges::borrowed_iterator_t<R>operator()(R&&r,constT1&old_value,constT2&new_value,Projproj={})const{return(*this)(ranges::begin(r),ranges::next(r),old_value,new_value,std::move(proj));}template<ranges::forward_rangeR,classProj=std::identityclassT1=std::projected_value_t<ranges::iterator_t<R>,Proj>,classT2=T1>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT2&>&&std::indirect_binary_predicate<ranges::equal_to,std::projected<ranges::iterator_t<R>,Proj>,constT1*>constexprranges::borrowed_iterator_t<R>operator()(R&&r,constT1&old_value,constT2&new_value,Projproj={})const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),old_value,new_value,std::move(proj));}};inlineconstexprreplace_fnreplace{};
structreplace_if_fn{template<std::input_iteratorI,std::sentinel_for<I>S,classProj=std::identity,classT=std::projected_value_t<I,Proj>,std::indirect_unary_predicate<std::projected<I,Proj>>Pred>requiresstd::indirectly_writable<I,constT&>constexprIoperator()(Ifirst,Slast,Predpred,constT&new_value,Projproj={})const{for(;first!=last;++first)if(!!std::invoke(pred,std::invoke(proj,*first)))*first=new_value;returnstd::move(first);}template<ranges::input_rangeR,classProj=std::identity,classT=std::projected_value_t<ranges::iterator_t<R>,Proj>std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT&>constexprranges::borrowed_iterator_t<R>operator()(R&&r,Predpred,constT&new_value,Projproj={})const{return(*this)(ranges::begin(r),ranges::end(r),std::move(pred),new_value,std::move(proj));}template<ranges::forward_rangeR,classProj=std::identity,classT=std::projected_value_t<ranges::iterator_t<R>,Proj>std::indirect_unary_predicate<std::projected<ranges::iterator_t<R>,Proj>>Pred>requiresstd::indirectly_writable<ranges::iterator_t<R>,constT&>constexprranges::borrowed_iterator_t<R>operator()(R&&r,Predpred,constT&new_value,Projproj={})const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),std::move(pred),new_value,std::move(proj));}};inlineconstexprreplace_if_fnreplace_if{};Example
Run this code
#include<algorithm>#include<array>#include<complex>#include<iostream>voidprintln(constauto&v){for(constauto&e:v)std::cout<<e<<' ';std::cout<<'\n';}intmain(){namespaceranges=std::ranges;std::arrayp{1,6,1,6,1,6};println(p);ranges::replace(p,6,9);println(p);std::arrayq{1,2,3,6,7,8,4,5};println(q);ranges::replace_if(q,[](intx){return5<x;},5);println(q);std::array<std::complex<double>,2>nums{{{1,3},{1,3}}};println(nums);#ifdef __cpp_lib_algorithm_default_value_typeranges::replace(nums,{1,3},{4,2});#elseranges::replace(nums,std::complex<double>{1,3},std::complex<double>{4,2});#endifprintln(nums);}Output:
1 6 1 6 1 6 1 9 1 9 1 9 1 2 3 6 7 8 4 5 1 2 3 5 5 5 4 5 (1,3) (1,3) (4,2) (4,2) See also