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