boost_mirror/utility
1
0
Fork 0
mirror of https://github.com/boostorg/utility.git synced 2025-05-09 23:14:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Edits for clarity

Browse Source 
[SVN r9224]
This commit is contained in:
Dave Abrahams 2001-02-16 05:51:37 +00:00
parent be5aaaae7b
commit 964d23f68c
1 changed files with 163 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

300
reverse_iterator.htm
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>
</head>
<body bgcolor="#FFFFFF" text="#000000"> <title>Reverse Iterator Adaptor Documentation</title>
<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" <img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align=
align="center" width="277" height="86"> "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 <tt>std::reverse_iterator</tt> class in situations where pairs of
motion. Invoking <tt>operator++()</tt> moves the reverse iterator mutable/const iterators are needed (e.g., in containers) because
backwards and calling <tt>operator--()</tt> moves the reverse iterator comparisons and conversions between the mutable and const versions are
forwards. The Boost reverse iterator adaptor is better to use than the implemented correctly.
<tt>std::reverse_iterator</tt> class in situations where pairs of
mutable/const iterators are needed (such as in containers) because
comparisons and conversions between the mutable and const versions are
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
Generator</a></h2>
<h2><a name="reverse_iterator_generator">The Reverse Iterator Type The <tt>reverse_iterator_generator</tt> template is a <a href=
Generator</a></h2> "../../more/generic_programming.html#type_generator">generator</a> of
reverse iterator types. The main template parameter for this class is the
The class <tt>reverse_iterator_generator</tt> is a helper class whose base <tt>BidirectionalIterator</tt> type that is being adapted. In most
purpose is to construct a reverse iterator type. The main template cases the associated types of the base iterator can be deduced using
parameter for this class is the <tt>BidirectionalIterator</tt> type <tt>std::iterator_traits</tt>, but in some situations the user may want to
that is being wrapped. In most cases the associated types of the base override these types, so there are also template parameters for the base
iterator can be deduced using <tt>std::iterator_traits</tt>, but in iterator's associated types.
some situations the user may want to override these types, so there
are also template parameters for the base iterators associates types.
<blockquote>
<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 this example we sort a sequence of letters and then output in descending order using reverse iterators.
the sequence in descending order using reverse iterators.
<blockquote>
<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>
The output is: </blockquote>
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
iterator.<br>
<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,
and in particular, the result type of <tt>operator*()</tt>
Typically the default for this parameter is the appropriate type.<br>
<b>Default:</b> If <tt>Value</tt> is supplied, <tt>Value&amp;</tt> is
used. Otherwise
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::reference</tt> is used.
</TD>
<TR>
<TD><tt>Pointer</tt></TD>
<TD>The <tt>pointer</tt> type of the resulting iterator, and in
particular, the result type of <tt>operator->()</tt>. Typically the
default for this parameter is the appropriate type.<br>
<b>Default:</b> If <tt>Value</tt> was supplied, then <tt>Value*</tt>.
Otherwise
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::pointer</tt> is used.</TD>
</TR>
<TR> <td>The iterator type being wrapped.
<TD><tt>Category</tt></TD>
<TD>The iterator category.<br>
<b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::iterator_category</tt>
</TD>
<TR> <tr>
<TD><tt>Distance</tt></TD> <td><tt>Value</tt>
<TD>The corresponding pointer type for the <tt>Value</tt>.<br>
<b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::difference_type</tt> <td>The value-type of the base iterator and the resulting reverse
</TD> iterator.<br>
<b>Default:</b><tt>std::iterator_traits&lt;BidirectionalIterator&gt;::value_type</tt>
</Table> <tr>
<td><tt>Reference</tt>
<h3>Model of</h3> <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
used. Otherwise
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::reference</tt>
is used.
If the base iterator is a model of <a <tr>
href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random <td><tt>Pointer</tt>
Access Iterator</a> then so is the resulting reverse iterator. If the
base iterator supports less functionality than this the resulting
reverse iterator will also support less functionality. The base
iterator must be at least a <a
href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional
Iterator</a>
<h3>Members</h3> <td>The <tt>pointer</tt> type of the resulting iterator, and in
particular, the result type of <tt>operator-&gt;()</tt>.<br>
<b>Default:</b> If <tt>Value</tt> was supplied, then <tt>Value*</tt>,
otherwise
<tt>std::iterator_traits&lt;BidirectionalIterator&gt;::pointer</tt>.
The reverse iterator type implements the member functions and <tr>
operators required of the <a <td><tt>Category</tt>
href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
Access Iterator</a> concept.
In addition it has the following constructor:
<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>
<td><tt>Distance</tt>
<td>The <tt>difference_type</tt> for the resulting iterator.<br>
<b>Default:</b>
<tt>std::iterator_traits&lt;BidirectionalIterator&amp;gt::difference_type</tt>
</table>
<h3>Concept Model</h3>
The indirect iterator will model whichever <a href=
"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
a model of <a href=
"http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
Iterator</a> then so is the resulting indirect iterator. If the base
iterator models a more restrictive concept, the resulting indirect iterator
will model the same concept. The base iterator must be at least a <a href=
"http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional
Iterator</a>
<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:
<blockquote>
<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>
<h2><a name="make_reverse_iterator">The Reverse Iterator Object Generator</a></h2> <p>
The <tt>make_reverse_iterator()</tt> function provides a more <h2><a name="make_reverse_iterator">The Reverse Iterator Object
convenient way to create reverse iterator objects. The function saves Generator</a></h2>
the user the trouble of explicitly writing out the iterator types. The <tt>make_reverse_iterator()</tt> function provides a more convenient
way to create reverse iterator objects. The function saves the user the
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>
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
original order.
<h3>Example</h3> <blockquote>
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
original order.
<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>
The output is: </blockquote>
The output is:
<blockquote>
<pre> <pre>
letters in ascending order: !dehllloorw letters in ascending order: !dehllloorw
</pre> </pre>
</blockquote>
<hr>
<hr> <p>Revised
<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> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->15
<p>© Copyright Jeremy Siek 2000. Permission to copy, use, Feb 2001<!--webbot bot="Timestamp" endspan i-checksum="14373" -->
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>
</html> <p>&copy; Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell
<!-- LocalWords: html charset alt gif hpp BidirectionalIterator const namespace struct 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: 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
--> -->