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>Reverse 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=
"reverse-iterator">
16 <h1 class=
"title">Reverse 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 reverse iterator adaptor iterates through the adapted iterator
46 range in the opposite direction.
</td>
50 <div class=
"contents topic" id=
"table-of-contents">
51 <p class=
"topic-title first">Table of Contents
</p>
53 <li><a class=
"reference internal" href=
"#reverse-iterator-synopsis" id=
"id2"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> synopsis
</a></li>
54 <li><a class=
"reference internal" href=
"#reverse-iterator-requirements" id=
"id3"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> requirements
</a></li>
55 <li><a class=
"reference internal" href=
"#reverse-iterator-models" id=
"id4"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> models
</a></li>
56 <li><a class=
"reference internal" href=
"#reverse-iterator-operations" id=
"id5"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> operations
</a></li>
57 <li><a class=
"reference internal" href=
"#example" id=
"id6">Example
</a></li>
60 <div class=
"section" id=
"reverse-iterator-synopsis">
61 <h1><a class=
"toc-backref" href=
"#id2"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> synopsis
</a></h1>
62 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
63 <!-- Software License, Version 1.0. (See accompanying -->
64 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
65 <pre class=
"literal-block">
66 template
<class Iterator
>
67 class reverse_iterator
70 typedef iterator_traits
<Iterator
>::value_type value_type;
71 typedef iterator_traits
<Iterator
>::reference reference;
72 typedef iterator_traits
<Iterator
>::pointer pointer;
73 typedef iterator_traits
<Iterator
>::difference_type difference_type;
74 typedef /* see below */ iterator_category;
77 explicit reverse_iterator(Iterator x) ;
79 template
<class OtherIterator
>
81 reverse_iterator
<OtherIterator
> const
& r
82 , typename enable_if_convertible
<OtherIterator, Iterator
>::type* =
0 // exposition
84 Iterator const
& base() const;
85 reference operator*() const;
86 reverse_iterator
& operator++();
87 reverse_iterator
& operator--();
89 Iterator m_iterator; // exposition
92 <p>If
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> models Random Access Traversal Iterator and Readable
93 Lvalue Iterator, then
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt> is convertible to
94 <tt class=
"docutils literal"><span class=
"pre">random_access_iterator_tag
</span></tt>. Otherwise, if
95 <tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> models Bidirectional Traversal Iterator and Readable
96 Lvalue Iterator, then
<tt class=
"docutils literal"><span class=
"pre">iterator_category
</span></tt> is convertible to
97 <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
98 convertible to
<tt class=
"docutils literal"><span class=
"pre">input_iterator_tag
</span></tt>.
</p>
100 <div class=
"section" id=
"reverse-iterator-requirements">
101 <h1><a class=
"toc-backref" href=
"#id3"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> requirements
</a></h1>
102 <p><tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt> must be a model of Bidirectional Traversal Iterator. The
103 type
<tt class=
"docutils literal"><span class=
"pre">iterator_traits
<Iterator
>::reference
</span></tt> must be the type of
104 <tt class=
"docutils literal"><span class=
"pre">*i
</span></tt>, where
<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>.
</p>
106 <div class=
"section" id=
"reverse-iterator-models">
107 <h1><a class=
"toc-backref" href=
"#id4"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> models
</a></h1>
108 <p>A specialization of
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> models the same iterator
109 traversal and iterator access concepts modeled by its
<tt class=
"docutils literal"><span class=
"pre">Iterator
</span></tt>
110 argument. In addition, it may model old iterator concepts
111 specified in the following table:
</p>
112 <table border=
"1" class=
"docutils">
117 <thead valign=
"bottom">
118 <tr><th class=
"head">If
<tt class=
"docutils literal"><span class=
"pre">I
</span></tt> models
</th>
119 <th class=
"head">then
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
<I
></span></tt> models
</th>
123 <tr><td>Readable Lvalue Iterator,
124 Bidirectional Traversal Iterator
</td>
125 <td>Bidirectional Iterator
</td>
127 <tr><td>Writable Lvalue Iterator,
128 Bidirectional Traversal Iterator
</td>
129 <td>Mutable Bidirectional Iterator
</td>
131 <tr><td>Readable Lvalue Iterator,
132 Random Access Traversal Iterator
</td>
133 <td>Random Access Iterator
</td>
135 <tr><td>Writable Lvalue Iterator,
136 Random Access Traversal Iterator
</td>
137 <td>Mutable Random Access Iterator
</td>
141 <p><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
<X
></span></tt> is interoperable with
142 <tt class=
"docutils literal"><span class=
"pre">reverse_iterator
<Y
></span></tt> if and only if
<tt class=
"docutils literal"><span class=
"pre">X
</span></tt> is interoperable with
143 <tt class=
"docutils literal"><span class=
"pre">Y
</span></tt>.
</p>
145 <div class=
"section" id=
"reverse-iterator-operations">
146 <h1><a class=
"toc-backref" href=
"#id5"><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> operations
</a></h1>
147 <p>In addition to the operations required by the concepts modeled by
148 <tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt>,
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> provides the following
150 <p><tt class=
"docutils literal"><span class=
"pre">reverse_iterator();
</span></tt></p>
151 <table class=
"docutils field-list" frame=
"void" rules=
"none">
152 <col class=
"field-name" />
153 <col class=
"field-body" />
155 <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>
157 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body">Constructs an instance of
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> with
<tt class=
"docutils literal"><span class=
"pre">m_iterator
</span></tt>
158 default constructed.
</td>
162 <p><tt class=
"docutils literal"><span class=
"pre">explicit
</span> <span class=
"pre">reverse_iterator(Iterator
</span> <span class=
"pre">x);
</span></tt></p>
163 <table class=
"docutils field-list" frame=
"void" rules=
"none">
164 <col class=
"field-name" />
165 <col class=
"field-body" />
167 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body">Constructs an instance of
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> with
168 <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>
172 <pre class=
"literal-block">
173 template
<class OtherIterator
>
175 reverse_iterator
<OtherIterator
> const
& r
176 , typename enable_if_convertible
<OtherIterator, Iterator
>::type* =
0 // exposition
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">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>
185 <tr class=
"field"><th class=
"field-name">Effects:
</th><td class=
"field-body">Constructs instance of
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt> whose
186 <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>
190 <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>
191 <table class=
"docutils field-list" frame=
"void" rules=
"none">
192 <col class=
"field-name" />
193 <col class=
"field-body" />
195 <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>
199 <p><tt class=
"docutils literal"><span class=
"pre">reference
</span> <span class=
"pre">operator*()
</span> <span class=
"pre">const;
</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"></td>
208 <pre class=
"literal-block">
209 Iterator tmp = m_iterator;
212 <p><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
&</span> <span class=
"pre">operator++();
</span></tt></p>
213 <table class=
"docutils field-list" frame=
"void" rules=
"none">
214 <col class=
"field-name" />
215 <col class=
"field-body" />
217 <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>
219 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">*this
</span></tt></td>
223 <p><tt class=
"docutils literal"><span class=
"pre">reverse_iterator
&</span> <span class=
"pre">operator--();
</span></tt></p>
224 <table class=
"docutils field-list" frame=
"void" rules=
"none">
225 <col class=
"field-name" />
226 <col class=
"field-body" />
228 <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>
230 <tr class=
"field"><th class=
"field-name">Returns:
</th><td class=
"field-body"><tt class=
"docutils literal"><span class=
"pre">*this
</span></tt></td>
234 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
235 <!-- Software License, Version 1.0. (See accompanying -->
236 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
237 <pre class=
"literal-block">
238 template
<class BidirectionalIterator
>
239 reverse_iterator
<BidirectionalIterator
>n
240 make_reverse_iterator(BidirectionalIterator x);
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">An instance of
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
<BidirectionalIterator
></span></tt>
247 with a
<tt class=
"docutils literal"><span class=
"pre">current
</span></tt> constructed from
<tt class=
"docutils literal"><span class=
"pre">x
</span></tt>.
</td>
251 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
252 <!-- Software License, Version 1.0. (See accompanying -->
253 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
255 <div class=
"section" id=
"example">
256 <h1><a class=
"toc-backref" href=
"#id6">Example
</a></h1>
257 <p>The following example prints an array of characters in reverse order
258 using
<tt class=
"docutils literal"><span class=
"pre">reverse_iterator
</span></tt>.
</p>
259 <pre class=
"literal-block">
260 char letters_[] =
"hello world!
";
261 const int N = sizeof(letters_)/sizeof(char) -
1;
262 typedef char* base_iterator;
263 base_iterator letters(letters_);
264 std::cout
<< "original sequence of letters:\t\t\t
" << letters_
<< std::endl;
266 boost::reverse_iterator
<base_iterator
>
267 reverse_letters_first(letters + N),
268 reverse_letters_last(letters);
270 std::cout
<< "sequence in reverse order:\t\t\t
";
271 std::copy(reverse_letters_first, reverse_letters_last,
272 std::ostream_iterator
<char
>(std::cout));
273 std::cout
<< std::endl;
275 std::cout
<< "sequence in double-reversed (normal) order:\t
";
276 std::copy(boost::make_reverse_iterator(reverse_letters_last),
277 boost::make_reverse_iterator(reverse_letters_first),
278 std::ostream_iterator
<char
>(std::cout));
279 std::cout
<< std::endl;
281 <p>The output is:
</p>
282 <pre class=
"literal-block">
283 original sequence of letters: hello world!
284 sequence in reverse order: !dlrow olleh
285 sequence in double-reversed (normal) order: hello world!
287 <p>The source code for this example can be found
<a class=
"reference external" href=
"../example/reverse_iterator_example.cpp">here
</a>.
</p>
291 <hr class=
"footer" />
292 <a class=
"reference external" href=
"reverse_iterator.rst">View document source
</a>.
293 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.