ceph/src/boost/libs/iterator/doc/counting_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>Counting 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="counting-iterator">
  16 <h1 class="title">Counting 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"><p class="first">How would you fill up a vector with the numbers zero
  43 through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>?  The only iterator
  44 operation missing from builtin integer types is an
  45 <tt class="docutils literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
  46 The counting iterator adaptor adds this crucial piece of
  47 functionality to whatever type it wraps.  One can use the
  48 counting iterator adaptor not only with integer types, but with
  49 any incrementable type.</p>
  50 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
  51 <!-- Software License, Version 1.0. (See accompanying -->
  52 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
  53 <p class="last"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="docutils literal"><span class="pre">operator*</span></tt> that
  54 returns the current value of the object. All other iterator operations
  55 are forwarded to the adapted object.</p>
  56 </td>
  57 </tr>
  58 </tbody>
  59 </table>
  60 <div class="contents topic" id="table-of-contents">
  61 <p class="topic-title first">Table of Contents</p>
  62 <ul class="simple">
  63 <li><a class="reference internal" href="#counting-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
  64 <li><a class="reference internal" href="#counting-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
  65 <li><a class="reference internal" href="#counting-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></li>
  66 <li><a class="reference internal" href="#counting-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
  67 <li><a class="reference internal" href="#example" id="id6">Example</a></li>
  68 </ul>
  69 </div>
  70 <div class="section" id="counting-iterator-synopsis">
  71 <h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
  72 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
  73 <!-- Software License, Version 1.0. (See accompanying -->
  74 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
  75 <pre class="literal-block">
  76 template &lt;
  77     class Incrementable
  78   , class CategoryOrTraversal = use_default
  79   , class Difference = use_default
  80 &gt;
  81 class counting_iterator
  82 {
  83 public:
  84     typedef Incrementable value_type;
  85     typedef const Incrementable&amp; reference;
  86     typedef const Incrementable* pointer;
  87     typedef /* see below */ difference_type;
  88     typedef /* see below */ iterator_category;
  89
  90     counting_iterator();
  91     counting_iterator(counting_iterator const&amp; rhs);
  92     explicit counting_iterator(Incrementable x);
  93     Incrementable const&amp; base() const;
  94     reference operator*() const;
  95     counting_iterator&amp; operator++();
  96     counting_iterator&amp; operator--();
  97 private:
  98     Incrementable m_inc; // exposition
  99 };
 100 </pre>
 101 <p>If the <tt class="docutils literal"><span class="pre">Difference</span></tt> argument is <tt class="docutils literal"><span class="pre">use_default</span></tt> then
 102 <tt class="docutils literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
 103 type. Otherwise <tt class="docutils literal"><span class="pre">difference_type</span></tt> is <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
 104 <p><tt class="docutils literal"><span class="pre">iterator_category</span></tt> is determined according to the following
 105 algorithm:</p>
 106 <pre class="literal-block">
 107 if (CategoryOrTraversal is not use_default)
 108     return CategoryOrTraversal
 109 else if (numeric_limits&lt;Incrementable&gt;::is_specialized)
 110     return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
 111         random_access_traversal_tag, Incrementable, const Incrementable&amp;)
 112 else
 113     return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
 114          iterator_traversal&lt;Incrementable&gt;::type,
 115          Incrementable, const Incrementable&amp;)
 116 </pre>
 117 <dl class="docutils">
 118 <dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
 119 <dd><tt class="docutils literal"><span class="pre">operator-</span></tt> and a <tt class="docutils literal"><span class="pre">difference_type</span></tt> that avoids overflows in
 120 the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
 121 is true.]</dd>
 122 </dl>
 123 </div>
 124 <div class="section" id="counting-iterator-requirements">
 125 <h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
 126 <p>The <tt class="docutils literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
 127 <p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>
 128 or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
 129 <pre class="literal-block">
 130 Incrementable i, j;
 131 ++i;         // pre-increment
 132 i == j;      // operator equal
 133 </pre>
 134 <p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
 135 <tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
 136 the following expression must also be well-formed:</p>
 137 <pre class="literal-block">
 138 --i
 139 </pre>
 140 <p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
 141 <tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt>,
 142 the following must must also be valid:</p>
 143 <pre class="literal-block">
 144 counting_iterator::difference_type n;
 145 i += n;
 146 n = i - j;
 147 i &lt; j;
 148 </pre>
 149 </div>
 150 <div class="section" id="counting-iterator-models">
 151 <h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
 152 <p>Specializations of <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
 153 Iterator. In addition, they model the concepts corresponding to the
 154 iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible.
 155 Also, if <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="docutils literal"><span class="pre">use_default</span></tt> then
 156 <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
 157 tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>.  Otherwise, if
 158 <tt class="docutils literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
 159 <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
 160 Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
 161 concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p>
 162 <p><tt class="docutils literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
 163 <tt class="docutils literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
 164 interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
 165 </div>
 166 <div class="section" id="counting-iterator-operations">
 167 <h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
 168 <p>In addition to the operations required by the concepts modeled by
 169 <tt class="docutils literal"><span class="pre">counting_iterator</span></tt>, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> provides the following
 170 operations.</p>
 171 <p><tt class="docutils literal"><span class="pre">counting_iterator();</span></tt></p>
 172 <table class="docutils field-list" frame="void" rules="none">
 173 <col class="field-name" />
 174 <col class="field-body" />
 175 <tbody valign="top">
 176 <tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
 177 </tr>
 178 <tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="docutils literal"><span class="pre">m_inc</span></tt>.</td>
 179 </tr>
 180 </tbody>
 181 </table>
 182 <p><tt class="docutils literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
 183 <table class="docutils field-list" frame="void" rules="none">
 184 <col class="field-name" />
 185 <col class="field-body" />
 186 <tbody valign="top">
 187 <tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">rhs.m_inc</span></tt>.</td>
 188 </tr>
 189 </tbody>
 190 </table>
 191 <p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
 192 <table class="docutils field-list" frame="void" rules="none">
 193 <col class="field-name" />
 194 <col class="field-body" />
 195 <tbody valign="top">
 196 <tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 197 </tr>
 198 </tbody>
 199 </table>
 200 <p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
 201 <table class="docutils field-list" frame="void" rules="none">
 202 <col class="field-name" />
 203 <col class="field-body" />
 204 <tbody valign="top">
 205 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
 206 </tr>
 207 </tbody>
 208 </table>
 209 <p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
 210 <table class="docutils field-list" frame="void" rules="none">
 211 <col class="field-name" />
 212 <col class="field-body" />
 213 <tbody valign="top">
 214 <tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_inc</span></tt></td>
 215 </tr>
 216 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
 217 </tr>
 218 </tbody>
 219 </table>
 220 <p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
 221 <table class="docutils field-list" frame="void" rules="none">
 222 <col class="field-name" />
 223 <col class="field-body" />
 224 <tbody valign="top">
 225 <tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_inc</span></tt></td>
 226 </tr>
 227 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
 228 </tr>
 229 </tbody>
 230 </table>
 231 <p><tt class="docutils literal"><span class="pre">Incrementable</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
 232 <table class="docutils field-list" frame="void" rules="none">
 233 <col class="field-name" />
 234 <col class="field-body" />
 235 <tbody valign="top">
 236 <tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
 237 </tr>
 238 </tbody>
 239 </table>
 240 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
 241 <!-- Software License, Version 1.0. (See accompanying -->
 242 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 243 <pre class="literal-block">
 244 template &lt;class Incrementable&gt;
 245 counting_iterator&lt;Incrementable&gt; make_counting_iterator(Incrementable x);
 246 </pre>
 247 <table class="docutils field-list" frame="void" rules="none">
 248 <col class="field-name" />
 249 <col class="field-body" />
 250 <tbody valign="top">
 251 <tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">counting_iterator&lt;Incrementable&gt;</span></tt>
 252 with <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 253 </tr>
 254 </tbody>
 255 </table>
 256 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
 257 <!-- Software License, Version 1.0. (See accompanying -->
 258 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 259 </div>
 260 <div class="section" id="example">
 261 <h1><a class="toc-backref" href="#id6">Example</a></h1>
 262 <p>This example fills an array with numbers and a second array with
 263 pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both
 264 tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
 265 into the first array via indirection through the second array.</p>
 266 <pre class="literal-block">
 267 int N = 7;
 268 std::vector&lt;int&gt; numbers;
 269 typedef std::vector&lt;int&gt;::iterator n_iter;
 270 std::copy(boost::counting_iterator&lt;int&gt;(0),
 271          boost::counting_iterator&lt;int&gt;(N),
 272          std::back_inserter(numbers));
 273
 274 std::vector&lt;std::vector&lt;int&gt;::iterator&gt; pointers;
 275 std::copy(boost::make_counting_iterator(numbers.begin()),
 276           boost::make_counting_iterator(numbers.end()),
 277           std::back_inserter(pointers));
 278
 279 std::cout &lt;&lt; &quot;indirectly printing out the numbers from 0 to &quot;
 280           &lt;&lt; N &lt;&lt; std::endl;
 281 std::copy(boost::make_indirect_iterator(pointers.begin()),
 282           boost::make_indirect_iterator(pointers.end()),
 283           std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
 284 std::cout &lt;&lt; std::endl;
 285 </pre>
 286 <p>The output is:</p>
 287 <pre class="literal-block">
 288 indirectly printing out the numbers from 0 to 7
 289 0 1 2 3 4 5 6
 290 </pre>
 291 <p>The source code for this example can be found <a class="reference external" href="../example/counting_iterator_example.cpp">here</a>.</p>
 292 </div>
 293 </div>
 294 <div class="footer">
 295 <hr class="footer" />
 296 <a class="reference external" href="counting_iterator.rst">View document source</a>.
 297 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.
 298
 299 </div>
 300 </body>
 301 </html>