From cppreference.com
Defined in header
Call signature
template<std::input_iteratorI,std::sentinel_for<I>S,/*indirectly-binary-left-foldable*/<std::iter_value_t<I>,I>F>requiresstd::constructible_from<std::iter_value_t<I>,std::iter_reference_t<I>>constexprautofold_left_first(Ifirst,Slast,Ff); (1) (since C++23)template<ranges::input_rangeR,/*indirectly-binary-left-foldable*/<ranges::range_value_t<R>,ranges::iterator_t<R>>F>requiresstd::constructible_from<ranges::range_value_t<R>,ranges::range_reference_t<R>>constexprautofold_left_first(R&&r,Ff); (2) (since C++23)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(x1, x2), x3), ...), 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 f - the binary function object Return value
An
object containing the left-fold result, or does not contain a value 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>
macroValueStdFeature
(C++23)std::ranges
Possible implementations
structfold_left_first_fn{template<std::input_iteratorI,std::sentinel_for<I>S,/*indirectly-binary-left-foldable*/<std::iter_value_t<I>,I>F>requiresstd::constructible_from<std::iter_value_t<I>,std::iter_reference_t<I>>constexprautooperator()(Ifirst,Slast,Ff)const{usingU=decltype(ranges::fold_left(std::move(first),last,std::iter_value_t<I>(*first),f));if(first==last)returnstd::optional<U>();std::optional<U>init(std::in_place,*first);for(++first;first!=last;++first)*init=std::invoke(f,std::move(*init),*first);returnstd::move(init);}template<ranges::input_rangeR,/*indirectly-binary-left-foldable*/<ranges::range_value_t<R>,ranges::iterator_t<R>>F>requiresstd::constructible_from<ranges::range_value_t<R>,ranges::range_reference_t<R>>constexprautooperator()(R&&r,Ff)const{return(*this)(ranges::begin(r),ranges::end(r),std::ref(f));}template<ranges::forward_rangeR,/*indirectly-binary-left-foldable*/<ranges::range_value_t<R>,ranges::iterator_t<R>>F>requiresstd::constructible_from<ranges::range_value_t<R>,ranges::range_reference_t<R>>constexprautooperator()(R&&r,Ff)const{return(*this)(ranges::begin(r),ranges::next(ranges::begin(r),ranges::end(r)),std::ref(f));}};inlineconstexprfold_left_first_fnfold_left_first;Example
Run this code
#include<algorithm>#include<array>#include<functional>#include<ranges>#include<utility>intmain(){constexprstd::arrayv{1,2,3,4,5,6,7,8};static_assert(*std::ranges::fold_left_first(v.begin(),v.end(),std::plus{})==36&&*std::ranges::fold_left_first(v,std::multiplies{})==40320);constexprstd::arrayw{1,2,3,4,13,1,2,3,4,13,1,2,3,4,13,1,2,3,4,};static_assert("Find the only value that (by precondition) occurs odd number of times:"&&*std::ranges::fold_left_first(w,[](intp,intq){returnp^q;})==13);constexprautopairs=std::to_array<std::pair<char,float>>({{'A',3.0f},{'B',3.5f},{'C',4.0f}});static_assert("Get the product of all pair::second in pairs:"&&*std::ranges::fold_left_first(pairs|std::ranges::views::values,std::multiplies{})==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
(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)