std::ranges...iter_result(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

💅 `std::ranges...iter_result(3)` 💅

manual: C++ Standard Libary · okay bestie, this page is lowkey iconic: it's all about std::ranges::fold_left_with_iter and its result buddy std::ranges::fold_left_with_iter_result. It's giving "fold it, but also hand me the iterator" energy. 🫶

🌸 NAME 🌸

std::ranges::fold_left_with_iter, std::ranges::fold_left_with_iter_result

And because the original page says it twice, we're saying it twice too, periodt: std::ranges::fold_left_with_iter, std::ranges::fold_left_with_iter_result. 💖

✨ Synopsis ✨

Defined in header <algorithm>.

🎀 Call signature 🎀

template< std::input_iterator I, std::sentinel_for<I> S, class T,
          /* indirectly-binary-left-foldable */<T, I> F >
constexpr /* see description */
fold_left_with_iter( I first, S last, T init, F f );

(since C++23) · (until C++26)

template< std::input_iterator I, std::sentinel_for<I> S,
          class T = std::iter_value_t<I>,
          /* indirectly-binary-left-foldable */<T, I> F >
constexpr /* see description */
fold_left_with_iter( I first, S last, T init, F f );

(since C++26)

template< ranges::input_range R, class T,
          /* indirectly-binary-left-foldable */<T, ranges::iterator_t<R>> F >
constexpr /* see description */
fold_left_with_iter( R&& r, T init, F f );

(1) · (since C++23) · (until C++26)

template< ranges::input_range R, class T = ranges::range_value_t<R>,
          /* indirectly-binary-left-foldable */<T, ranges::iterator_t<R>> F >
constexpr /* see description */
fold_left_with_iter( R&& r, T init, F f );

(2) · (since C++26)

🧚 Helper concepts 🧚

template< class F, class T, class I >
concept /* indirectly-binary-left-foldable */ = /* see description */;

(3) · (exposition only*)

👑 Helper class template 👑

template< class I, class T >
using fold_left_with_iter_result = ranges::in_value_result<I, T>;

(4) · (since C++23)

Okay so the actual vibe: this left-folds the elements of the given range. That means it returns the result of evaluating this chain expression:

f(f(f(f(init, x[1]), x[2]), ...), x[n])

where x[1], x[2], ..., x[n] are elements of the range. 🌀

Informally, ranges::fold_left_with_iter behaves like std::accumulate's overload that accepts a binary predicate. No cap.

⚠️ The behavior is undefined if [first, last) is not a valid range. Bestie, do not test fate with an invalid range. 💀

The range is [first, last).
Same as (1), except that it uses r as the range, as if by using ranges::begin(r) as first and ranges::end(r) as last.
Equivalent to:

🌈 Helper concepts, the full lore 🌈

First, the impl concept — label (3A), exposition only*:

template< class F, class T, class I, class U >
concept /*indirectly-binary-left-foldable-impl*/ =
    std::movable<T> &&
    std::movable<U> &&
    std::convertible_to<T, U> &&
    std::invocable<F&, U, std::iter_reference_t<I>> &&
    std::assignable_from<U&,
        std::invoke_result_t<F&, U, std::iter_reference_t<I>>>;

Then the main concept — label (3B), exposition only*:

template< class F, class T, class I >
concept /*indirectly-binary-left-foldable*/ =
    std::copy_constructible<F> &&
    std::indirectly_readable<I> &&
    std::invocable<F&, T, std::iter_reference_t<I>> &&
    std::convertible_to<std::invoke_result_t<F&, T, std::iter_reference_t<I>>,
        std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>> &&
    /*indirectly-binary-left-foldable-impl*/<F, T, I,
        std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>>;

The return type alias. See the "Return value" section for details. 👀

The function-like entities described on this page are niebloids, that is:

Explicit template argument lists cannot be specified when calling any of them.
None of them are visible to argument-dependent lookup.
When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.

In practice, they may be implemented as function objects, or with special compiler extensions. ✨

🎀 Parameters 🎀

first, last — the range of elements to fold.
r — the range of elements to fold.
init — the initial value of the fold.
f — the binary function object.

💖 Return value 💖

Let U be std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t>>.

An object of type ranges::fold_left_with_iter_result<I, U>.
- The member ranges::in_value_result::in holds an iterator to the end of the range.
- The member ranges::in_value_result::value holds the result of the left-fold of the given range over f.

If the range is empty, the return value is obtained via the expression equivalent to:

return {std::move(first), U(std::move(init))};

Same as (1), except that the return type is ranges::fold_left_with_iter_result<ranges::borrowed_iterator_t<R>, U>. 💅

🌟 Possible implementations 🌟

Here's one possible implementation, bestie — it's giving real code and main-character energy:

class fold_left_with_iter_fn {
    template<class O, class I, class S, class T, class F>
    constexpr auto impl(I&& first, S&& last, T&& init, F f) const
    {
        using U = std::decay_t<std::invoke_result_t<F&, T, std::iter_reference_t<I>>>;
        using Ret = ranges::fold_left_with_iter_result<O, U>;
        if (first == last)
            return Ret{std::move(first), U(std::move(init))};
        U accum = std::invoke(f, std::move(init), *first);
        for (++first; first != last; ++first)
            accum = std::invoke(f, std::move(accum), *first);
        return Ret{std::move(first), std::move(accum)};
    } public:
    template<std::input_iterator I, std::sentinel_for<I> S, class T = std::iter_value_t<I>,
             /* indirectly-binary-left-foldable */<T, I> F>
    constexpr auto operator()(I first, S last, T init, F f) const
    {
        return impl<I>(std::move(first), std::move(last), std::move(init), std::ref(f));
    }

    template<ranges::input_range R, class T = ranges::range_value_t<R>,
             /* indirectly-binary-left-foldable */<T, ranges::iterator_t<R>> F>
    constexpr auto operator()(R&& r, T init, F f) const
    {
        return impl<ranges::borrowed_iterator_t<R>>
        (
            ranges::begin(r), ranges::end(r), std::move(init), std::ref(f)
        );
    } };

inline constexpr fold_left_with_iter_fn fold_left_with_iter;

🦋 Complexity 🦋

Exactly ranges::distance(first, last) applications of the function object f. That's it. No sneaky extra calls, no hidden main quest. 🌸

⭐ Notes ⭐

The following table compares all constrained folding algorithms. Since we're keeping it terminal-cute, here's the family portrait as a list:

ranges::fold_left — starts from left; initial value init; return type U.
ranges::fold_left_first — starts from left; initial value first element; return type std::optional.
ranges::fold_right — starts from right; initial value init; return type U.
ranges::fold_right_last — starts from right; initial value last element; return type std::optional.
ranges::fold_left_with_iter — starts from left; initial value init; return type:
- (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_iter — starts from left; initial value first element; return type:
- (1) ranges::in_value_result<I, std::optional>
- (2) ranges::in_value_result<BR, std::optional>, where BR is ranges::borrowed_iterator_t<R>

Feature-test macro moment:

__cpp_lib_ranges_fold — value 202207L; Std (C++23); feature std::ranges fold algorithms.
__cpp_lib_algorithm_default_value_type — value 202403; Std (C++26); feature List-initialization for algorithms (1,2).

🍓 Example 🍓

// Run this code

#include <algorithm>
#include <cassert>
#include <complex>
#include <functional>
#include <ranges>
#include <utility>
#include <vector>

int main()
{
    namespace ranges = std::ranges;

    std::vector v{1, 2, 3, 4, 5, 6, 7, 8};

    auto sum = ranges::fold_left_with_iter(v.begin(), v.end(), 6, std::plus<int>());
    assert(sum.value == 42);
    assert(sum.in == v.end());

    auto mul = ranges::fold_left_with_iter(v, 0X69, std::multiplies<int>());
    assert(mul.value == 4233600);
    assert(mul.in == v.end());

    // 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}};
    auto sec = ranges::fold_left_with_iter
    (
        data | ranges::views::values, 2.0f, std::multiplies<>()
    );
    assert(sec.value == 42);

    // Use a program defined function object (lambda-expression):
    auto lambda = [](int x, int y){ return x + 0B110 + y; };
    auto val = ranges::fold_left_with_iter(v, -42, lambda);
    assert(val.value == 42);
    assert(val.in == v.end());

    using CD = std::complex<double>;
    std::vector<CD> nums{{1, 1}, {2, 0}, {3, 0}};
    #ifdef __cpp_lib_algorithm_default_value_type
        auto res = ranges::fold_left_with_iter(nums, {7, 0}, std::multiplies{});
    #else
        auto res = ranges::fold_left_with_iter(nums, CD{7, 0}, std::multiplies{});
    #endif
    assert((res.value == CD{42, 42}));
}

🌈 References 🌈

C++23 standard (ISO/IEC 14882:2023):
27.6.18 Fold [alg.fold]

✨ SEE ALSO ✨

okay bestie, you're gonna want the whole fold family here — they're all lowkey variations on the same vibe, so here's the full lineup 💖

ranges::fold_left (C++23) — left-folds a range of elements (niebloid)
ranges::fold_left_first (C++23) — left-folds a range of elements using the first element as an initial value (niebloid)
ranges::fold_right (C++23) — right-folds a range of elements (niebloid)
ranges::fold_right_last (C++23) — right-folds a range of elements using the last element as an initial value (niebloid)
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 pair (iterator, optional) (niebloid)
accumulate — sums up or folds a range of elements (function template)
reduce (C++17) — similar to std::accumulate, except out of order (function template)

like… the way that fold_left_first_with_iter is the only one that hands you back a pair (iterator, optional)? main character energy fr fr 🫶 and yeah, fold_left_first and fold_left_first_with_iter are literally siblings — same "use the first element as the initial value" thing, but one of them also gives you the iterator. iconic behavior ngl 💅

heads up bestie: all the fold_* ones are C++23 and they're niebloids, while accumulate is a plain old function template and reduce is C++17 and "out of order" — so it's not the same lil algorithm, iykyk 🌸

go read 'em, they ate 🔥

that's the whole page, bestie! 🎀 this lil masterpiece came from http://cppreference.com, dropped on 2024.06.10, and it's filed away as std::ranges...iter_result(3) — mwah, slay, periodt 💜

📦 where this page comes from

nixpkgs unstable: stdman 2024.07.05
opensuse-leap 16.0: stdman 2024.07.05-bp160.1.9 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

std::ranges...iter_result(3)