SysTutorials

Linux Manual Pages › Section 3

stdinclusive_scan(3)

std::inclusive_scan - std::inclusive_scan

Synopsis

Defined in header <numeric>
template< class InputIt, class OutputIt >
OutputIt inclusive_scan( InputIt first,                                   (1) (since C++17)
InputIt last, OutputIt d_first );
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 >
ForwardtIt2 inclusive_scan( ExecutionPolicy&& policy, ForwardIt1 first,   (2) (since C++17)
ForwardIt1 last, ForwardIt2 d_first );
template< class InputIt, class OutputIt, class BinaryOperation >
OutputIt inclusive_scan( InputIt first, InputIt last,                     (3) (since C++17)
OutputIt d_first, BinaryOperation binary_op );
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2,
class BinaryOperation >
ForwardIt2 inclusive_scan( ExecutionPolicy&& policy,                      (4) (since C++17)
ForwardIt1 first, ForwardIt1 last,
ForwardIt2 d_first, BinaryOperation binary_op );
template< class InputIt, class OutputIt, class BinaryOperation, class T >
OutputIt inclusive_scan( InputIt first, InputIt last, OutputIt d_first,   (5) (since C++17)
BinaryOperation binary_op, T init );
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2,
class BinaryOperation, class T >
ForwardIt2 inclusive_scan( ExecutionPolicy&& policy,                      (6) (since C++17)
ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first,
BinaryOperation binary_op, T init );

Computes an inclusive prefix sum operation using binary_op (or std::plus<>() for overloads (1-2)) for the range [first, last), using init as the initial value (if provided), and writes the results to the range beginning at d_first. "inclusive" means that the i-th input element is included in the i-th sum. Formally, assigns through each iterator i in [d_first, d_first + (last - first)) the value of:

1

1, …, a

K), GNSUM(op, a

M, …, a

N)) for any K where 1 < K+1 = M ≤ N In other words, the summation operations may be performed in arbitrary order, and the behavior is nondeterministic if binary_op is not associative. Overloads (2,4,6) are executed according to policy. This overload only participates in overload resolution if std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true. binary_op shall not invalidate iterators (including the end iterators) or subranges, nor modify elements in the ranges [first, last) or [d_first, d_first + (last - first)). Otherwise, the behavior is undefined.

Parameters

first, last - the range of elements to sum d_first - the beginning of the destination range; may be equal to first policy - the execution policy to use. See execution_policy for details. init - the initial value (optional) binary_op - binary FunctionObject that will be applied in to the result of dereferencing the input iterators, the results of other binary_op, and init (if provided).

Type requirements

InputIt must meet the requirements of LegacyInputIterator.

OutputIt must meet the requirements of LegacyOutputIterator.

ForwardIt1 must meet the requirements of LegacyForwardIterator. and, if init is not provided, ForwardIt1’s value_type must be MoveConstructible and binary_op(*first, *first) must be convertible to ForwardIt1’s value type

ForwardIt2 must meet the requirements of LegacyForwardIterator.

T (if init is provided) must meet the requirements of MoveConstructible. All of binary_op(init, *first), binary_op(init, init), and binary_op(*first, *first) must be convertible to T

Return value

Iterator to the element past the last element written.

Complexity

O(last - first) applications of the binary operation

Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

Example

// Run this code

#include <functional>
#include <iostream>
#include <iterator>
#include <numeric>
#include <vector>
int main()
{
std::vector data{3, 1, 4, 1, 5, 9, 2, 6};
std::cout << "exclusive sum: ";
std::exclusive_scan(data.begin(), data.end(),
std::ostream_iterator<int>(std::cout, " "),
0);
std::cout << "\ninclusive sum: ";
std::inclusive_scan(data.begin(), data.end(),
std::ostream_iterator<int>(std::cout, " "));
std::cout << "\n\nexclusive product: ";
std::exclusive_scan(data.begin(), data.end(),
std::ostream_iterator<int>(std::cout, " "),
1, std::multiplies<>{});
std::cout << "\ninclusive product: ";
std::inclusive_scan(data.begin(), data.end(),
std::ostream_iterator<int>(std::cout, " "),
std::multiplies<>{});
}

Output:

  exclusive sum: 0 3 4 8 9 14 23 25   inclusive sum: 3 4 8 9 14 23 25 31

  exclusive product: 1 3 3 12 12 60 540 1080   inclusive product: 3 3 12 12 60 540 1080 6480

See also

                         computes the differences between adjacent elements in a range adjacent_difference (function template)                          sums up a range of elements accumulate (function template)                          computes the partial sum of a range of elements partial_sum (function template) transform_inclusive_scan applies a functor, then calculates inclusive scan                          (function template) (C++17) exclusive_scan similar to std::partial_sum, excludes the ith input element from the ith sum                          (function template) (C++17)