Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / 5962333b719c9a350394e8b3a2ddcc7c5d280c72 / . / doc / counting_iterator.html
blob: 1cb5a17ee78fd28442a4eda04f6327276dc68211 [file] [log] [blame]
Brian Silverman59623332018-08-04 23:36:56 -0700[diff] [blame^]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
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 &lt;
77 class Incrementable
78 , class CategoryOrTraversal = use_default
79 , class Difference = use_default
80&gt;
81class counting_iterator
82{
83public:
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--();
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&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;)
112else
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
120the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::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 &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
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&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.
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&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
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&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">
244template &lt;class Incrementable&gt;
245counting_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>
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&lt;int&gt; numbers;
269typedef std::vector&lt;int&gt;::iterator n_iter;
270std::copy(boost::counting_iterator&lt;int&gt;(0),
271 boost::counting_iterator&lt;int&gt;(N),
272 std::back_inserter(numbers));
273
274std::vector&lt;std::vector&lt;int&gt;::iterator&gt; pointers;
275std::copy(boost::make_counting_iterator(numbers.begin()),
276 boost::make_counting_iterator(numbers.end()),
277 std::back_inserter(pointers));
278
279std::cout &lt;&lt; &quot;indirectly printing out the numbers from 0 to &quot;
280 &lt;&lt; N &lt;&lt; std::endl;
281std::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;));
284std::cout &lt;&lt; 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>