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">
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>Indirect 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" />
15 <div class=
"document" id=
"indirect-iterator">
16 <h1 class=
"title">Indirect Iterator
</h1>
17 <table class=
"docinfo" frame=
"void" rules=
"none">
18 <col class=
"docinfo-name" />
19 <col class=
"docinfo-content" />
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>
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" />
42 <tr class=
"field"><th class=
"field-name">abstract:
</th><td class=
"field-body"><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
43 <!-- Software License, Version 1.0. (See accompanying -->
44 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
45 <tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> adapts an iterator by applying an
46 <em>extra
</em> dereference inside of
<tt class=
"docutils literal"><span class=
"pre">operator*()
</span></tt>. For example, this
47 iterator adaptor makes it possible to view a container of pointers
48 (e.g.
<tt class=
"docutils literal"><span class=
"pre">list
<foo*
></span></tt>) as if it were a container of the pointed-to type
49 (e.g.
<tt class=
"docutils literal"><span class=
"pre">list
<foo
></span></tt>).
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> depends on two
50 auxiliary traits,
<tt class=
"docutils literal"><span class=
"pre">pointee
</span></tt> and
<tt class=
"docutils literal"><span class=
"pre">indirect_reference
</span></tt>, to
51 provide support for underlying iterators whose
<tt class=
"docutils literal"><span class=
"pre">value_type
</span></tt> is
56 <div class=
"contents topic" id=
"table-of-contents">
57 <p class=
"topic-title first">Table of Contents
</p>
59 <li><a class=
"reference internal" href=
"#indirect-iterator-synopsis" id=
"id2"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> synopsis
</a></li>
60 <li><a class=
"reference internal" href=
"#indirect-iterator-requirements" id=
"id3"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> requirements
</a></li>
61 <li><a class=
"reference internal" href=
"#indirect-iterator-models" id=
"id4"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> models
</a></li>
62 <li><a class=
"reference internal" href=
"#indirect-iterator-operations" id=
"id5"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> operations
</a></li>
63 <li><a class=
"reference internal" href=
"#example" id=
"id6">Example
</a></li>
66 <div class=
"section" id=
"indirect-iterator-synopsis">
67 <h1><a class=
"toc-backref" href=
"#id2"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> synopsis
</a></h1>
68 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
69 <!-- Software License, Version 1.0. (See accompanying -->
70 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
71 <pre class=
"literal-block">
74 , class Value = use_default
75 , class CategoryOrTraversal = use_default
76 , class Reference = use_default
77 , class Difference = use_default
79 class indirect_iterator
82 typedef /* see below */ value_type;
83 typedef /* see below */ reference;
84 typedef /* see below */ pointer;
85 typedef /* see below */ difference_type;
86 typedef /* see below */ iterator_category;
89 indirect_iterator(Iterator x);
92 class Iterator2, class Value2, class Category2
93 , class Reference2, class Difference2
97 Iterator2, Value2, Category2, Reference2, Difference2
99 , typename enable_if_convertible
<Iterator2, Iterator
>::type* =
0 // exposition
102 Iterator const
& base() const;
103 reference operator*() const;
104 indirect_iterator
& operator++();
105 indirect_iterator
& operator--();
107 Iterator m_iterator; // exposition
110 <p>The member types of
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> are defined according to
111 the following pseudo-code, where
<tt class=
"docutils literal"><span class=
"pre">V
</span></tt> is
112 <tt class=
"docutils literal"><span class=
"pre">iterator_traits
<Iterator
>::value_type
</span></tt></p>
113 <pre class=
"literal-block">
114 if (Value is use_default) then
115 typedef remove_const
<pointee
<V
>::type
>::type value_type;
117 typedef remove_const
<Value
>::type value_type;
119 if (Reference is use_default) then
120 if (Value is use_default) then
121 typedef indirect_reference
<V
>::type reference;
123 typedef Value
& reference;
125 typedef Reference reference;
127 if (Value is use_default) then
128 typedef pointee
<V
>::type* pointer;
130 typedef Value* pointer;
132 if (Difference is use_default)
133 typedef iterator_traits
<Iterator
>::difference_type difference_type;
135 typedef Difference difference_type;
137 if (CategoryOrTraversal is use_default)
138 typedef
<em>iterator-category
</em> (
139 iterator_traversal
<Iterator
>::type,``reference``,``value_type``
142 typedef
<em>iterator-category
</em> (
143 CategoryOrTraversal,``reference``,``value_type``
147 <div class=
"section" id=
"indirect-iterator-requirements">
148 <h1><a class=
"toc-backref" href=
"#id3"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> requirements
</a></h1>
149 <p>The expression
<tt class=
"docutils literal"><span class=
"pre">*v
</span></tt>, where
<tt class=
"docutils literal"><span class=
"pre">v
</span></tt> is an object of
150 <tt class=
"docutils literal"><span class=
"pre">iterator_traits
<Iterator
>::value_type
</span></tt>, shall be valid
151 expression and convertible to
<tt class=
"docutils literal"><span class=
"pre">reference
</span></tt>.
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> shall
152 model the traversal concept indicated by
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt>.
153 <tt class=
"docutils literal"><span class=
"pre">Value
</span></tt>,
<tt class=
"docutils literal"><span class=
"pre">Reference
</span></tt>, and
<tt class=
"docutils literal"><span class=
"pre">Difference
</span></tt> shall be chosen so
154 that
<tt class=
"docutils literal"><span class=
"pre">value_type
</span></tt>,
<tt class=
"docutils literal"><span class=
"pre">reference
</span></tt>, and
<tt class=
"docutils literal"><span class=
"pre">difference_type
</span></tt> meet
155 the requirements indicated by
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt>.
</p>
156 <p>[Note: there are further requirements on the
157 <tt class=
"docutils literal"><span class=
"pre">iterator_traits
<Iterator
>::value_type
</span></tt> if the
<tt class=
"docutils literal"><span class=
"pre">Value
</span></tt>
158 parameter is not
<tt class=
"docutils literal"><span class=
"pre">use_default
</span></tt>, as implied by the algorithm for
159 deducing the default for the
<tt class=
"docutils literal"><span class=
"pre">value_type
</span></tt> member.]
</p>
161 <div class=
"section" id=
"indirect-iterator-models">
162 <h1><a class=
"toc-backref" href=
"#id4"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> models
</a></h1>
163 <p>In addition to the concepts indicated by
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt>
164 and by
<tt class=
"docutils literal"><span class=
"pre">iterator_traversal
<indirect_iterator
>::type
</span></tt>, a
165 specialization of
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> models the following
166 concepts, Where
<tt class=
"docutils literal"><span class=
"pre">v
</span></tt> is an object of
167 <tt class=
"docutils literal"><span class=
"pre">iterator_traits
<Iterator
>::value_type
</span></tt>:
</p>
170 <li>Readable Iterator if
<tt class=
"docutils literal"><span class=
"pre">reference(*v)
</span></tt> is convertible to
171 <tt class=
"docutils literal"><span class=
"pre">value_type
</span></tt>.
</li>
172 <li>Writable Iterator if
<tt class=
"docutils literal"><span class=
"pre">reference(*v)
</span> <span class=
"pre">=
</span> <span class=
"pre">t
</span></tt> is a valid
173 expression (where
<tt class=
"docutils literal"><span class=
"pre">t
</span></tt> is an object of type
174 <tt class=
"docutils literal"><span class=
"pre">indirect_iterator::value_type
</span></tt>)
</li>
175 <li>Lvalue Iterator if
<tt class=
"docutils literal"><span class=
"pre">reference
</span></tt> is a reference type.
</li>
178 <p><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
<X,V1,C1,R1,D1
></span></tt> is interoperable with
179 <tt class=
"docutils literal"><span class=
"pre">indirect_iterator
<Y,V2,C2,R2,D2
></span></tt> if and only if
<tt class=
"docutils literal"><span class=
"pre">X
</span></tt> is
180 interoperable with
<tt class=
"docutils literal"><span class=
"pre">Y
</span></tt>.
</p>
182 <div class=
"section" id=
"indirect-iterator-operations">
183 <h1><a class=
"toc-backref" href=
"#id5"><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> operations
</a></h1>
184 <p>In addition to the operations required by the concepts described
185 above, specializations of
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> provide the
186 following operations.
</p>
187 <p><tt class=
"docutils literal"><span class=
"pre">indirect_iterator();
</span></tt></p>
188 <table class=
"docutils field-list" frame=
"void" rules=
"none">
189 <col class=
"field-name" />
190 <col class=
"field-body" />
192 <tr class=
"field"><th class=
"field-name">Requires:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> must be Default Constructible.
</td>
194 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body">Constructs an instance of
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> with
195 a default-constructed
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt>.
</td>
199 <p><tt class=
"docutils literal"><span class=
"pre">indirect_iterator(Iterator
</span> <span class=
"pre">x);
</span></tt></p>
200 <table class=
"docutils field-list" frame=
"void" rules=
"none">
201 <col class=
"field-name" />
202 <col class=
"field-body" />
204 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body">Constructs an instance of
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> with
205 <tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> copy constructed from
<tt class=
"docutils literal"><span class=
"pre">x
</span></tt>.
</td>
209 <pre class=
"literal-block">
211 class Iterator2, class Value2, unsigned Access, class Traversal
212 , class Reference2, class Difference2
215 indirect_iterator
<
216 Iterator2, Value2, Access, Traversal, Reference2, Difference2
218 , typename enable_if_convertible
<Iterator2, Iterator
>::type* =
0 // exposition
221 <table class=
"docutils field-list" frame=
"void" rules=
"none">
222 <col class=
"field-name" />
223 <col class=
"field-body" />
225 <tr class=
"field"><th class=
"field-name">Requires:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">Iterator2
</span></tt> is implicitly convertible to
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt>.
</td>
227 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body">Constructs an instance of
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> whose
228 <tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> subobject is constructed from
<tt class=
"docutils literal"><span class=
"pre">y.base()
</span></tt>.
</td>
232 <p><tt class=
"docutils literal"><span class=
"pre">Iterator
</span> <span class=
"pre">const
&</span> <span class=
"pre">base()
</span> <span class=
"pre">const;
</span></tt></p>
233 <table class=
"docutils field-list" frame=
"void" rules=
"none">
234 <col class=
"field-name" />
235 <col class=
"field-body" />
237 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt></td>
241 <p><tt class=
"docutils literal"><span class=
"pre">reference
</span> <span class=
"pre">operator*()
</span> <span class=
"pre">const;
</span></tt></p>
242 <table class=
"docutils field-list" frame=
"void" rules=
"none">
243 <col class=
"field-name" />
244 <col class=
"field-body" />
246 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">**m_iterator
</span></tt></td>
250 <p><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
&</span> <span class=
"pre">operator++();
</span></tt></p>
251 <table class=
"docutils field-list" frame=
"void" rules=
"none">
252 <col class=
"field-name" />
253 <col class=
"field-body" />
255 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">++m_iterator
</span></tt></td>
257 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">*this
</span></tt></td>
261 <p><tt class=
"docutils literal"><span class=
"pre">indirect_iterator
&</span> <span class=
"pre">operator--();
</span></tt></p>
262 <table class=
"docutils field-list" frame=
"void" rules=
"none">
263 <col class=
"field-name" />
264 <col class=
"field-body" />
266 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">--m_iterator
</span></tt></td>
268 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">*this
</span></tt></td>
272 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
273 <!-- Software License, Version 1.0. (See accompanying -->
274 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
276 <div class=
"section" id=
"example">
277 <h1><a class=
"toc-backref" href=
"#id6">Example
</a></h1>
278 <p>This example prints an array of characters, using
279 <tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> to access the array of characters through an
280 array of pointers. Next
<tt class=
"docutils literal"><span class=
"pre">indirect_iterator
</span></tt> is used with the
281 <tt class=
"docutils literal"><span class=
"pre">transform
</span></tt> algorithm to copy the characters (incremented by one) to
282 another array. A constant indirect iterator is used for the source and
283 a mutable indirect iterator is used for the destination. The last part
284 of the example prints the original array of characters, but this time
285 using the
<tt class=
"docutils literal"><span class=
"pre">make_indirect_iterator
</span></tt> helper function.
</p>
286 <pre class=
"literal-block">
287 char characters[] =
"abcdefg
";
288 const int N = sizeof(characters)/sizeof(char) -
1; // -
1 since characters has a null char
289 char* pointers_to_chars[N]; // at the end.
290 for (int i =
0; i
< N; ++i)
291 pointers_to_chars[i] =
&characters[i];
293 // Example of using indirect_iterator
295 boost::indirect_iterator
<char**, char
>
296 indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
298 std::copy(indirect_first, indirect_last, std::ostream_iterator
<char
>(std::cout,
",
"));
299 std::cout
<< std::endl;
302 // Example of making mutable and constant indirect iterators
304 char mutable_characters[N];
305 char* pointers_to_mutable_chars[N];
306 for (int j =
0; j
< N; ++j)
307 pointers_to_mutable_chars[j] =
&mutable_characters[j];
309 boost::indirect_iterator
<char* const*
> mutable_indirect_first(pointers_to_mutable_chars),
310 mutable_indirect_last(pointers_to_mutable_chars + N);
311 boost::indirect_iterator
<char* const*, char const
> const_indirect_first(pointers_to_chars),
312 const_indirect_last(pointers_to_chars + N);
314 std::transform(const_indirect_first, const_indirect_last,
315 mutable_indirect_first, std::bind1st(std::plus
<char
>(),
1));
317 std::copy(mutable_indirect_first, mutable_indirect_last,
318 std::ostream_iterator
<char
>(std::cout,
",
"));
319 std::cout
<< std::endl;
322 // Example of using make_indirect_iterator()
324 std::copy(boost::make_indirect_iterator(pointers_to_chars),
325 boost::make_indirect_iterator(pointers_to_chars + N),
326 std::ostream_iterator
<char
>(std::cout,
",
"));
327 std::cout
<< std::endl;
329 <p>The output is:
</p>
330 <pre class=
"literal-block">
335 <p>The source code for this example can be found
<a class=
"reference external" href=
"../example/indirect_iterator_example.cpp">here
</a>.
</p>
339 <hr class=
"footer" />
340 <a class=
"reference external" href=
"indirect_iterator.rst">View document source
</a>.
341 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.