ceph/src/boost/libs/iterator/doc/transform_iterator.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
   7 <title>Transform Iterator</title>
   8 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
   9 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
  10 <meta name="date" content="2006-09-11" />
  11 <meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
  12 <link rel="stylesheet" href="../../../rst.css" type="text/css" />
  13 </head>
  14 <body>
  15 <div class="document" id="transform-iterator">
  16 <h1 class="title">Transform Iterator</h1>
  17 <table class="docinfo" frame="void" rules="none">
  18 <col class="docinfo-name" />
  19 <col class="docinfo-content" />
  20 <tbody valign="top">
  21 <tr><th class="docinfo-name">Author:</th>
  22 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
  23 <tr><th class="docinfo-name">Contact:</th>
  24 <td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
  25 <tr><th class="docinfo-name">Organization:</th>
  26 <td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
  27 Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
  28 Railway Operation and Construction</a></td></tr>
  29 <tr><th class="docinfo-name">Date:</th>
  30 <td>2006-09-11</td></tr>
  31 <tr><th class="docinfo-name">Copyright:</th>
  32 <td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
  33 </tbody>
  34 </table>
  35 <!-- Distributed under the Boost -->
  36 <!-- Software License, Version 1.0. (See accompanying -->
  37 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
  38 <table class="docutils field-list" frame="void" rules="none">
  39 <col class="field-name" />
  40 <col class="field-body" />
  41 <tbody valign="top">
  42 <tr class="field"><th class="field-name">abstract:</th><td class="field-body"><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
  43 <!-- Software License, Version 1.0. (See accompanying -->
  44 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
  45 The transform iterator adapts an iterator by modifying the
  46 <tt class="docutils literal"><span class="pre">operator*</span></tt> to apply a function object to the result of
  47 dereferencing the iterator and returning the result.</td>
  48 </tr>
  49 </tbody>
  50 </table>
  51 <div class="contents topic" id="table-of-contents">
  52 <p class="topic-title first">Table of Contents</p>
  53 <ul class="simple">
  54 <li><a class="reference internal" href="#transform-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> synopsis</a></li>
  55 <li><a class="reference internal" href="#transform-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
  56 <li><a class="reference internal" href="#transform-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models</a></li>
  57 <li><a class="reference internal" href="#transform-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> operations</a></li>
  58 <li><a class="reference internal" href="#example" id="id6">Example</a></li>
  59 </ul>
  60 </div>
  61 <div class="section" id="transform-iterator-synopsis">
  62 <h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> synopsis</a></h1>
  63 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
  64 <!-- Software License, Version 1.0. (See accompanying -->
  65 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
  66 <!-- Version 1.3 of this document was accepted for TR1 -->
  67 <pre class="literal-block">
  68 template &lt;class UnaryFunction,
  69           class Iterator,
  70           class Reference = use_default,
  71           class Value = use_default&gt;
  72 class transform_iterator
  73 {
  74 public:
  75   typedef /* see below */ value_type;
  76   typedef /* see below */ reference;
  77   typedef /* see below */ pointer;
  78   typedef iterator_traits&lt;Iterator&gt;::difference_type difference_type;
  79   typedef /* see below */ iterator_category;
  80
  81   transform_iterator();
  82   transform_iterator(Iterator const&amp; x, UnaryFunction f);
  83
  84   template&lt;class F2, class I2, class R2, class V2&gt;
  85   transform_iterator(
  86         transform_iterator&lt;F2, I2, R2, V2&gt; const&amp; t
  87       , typename enable_if_convertible&lt;I2, Iterator&gt;::type* = 0      // exposition only
  88       , typename enable_if_convertible&lt;F2, UnaryFunction&gt;::type* = 0 // exposition only
  89   );
  90   UnaryFunction functor() const;
  91   Iterator const&amp; base() const;
  92   reference operator*() const;
  93   transform_iterator&amp; operator++();
  94   transform_iterator&amp; operator--();
  95 private:
  96   Iterator m_iterator; // exposition only
  97   UnaryFunction m_f;   // exposition only
  98 };
  99 </pre>
 100 <p>If <tt class="docutils literal"><span class="pre">Reference</span></tt> is <tt class="docutils literal"><span class="pre">use_default</span></tt> then the <tt class="docutils literal"><span class="pre">reference</span></tt> member of
 101 <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> is
 102 <tt class="docutils literal"><span class="pre">result_of&lt;const UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.
 103 Otherwise, <tt class="docutils literal"><span class="pre">reference</span></tt> is <tt class="docutils literal"><span class="pre">Reference</span></tt>.</p>
 104 <p>If <tt class="docutils literal"><span class="pre">Value</span></tt> is <tt class="docutils literal"><span class="pre">use_default</span></tt> then the <tt class="docutils literal"><span class="pre">value_type</span></tt> member is
 105 <tt class="docutils literal"><span class="pre">remove_cv&lt;remove_reference&lt;reference&gt;</span> <span class="pre">&gt;::type</span></tt>.  Otherwise,
 106 <tt class="docutils literal"><span class="pre">value_type</span></tt> is <tt class="docutils literal"><span class="pre">Value</span></tt>.</p>
 107 <p>If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and if <tt class="docutils literal"><span class="pre">Iterator</span></tt>
 108 models Random Access Traversal Iterator, then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
 109 convertible to <tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt>. Otherwise, if
 110 <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Bidirectional Traversal Iterator, then
 111 <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
 112 <tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt>.  Otherwise <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
 113 convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>. If <tt class="docutils literal"><span class="pre">Iterator</span></tt> does not
 114 model Readable Lvalue Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
 115 convertible to <tt class="docutils literal"><span class="pre">input_iterator_tag</span></tt>.</p>
 116 </div>
 117 <div class="section" id="transform-iterator-requirements">
 118 <h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> requirements</a></h1>
 119 <p>The type <tt class="docutils literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and
 120 the expression <tt class="docutils literal"><span class="pre">f(*i)</span></tt> must be valid where <tt class="docutils literal"><span class="pre">f</span></tt> is a const object of
 121 type <tt class="docutils literal"><span class="pre">UnaryFunction</span></tt>, <tt class="docutils literal"><span class="pre">i</span></tt> is an object of type <tt class="docutils literal"><span class="pre">Iterator</span></tt>, and
 122 where the type of <tt class="docutils literal"><span class="pre">f(*i)</span></tt> must be
 123 <tt class="docutils literal"><span class="pre">result_of&lt;const UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.</p>
 124 <p>The argument <tt class="docutils literal"><span class="pre">Iterator</span></tt> shall model Readable Iterator.</p>
 125 </div>
 126 <div class="section" id="transform-iterator-models">
 127 <h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models</a></h1>
 128 <p>The resulting <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models the most refined of the
 129 following that is also modeled by <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</p>
 130 <blockquote>
 131 <ul class="simple">
 132 <li>Writable Lvalue Iterator if <tt class="docutils literal"><span class="pre">transform_iterator::reference</span></tt> is a non-const reference.</li>
 133 <li>Readable Lvalue Iterator if <tt class="docutils literal"><span class="pre">transform_iterator::reference</span></tt> is a const reference.</li>
 134 <li>Readable Iterator otherwise.</li>
 135 </ul>
 136 </blockquote>
 137 <p>The <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models the most refined standard traversal
 138 concept that is modeled by the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument.</p>
 139 <p>If <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> is a model of Readable Lvalue Iterator then
 140 it models the following original iterator concepts depending on what
 141 the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument models.</p>
 142 <table border="1" class="docutils">
 143 <colgroup>
 144 <col width="47%" />
 145 <col width="53%" />
 146 </colgroup>
 147 <thead valign="bottom">
 148 <tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
 149 <th class="head">then <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models</th>
 150 </tr>
 151 </thead>
 152 <tbody valign="top">
 153 <tr><td>Single Pass Iterator</td>
 154 <td>Input Iterator</td>
 155 </tr>
 156 <tr><td>Forward Traversal Iterator</td>
 157 <td>Forward Iterator</td>
 158 </tr>
 159 <tr><td>Bidirectional Traversal Iterator</td>
 160 <td>Bidirectional Iterator</td>
 161 </tr>
 162 <tr><td>Random Access Traversal Iterator</td>
 163 <td>Random Access Iterator</td>
 164 </tr>
 165 </tbody>
 166 </table>
 167 <p>If <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models Writable Lvalue Iterator then it is a
 168 mutable iterator (as defined in the old iterator requirements).</p>
 169 <p><tt class="docutils literal"><span class="pre">transform_iterator&lt;F1,</span> <span class="pre">X,</span> <span class="pre">R1,</span> <span class="pre">V1&gt;</span></tt> is interoperable with
 170 <tt class="docutils literal"><span class="pre">transform_iterator&lt;F2,</span> <span class="pre">Y,</span> <span class="pre">R2,</span> <span class="pre">V2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
 171 interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
 172 </div>
 173 <div class="section" id="transform-iterator-operations">
 174 <h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt> operations</a></h1>
 175 <p>In addition to the operations required by the concepts modeled by
 176 <tt class="docutils literal"><span class="pre">transform_iterator</span></tt>, <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> provides the following
 177 operations.</p>
 178 <p><tt class="docutils literal"><span class="pre">transform_iterator();</span></tt></p>
 179 <table class="docutils field-list" frame="void" rules="none">
 180 <col class="field-name" />
 181 <col class="field-body" />
 182 <tbody valign="top">
 183 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
 184 and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
 185 </tr>
 186 </tbody>
 187 </table>
 188 <p><tt class="docutils literal"><span class="pre">transform_iterator(Iterator</span> <span class="pre">const&amp;</span> <span class="pre">x,</span> <span class="pre">UnaryFunction</span> <span class="pre">f);</span></tt></p>
 189 <table class="docutils field-list" frame="void" rules="none">
 190 <col class="field-name" />
 191 <col class="field-body" />
 192 <tbody valign="top">
 193 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
 194 initialized to <tt class="docutils literal"><span class="pre">f</span></tt> and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 195 </tr>
 196 </tbody>
 197 </table>
 198 <pre class="literal-block">
 199 template&lt;class F2, class I2, class R2, class V2&gt;
 200 transform_iterator(
 201       transform_iterator&lt;F2, I2, R2, V2&gt; const&amp; t
 202     , typename enable_if_convertible&lt;I2, Iterator&gt;::type* = 0      // exposition only
 203     , typename enable_if_convertible&lt;F2, UnaryFunction&gt;::type* = 0 // exposition only
 204 );
 205 </pre>
 206 <table class="docutils field-list" frame="void" rules="none">
 207 <col class="field-name" />
 208 <col class="field-body" />
 209 <tbody valign="top">
 210 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
 211 initialized to <tt class="docutils literal"><span class="pre">t.functor()</span></tt> and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to
 212 <tt class="docutils literal"><span class="pre">t.base()</span></tt>.</td>
 213 </tr>
 214 <tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
 215 </tr>
 216 </tbody>
 217 </table>
 218 <p><tt class="docutils literal"><span class="pre">UnaryFunction</span> <span class="pre">functor()</span> <span class="pre">const;</span></tt></p>
 219 <table class="docutils field-list" frame="void" rules="none">
 220 <col class="field-name" />
 221 <col class="field-body" />
 222 <tbody valign="top">
 223 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_f</span></tt></td>
 224 </tr>
 225 </tbody>
 226 </table>
 227 <p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
 228 <table class="docutils field-list" frame="void" rules="none">
 229 <col class="field-name" />
 230 <col class="field-body" />
 231 <tbody valign="top">
 232 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
 233 </tr>
 234 </tbody>
 235 </table>
 236 <p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
 237 <table class="docutils field-list" frame="void" rules="none">
 238 <col class="field-name" />
 239 <col class="field-body" />
 240 <tbody valign="top">
 241 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_f(*m_iterator)</span></tt></td>
 242 </tr>
 243 </tbody>
 244 </table>
 245 <p><tt class="docutils literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
 246 <table class="docutils field-list" frame="void" rules="none">
 247 <col class="field-name" />
 248 <col class="field-body" />
 249 <tbody valign="top">
 250 <tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator</span></tt></td>
 251 </tr>
 252 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
 253 </tr>
 254 </tbody>
 255 </table>
 256 <p><tt class="docutils literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
 257 <table class="docutils field-list" frame="void" rules="none">
 258 <col class="field-name" />
 259 <col class="field-body" />
 260 <tbody valign="top">
 261 <tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator</span></tt></td>
 262 </tr>
 263 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
 264 </tr>
 265 </tbody>
 266 </table>
 267 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
 268 <!-- Software License, Version 1.0. (See accompanying -->
 269 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 270 <pre class="literal-block">
 271 template &lt;class UnaryFunction, class Iterator&gt;
 272 transform_iterator&lt;UnaryFunction, Iterator&gt;
 273 make_transform_iterator(Iterator it, UnaryFunction fun);
 274 </pre>
 275 <table class="docutils field-list" frame="void" rules="none">
 276 <col class="field-name" />
 277 <col class="field-body" />
 278 <tbody valign="top">
 279 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
 280 initialized to <tt class="docutils literal"><span class="pre">f</span></tt> and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 281 </tr>
 282 </tbody>
 283 </table>
 284 <pre class="literal-block">
 285 template &lt;class UnaryFunction, class Iterator&gt;
 286 transform_iterator&lt;UnaryFunction, Iterator&gt;
 287 make_transform_iterator(Iterator it);
 288 </pre>
 289 <table class="docutils field-list" frame="void" rules="none">
 290 <col class="field-name" />
 291 <col class="field-body" />
 292 <tbody valign="top">
 293 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="docutils literal"><span class="pre">m_f</span></tt>
 294 default constructed and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 295 </tr>
 296 </tbody>
 297 </table>
 298 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
 299 <!-- Software License, Version 1.0. (See accompanying -->
 300 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 301 </div>
 302 <div class="section" id="example">
 303 <h1><a class="toc-backref" href="#id6">Example</a></h1>
 304 <p>This is a simple example of using the transform_iterators class to
 305 generate iterators that multiply (or add to) the value returned by
 306 dereferencing the iterator. It would be cooler to use lambda library
 307 in this example.</p>
 308 <pre class="literal-block">
 309 int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
 310 const int N = sizeof(x)/sizeof(int);
 311
 312 typedef boost::binder1st&lt; std::multiplies&lt;int&gt; &gt; Function;
 313 typedef boost::transform_iterator&lt;Function, int*&gt; doubling_iterator;
 314
 315 doubling_iterator i(x, boost::bind1st(std::multiplies&lt;int&gt;(), 2)),
 316   i_end(x + N, boost::bind1st(std::multiplies&lt;int&gt;(), 2));
 317
 318 std::cout &lt;&lt; &quot;multiplying the array by 2:&quot; &lt;&lt; std::endl;
 319 while (i != i_end)
 320   std::cout &lt;&lt; *i++ &lt;&lt; &quot; &quot;;
 321 std::cout &lt;&lt; std::endl;
 322
 323 std::cout &lt;&lt; &quot;adding 4 to each element in the array:&quot; &lt;&lt; std::endl;
 324 std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus&lt;int&gt;(), 4)),
 325           boost::make_transform_iterator(x + N, boost::bind1st(std::plus&lt;int&gt;(), 4)),
 326           std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
 327 std::cout &lt;&lt; std::endl;
 328 </pre>
 329 <p>The output is:</p>
 330 <pre class="literal-block">
 331 multiplying the array by 2:
 332 2 4 6 8 10 12 14 16
 333 adding 4 to each element in the array:
 334 5 6 7 8 9 10 11 12
 335 </pre>
 336 <p>The source code for this example can be found <a class="reference external" href="../example/transform_iterator_example.cpp">here</a>.</p>
 337 </div>
 338 </div>
 339 <div class="footer">
 340 <hr class="footer" />
 341 <a class="reference external" href="transform_iterator.rst">View document source</a>.
 342 Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 343
 344 </div>
 345 </body>
 346 </html>