1Utilities(3) QuantLib Utilities(3)
2
6 Utilities - Iterators are meant to build a sequence on the fly from one
7 or more other sequences, without having to allocate place for storing
8 it. A couple of examples: suppose we have a function which calculates
9 the average of a sequence, and that for genericity we have implemented
10 it as a template function which takes the beginning and the end of the
11 sequence, so that its declaration is:
12 template <class Iterator>
14 typename Iterator::value_type
15 average(const Iterator& begin, const Iterator& end)
16 This kind of genericity allows one to use the same function to
18 calculate the average of a std::vector, a std::list, a
19 QuantLib::History, any other container, of a subset of any of the
20 former.
21 Now let's say we have two sequences of numbers, and we want to
23 calculate the average of their products. One approach could be to store
24 the products in another sequence, and to calculate the average of the
25 latter, as in:
26 // we have sequence1 and sequence2 and assume equal size:
28 // first we store their product in a vector...
29 std::vector<double> products;
30 std::transform(sequence1.begin(),sequence1.end(), // first sequence
31 sequence2.begin(), // second sequence
32 std::back_inserter(products), // output
33 std::multiplies<double>()); // operation to perform
34 // ...then we calculate the average
35 double result = average(products.begin(),products.end());
36 The above works, however, it might be not particularly efficient since
38 we have to allocate the product vector, quite possibly just to throw it
39 away when the calculation is done.
40 QuantLib::coupling_iterator allows us to do the same thing without
42 allocating the extra vector: what we do is simply:
43 // we have sequence1 and sequence2 and assume equal size:
45 double result = average(
46 make_coupling_iterator(sequence1.begin(),
47 sequence2.begin(),
48 std::multiplies<double()),
49 make_coupling_iterator(sequence1.end(),
50 sequence2.end(),
51 std::multiplies<double()));
52 The call to make_coupling_iterator creates an iterator which is really
54 a reference to the two iterators and the operation we passed.
55 Dereferencing such iterator returns the result of applying such
56 operation to the values pointed to by the two contained iterators.
57 Advancing the coupling iterator advances the two underlying ones. One
58 can see how iterating on such iterator generates the products one by
59 one so that they can be processed by average(), but does not need
60 allocating memory for storing the results. The product sequence is
61 generated on the fly.
62 The other iterators share the same principle but have different
64 functionalities:
65 · combining_iterator is the same as coupling_iterator, but works on $ N
67 $ sequences while the latter works on 2;
68 · filtering_iterator generates the elements of a given sequence which
70 satisfy a given predicate, i.e., it takes a sequence $ [x_0,x_1,ots]
71 $ and a predicate $ p $ and generates the sequence of those $ x_i $
72 for which $ p(x_i) $ returns true;
73 · processing_iterator takes a sequence $ [x_0,x_1,ots] $ and a function
75 $ f $ and generates the sequence $ [f(x_0),f(x_1),ots] $;
76 · stepping_iterator takes a sequence $ [x_0,x_1,ots] $ and a step $ m $
78 and generates the sequence $ [x_0,x_m,x_{2m},ots] $
79Version 0.8.1 29 Oct 2007 Utilities(3)