← Back to branch summary

~ubuntu-branches/debian/sid/boost1.49/sid

« back to all changes in this revision

Viewing changes to libs/iterator/doc/counting_iterator.html

  • Committer: Package Import Robot
  • Author(s): Steve M. Robbins
  • Date: 2012-02-26 00:31:44 UTC
  • Revision ID: package-import@ubuntu.com-20120226003144-eaytp12cbf6ubpms
Tags: upstream-1.49.0
Import upstream version 1.49.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
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>