The return value is the end of the output range [result, result + (last - first) ).
<numeric> OutputIterator adjacent_difference(InputIterator first, InputIterator last, OutputIterator result); OutputIterator adjacent_difference(InputIterator first, InputIterator last, OutputIterator result, BinaryFunction op);
Calculates the differences of adjacent elements throughout the range [first, last). This means that in the new sequence, the value is the value of the difference of the current element and the previous element in the original sequence (the first value is unchanged). For example, if the original sequence is {1, 1, 2, 2, 3}, the resulting sequence is {1, 1 – 1, 2 – 1, 2 – 2, 3 – 2}, that is: {1, 0, 1, 0, 1}.
The second form uses the binary function op instead of the – operator to perform the "differencing." For example, if you use multiplies<int>( ) as the function object for the sequence, the output is {1, 1, 2, 4, 6}.
The return value is the end of the output range [result, result + (last - first) ).
Example
This program tests all the algorithms in <numeric> in both forms, on integer arrays. You’ll notice that in the test of the form where you supply the function or functions, the function objects used are the ones that produce the same result as form one, so the results will be exactly the same. This should also demonstrate a bit more clearly the operations that are going on and how to substitute your own operations.
//: C06:NumericTest.cpp
//{L} ../TestSuite/Test
#include "PrintSequence.h"
#include <numeric>
#include <algorithm>
#include <iostream>
#include <iterator>
#include <functional>
using namespace std;
int main() {
int a[] = { 1, 1, 2, 2, 3, 5, 7, 9, 11, 13 };
const int asz = sizeof a / sizeof a[0];
print(a, a + asz, "a", " ");
int r = accumulate(a, a + asz, 0);
cout << "accumulate 1: " << r << endl;
// Should produce the same result:
r = accumulate(a, a + asz, 0, plus<int>());
cout << "accumulate 2: " << r << endl;
int b[] = { 1, 2, 3, 4, 1, 2, 3, 4, 1, 2 };
print(b, b + sizeof b / sizeof b[0], "b", " ");
r = inner_product(a, a + asz, b, 0);
cout << "inner_product 1: " << r << endl;
// Should produce the same result:
r = inner_product(a, a + asz, b, 0,
plus<int>(), multiplies<int>());
cout << "inner_product 2: " << r << endl;
int* it = partial_sum(a, a + asz, b);
print(b, it, "partial_sum 1", " ");
// Should produce the same result:
it = partial_sum(a, a + asz, b, plus<int>());
print(b, it, "partial_sum 2", " ");
it = adjacent_difference(a, a + asz, b);
print(b, it, "adjacent_difference 1"," ");
// Should produce the same result:
it = adjacent_difference(a, a + asz, b,
minus<int>());
print(b, it, "adjacent_difference 2"," ");
} ///:~
Note that the return value of inner_product( ) and partial_sum( ) is the past-the-end iterator for the resulting sequence, so it is used as the second iterator in the print( ) function.
Since the second form of each function allows you to provide your own function object, only the first form of the functions is purely "numeric." You could conceivably do some things that are not intuitively numeric with something like inner_product( ).
General utilities
Finally, here are some basic tools that are used with the other algorithms; you may or may not use them directly yourself.
<utility> struct pair; make_pair( );
This was described and used earlier in this chapter. A pair is simply a way to package two objects (which may be of different types) together into a single object. This is typically used when you need to return more than one object from a function, but it can also be used to create a container that holds pair objects or to pass more than one object as a single argument. You access the elements by saying p.first and p.second, in which p is the pair object. The function equal_range( ), described in the last chapter and in this one, returns its result as a pair of iterators. You can insert( ) a pair directly into a map or multimap; a pair is the value_type for those containers.
If you want to create a pair "on the fly,", you typically use the template function make_pair( ) rather than explicitly constructing a pair object.
<iterator> distance(InputIterator first, InputIterator last);
Tells you the number of elements between first and last. More precisely, it returns an integral value that tells you the number of times first must be incremented before it is equal to last. No dereferencing of the iterators occurs during this process.
<iterator> void advance(InputIterator& i, Distance n);
Moves the iterator i forward by the value of n. (The iterator can also be moved backward for negative values of n if the iterator is also a bidirectional iterator.) This algorithm is aware of bidirectional iterators and will use the most efficient approach.
<iterator> back_insert_iterator<Container> back_inserter(Container& x); front_insert_iterator<Container> front_inserter(Container& x); insert_iterator<Container> inserter(Container& x, Iterator i);
These functions are used to create iterators for the given containers that will insert elements into the container, rather than overwrite the existing elements in the container using operator= (which is the default behavior). Each type of iterator uses a different operation for insertion: back_insert_iterator uses push_back( ), front_insert_iterator uses push_front( ), and insert_iterator uses insert( ) (and thus it can be used with the associative containers, while the other two can be used with sequence containers). These will be shown in some detail in the next chapter.
const LessThanComparable& min(const LessThanComparable& a, const LessThanComparable& b); const T& min(const T& a, const T& b, BinaryPredicate binary_pred);
Returns the lesser of its two arguments, or returns the first argument if the two are equivalent. The first version performs comparisons using operator<, and the second passes both arguments to binary_pred to perform the comparison.