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@boost-consulting.com">dave@boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>, <a class="last reference external" href="mailto:witt@ive.uni-hannover.de">witt@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 27Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport 28Railway 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 43through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>? The only iterator 44operation 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. 46The counting iterator adaptor adds this crucial piece of 47functionality to whatever type it wraps. One can use the 48counting iterator adaptor not only with integer types, but with 49any 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 54returns the current value of the object. All other iterator operations 55are 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"> 76template < 77 class Incrementable 78 , class CategoryOrTraversal = use_default 79 , class Difference = use_default 80> 81class counting_iterator 82{ 83public: 84 typedef Incrementable value_type; 85 typedef const Incrementable& 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& rhs); 92 explicit counting_iterator(Incrementable x); 93 Incrementable const& base() const; 94 reference operator*() const; 95 counting_iterator& operator++(); 96 counting_iterator& operator--(); 97private: 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 103type. 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 105algorithm:</p> 106<pre class="literal-block"> 107if (CategoryOrTraversal is not use_default) 108 return CategoryOrTraversal 109else if (numeric_limits<Incrementable>::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&) 112else 113 return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>( 114 iterator_traversal<Incrementable>::type, 115 Incrementable, const Incrementable&) 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 120the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits<Incrementable>::is_specialized</span></tt> 121is 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> 128or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p> 129<pre class="literal-block"> 130Incrementable i, j; 131++i; // pre-increment 132i == 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>, 136the 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>, 142the following must must also be valid:</p> 143<pre class="literal-block"> 144counting_iterator::difference_type n; 145i += n; 146n = i - j; 147i < 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 153Iterator. In addition, they model the concepts corresponding to the 154iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible. 155Also, 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 157tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>. Otherwise, if 158<tt class="docutils literal"><span class="pre">numeric_limits<Incrementable>::is_specialized</span></tt>, then 159<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator. 160Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal 161concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p> 162<p><tt class="docutils literal"><span class="pre">counting_iterator<X,C1,D1></span></tt> is interoperable with 163<tt class="docutils literal"><span class="pre">counting_iterator<Y,C2,D2></span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is 164interoperable 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 170operations.</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&</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&</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&</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&</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"> 244template <class Incrementable> 245counting_iterator<Incrementable> 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<Incrementable></span></tt> 252with <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 263pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both 264tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers 265into the first array via indirection through the second array.</p> 266<pre class="literal-block"> 267int N = 7; 268std::vector<int> numbers; 269typedef std::vector<int>::iterator n_iter; 270std::copy(boost::counting_iterator<int>(0), 271 boost::counting_iterator<int>(N), 272 std::back_inserter(numbers)); 273 274std::vector<std::vector<int>::iterator> pointers; 275std::copy(boost::make_counting_iterator(numbers.begin()), 276 boost::make_counting_iterator(numbers.end()), 277 std::back_inserter(pointers)); 278 279std::cout << "indirectly printing out the numbers from 0 to " 280 << N << std::endl; 281std::copy(boost::make_indirect_iterator(pointers.begin()), 282 boost::make_indirect_iterator(pointers.end()), 283 std::ostream_iterator<int>(std::cout, " ")); 284std::cout << std::endl; 285</pre> 286<p>The output is:</p> 287<pre class="literal-block"> 288indirectly printing out the numbers from 0 to 7 2890 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>. 297Generated 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> 302