function template
<numeric>

std::accumulate

sum (1)
template <class InputIterator, class T>
   T accumulate (InputIterator first, InputIterator last, T init);
custom (2)
template <class InputIterator, class T, class BinaryOperation>
   T accumulate (InputIterator first, InputIterator last, T init,
                 BinaryOperation binary_op);
Accumulate values in range
Returns the result of accumulating all the values in the range [first,last) to init.

The default operation is to add the elements up, but a different operation can be specified as binary_op.

The behavior of this function template is equivalent to:
1
2
3
4
5
6
7
8
9
template <class InputIterator, class T>
   T accumulate (InputIterator first, InputIterator last, T init)
{
  while (first!=last) {
    init = init + *first;  // or: init=binary_op(init,*first) for the binary_op version
    ++first;
  }
  return init;
}


Parameters

first, last
Input iterators to the initial and final positions in a sequence. The range used is [first,last), which contains all the elements between first and last, including the element pointed by first but not the element pointed by last.
init
Initial value for the accumulator.
binary_op
Binary operation taking an element of type T as first argument and an element in the range as second, and which returns a value that can be assigned to type T.
This can either be a function pointer or a function object.
The operation shall not modify the elements passed as its arguments.

Return value

The result of accumulating init and all the elements in the range [first,last).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// accumulate example
#include <iostream>     // std::cout
#include <functional>   // std::minus
#include <numeric>      // std::accumulate

int myfunction (int x, int y) {return x+2*y;}
struct myclass {
	int operator()(int x, int y) {return x+3*y;}
} myobject;

int main () {
  int init = 100;
  int numbers[] = {10,20,30};

  std::cout << "using default accumulate: ";
  std::cout << std::accumulate(numbers,numbers+3,init);
  std::cout << '\n';

  std::cout << "using functional's minus: ";
  std::cout << std::accumulate (numbers, numbers+3, init, std::minus<int>());
  std::cout << '\n';

  std::cout << "using custom function: ";
  std::cout << std::accumulate (numbers, numbers+3, init, myfunction);
  std::cout << '\n';

  std::cout << "using custom object: ";
  std::cout << std::accumulate (numbers, numbers+3, init, myobject);
  std::cout << '\n';

  return 0;
}


Output:

using default accumulate: 160
using functional's minus: 40
using custom function: 220
using custom object: 280

Complexity

Linear in the distance between first and last.

Data races

The elements in the range [first,last) are accessed (each element is accessed exactly once).

Exceptions

Throws if any of binary_op, the assignments or an operation on an iterator throws.
Note that invalid arguments cause undefined behavior.

See also