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>Transform 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=
"transform-iterator">
16 <h1 class=
"title">Transform 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 The transform iterator adapts an iterator by modifying the
46 <tt class=
"docutils literal"><span class=
"pre">operator*
</span></tt> to apply a function object to the result of
47 dereferencing the iterator and returning the result.
</td>
51 <div class=
"contents topic" id=
"table-of-contents">
52 <p class=
"topic-title first">Table of Contents
</p>
54 <li><a class=
"reference internal" href=
"#transform-iterator-synopsis" id=
"id2"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> synopsis
</a></li>
55 <li><a class=
"reference internal" href=
"#transform-iterator-requirements" id=
"id3"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> requirements
</a></li>
56 <li><a class=
"reference internal" href=
"#transform-iterator-models" id=
"id4"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> models
</a></li>
57 <li><a class=
"reference internal" href=
"#transform-iterator-operations" id=
"id5"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> operations
</a></li>
58 <li><a class=
"reference internal" href=
"#example" id=
"id6">Example
</a></li>
61 <div class=
"section" id=
"transform-iterator-synopsis">
62 <h1><a class=
"toc-backref" href=
"#id2"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> synopsis
</a></h1>
63 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
64 <!-- Software License, Version 1.0. (See accompanying -->
65 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
66 <!-- Version 1.3 of this document was accepted for TR1 -->
67 <pre class=
"literal-block">
68 template
<class UnaryFunction,
70 class Reference = use_default,
71 class Value = use_default
>
72 class transform_iterator
75 typedef /* see below */ value_type;
76 typedef /* see below */ reference;
77 typedef /* see below */ pointer;
78 typedef iterator_traits
<Iterator
>::difference_type difference_type;
79 typedef /* see below */ iterator_category;
82 transform_iterator(Iterator const
& x, UnaryFunction f);
84 template
<class F2, class I2, class R2, class V2
>
86 transform_iterator
<F2, I2, R2, V2
> const
& t
87 , typename enable_if_convertible
<I2, Iterator
>::type* =
0 // exposition only
88 , typename enable_if_convertible
<F2, UnaryFunction
>::type* =
0 // exposition only
90 UnaryFunction functor() const;
91 Iterator const
& base() const;
92 reference operator*() const;
93 transform_iterator
& operator++();
94 transform_iterator
& operator--();
96 Iterator m_iterator; // exposition only
97 UnaryFunction m_f; // exposition only
100 <p>If
<tt class=
"docutils literal"><span class=
"pre">Reference
</span></tt> is
<tt class=
"docutils literal"><span class=
"pre">use_default
</span></tt> then the
<tt class=
"docutils literal"><span class=
"pre">reference
</span></tt> member of
101 <tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> is
102 <tt class=
"docutils literal"><span class=
"pre">result_of
<const UnaryFunction(iterator_traits
<Iterator
>::reference)
>::type
</span></tt>.
103 Otherwise,
<tt class=
"docutils literal"><span class=
"pre">reference
</span></tt> is
<tt class=
"docutils literal"><span class=
"pre">Reference
</span></tt>.
</p>
104 <p>If
<tt class=
"docutils literal"><span class=
"pre">Value
</span></tt> is
<tt class=
"docutils literal"><span class=
"pre">use_default
</span></tt> then the
<tt class=
"docutils literal"><span class=
"pre">value_type
</span></tt> member is
105 <tt class=
"docutils literal"><span class=
"pre">remove_cv
<remove_reference
<reference
></span> <span class=
"pre">>::type
</span></tt>. Otherwise,
106 <tt class=
"docutils literal"><span class=
"pre">value_type
</span></tt> is
<tt class=
"docutils literal"><span class=
"pre">Value
</span></tt>.
</p>
107 <p>If
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> models Readable Lvalue Iterator and if
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt>
108 models Random Access Traversal Iterator, then
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt> is
109 convertible to
<tt class=
"docutils literal"><span class=
"pre">random_access_iterator_tag
</span></tt>. Otherwise, if
110 <tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> models Bidirectional Traversal Iterator, then
111 <tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt> is convertible to
112 <tt class=
"docutils literal"><span class=
"pre">bidirectional_iterator_tag
</span></tt>. Otherwise
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt> is
113 convertible to
<tt class=
"docutils literal"><span class=
"pre">forward_iterator_tag
</span></tt>. If
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> does not
114 model Readable Lvalue Iterator then
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt> is
115 convertible to
<tt class=
"docutils literal"><span class=
"pre">input_iterator_tag
</span></tt>.
</p>
117 <div class=
"section" id=
"transform-iterator-requirements">
118 <h1><a class=
"toc-backref" href=
"#id3"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> requirements
</a></h1>
119 <p>The type
<tt class=
"docutils literal"><span class=
"pre">UnaryFunction
</span></tt> must be Assignable, Copy Constructible, and
120 the expression
<tt class=
"docutils literal"><span class=
"pre">f(*i)
</span></tt> must be valid where
<tt class=
"docutils literal"><span class=
"pre">f
</span></tt> is a const object of
121 type
<tt class=
"docutils literal"><span class=
"pre">UnaryFunction
</span></tt>,
<tt class=
"docutils literal"><span class=
"pre">i
</span></tt> is an object of type
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt>, and
122 where the type of
<tt class=
"docutils literal"><span class=
"pre">f(*i)
</span></tt> must be
123 <tt class=
"docutils literal"><span class=
"pre">result_of
<const UnaryFunction(iterator_traits
<Iterator
>::reference)
>::type
</span></tt>.
</p>
124 <p>The argument
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> shall model Readable Iterator.
</p>
126 <div class=
"section" id=
"transform-iterator-models">
127 <h1><a class=
"toc-backref" href=
"#id4"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> models
</a></h1>
128 <p>The resulting
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> models the most refined of the
129 following that is also modeled by
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt>.
</p>
132 <li>Writable Lvalue Iterator if
<tt class=
"docutils literal"><span class=
"pre">transform_iterator::reference
</span></tt> is a non-const reference.
</li>
133 <li>Readable Lvalue Iterator if
<tt class=
"docutils literal"><span class=
"pre">transform_iterator::reference
</span></tt> is a const reference.
</li>
134 <li>Readable Iterator otherwise.
</li>
137 <p>The
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> models the most refined standard traversal
138 concept that is modeled by the
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> argument.
</p>
139 <p>If
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> is a model of Readable Lvalue Iterator then
140 it models the following original iterator concepts depending on what
141 the
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> argument models.
</p>
142 <table border=
"1" class=
"docutils">
147 <thead valign=
"bottom">
148 <tr><th class=
"head">If
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> models
</th>
149 <th class=
"head">then
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> models
</th>
153 <tr><td>Single Pass Iterator
</td>
154 <td>Input Iterator
</td>
156 <tr><td>Forward Traversal Iterator
</td>
157 <td>Forward Iterator
</td>
159 <tr><td>Bidirectional Traversal Iterator
</td>
160 <td>Bidirectional Iterator
</td>
162 <tr><td>Random Access Traversal Iterator
</td>
163 <td>Random Access Iterator
</td>
167 <p>If
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> models Writable Lvalue Iterator then it is a
168 mutable iterator (as defined in the old iterator requirements).
</p>
169 <p><tt class=
"docutils literal"><span class=
"pre">transform_iterator
<F1,
</span> <span class=
"pre">X,
</span> <span class=
"pre">R1,
</span> <span class=
"pre">V1
></span></tt> is interoperable with
170 <tt class=
"docutils literal"><span class=
"pre">transform_iterator
<F2,
</span> <span class=
"pre">Y,
</span> <span class=
"pre">R2,
</span> <span class=
"pre">V2
></span></tt> if and only if
<tt class=
"docutils literal"><span class=
"pre">X
</span></tt> is
171 interoperable with
<tt class=
"docutils literal"><span class=
"pre">Y
</span></tt>.
</p>
173 <div class=
"section" id=
"transform-iterator-operations">
174 <h1><a class=
"toc-backref" href=
"#id5"><tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> operations
</a></h1>
175 <p>In addition to the operations required by the concepts modeled by
176 <tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt>,
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> provides the following
178 <p><tt class=
"docutils literal"><span class=
"pre">transform_iterator();
</span></tt></p>
179 <table class=
"docutils field-list" frame=
"void" rules=
"none">
180 <col class=
"field-name" />
181 <col class=
"field-body" />
183 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body">An instance of
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> with
<tt class=
"docutils literal"><span class=
"pre">m_f
</span></tt>
184 and
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> default constructed.
</td>
188 <p><tt class=
"docutils literal"><span class=
"pre">transform_iterator(Iterator
</span> <span class=
"pre">const
&</span> <span class=
"pre">x,
</span> <span class=
"pre">UnaryFunction
</span> <span class=
"pre">f);
</span></tt></p>
189 <table class=
"docutils field-list" frame=
"void" rules=
"none">
190 <col class=
"field-name" />
191 <col class=
"field-body" />
193 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body">An instance of
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> with
<tt class=
"docutils literal"><span class=
"pre">m_f
</span></tt>
194 initialized to
<tt class=
"docutils literal"><span class=
"pre">f
</span></tt> and
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> initialized to
<tt class=
"docutils literal"><span class=
"pre">x
</span></tt>.
</td>
198 <pre class=
"literal-block">
199 template
<class F2, class I2, class R2, class V2
>
201 transform_iterator
<F2, I2, R2, V2
> const
& t
202 , typename enable_if_convertible
<I2, Iterator
>::type* =
0 // exposition only
203 , typename enable_if_convertible
<F2, UnaryFunction
>::type* =
0 // exposition only
206 <table class=
"docutils field-list" frame=
"void" rules=
"none">
207 <col class=
"field-name" />
208 <col class=
"field-body" />
210 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body">An instance of
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
</span></tt> with
<tt class=
"docutils literal"><span class=
"pre">m_f
</span></tt>
211 initialized to
<tt class=
"docutils literal"><span class=
"pre">t.functor()
</span></tt> and
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> initialized to
212 <tt class=
"docutils literal"><span class=
"pre">t.base()
</span></tt>.
</td>
214 <tr class=
"field"><th class=
"field-name">Requires:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">OtherIterator
</span></tt> is implicitly convertible to
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt>.
</td>
218 <p><tt class=
"docutils literal"><span class=
"pre">UnaryFunction
</span> <span class=
"pre">functor()
</span> <span class=
"pre">const;
</span></tt></p>
219 <table class=
"docutils field-list" frame=
"void" rules=
"none">
220 <col class=
"field-name" />
221 <col class=
"field-body" />
223 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">m_f
</span></tt></td>
227 <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>
228 <table class=
"docutils field-list" frame=
"void" rules=
"none">
229 <col class=
"field-name" />
230 <col class=
"field-body" />
232 <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>
236 <p><tt class=
"docutils literal"><span class=
"pre">reference
</span> <span class=
"pre">operator*()
</span> <span class=
"pre">const;
</span></tt></p>
237 <table class=
"docutils field-list" frame=
"void" rules=
"none">
238 <col class=
"field-name" />
239 <col class=
"field-body" />
241 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">m_f(*m_iterator)
</span></tt></td>
245 <p><tt class=
"docutils literal"><span class=
"pre">transform_iterator
&</span> <span class=
"pre">operator++();
</span></tt></p>
246 <table class=
"docutils field-list" frame=
"void" rules=
"none">
247 <col class=
"field-name" />
248 <col class=
"field-body" />
250 <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>
252 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">*this
</span></tt></td>
256 <p><tt class=
"docutils literal"><span class=
"pre">transform_iterator
&</span> <span class=
"pre">operator--();
</span></tt></p>
257 <table class=
"docutils field-list" frame=
"void" rules=
"none">
258 <col class=
"field-name" />
259 <col class=
"field-body" />
261 <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>
263 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">*this
</span></tt></td>
267 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
268 <!-- Software License, Version 1.0. (See accompanying -->
269 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
270 <pre class=
"literal-block">
271 template
<class UnaryFunction, class Iterator
>
272 transform_iterator
<UnaryFunction, Iterator
>
273 make_transform_iterator(Iterator it, UnaryFunction fun);
275 <table class=
"docutils field-list" frame=
"void" rules=
"none">
276 <col class=
"field-name" />
277 <col class=
"field-body" />
279 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body">An instance of
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
<UnaryFunction,
</span> <span class=
"pre">Iterator
></span></tt> with
<tt class=
"docutils literal"><span class=
"pre">m_f
</span></tt>
280 initialized to
<tt class=
"docutils literal"><span class=
"pre">f
</span></tt> and
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> initialized to
<tt class=
"docutils literal"><span class=
"pre">x
</span></tt>.
</td>
284 <pre class=
"literal-block">
285 template
<class UnaryFunction, class Iterator
>
286 transform_iterator
<UnaryFunction, Iterator
>
287 make_transform_iterator(Iterator it);
289 <table class=
"docutils field-list" frame=
"void" rules=
"none">
290 <col class=
"field-name" />
291 <col class=
"field-body" />
293 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body">An instance of
<tt class=
"docutils literal"><span class=
"pre">transform_iterator
<UnaryFunction,
</span> <span class=
"pre">Iterator
></span></tt> with
<tt class=
"docutils literal"><span class=
"pre">m_f
</span></tt>
294 default constructed and
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt> initialized to
<tt class=
"docutils literal"><span class=
"pre">x
</span></tt>.
</td>
298 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
299 <!-- Software License, Version 1.0. (See accompanying -->
300 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
302 <div class=
"section" id=
"example">
303 <h1><a class=
"toc-backref" href=
"#id6">Example
</a></h1>
304 <p>This is a simple example of using the transform_iterators class to
305 generate iterators that multiply (or add to) the value returned by
306 dereferencing the iterator. It would be cooler to use lambda library
308 <pre class=
"literal-block">
309 int x[] = {
1,
2,
3,
4,
5,
6,
7,
8 };
310 const int N = sizeof(x)/sizeof(int);
312 typedef boost::binder1st
< std::multiplies
<int
> > Function;
313 typedef boost::transform_iterator
<Function, int*
> doubling_iterator;
315 doubling_iterator i(x, boost::bind1st(std::multiplies
<int
>(),
2)),
316 i_end(x + N, boost::bind1st(std::multiplies
<int
>(),
2));
318 std::cout
<< "multiplying the array by
2:
" << std::endl;
320 std::cout
<< *i++
<< " ";
321 std::cout
<< std::endl;
323 std::cout
<< "adding
4 to each element in the array:
" << std::endl;
324 std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus
<int
>(),
4)),
325 boost::make_transform_iterator(x + N, boost::bind1st(std::plus
<int
>(),
4)),
326 std::ostream_iterator
<int
>(std::cout,
" "));
327 std::cout
<< std::endl;
329 <p>The output is:
</p>
330 <pre class=
"literal-block">
331 multiplying the array by
2:
333 adding
4 to each element in the array:
336 <p>The source code for this example can be found
<a class=
"reference external" href=
"../example/transform_iterator_example.cpp">here
</a>.
</p>
340 <hr class=
"footer" />
341 <a class=
"reference external" href=
"transform_iterator.rst">View document source
</a>.
342 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.