mirror of
https://github.com/boostorg/utility.git
synced 2025-05-08 10:24:00 +00:00
finished 1st draft of reverse iterator docs
[SVN r9149]
This commit is contained in:
Jeremy Siek
parent
387540d5f1
commit
ee269884fc
232
reverse_iterator.htm
Normal file
232
reverse_iterator.htm
Normal file
@ -0,0 +1,232 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<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">
|
||||
|
||||
<h1>Reverse Iterator Adaptor</h1>
|
||||
|
||||
Defined in header
|
||||
<a href="../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a>
|
||||
|
||||
<p>
|
||||
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
|
||||
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>
|
||||
|
||||
<pre>
|
||||
namespace boost {
|
||||
template <class <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>,
|
||||
class Value, class Reference, class Pointer, class Category, class Distance>
|
||||
struct reverse_iterator_generator;
|
||||
|
||||
template <class <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>>
|
||||
typename reverse_iterator_generator<BidirectionalIterator>::type
|
||||
make_reverse_iterator(BidirectionalIterator base)
|
||||
}
|
||||
</pre>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><a name="reverse_iterator_generator">The Reverse Iterator Type
|
||||
Generator</a></h2>
|
||||
|
||||
The class <tt>reverse_iterator_generator</tt> is a helper class whose
|
||||
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>
|
||||
template <class <a href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">BidirectionalIterator</a>,
|
||||
class Value, class Reference, class Pointer, class Category, class Distance>
|
||||
class reverse_iterator_generator
|
||||
{
|
||||
public:
|
||||
typedef <tt><a href="./iterator_adaptor.htm">iterator_adaptor</a><...></tt> type; // the resulting reverse iterator type
|
||||
};
|
||||
</pre>
|
||||
|
||||
<h3>Example</h3>
|
||||
|
||||
In this example we sort a sequence of letters and then output
|
||||
the sequence in descending order using reverse iterators.
|
||||
|
||||
<pre>
|
||||
#include <boost/config.hpp>
|
||||
#include <iostream>
|
||||
#include <algorithm>
|
||||
#include <boost/iterator_adaptors.hpp>
|
||||
|
||||
int main(int, char*[])
|
||||
{
|
||||
char letters[] = "hello world!";
|
||||
const int N = sizeof(letters)/sizeof(char) - 1;
|
||||
std::cout << "original sequence of letters:\t"
|
||||
<< letters << std::endl;
|
||||
|
||||
std::sort(letters, letters + N);
|
||||
|
||||
// Use reverse_iterator_generator to print a sequence
|
||||
// of letters in reverse order.
|
||||
|
||||
boost::reverse_iterator_generator<char*>::type
|
||||
reverse_letters_first(letters + N),
|
||||
reverse_letters_last(letters);
|
||||
|
||||
std::cout << "letters in descending order:\t";
|
||||
std::copy(reverse_letters_first, reverse_letters_last,
|
||||
std::ostream_iterator<char>(std::cout));
|
||||
std::cout << std::endl;
|
||||
|
||||
// to be continued...
|
||||
</pre>
|
||||
The output is:
|
||||
<pre>
|
||||
original sequence of letters: hello world!
|
||||
letters in descending order: wroolllhed!
|
||||
</pre>
|
||||
|
||||
<h3>Template Parameters</h3>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>Parameter</TH><TH>Description</TH>
|
||||
</TR>
|
||||
|
||||
<TR>
|
||||
<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>
|
||||
<TD><tt>Value</tt></TD>
|
||||
<TD>The value-type of the base iterator and the resulting reverse iterator.<br>
|
||||
<b>Default:</b><tt>std::iterator_traits<BidirectionalIterator>::value_type</tt>
|
||||
</TD>
|
||||
|
||||
<TR>
|
||||
<TD><tt>Reference</tt></TD>
|
||||
<TD>The corresponding reference type for the <tt>value_type</tt>.<br>
|
||||
<b>Default:</b><tt>std::iterator_traits<BidirectionalIterator>::reference</tt>
|
||||
</TD>
|
||||
|
||||
<TR>
|
||||
<TD><tt>Pointer</tt></TD>
|
||||
<TD>The pointer type for the <tt>value_type</tt>.<br>
|
||||
<b>Default:</b><tt>std::iterator_traits<BidirectionalIterator>::pointer</tt>
|
||||
</TD>
|
||||
|
||||
<TR>
|
||||
<TD><tt>Category</tt></TD>
|
||||
<TD>The iterator category.<br>
|
||||
<b>Default:</b><tt>std::iterator_traits<BidirectionalIterator>::iterator_category</tt>
|
||||
</TD>
|
||||
|
||||
<TR>
|
||||
<TD><tt>Distance</tt></TD>
|
||||
<TD>The corresponding pointer type for the <tt>Value</tt>.<br>
|
||||
<b>Default:</b><tt>std::iterator_traits<BidirectionalIterator>::difference_type</tt>
|
||||
</TD>
|
||||
|
||||
|
||||
</Table>
|
||||
|
||||
<h3>Model of</h3>
|
||||
|
||||
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 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>
|
||||
|
||||
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:
|
||||
|
||||
<pre>
|
||||
reverse_iterator_generator::type(const BidirectionalIterator& it)
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
<hr>
|
||||
<p>
|
||||
|
||||
<h2><a name="make_reverse_iterator">The Reverse Iterator Object Generator</a></h2>
|
||||
|
||||
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.
|
||||
|
||||
<pre>
|
||||
template <class BidirectionalIterator>
|
||||
typename reverse_iterator_generator<BidirectionalIterator>::type
|
||||
make_reverse_iterator(BidirectionalIterator base)
|
||||
</pre>
|
||||
|
||||
|
||||
<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.
|
||||
|
||||
<pre>
|
||||
// continuing from the previous example...
|
||||
|
||||
std::cout << "letters in ascending order:\t";
|
||||
std::copy(boost::make_reverse_iterator(reverse_letters_last),
|
||||
boost::make_reverse_iterator(reverse_letters_first),
|
||||
std::ostream_iterator<char>(std::cout));
|
||||
std::cout << std::endl;
|
||||
|
||||
return 0;
|
||||
}
|
||||
</pre>
|
||||
The output is:
|
||||
<pre>
|
||||
letters in ascending order: !dehllloorw
|
||||
</pre>
|
||||
|
||||
<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 "as is"
|
||||
without express or implied warranty, and with no claim as to its suitability for
|
||||
any purpose.</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
<!-- LocalWords: html charset alt gif hpp BidirectionalIterator const namespace struct
|
||||
-->
|
||||
<!-- LocalWords: ConstPointer ConstReference typename iostream int abcdefg
|
||||
-->
|
||||
<!-- LocalWords: sizeof PairGen pre Siek wroolllhed dehllloorw
|
||||
-->
|
||||
42
reverse_iterator_example.cpp
Normal file
42
reverse_iterator_example.cpp
Normal file
@ -0,0 +1,42 @@
|
||||
// (C) Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell and
|
||||
// distribute this software is granted provided this copyright notice appears
|
||||
// in all copies. This software is provided "as is" without express or implied
|
||||
// warranty, and with no claim as to its suitability for any purpose.
|
||||
|
||||
#include <boost/config.hpp>
|
||||
#include <iostream>
|
||||
#include <algorithm>
|
||||
#include <boost/iterator_adaptors.hpp>
|
||||
|
||||
int main(int, char*[])
|
||||
{
|
||||
char letters[] = "hello world!";
|
||||
const int N = sizeof(letters)/sizeof(char) - 1;
|
||||
std::cout << "original sequence of letters:\t"
|
||||
<< letters << std::endl;
|
||||
|
||||
std::sort(letters, letters + N);
|
||||
|
||||
// Use reverse_iterator_generator to print a sequence
|
||||
// of letters in reverse order.
|
||||
|
||||
boost::reverse_iterator_generator<char*>::type
|
||||
reverse_letters_first(letters + N),
|
||||
reverse_letters_last(letters);
|
||||
|
||||
std::cout << "letters in descending order:\t";
|
||||
std::copy(reverse_letters_first, reverse_letters_last,
|
||||
std::ostream_iterator<char>(std::cout));
|
||||
std::cout << std::endl;
|
||||
|
||||
// Use make_reverse_iterator() to print the sequence
|
||||
// of letters in reverse-reverse order.
|
||||
|
||||
std::cout << "letters in ascending order:\t";
|
||||
std::copy(boost::make_reverse_iterator(reverse_letters_last),
|
||||
boost::make_reverse_iterator(reverse_letters_first),
|
||||
std::ostream_iterator<char>(std::cout));
|
||||
std::cout << std::endl;
|
||||
|
||||
return 0;
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user