ceph/src/boost/libs/utility/generator_iterator.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Language" content="en-us">
   6   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   7
   8   <title>Generator Iterator Adaptor Documentation</title>
   9 </head>
  10
  11 <body bgcolor="#FFFFFF" text="#000000">
  12   <img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle"
  13   width="277" height="86">
  14
  15   <h1>Generator Iterator Adaptor</h1>
  16
  17   <p>Defined in header <a href=
  18   "../../boost/generator_iterator.hpp">boost/generator_iterator.hpp</a></p>
  19
  20   <p>The generator iterator adaptor makes it easier to create custom input
  21   iterators from 0-ary functions and function objects. The adaptor takes a
  22   <a href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> and
  23   creates a model of <a href=
  24   "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>. Each
  25   increment retrieves an item from the generator and makes it available to be
  26   retrieved by dereferencing. The motivation for this iterator is that some
  27   concepts can be more naturally expressed as a generator, while most STL
  28   algorithms expect an iterator. An example is the <a href=
  29   "../random/index.html">Random Number</a> library.</p>
  30
  31   <h2>Synopsis</h2>
  32
  33   <blockquote>
  34     <pre>
  35 namespace boost {
  36   template &lt;class Generator&gt;
  37   class generator_iterator_policies;
  38
  39   template &lt;class Generator&gt;
  40   class generator_iterator_generator;
  41
  42   template &lt;class Generator&gt;
  43   typename generator_iterator_generator&lt;Generator&gt;::type
  44   make_generator_iterator(Generator &amp; gen);
  45 }
  46 </pre>
  47   </blockquote>
  48   <hr>
  49
  50   <h2>The Generator Iterator Generator Class</h2>
  51
  52   <p>The class generator_iterator_generator is a helper class whose purpose
  53   is to construct a generator iterator type. The template parameter for this
  54   class is the Generator function object type that is being wrapped. The
  55   generator iterator adaptor only holds a reference (or pointer) to the
  56   function object, therefore the function object must outlive the generator
  57   iterator adaptor constructed from it.</p>
  58   <pre>
  59 template &lt;class Generator&gt;
  60 class generator_iterator_generator
  61 {
  62 public:
  63   typedef <i>unspecified</i> type; // the resulting generator iterator type
  64 }
  65 </pre>
  66
  67   <h3>Template Parameters</h3>
  68
  69   <table border summary="">
  70     <tr>
  71       <th>Parameter</th>
  72
  73       <th>Description</th>
  74     </tr>
  75
  76     <tr>
  77       <td><tt><a href=
  78       "http://www.sgi.com/tech/stl/Generator.html">Generator</a></tt></td>
  79
  80       <td>The generator (0-ary function object) type being wrapped. The
  81       return type of the function must be defined as
  82       <tt>Generator::result_type</tt>. The function object must be a model of
  83       <a href=
  84       "http://www.sgi.com/tech/stl/Generator.html">Generator</a>.</td>
  85     </tr>
  86   </table>
  87
  88   <h3>Concept Model</h3>
  89
  90   <p>The generator iterator class is a model of <a href=
  91   "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>.</p>
  92
  93   <h3>Members</h3>
  94
  95   <p>The generator iterator implements the member functions and operators
  96   required of the <a href=
  97   "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>
  98   concept.<br></p>
  99   <hr>
 100
 101   <h2><a name="make_generator_iterator" id="make_generator_iterator">The
 102   Generator Iterator Object Generator</a></h2>
 103
 104   <p>The <tt>make_generator_iterator()</tt> function provides a convenient
 105   way to create generator iterator objects. The function saves the user the
 106   trouble of explicitly writing out the iterator types.</p>
 107
 108   <blockquote>
 109     <pre>
 110 template &lt;class Generator&gt;
 111 typename generator_iterator_generator&lt;Generator&gt;::type
 112 make_generator_iterator(Generator &amp; gen);
 113 </pre>
 114   </blockquote>
 115   <hr>
 116
 117   <h3>Example</h3>
 118
 119   <p>The following program shows how <code>generator_iterator</code>
 120   transforms a generator into an input iterator.</p>
 121
 122   <blockquote>
 123     <pre>
 124 #include &lt;iostream&gt;
 125 #include &lt;boost/generator_iterator.hpp&gt;
 126
 127 class my_generator
 128 {
 129 public:
 130   typedef int result_type;
 131   my_generator() : state(0) { }
 132   int operator()() { return ++state; }
 133 private:
 134   int state;
 135 };
 136
 137 int main()
 138 {
 139   my_generator gen;
 140   boost::generator_iterator_generator&lt;my_generator&gt;::type it = boost::make_generator_iterator(gen);
 141   for(int i = 0; i &lt; 10; ++i, ++it)
 142     std::cout &lt;&lt; *it &lt;&lt; std::endl;
 143 }
 144 </pre>
 145   </blockquote>
 146   <hr>
 147
 148   <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
 149   "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
 150   height="31" width="88"></a></p>
 151
 152   <p>Revised
 153   <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
 154
 155   <p><i>Copyright &copy; 2001 <a href=
 156   "http://www.boost.org/people/jens_maurer.htm">Jens Maurer</a></i></p>
 157
 158   <p><i>Distributed under the Boost Software License, Version 1.0. (See
 159   accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
 160   copy at <a href=
 161   "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
 162 </body>
 163 </html>