1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Reverse Iterator</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Chapter 1. Boost.Iterator"> 8<link rel="up" href="../specialized.html" title="Specialized Adaptors"> 9<link rel="prev" href="permutation.html" title="Permutation Iterator"> 10<link rel="next" href="shared_container.html" title="Shared Container Iterator"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="permutation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="iterator.specialized.reverse"></a><a class="link" href="reverse.html" title="Reverse Iterator">Reverse Iterator</a> 28</h3></div></div></div> 29<p> 30 The reverse iterator adaptor iterates through the adapted iterator range 31 in the opposite direction. 32 </p> 33<h3> 34<a name="iterator.specialized.reverse.h0"></a> 35 <span class="phrase"><a name="iterator.specialized.reverse.example"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.example">Example</a> 36 </h3> 37<p> 38 The following example prints an array of characters in reverse order using 39 <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>. 40 </p> 41<pre class="programlisting"><span class="keyword">char</span> <span class="identifier">letters_</span><span class="special">[]</span> <span class="special">=</span> <span class="string">"hello world!"</span><span class="special">;</span> 42<span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">N</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">letters_</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">char</span><span class="special">)</span> <span class="special">-</span> <span class="number">1</span><span class="special">;</span> 43<span class="keyword">typedef</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">base_iterator</span><span class="special">;</span> 44<span class="identifier">base_iterator</span> <span class="identifier">letters</span><span class="special">(</span><span class="identifier">letters_</span><span class="special">);</span> 45<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"original sequence of letters:\t\t\t"</span> <span class="special"><<</span> <span class="identifier">letters_</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 46 47<span class="identifier">boost</span><span class="special">::</span><span class="identifier">reverse_iterator</span><span class="special"><</span><span class="identifier">base_iterator</span><span class="special">></span> 48 <span class="identifier">reverse_letters_first</span><span class="special">(</span><span class="identifier">letters</span> <span class="special">+</span> <span class="identifier">N</span><span class="special">),</span> 49 <span class="identifier">reverse_letters_last</span><span class="special">(</span><span class="identifier">letters</span><span class="special">);</span> 50 51<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"sequence in reverse order:\t\t\t"</span><span class="special">;</span> 52<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">reverse_letters_first</span><span class="special">,</span> <span class="identifier">reverse_letters_last</span><span class="special">,</span> 53 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special"><</span><span class="keyword">char</span><span class="special">>(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">));</span> 54<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 55 56<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"sequence in double-reversed (normal) order:\t"</span><span class="special">;</span> 57<span class="identifier">std</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_reverse_iterator</span><span class="special">(</span><span class="identifier">reverse_letters_last</span><span class="special">),</span> 58 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_reverse_iterator</span><span class="special">(</span><span class="identifier">reverse_letters_first</span><span class="special">),</span> 59 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special"><</span><span class="keyword">char</span><span class="special">>(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">));</span> 60<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 61</pre> 62<p> 63 The output is: 64 </p> 65<pre class="programlisting">original sequence of letters: hello world! 66sequence in reverse order: !dlrow olleh 67sequence in double-reversed (normal) order: hello world! 68</pre> 69<p> 70 The source code for this example can be found <a href="../../../../example/reverse_iterator_example.cpp" target="_top">here</a>. 71 </p> 72<h3> 73<a name="iterator.specialized.reverse.h1"></a> 74 <span class="phrase"><a name="iterator.specialized.reverse.reference"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.reference">Reference</a> 75 </h3> 76<h4> 77<a name="iterator.specialized.reverse.h2"></a> 78 <span class="phrase"><a name="iterator.specialized.reverse.synopsis"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.synopsis">Synopsis</a> 79 </h4> 80<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">></span> 81<span class="keyword">class</span> <span class="identifier">reverse_iterator</span> 82<span class="special">{</span> 83<span class="keyword">public</span><span class="special">:</span> 84 <span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span> 85 <span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">reference</span> <span class="identifier">reference</span><span class="special">;</span> 86 <span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">pointer</span> <span class="identifier">pointer</span><span class="special">;</span> 87 <span class="keyword">typedef</span> <span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span> 88 <span class="keyword">typedef</span> <span class="comment">/* see below */</span> <span class="identifier">iterator_category</span><span class="special">;</span> 89 90 <span class="identifier">reverse_iterator</span><span class="special">()</span> <span class="special">{}</span> 91 <span class="keyword">explicit</span> <span class="identifier">reverse_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">;</span> 92 93 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">></span> 94 <span class="identifier">reverse_iterator</span><span class="special">(</span> 95 <span class="identifier">reverse_iterator</span><span class="special"><</span><span class="identifier">OtherIterator</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span> 96 <span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special"><</span><span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span> 97 <span class="special">);</span> 98 <span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 99 <span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span> 100 <span class="identifier">reverse_iterator</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">++();</span> 101 <span class="identifier">reverse_iterator</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">--();</span> 102<span class="keyword">private</span><span class="special">:</span> 103 <span class="identifier">Iterator</span> <span class="identifier">m_iterator</span><span class="special">;</span> <span class="comment">// exposition</span> 104<span class="special">};</span> 105</pre> 106<p> 107 If <code class="computeroutput"><span class="identifier">Iterator</span></code> models Random 108 Access Traversal Iterator and Readable Lvalue Iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code> is convertible to <code class="computeroutput"><span class="identifier">random_access_iterator_tag</span></code>. Otherwise, 109 if <code class="computeroutput"><span class="identifier">Iterator</span></code> models Bidirectional 110 Traversal Iterator and Readable Lvalue Iterator, then <code class="computeroutput"><span class="identifier">iterator_category</span></code> 111 is convertible to <code class="computeroutput"><span class="identifier">bidirectional_iterator_tag</span></code>. 112 Otherwise, <code class="computeroutput"><span class="identifier">iterator_category</span></code> 113 is convertible to <code class="computeroutput"><span class="identifier">input_iterator_tag</span></code>. 114 </p> 115<h4> 116<a name="iterator.specialized.reverse.h3"></a> 117 <span class="phrase"><a name="iterator.specialized.reverse.requirements"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.requirements">Requirements</a> 118 </h4> 119<p> 120 <code class="computeroutput"><span class="identifier">Iterator</span></code> must be a model 121 of Bidirectional Traversal Iterator. The type <code class="computeroutput"><span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">reference</span></code> 122 must be the type of <code class="computeroutput"><span class="special">*</span><span class="identifier">i</span></code>, 123 where <code class="computeroutput"><span class="identifier">i</span></code> is an object of type 124 <code class="computeroutput"><span class="identifier">Iterator</span></code>. 125 </p> 126<h4> 127<a name="iterator.specialized.reverse.h4"></a> 128 <span class="phrase"><a name="iterator.specialized.reverse.concepts"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.concepts">Concepts</a> 129 </h4> 130<p> 131 A specialization of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> 132 models the same iterator traversal and iterator access concepts modeled by 133 its <code class="computeroutput"><span class="identifier">Iterator</span></code> argument. In 134 addition, it may model old iterator concepts specified in the following table: 135 </p> 136<div class="table"> 137<a name="iterator.specialized.reverse.categories"></a><p class="title"><b>Table 1.15. Categories</b></p> 138<div class="table-contents"><table class="table" summary="Categories"> 139<colgroup> 140<col> 141<col> 142</colgroup> 143<thead><tr> 144<th> 145 <p> 146 If <code class="computeroutput"><span class="identifier">I</span></code> models 147 </p> 148 </th> 149<th> 150 <p> 151 then <code class="computeroutput"><span class="identifier">reverse_iterator</span><span class="special"><</span><span class="identifier">I</span><span class="special">></span></code> models 152 </p> 153 </th> 154</tr></thead> 155<tbody> 156<tr> 157<td> 158 <p> 159 Readable Lvalue Iterator, Bidirectional Traversal Iterator 160 </p> 161 </td> 162<td> 163 <p> 164 Bidirectional Iterator 165 </p> 166 </td> 167</tr> 168<tr> 169<td> 170 <p> 171 Writable Lvalue Iterator, Bidirectional Traversal Iterator 172 </p> 173 </td> 174<td> 175 <p> 176 Mutable Bidirectional Iterator 177 </p> 178 </td> 179</tr> 180<tr> 181<td> 182 <p> 183 Readable Lvalue Iterator, Random Access Traversal Iterator 184 </p> 185 </td> 186<td> 187 <p> 188 Random Access Iterator 189 </p> 190 </td> 191</tr> 192<tr> 193<td> 194 <p> 195 Writable Lvalue Iterator, Random Access Traversal Iterator 196 </p> 197 </td> 198<td> 199 <p> 200 Mutable Random Access Iterator 201 </p> 202 </td> 203</tr> 204</tbody> 205</table></div> 206</div> 207<br class="table-break"><p> 208 <code class="computeroutput"><span class="identifier">reverse_iterator</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span></code> is 209 interoperable with <code class="computeroutput"><span class="identifier">reverse_iterator</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span></code> 210 if and only if <code class="computeroutput"><span class="identifier">X</span></code> is interoperable 211 with <code class="computeroutput"><span class="identifier">Y</span></code>. 212 </p> 213<h4> 214<a name="iterator.specialized.reverse.h5"></a> 215 <span class="phrase"><a name="iterator.specialized.reverse.operations"></a></span><a class="link" href="reverse.html#iterator.specialized.reverse.operations">Operations</a> 216 </h4> 217<p> 218 In addition to the operations required by the concepts modeled by <code class="computeroutput"><span class="identifier">reverse_iterator</span></code>, <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> 219 provides the following operations. 220 </p> 221<pre class="programlisting"><span class="identifier">reverse_iterator</span><span class="special">();</span> 222</pre> 223<p> 224 <span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">Iterator</span></code> 225 must be Default Constructible.<br> <span class="bold"><strong>Effects: </strong></span> 226 Constructs an instance of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> 227 with <code class="computeroutput"><span class="identifier">m_iterator</span></code> default constructed. 228 </p> 229<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">reverse_iterator</span><span class="special">(</span><span class="identifier">Iterator</span> <span class="identifier">x</span><span class="special">);</span> 230</pre> 231<p> 232 <span class="bold"><strong>Effects: </strong></span> Constructs an instance of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> with <code class="computeroutput"><span class="identifier">m_iterator</span></code> 233 copy constructed from <code class="computeroutput"><span class="identifier">x</span></code>. 234 </p> 235<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">OtherIterator</span><span class="special">></span> 236<span class="identifier">reverse_iterator</span><span class="special">(</span> 237 <span class="identifier">reverse_iterator</span><span class="special"><</span><span class="identifier">OtherIterator</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span> 238 <span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">enable_if_convertible</span><span class="special"><</span><span class="identifier">OtherIterator</span><span class="special">,</span> <span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">type</span><span class="special">*</span> <span class="special">=</span> <span class="number">0</span> <span class="comment">// exposition</span> 239<span class="special">);</span> 240</pre> 241<p> 242 <span class="bold"><strong>Requires: </strong></span> <code class="computeroutput"><span class="identifier">OtherIterator</span></code> 243 is implicitly convertible to <code class="computeroutput"><span class="identifier">Iterator</span></code>.<br> 244 <span class="bold"><strong>Effects: </strong></span> Constructs instance of <code class="computeroutput"><span class="identifier">reverse_iterator</span></code> whose <code class="computeroutput"><span class="identifier">m_iterator</span></code> 245 subobject is constructed from <code class="computeroutput"><span class="identifier">y</span><span class="special">.</span><span class="identifier">base</span><span class="special">()</span></code>. 246 </p> 247<pre class="programlisting"><span class="identifier">Iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">base</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 248</pre> 249<p> 250 <span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="identifier">m_iterator</span></code> 251 </p> 252<pre class="programlisting"><span class="identifier">reference</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span> 253</pre> 254<p> 255 <span class="bold"><strong>Effects: </strong></span> Iterator tmp = m_iterator; return 256 *--tmp; 257 </p> 258<pre class="programlisting"><span class="identifier">reverse_iterator</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">++();</span> 259</pre> 260<p> 261 <span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">--</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns: 262 </strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> 263 </p> 264<pre class="programlisting"><span class="identifier">reverse_iterator</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">--();</span> 265</pre> 266<p> 267 <span class="bold"><strong>Effects: </strong></span> <code class="computeroutput"><span class="special">++</span><span class="identifier">m_iterator</span></code><br> <span class="bold"><strong>Returns: 268 </strong></span> <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> 269 </p> 270</div> 271<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 272<td align="left"></td> 273<td align="right"><div class="copyright-footer">Copyright © 2003, 2005 David Abrahams Jeremy Siek Thomas 274 Witt<p> 275 Distributed under the Boost Software License, Version 1.0. (See accompanying 276 file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt"> 277 http://www.boost.org/LICENSE_1_0.txt </ulink>) 278 </p> 279</div></td> 280</tr></table> 281<hr> 282<div class="spirit-nav"> 283<a accesskey="p" href="permutation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../specialized.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="shared_container.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 284</div> 285</body> 286</html> 287
