std::adjacent_difference

difference (1)	template <class InputIterator, class OutputIterator> OutputIterator adjacent_difference (InputIterator first, InputIterator last, OutputIterator result);
custom (2)	template <class InputIterator, class OutputIterator, class BinaryOperation> OutputIterator adjacent_difference ( InputIterator first, InputIterator last, OutputIterator result, BinaryOperation binary_op );

difference (1)

template <class InputIterator, class OutputIterator> OutputIterator adjacent_difference (InputIterator first, InputIterator last, OutputIterator result);

custom (2)

template <class InputIterator, class OutputIterator, class BinaryOperation> OutputIterator adjacent_difference ( InputIterator first, InputIterator last, OutputIterator result, BinaryOperation binary_op );

Compute adjacent difference of range

Assigns to every element in the range starting at result the difference between its corresponding element in the range [first,last) and the one preceding it (except for *result, which is assigned *first).

If x represents an element in [first,last) and y represents an element in result, the ys can be calculated as:


y₀ = x₀ 

y₁ = x₁ - x₀ 

y₂ = x₂ - x₁ 

y₃ = x₃ - x₂ 

y₄ = x₄ - x₃ 

 ... ... ...

The default operation is to calculate the difference, but some other operation can be specified as binary_op instead.

The behavior of this function template is equivalent to:

template <class InputIterator, class OutputIterator>
 OutputIterator adjacent_difference (InputIterator first, InputIterator last,
 OutputIterator result)
{
 if (first!=last) {
 typename iterator_traits<InputIterator>::value_type val,prev;
 *result = prev = *first;
 while (++first!=last) {
 val = *first;
 *++result = val - prev; // or: *++result = binary_op(val,prev)
 prev = val;
 }
 ++result;
 }
 return result;
}

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.
result: Output iterator to the initial position in the destination sequence where the differences are stored. The range starts at result and shall have a size large enough to contain as many elements as the range above ([first,last)).
binary_op: Binary operation taking as arguments two elements of the type pointed by InputIterator, and returning the result of the replacement for the difference operation.
This can either be a function pointer or a function object.

Return value

An iterator pointing to past the last element of the destination sequence where resulting elements have been stored.

Example

// adjacent_difference example
#include <iostream> // std::cout
#include <functional> // std::multiplies
#include <numeric> // std::adjacent_difference
int myop (int x, int y) {return x+y;}
int main () {
 int val[] = {1,2,3,5,9,11,12};
 int result[7];
 std::adjacent_difference (val, val+7, result);
 std::cout << "using default adjacent_difference: ";
 for (int i=0; i<7; i++) std::cout << result[i] << ' ';
 std::cout << '\n';
 std::adjacent_difference (val, val+7, result, std::multiplies<int>());
 std::cout << "using functional operation multiplies: ";
 for (int i=0; i<7; i++) std::cout << result[i] << ' ';
 std::cout << '\n';
 std::adjacent_difference (val, val+7, result, myop);
 std::cout << "using custom function: ";
 for (int i=0; i<7; i++) std::cout << result[i] << ' ';
 std::cout << '\n';
 return 0;
}

Output:


using default adjacent_difference: 1 1 1 2 4 2 1
using functional operation multiplies: 1 2 6 15 45 99 132
using custom function: 1 3 5 8 14 20 23

Complexity

Linear in the distance between first and last, minus one (in number of subtractions or applications of binary_op).

Data races

The elements in the range [first1,last1) are accessed (each element is accessed exactly once).
The elements in the range beginning at result are modified.

Exceptions

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