]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | |
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 < | |
77 | class Incrementable | |
78 | , class CategoryOrTraversal = use_default | |
79 | , class Difference = use_default | |
80 | > | |
81 | class counting_iterator | |
82 | { | |
83 | public: | |
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--(); | |
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<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&) | |
112 | else | |
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 | |
120 | the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits<Incrementable>::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 < 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<Incrementable>::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<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 | |
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&</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"> | |
244 | template <class Incrementable> | |
245 | counting_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> | |
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<int> numbers; | |
269 | typedef std::vector<int>::iterator n_iter; | |
270 | std::copy(boost::counting_iterator<int>(0), | |
271 | boost::counting_iterator<int>(N), | |
272 | std::back_inserter(numbers)); | |
273 | ||
274 | std::vector<std::vector<int>::iterator> 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 << "indirectly printing out the numbers from 0 to " | |
280 | << N << std::endl; | |
281 | std::copy(boost::make_indirect_iterator(pointers.begin()), | |
282 | boost::make_indirect_iterator(pointers.end()), | |
283 | std::ostream_iterator<int>(std::cout, " ")); | |
284 | std::cout << 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> |