Edits for clarity

[SVN r9224]
This commit is contained in:
Dave Abrahams 2001-02-16 05:51:37 +00:00
parent be5aaaae7b
commit 964d23f68c

View File

@ -1,74 +1,74 @@
<html> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<head> <meta name="generator" content="HTML Tidy, see www.w3.org">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="ProgId" content="FrontPage.Editor.Document">
<title>Reverse Iterator Adaptor Documentation</title> <title>Reverse Iterator Adaptor Documentation</title>
</head>
<body bgcolor="#FFFFFF" text="#000000"> <img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align=
"center" width="277" height="86">
<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="center" width="277" height="86">
<h1>Reverse Iterator Adaptor</h1> <h1>Reverse Iterator Adaptor</h1>
Defined in header <a href=
"../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a>
Defined in header <p>The reverse iterator adaptor flips the direction of a base iterator's
<a href="../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a> motion. Invoking <tt>operator++()</tt> moves the base iterator backward and
invoking <tt>operator--()</tt> moves the base iterator forward. The Boost
<p> reverse iterator adaptor is better to use than the
The reverse iterator adaptor flips the direction of an iterators
motion. Invoking <tt>operator++()</tt> moves the reverse iterator
backwards and calling <tt>operator--()</tt> moves the reverse iterator
forwards. The Boost reverse iterator adaptor is better to use than the
<tt>std::reverse_iterator</tt> class in situations where pairs of <tt>std::reverse_iterator</tt> class in situations where pairs of
mutable/const iterators are needed (such as in containers) because mutable/const iterators are needed (e.g., in containers) because
comparisons and conversions between the mutable and const versions are comparisons and conversions between the mutable and const versions are
implemented correctly. implemented correctly.
<h2>Synopsis</h2> <h2>Synopsis</h2>
<pre> <pre>
namespace boost { namespace boost {
template &lt;class <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>, template &lt;class <a href=
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>,
class Value, class Reference, class Pointer, class Category, class Distance&gt; class Value, class Reference, class Pointer, class Category, class Distance&gt;
struct reverse_iterator_generator; struct reverse_iterator_generator;
template &lt;class <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>&gt; template &lt;class <a href=
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>&gt;
typename reverse_iterator_generator&lt;BidirectionalIterator&gt;::type typename reverse_iterator_generator&lt;BidirectionalIterator&gt;::type
make_reverse_iterator(BidirectionalIterator base) make_reverse_iterator(BidirectionalIterator base)
} }
</pre> </pre>
<hr> <hr>
<h2><a name="reverse_iterator_generator">The Reverse Iterator Type <h2><a name="reverse_iterator_generator">The Reverse Iterator Type
Generator</a></h2> Generator</a></h2>
The <tt>reverse_iterator_generator</tt> template is a <a href=
"../../more/generic_programming.html#type_generator">generator</a> of
reverse iterator types. The main template parameter for this class is the
base <tt>BidirectionalIterator</tt> type that is being adapted. In most
cases the associated types of the base iterator can be deduced using
<tt>std::iterator_traits</tt>, but in some situations the user may want to
override these types, so there are also template parameters for the base
iterator's associated types.
The class <tt>reverse_iterator_generator</tt> is a helper class whose <blockquote>
purpose is to construct a reverse iterator type. The main template
parameter for this class is the <tt>BidirectionalIterator</tt> type
that is being wrapped. In most cases the associated types of the base
iterator can be deduced using <tt>std::iterator_traits</tt>, but in
some situations the user may want to override these types, so there
are also template parameters for the base iterators associates types.
<pre> <pre>
template &lt;class <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>, template &lt;class <a href=
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>,
class Value, class Reference, class Pointer, class Category, class Distance&gt; class Value, class Reference, class Pointer, class Category, class Distance&gt;
class reverse_iterator_generator class reverse_iterator_generator
{ {
public: public:
typedef <tt><a href="./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a>&lt...&gt;</tt> type; // the resulting reverse iterator type typedef <tt><a href=
"./iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a>&lt;...&gt;</tt> type; // the resulting reverse iterator type
}; };
</pre> </pre>
</blockquote>
<h3>Example</h3> <h3>Example</h3>
In this example we sort a sequence of letters and then output the sequence
in descending order using reverse iterators.
In this example we sort a sequence of letters and then output <blockquote>
the sequence in descending order using reverse iterators.
<pre> <pre>
#include &lt;boost/config.hpp&gt; #include &lt;boost/config.hpp&gt;
#include &lt;iostream&gt; #include &lt;iostream&gt;
@ -98,148 +98,162 @@ int main(int, char*[])
// to be continued... // to be continued...
</pre> </pre>
</blockquote>
The output is: The output is:
<blockquote>
<pre> <pre>
original sequence of letters: hello world! original sequence of letters: hello world!
letters in descending order: wroolllhed! letters in descending order: wroolllhed!
</pre> </pre>
</blockquote>
<h3>Template Parameters</h3> <h3>Template Parameters</h3>
<Table border> <table border>
<TR> <tr>
<TH>Parameter</TH><TH>Description</TH> <th>Parameter
</TR>
<TR> <th>Description
<TD><tt><a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a></tt></TD>
<TD>The iterator type being wrapped.</TD>
</TD>
</TR>
<TR> <tr>
<TD><tt>Value</tt></TD> <td><tt><a href=
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a></tt>
<TD>The value-type of the base iterator and the resulting reverse
<td>The iterator type being wrapped.
<tr>
<td><tt>Value</tt>
<td>The value-type of the base iterator and the resulting reverse
iterator.<br> iterator.<br>
<b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::value_type</tt> <b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::value_type</tt>
</TD>
<TR>
<TD><tt>Reference</tt></TD>
<TD>The <tt>reference</tt> type for the resulting iterator, <tr>
and in particular, the result type of <tt>operator*()</tt> <td><tt>Reference</tt>
Typically the default for this parameter is the appropriate type.<br>
<td>The <tt>reference</tt> type of the resulting iterator, and in
particular, the result type of <tt>operator*()</tt>.<br>
<b>Default:</b> If <tt>Value</tt> is supplied, <tt>Value&amp;</tt> is <b>Default:</b> If <tt>Value</tt> is supplied, <tt>Value&amp;</tt> is
used. Otherwise used. Otherwise
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::reference</tt> is used. <tt>std::iterator_traits&lt;BidirectionalIterator&gt;::reference</tt>
</TD> is used.
<TR> <tr>
<TD><tt>Pointer</tt></TD> <td><tt>Pointer</tt>
<TD>The <tt>pointer</tt> type of the resulting iterator, and in <td>The <tt>pointer</tt> type of the resulting iterator, and in
particular, the result type of <tt>operator->()</tt>. Typically the particular, the result type of <tt>operator-&gt;()</tt>.<br>
default for this parameter is the appropriate type.<br> <b>Default:</b> If <tt>Value</tt> was supplied, then <tt>Value*</tt>,
<b>Default:</b> If <tt>Value</tt> was supplied, then <tt>Value*</tt>. otherwise
Otherwise <tt>std::iterator_traits&lt;BidirectionalIterator&gt;::pointer</tt>.
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::pointer</tt> is used.</TD>
</TR> <tr>
<td><tt>Category</tt>
<td>The <tt>iterator_category</tt> type for the resulting iterator.<br>
<b>Default:</b>
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::iterator_category</tt>
<TR> <tr>
<TD><tt>Category</tt></TD> <td><tt>Distance</tt>
<TD>The iterator category.<br>
<b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::iterator_category</tt>
</TD>
<TR> <td>The <tt>difference_type</tt> for the resulting iterator.<br>
<TD><tt>Distance</tt></TD> <b>Default:</b>
<TD>The corresponding pointer type for the <tt>Value</tt>.<br> <tt>std::iterator_traits&lt;BidirectionalIterator&amp;gt::difference_type</tt>
<b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::difference_type</tt>
</TD>
</table>
</Table> <h3>Concept Model</h3>
The indirect iterator will model whichever <a href=
<h3>Model of</h3> "http://www.sgi.com/tech/stl/Iterators.html">standard iterator concept
category</a> is modeled by the base iterator. Thus, if the base iterator is
If the base iterator is a model of <a a model of <a href=
href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random "http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
Access Iterator</a> then so is the resulting reverse iterator. If the Iterator</a> then so is the resulting indirect iterator. If the base
base iterator supports less functionality than this the resulting iterator models a more restrictive concept, the resulting indirect iterator
reverse iterator will also support less functionality. The base will model the same concept. The base iterator must be at least a <a href=
iterator must be at least a <a "http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional
href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional
Iterator</a> Iterator</a>
<h3>Members</h3> <h3>Members</h3>
The reverse iterator type implements the member functions and operators
required of the <a href=
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
Iterator</a> concept. In addition it has the following constructor:
The reverse iterator type implements the member functions and <blockquote>
operators required of the <a
href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
Access Iterator</a> concept.
In addition it has the following constructor:
<pre> <pre>
reverse_iterator_generator::type(const BidirectionalIterator&amp; it) reverse_iterator_generator::type(const BidirectionalIterator&amp; it)
</pre> </pre>
</blockquote>
<br>
<br>
<p>
<hr> <hr>
<p> <p>
<h2><a name="make_reverse_iterator">The Reverse Iterator Object Generator</a></h2> <h2><a name="make_reverse_iterator">The Reverse Iterator Object
Generator</a></h2>
The <tt>make_reverse_iterator()</tt> function provides a more The <tt>make_reverse_iterator()</tt> function provides a more convenient
convenient way to create reverse iterator objects. The function saves way to create reverse iterator objects. The function saves the user the
the user the trouble of explicitly writing out the iterator types. trouble of explicitly writing out the iterator types.
<blockquote>
<pre> <pre>
template &lt;class BidirectionalIterator&gt; template &lt;class BidirectionalIterator&gt;
typename reverse_iterator_generator&lt;BidirectionalIterator&gt;::type typename reverse_iterator_generator&lt;BidirectionalIterator&gt;::type
make_reverse_iterator(BidirectionalIterator base) make_reverse_iterator(BidirectionalIterator base);
</pre> </pre>
</blockquote>
<h3>Example</h3> <h3>Example</h3>
In this part of the example we use <tt>make_reverse_iterator()</tt> to In this part of the example we use <tt>make_reverse_iterator()</tt> to
print the sequence of letters in reverse-reverse order, which is the print the sequence of letters in reverse-reverse order, which is the
original order. original order.
<blockquote>
<pre> <pre>
// continuing from the previous example... // continuing from the previous example...
std::cout << "letters in ascending order:\t"; std::cout &lt;&lt; "letters in ascending order:\t";
std::copy(boost::make_reverse_iterator(reverse_letters_last), std::copy(boost::make_reverse_iterator(reverse_letters_last),
boost::make_reverse_iterator(reverse_letters_first), boost::make_reverse_iterator(reverse_letters_first),
std::ostream_iterator<char>(std::cout)); std::ostream_iterator&lt;char&gt;(std::cout));
std::cout << std::endl; std::cout &lt;&lt; std::endl;
return 0; return 0;
} }
</pre> </pre>
</blockquote>
The output is: The output is:
<blockquote>
<pre> <pre>
letters in ascending order: !dehllloorw letters in ascending order: !dehllloorw
</pre> </pre>
</blockquote>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->10 Feb 2001<!--webbot bot="Timestamp" endspan i-checksum="14373" --></p>
<p>© Copyright Jeremy Siek 2000. Permission to copy, use,
modify, sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided &quot;as is&quot;
without express or implied warranty, and with no claim as to its suitability for
any purpose.</p>
</body> <p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->15
Feb 2001<!--webbot bot="Timestamp" endspan i-checksum="14373" -->
</html>
<p>&copy; Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell
and distribute this document is granted provided this copyright notice
appears in all copies. This document is provided "as is" without express or
implied warranty, and with no claim as to its suitability for any purpose.
<!-- LocalWords: html charset alt gif hpp BidirectionalIterator const namespace struct <!-- LocalWords: html charset alt gif hpp BidirectionalIterator const namespace struct
--> -->
<!-- LocalWords: ConstPointer ConstReference typename iostream int abcdefg <!-- LocalWords: ConstPointer ConstReference typename iostream int abcdefg
--> -->
<!-- LocalWords: sizeof PairGen pre Siek wroolllhed dehllloorw <!-- LocalWords: sizeof PairGen pre Siek wroolllhed dehllloorw
--> -->