std::accumulate(3)

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

💖 std::accumulate(3) 💖

okay bestie, welcome to std::accumulate — a.k.a. the C++ Standard Library function that lives in std::accumulate(3) land and just... adds stuff up for you. that's it. that's the vibe. she folds, she sums, she does it in order, and she's iconic for it 🫶

✨ Synopsis ✨

first things first, she's Defined in header <numeric> — don't forget to include her or she'll ghost you 😭

template< class InputIt, class T >                       (1)
(constexpr since C++20)
T accumulate( InputIt first, InputIt last, T init );
template< class InputIt, class T, class BinaryOp >
T accumulate( InputIt first, InputIt last, T init,       (2)
(constexpr since C++20)
BinaryOp op );

so what does she actually do? she computes the sum of the given value init and the elements in the range [first, last). literally that's the whole thing 💅

  • (1) — initializes the accumulator acc (of type T) with the initial value init and then modifies it with
acc = acc + *i

(until C++20)

acc = std::move(acc) + *i

(since C++20)

for every iterator i in the range [first, last) in order. no skipping, no shuffling, in order fr fr.

  • (2) — same deal, initializes the accumulator acc (of type T) with the initial value init and then modifies it with
acc = op(acc, *i)

(until C++20)

acc = op(std::move(acc), *i)

(since C++20)

for every iterator i in the range [first, last) in order.

💀 GIRL. WARNING. if any of the following conditions is satisfied, the behavior is undefined — and undefined is not cute, undefined is chaos: - T is not CopyConstructible. - T is not CopyAssignable. - op modifies any element of [first, last). - op invalidates any iterator or subrange in [first, last].

like bestie... just don't. 🚩

🌸 Parameters 🌸

  • first, last — the range of elements to sum 🧚
  • init — initial value of the sum
  • op — binary operation function object that will be applied.

the signature of the function should be equivalent to the following:

Ret fun(const Type1 &a, const Type2 &b);

okay so about op, here's the tea ☕ — the signature does not need to have const &. The type Type1 must be such that an object of type T can be implicitly converted to Type1. The type Type2 must be such that an object of type InputIt can be dereferenced and then implicitly converted to Type2. The type Ret must be such that an object of type T can be assigned a value of type Ret. no cap, that's the whole requirement bestie 💖

🦋 Type requirements 🦋

  • InputIt must meet the requirements of LegacyInputIterator.

⭐ Return value ⭐

acc after all modifications. yes queen, the final accumulator, that's her, main character energy 👑

🎀 Possible implementation 🎀

accumulate (1)

template<class InputIt, class T>
constexpr // since C++20
T accumulate(InputIt first, InputIt last, T init)
{
    for (; first != last; ++first)
        init = std::move(init) + *first; // std::move since C++20

    return init;
}

accumulate (2)

template<class InputIt, class T, class BinaryOperation>
constexpr // since C++20
T accumulate(InputIt first, InputIt last, T init, BinaryOperation op)
{
    for (; first != last; ++first)
        init = op(std::move(init), *first); // std::move since C++20

    return init;
}

🧚 Notes 🧚

std::accumulate performs a left fold. so if you're sitting there like "okay but what if I want a right fold" — you gotta reverse the order of the arguments to the binary operator, and use reverse iterators. iykyk 😌

and this next part is the classic trap, so listen up 🙈: if left to type inference, op operates on values of the same type as init which can result in unwanted casting of the iterator elements. for example:

std::accumulate(v.begin(), v.end(), 0)

likely does not give the result one wishes for when v is of type std::vector<double>. yeah. she's summing doubles into an int accumulator. tragic. don't do that to yourself 💀

🌈 Example 🌈

// Run this code

#include <functional>
#include <iostream>
#include <numeric>
#include <string>
#include <vector>

int main()
{
    std::vector<int> v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10};

    int sum = std::accumulate(v.begin(), v.end(), 0);
    int product = std::accumulate(v.begin(), v.end(), 1, std::multiplies<int>());

    auto dash_fold = [](std::string a, int b)
    {
        return std::move(a) + '-' + std::to_string(b);
    };

    std::string s = std::accumulate(std::next(v.begin()), v.end(),
                                    std::to_string(v[0]), // start with first element
                                    dash_fold);

    // Right fold using reverse iterators
    std::string rs = std::accumulate(std::next(v.rbegin()), v.rend(),
                                     std::to_string(v.back()), // start with last element
                                     dash_fold);

    std::cout << "sum: " << sum << '\n'
              << "product: " << product << '\n'
              << "dash-separated string: " << s << '\n'
              << "dash-separated string (right-folded): " << rs << '\n';
}

Output:

sum: 55
product: 3628800
dash-separated string: 1-2-3-4-5-6-7-8-9-10
dash-separated string (right-folded): 10-9-8-7-6-5-4-3-2-1

like?? the dash-separated string ATE. both directions. obsessed 🔥

💜 Defect reports 💜

the following behavior-changing defect reports were applied retroactively to previously published C++ standards. yes, they went back and fixed the past, we love a glow-up ✨

  • LWG 242 — Applied to C++98. Behavior as published: op could not have side effects. Correct behavior: it cannot modify the ranges involved.
  • LWG 2055 (P0616R0) — Applied to C++20. Behavior as published: acc was not moved while being accumulated. Correct behavior: it is moved.

👑 See also 👑

  • adjacent_difference — computes the differences between adjacent elements in a range (function template)
  • inner_product — computes the inner product of two ranges of elements (function template)
  • partial_sum — computes the partial sum of a range of elements (function template)
  • reduce (C++17) — similar to std::accumulate, except out of order (function template)
  • ranges::fold_left (C++23) — left-folds a range of elements (niebloid)

okay that's the whole page bestie, go forth and fold 💅🦋

source: http://cppreference.com — version 2024.06.10 — and this lil std::accumulate(3) page was last touched on that date 🎀 mwah, ily, go sum something 💖

📦 where this page comes from