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

http://hadesmem.googlecode.com/ · text · 256 lines · 188 code · 68 blank · 0 comment · 0 complexity · fd09387a4df8ed14076f6c29e13780d7 MD5 · raw file

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