ceph/src/boost/libs/iterator/doc/zip_iterator_eg.rst

   1 .. Copyright David Abrahams 2006. Distributed under the Boost
   2 .. Software License, Version 1.0. (See accompanying
   3 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   4
   5 Examples
   6 ........
   7
   8 There are two main types of applications of the ``zip_iterator``. The first
   9 one concerns runtime efficiency: If one has several controlled sequences
  10 of the same length that must be somehow processed, e.g., with the
  11 ``for_each`` algorithm, then it is more efficient to perform just
  12 one parallel-iteration rather than several individual iterations. For an
  13 example, assume that ``vect_of_doubles`` and ``vect_of_ints``
  14 are two vectors of equal length containing doubles and ints, respectively,
  15 and consider the following two iterations:
  16
  17 ::
  18
  19
  20     std::vector<double>::const_iterator beg1 = vect_of_doubles.begin();
  21     std::vector<double>::const_iterator end1 = vect_of_doubles.end();
  22     std::vector<int>::const_iterator beg2 = vect_of_ints.begin();
  23     std::vector<int>::const_iterator end2 = vect_of_ints.end();
  24
  25     std::for_each(beg1, end1, func_0());
  26     std::for_each(beg2, end2, func_1());
  27
  28 These two iterations can now be replaced with a single one as follows:
  29
  30 ::
  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
  43 A non-generic implementation of ``zip_func`` could look as follows:
  44
  45 ::
  46
  47
  48       struct zip_func :
  49         public std::unary_function<const boost::tuple<const double&, const int&>&, void>
  50       {
  51         void operator()(const boost::tuple<const double&, const int&>& t) const
  52         {
  53           m_f0(t.get<0>());
  54           m_f1(t.get<1>());
  55         }
  56
  57       private:
  58         func_0 m_f0;
  59         func_1 m_f1;
  60       };
  61
  62 The second important application of the ``zip_iterator`` is as a building block
  63 to make combining iterators. A combining iterator is an iterator
  64 that parallel-iterates over several controlled sequences and, upon
  65 dereferencing, returns the result of applying a functor to the values of the
  66 sequences at the respective positions. This can now be achieved by using the
  67 ``zip_iterator`` in conjunction with the ``transform_iterator``.
  68
  69 Suppose, for example, that you have two vectors of doubles, say
  70 ``vect_1`` and ``vect_2``, and you need to expose to a client
  71 a controlled sequence containing the products of the elements of
  72 ``vect_1`` and ``vect_2``. Rather than placing these products
  73 in a third vector, you can use a combining iterator that calculates the
  74 products on the fly. Let us assume that ``tuple_multiplies`` is a
  75 functor that works like ``std::multiplies``, except that it takes
  76 its two arguments packaged in a tuple. Then the two iterators
  77 ``it_begin`` and ``it_end`` defined below delimit a controlled
  78 sequence containing the products of the elements of ``vect_1`` and
  79 ``vect_2``:
  80
  81 ::
  82
  83
  84     typedef boost::tuple<
  85       std::vector<double>::const_iterator,
  86       std::vector<double>::const_iterator
  87       > the_iterator_tuple;
  88
  89     typedef boost::zip_iterator<
  90       the_iterator_tuple
  91       > the_zip_iterator;
  92
  93     typedef boost::transform_iterator<
  94       tuple_multiplies<double>,
  95       the_zip_iterator
  96       > the_transform_iterator;
  97
  98     the_transform_iterator it_begin(
  99       the_zip_iterator(
 100         the_iterator_tuple(
 101           vect_1.begin(),
 102           vect_2.begin()
 103           )
 104         ),
 105       tuple_multiplies<double>()
 106       );
 107
 108     the_transform_iterator it_end(
 109       the_zip_iterator(
 110         the_iterator_tuple(
 111           vect_1.end(),
 112           vect_2.end()
 113           )
 114         ),
 115       tuple_multiplies<double>()
 116       );