/Src/Dependencies/Boost/libs/iterator/doc/quickbook/zip_iterator.qbk

  1
  2[section:zip Zip Iterator]
  3
  4The zip iterator provides the ability to parallel-iterate
  5over several controlled sequences simultaneously. A zip 
  6iterator is constructed from a tuple of iterators. Moving
  7the zip iterator moves all the iterators in parallel.
  8Dereferencing the zip iterator returns a tuple that contains
  9the results of dereferencing the individual iterators. 
 10
 11[section:zip_example Example]
 12
 13There are two main types of applications of the `zip_iterator`. The first
 14one concerns runtime efficiency: If one has several controlled sequences
 15of the same length that must be somehow processed, e.g., with the 
 16`for_each` algorithm, then it is more efficient to perform just
 17one parallel-iteration rather than several individual iterations. For an 
 18example, assume that `vect_of_doubles` and `vect_of_ints`
 19are two vectors of equal length containing doubles and ints, respectively,
 20and consider the following two iterations:
 21
 22    std::vector<double>::const_iterator beg1 = vect_of_doubles.begin();
 23    std::vector<double>::const_iterator end1 = vect_of_doubles.end();
 24    std::vector<int>::const_iterator beg2 = vect_of_ints.begin();
 25    std::vector<int>::const_iterator end2 = vect_of_ints.end();
 26
 27    std::for_each(beg1, end1, func_0());
 28    std::for_each(beg2, end2, func_1());
 29
 30These two iterations can now be replaced with a single one as follows:
 31
 32
 33    std::for_each(
 34      boost::make_zip_iterator(
 35        boost::make_tuple(beg1, beg2)
 36        ),
 37      boost::make_zip_iterator(
 38        boost::make_tuple(end1, end2)
 39        ),
 40      zip_func()
 41      );
 42
 43A non-generic implementation of `zip_func` could look as follows:
 44
 45
 46      struct zip_func : 
 47        public std::unary_function<const boost::tuple<const double&, const int&>&, void>
 48      {
 49        void operator()(const boost::tuple<const double&, const int&>& t) const
 50        {
 51          m_f0(t.get<0>());
 52          m_f1(t.get<1>());
 53        }
 54
 55      private:
 56        func_0 m_f0;
 57        func_1 m_f1;
 58      };
 59
 60The second important application of the `zip_iterator` is as a building block
 61to make combining iterators. A combining iterator is an iterator
 62that parallel-iterates over several controlled sequences and, upon
 63dereferencing, returns the result of applying a functor to the values of the
 64sequences at the respective positions. This can now be achieved by using the
 65`zip_iterator` in conjunction with the `transform_iterator`. 
 66
 67Suppose, for example, that you have two vectors of doubles, say 
 68`vect_1` and `vect_2`, and you need to expose to a client
 69a controlled sequence containing the products of the elements of 
 70`vect_1` and `vect_2`. Rather than placing these products
 71in a third vector, you can use a combining iterator that calculates the
 72products on the fly. Let us assume that `tuple_multiplies` is a
 73functor that works like `std::multiplies`, except that it takes
 74its two arguments packaged in a tuple. Then the two iterators 
 75`it_begin` and `it_end` defined below delimit a controlled
 76sequence containing the products of the elements of `vect_1` and
 77`vect_2`:
 78
 79    typedef boost::tuple<
 80      std::vector<double>::const_iterator,
 81      std::vector<double>::const_iterator
 82      > the_iterator_tuple;
 83
 84    typedef boost::zip_iterator<
 85      the_iterator_tuple
 86      > the_zip_iterator;
 87
 88    typedef boost::transform_iterator<
 89      tuple_multiplies<double>,
 90      the_zip_iterator
 91      > the_transform_iterator;
 92
 93    the_transform_iterator it_begin(
 94      the_zip_iterator(
 95        the_iterator_tuple(
 96          vect_1.begin(),
 97          vect_2.begin()
 98          )
 99        ),
100      tuple_multiplies<double>()
101      );
102
103    the_transform_iterator it_end(
104      the_zip_iterator(
105        the_iterator_tuple(
106          vect_1.end(),
107          vect_2.end()
108          )
109        ),
110      tuple_multiplies<double>()
111      );
112
113[endsect]
114
115[section:zip_reference Reference]
116
117[h2 Synopsis]
118
119  template<typename IteratorTuple>
120  class zip_iterator
121  {  
122
123  public:
124    typedef /* see below */ reference;
125    typedef reference value_type;
126    typedef value_type* pointer;
127    typedef /* see below */ difference_type;
128    typedef /* see below */ iterator_category;
129
130    zip_iterator();
131    zip_iterator(IteratorTuple iterator_tuple);
132
133    template<typename OtherIteratorTuple>
134    zip_iterator(
135          const zip_iterator<OtherIteratorTuple>& other
136        , typename enable_if_convertible<
137                OtherIteratorTuple
138              , IteratorTuple>::type* = 0     // exposition only
139    );
140
141    const IteratorTuple& get_iterator_tuple() const;
142
143  private:
144    IteratorTuple m_iterator_tuple;     // exposition only
145  };
146
147  template<typename IteratorTuple> 
148  zip_iterator<IteratorTuple> 
149  make_zip_iterator(IteratorTuple t);
150
151The `reference` member of `zip_iterator` is the type of the tuple
152made of the reference types of the iterator types in the `IteratorTuple`
153argument.
154
155The `difference_type` member of `zip_iterator` is the `difference_type`
156of the first of the iterator types in the `IteratorTuple` argument.
157
158The `iterator_category` member of `zip_iterator` is convertible to the
159minimum of the traversal categories of the iterator types in the `IteratorTuple`
160argument. For example, if the `zip_iterator` holds only vector
161iterators, then `iterator_category` is convertible to 
162`boost::random_access_traversal_tag`. If you add a list iterator, then
163`iterator_category` will be convertible to `boost::bidirectional_traversal_tag`,
164but no longer to `boost::random_access_traversal_tag`.
165
166[h2 Requirements]
167
168All iterator types in the argument `IteratorTuple` shall model Readable Iterator.  
169
170[h2 Concepts]
171
172The resulting `zip_iterator` models Readable Iterator.
173
174The fact that the `zip_iterator` models only Readable Iterator does not 
175prevent you from modifying the values that the individual iterators point
176to. The tuple returned by the `zip_iterator`'s `operator*` is a tuple 
177constructed from the reference types of the individual iterators, not 
178their value types. For example, if `zip_it` is a `zip_iterator` whose
179first member iterator is an `std::vector<double>::iterator`, then the
180following line will modify the value which the first member iterator of
181`zip_it` currently points to:
182
183    zip_it->get<0>() = 42.0;
184
185
186Consider the set of standard traversal concepts obtained by taking
187the most refined standard traversal concept modeled by each individual
188iterator type in the `IteratorTuple` argument.The `zip_iterator` 
189models the least refined standard traversal concept in this set.
190
191`zip_iterator<IteratorTuple1>` is interoperable with
192`zip_iterator<IteratorTuple2>` if and only if `IteratorTuple1`
193is interoperable with `IteratorTuple2`.
194
195[h2 Operations]
196
197In addition to the operations required by the concepts modeled by
198`zip_iterator`, `zip_iterator` provides the following
199operations.
200
201  zip_iterator();
202
203[*Returns:] An instance of `zip_iterator` with `m_iterator_tuple`
204  default constructed.
205
206
207  zip_iterator(IteratorTuple iterator_tuple);
208
209[*Returns:] An instance of `zip_iterator` with `m_iterator_tuple`
210  initialized to `iterator_tuple`.
211
212
213    template<typename OtherIteratorTuple>
214    zip_iterator(
215          const zip_iterator<OtherIteratorTuple>& other
216        , typename enable_if_convertible<
217                OtherIteratorTuple
218              , IteratorTuple>::type* = 0     // exposition only
219    );
220
221[*Returns:] An instance of `zip_iterator` that is a copy of `other`.\n
222[*Requires:] `OtherIteratorTuple` is implicitly convertible to `IteratorTuple`.
223
224
225  const IteratorTuple& get_iterator_tuple() const;
226
227[*Returns:] `m_iterator_tuple`
228
229
230  reference operator*() const;
231
232[*Returns:] A tuple consisting of the results of dereferencing all iterators in
233  `m_iterator_tuple`.
234
235
236  zip_iterator& operator++();
237
238[*Effects:] Increments each iterator in `m_iterator_tuple`.\n
239[*Returns:] `*this`
240
241
242  zip_iterator& operator--();
243
244[*Effects:] Decrements each iterator in `m_iterator_tuple`.\n
245[*Returns:] `*this`
246
247    template<typename IteratorTuple> 
248    zip_iterator<IteratorTuple> 
249    make_zip_iterator(IteratorTuple t);
250
251[*Returns:] An instance of `zip_iterator<IteratorTuple>` with `m_iterator_tuple`
252  initialized to `t`.
253
254[endsect]
255
256[endsect]