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>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" /> 13</head> 14<body> 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" /> 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 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"><!-- 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) --> 45The 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 47dereferencing the iterator and returning the result.</td> 48</tr> 49</tbody> 50</table> 51<div class="contents topic" id="table-of-contents"> 52<p class="topic-title first">Table of Contents</p> 53<ul class="simple"> 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> 59</ul> 60</div> 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"> 68template <class UnaryFunction, 69 class Iterator, 70 class Reference = use_default, 71 class Value = use_default> 72class transform_iterator 73{ 74public: 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; 80 81 transform_iterator(); 82 transform_iterator(Iterator const& x, UnaryFunction f); 83 84 template<class F2, class I2, class R2, class V2> 85 transform_iterator( 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 89 ); 90 UnaryFunction functor() const; 91 Iterator const& base() const; 92 reference operator*() const; 93 transform_iterator& operator++(); 94 transform_iterator& operator--(); 95private: 96 Iterator m_iterator; // exposition only 97 UnaryFunction m_f; // exposition only 98}; 99</pre> 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>. 103Otherwise, <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> 108models Random Access Traversal Iterator, then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is 109convertible 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 113convertible 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 114model Readable Lvalue Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is 115convertible to <tt class="docutils literal"><span class="pre">input_iterator_tag</span></tt>.</p> 116</div> 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 120the 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 121type <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 122where 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> 125</div> 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 129following that is also modeled by <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</p> 130<blockquote> 131<ul class="simple"> 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> 135</ul> 136</blockquote> 137<p>The <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models the most refined standard traversal 138concept 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 140it models the following original iterator concepts depending on what 141the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument models.</p> 142<table border="1" class="docutils"> 143<colgroup> 144<col width="47%" /> 145<col width="53%" /> 146</colgroup> 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> 150</tr> 151</thead> 152<tbody valign="top"> 153<tr><td>Single Pass Iterator</td> 154<td>Input Iterator</td> 155</tr> 156<tr><td>Forward Traversal Iterator</td> 157<td>Forward Iterator</td> 158</tr> 159<tr><td>Bidirectional Traversal Iterator</td> 160<td>Bidirectional Iterator</td> 161</tr> 162<tr><td>Random Access Traversal Iterator</td> 163<td>Random Access Iterator</td> 164</tr> 165</tbody> 166</table> 167<p>If <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> models Writable Lvalue Iterator then it is a 168mutable 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 171interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p> 172</div> 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 177operations.</p> 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" /> 182<tbody valign="top"> 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> 184and <tt class="docutils literal"><span class="pre">m_iterator</span></tt> default constructed.</td> 185</tr> 186</tbody> 187</table> 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" /> 192<tbody valign="top"> 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> 194initialized 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> 195</tr> 196</tbody> 197</table> 198<pre class="literal-block"> 199template<class F2, class I2, class R2, class V2> 200transform_iterator( 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 204); 205</pre> 206<table class="docutils field-list" frame="void" rules="none"> 207<col class="field-name" /> 208<col class="field-body" /> 209<tbody valign="top"> 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> 211initialized 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> 213</tr> 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> 215</tr> 216</tbody> 217</table> 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" /> 222<tbody valign="top"> 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> 224</tr> 225</tbody> 226</table> 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" /> 231<tbody valign="top"> 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> 233</tr> 234</tbody> 235</table> 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" /> 240<tbody valign="top"> 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> 242</tr> 243</tbody> 244</table> 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" /> 249<tbody valign="top"> 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> 251</tr> 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> 253</tr> 254</tbody> 255</table> 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" /> 260<tbody valign="top"> 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> 262</tr> 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> 264</tr> 265</tbody> 266</table> 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"> 271template <class UnaryFunction, class Iterator> 272transform_iterator<UnaryFunction, Iterator> 273make_transform_iterator(Iterator it, UnaryFunction fun); 274</pre> 275<table class="docutils field-list" frame="void" rules="none"> 276<col class="field-name" /> 277<col class="field-body" /> 278<tbody valign="top"> 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> 280initialized 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> 281</tr> 282</tbody> 283</table> 284<pre class="literal-block"> 285template <class UnaryFunction, class Iterator> 286transform_iterator<UnaryFunction, Iterator> 287make_transform_iterator(Iterator it); 288</pre> 289<table class="docutils field-list" frame="void" rules="none"> 290<col class="field-name" /> 291<col class="field-body" /> 292<tbody valign="top"> 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> 294default 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> 295</tr> 296</tbody> 297</table> 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) --> 301</div> 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 305generate iterators that multiply (or add to) the value returned by 306dereferencing the iterator. It would be cooler to use lambda library 307in this example.</p> 308<pre class="literal-block"> 309int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 }; 310const int N = sizeof(x)/sizeof(int); 311 312typedef boost::binder1st< std::multiplies<int> > Function; 313typedef boost::transform_iterator<Function, int*> doubling_iterator; 314 315doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)), 316 i_end(x + N, boost::bind1st(std::multiplies<int>(), 2)); 317 318std::cout << "multiplying the array by 2:" << std::endl; 319while (i != i_end) 320 std::cout << *i++ << " "; 321std::cout << std::endl; 322 323std::cout << "adding 4 to each element in the array:" << std::endl; 324std::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, " ")); 327std::cout << std::endl; 328</pre> 329<p>The output is:</p> 330<pre class="literal-block"> 331multiplying the array by 2: 3322 4 6 8 10 12 14 16 333adding 4 to each element in the array: 3345 6 7 8 9 10 11 12 335</pre> 336<p>The source code for this example can be found <a class="reference external" href="../example/transform_iterator_example.cpp">here</a>.</p> 337</div> 338</div> 339<div class="footer"> 340<hr class="footer" /> 341<a class="reference external" href="transform_iterator.rst">View document source</a>. 342Generated 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. 343 344</div> 345</body> 346</html> 347