From cppreference.com
Defined in header
Call signature
template<std::input_iteratorI,std::sentinel_for<I>S,classT,/*indirectly-binary-left-foldable*/<T,I>F>constexprautofold_left(Ifirst,Slast,Tinit,Ff); (1)(since C++23)
(until C++26)template<std::input_iteratorI,std::sentinel_for<I>S,classT=std::iter_value_t<I>,/*indirectly-binary-left-foldable*/<T,I>F>constexprautofold_left(Ifirst,Slast,Tinit,Ff);(since C++26)template<ranges::input_rangeR,classT,/*indirectly-binary-left-foldable*/<T,ranges::iterator_t<R>>F>constexprautofold_left(R&&r,Tinit,Ff); (2)(since C++23)
(until C++26)template<ranges::input_rangeR,classT=ranges::range_value_t<R>,/*indirectly-binary-left-foldable*/<T,ranges::iterator_t<R>>F>constexprautofold_left(R&&r,Tinit,Ff);(since C++26)For the definition of /*indirectly-binary-left-foldable*/, see
.
Left-
the elements of the source range, that is, returns the result of evaluation of the chain expression:
f(f(f(f(init, x1), x2), ...), xn), where x1, x2, ..., xn are elements of the source range.
1) The source range is [first, last).
2) The source range is r.
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 source
r - the source range init - the initial value of the fold f - the binary function object Return value
The left-fold result, which is init if the source range is empty.
Notes
The following table compares all constrained folding algorithms. U below is the fold result type, it is the decayed type of F's result type.
Fold function template Starts from Initial value Return type ranges::fold_leftleftinitUranges::fold_left_firstleftfirst elementstd::optional<U>ranges::fold_rightrightinitUranges::fold_right_lastrightlast elementstd::optional<U>ranges::fold_left_with_iterleftinit(1) ranges::in_value_result<I,U>
(2) ranges::in_value_result<BR,U>,
where BR is ranges::borrowed_iterator_t<R>
ranges::fold_left_first_with_iterleftfirst element(1) ranges::in_value_result<I,std::optional<U>>
(2) ranges::in_value_result<BR,std::optional<U>>
where BR is ranges::borrowed_iterator_t<R>
macro ValueStdFeature
(C++23)std::ranges
__cpp_lib_algorithm_default_value_type
(C++26)
for algorithms (
)Possible implementations
structfold_left_fn{template<std::input_iteratorI,std::sentinel_for<I>S,classT=std::iter_value_t<I>,/*indirectly-binary-left-foldable*/<T,I>F>constexprautooperator()(Ifirst,Slast,Tinit,Ff)const{usingU=std::decay_t<std::invoke_result_t<F&,T,std::iter_reference_t<I>>>;if(first==last)returnU(std::move(init));Uaccum=std::invoke(f,std::move(init),*first);for(++first;first!=last;++first)accum=std::invoke(f,std::move(accum),*first);returnstd::move(accum);}template<ranges::input_rangeR,classT=ranges::range_value_t<R>,/*indirectly-binary-left-foldable*/<T,ranges::iterator_t<R>>F>constexprautooperator()(R&&r,Tinit,Ff)const{return(*this)(ranges::begin(r),ranges::end(r),std::move(init),std::ref(f));}template<ranges::forward_rangeR,classT=ranges::range_value_t<R>,/*indirectly-binary-left-foldable*/<T,ranges::iterator_t<R>>F>constexprautooperator()(R&&r,Tinit,Ff)const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),std::move(init),std::ref(f));}};inlineconstexprfold_left_fnfold_left;Example
Run this code
#include<algorithm>#include<complex>#include<functional>#include<iostream>#include<ranges>#include<string>#include<utility>#include<vector>intmain(){namespaceranges=std::ranges;std::vectorv{1,2,3,4,5,6,7,8};intsum=ranges::fold_left(v.begin(),v.end(),0,std::plus<int>());// (1)std::cout<<"sum: "<<sum<<'\n';intmul=ranges::fold_left(v,1,std::multiplies<int>());// (2)std::cout<<"mul: "<<mul<<'\n';// get the product of the std::pair::second of all pairs in the vector:std::vector<std::pair<char,float>>data{{'A',2.f},{'B',3.f},{'C',3.5f}};floatsec=ranges::fold_left(data|ranges::views::values,2.0f,std::multiplies<>());std::cout<<"sec: "<<sec<<'\n';// use a program defined function object (lambda-expression):std::stringstr=ranges::fold_left(v,"A",[](std::strings,intx){returns+':'+std::to_string(x);});std::cout<<"str: "<<str<<'\n';usingCD=std::complex<double>;std::vector<CD>nums{{1,1},{2,0},{3,0}};#ifdef __cpp_lib_algorithm_default_value_typeautores=ranges::fold_left(nums,{7,0},std::multiplies{});// (2)#elseautores=ranges::fold_left(nums,CD{7,0},std::multiplies{});// (2)#endifstd::cout<<"res: "<<res<<'\n';}Output:
sum: 36 mul: 40320 sec: 42 str: A:1:2:3:4:5:6:7:8 res: (42,42) References
C++23 standard (ISO/IEC 14882:2024):
27.6.18 Fold [alg.fold]
See also
(C++23)
left-folds a range of elements using the first element as an initial value
(algorithm function object)
(C++23)
right-folds a range of elements
(algorithm function object)
(C++23)
right-folds a range of elements using the last element as an initial value
(algorithm function object)
(C++23)
left-folds a range of elements, and returns a
(iterator, value)
(algorithm function object)
ranges::fold_left_first_with_iter
(C++23)
left-folds a range of elements using the first element as an initial value, and returns a
(iterator,
)
(algorithm function object)
sums up or folds a range of elements
(function template)
(C++17)
similar to
, except out of order
(function template)