File: ReverseIterator.html

package info (click to toggle)
stl-manual 3.30-9
links: PTS, VCS
area: main
in suites: lenny
size: 4,092 kB
ctags: 4,448
sloc: cpp: 17,845; ansic: 2,842; makefile: 41
file content (542 lines) | stat: -rw-r--r-- 15,471 bytes
parent folder | download | duplicates (6)
<HTML>
<!--
  -- Copyright (c) 1996-1999
  -- Silicon Graphics Computer Systems, Inc.
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Silicon Graphics makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -- Copyright (c) 1994
  -- Hewlett-Packard Company
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Hewlett-Packard Company makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -->
<Head>
<Title>reverse_iterator&lt;RandomAccessIterator, T, Reference, Distance&gt;</Title>
<!-- Generated by htmldoc -->
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
	ALINK="#ff0000"> 
<IMG SRC="CorpID.gif" 
     ALT="SGI" HEIGHT="43" WIDTH="151"> 
<!--end header-->
<BR Clear>
<H1>reverse_iterator&lt;RandomAccessIterator, T, Reference, Distance&gt;</H1>

<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "iterators.gif" Alt=""   WIDTH = "194"  HEIGHT = "38" ></TD>
<TD Align=right><Img src = "type.gif" Alt=""   WIDTH = "194"  HEIGHT = "39" ></TD>
</TR>
<TR>
<TD Align=left><Img src = "adaptors.gif" Alt=""   WIDTH = "194"  HEIGHT = "38" ></TD>
<TD Align=right></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Categories</b>: iterators, adaptors</TD>
<TD Align=right VAlign=top><b>Component type</b>: type</TD>
</TR>
</Table>

<h3>Description</h3>
<tt>Reverse_iterator</tt> is an iterator adaptor that enables backwards traversal
of a range.  <tt>Operator++</tt> applied to an object of 
class <tt>reverse_iterator&lt;<A href="RandomAccessIterator.html">RandomAccessIterator</A>&gt;</tt> means the same thing as
<tt>operator--</tt> applied to an object of class <tt><A href="RandomAccessIterator.html">RandomAccessIterator</A></tt>.
There are two different reverse iterator adaptors: the class
<tt>reverse_iterator</tt> has a template argument that is a
<A href="RandomAccessIterator.html">Random Access Iterator</A>, and the class <tt><A href="ReverseBidirectionalIterator.html">reverse_bidirectional_iterator</A></tt>
has a template argument that is a <A href="BidirectionalIterator.html">Bidirectional Iterator</A>. <A href="#1">[1]</A>
<h3>Example</h3>
<pre>
template &lt;class T&gt;
void forw(const <A href="Vector.html">vector</A>&lt;T&gt;&amp; V)
{
   vector&lt;T&gt;::iterator first = V.begin();
   vector&lt;T&gt;::iterator last = V.end();
   while (first != last) 
      cout &lt;&lt; *first++ &lt;&lt; endl;
}      

template &lt;class T&gt;
void rev(const <A href="Vector.html">vector</A>&lt;T&gt;&amp; V)
{
   typedef reverse_iterator&lt;vector&lt;T&gt;::iterator,
                            T,
                            vector&lt;T&gt;::reference_type,
                            vector&lt;T&gt;::difference_type&gt; 
           reverse_iterator; <A href="#2">[2]</A>
   reverse_iterator rfirst(V.end());
   reverse_iterator rlast(V.begin());

   while (rfirst != rlast) 
      cout &lt;&lt; *rfirst++ &lt;&lt; endl;
}      
</pre>
<P>
In the function <tt>forw</tt>, the elements are printed in the order
<tt>*first</tt>, <tt>*(first+1)</tt>, ..., <tt>*(last-1)</tt>.  In the function 
<tt>rev</tt>, they are printed in the order <tt>*(last - 1)</tt>, <tt>*(last-2)</tt>, ...,
<tt>*first</tt>. <A href="#3">[3]</A>
<h3>Definition</h3>
Defined in the standard header <A href="iterator">iterator</A>, and in the nonstandard
backward-compatibility header <A href="iterator.h">iterator.h</A>.
<h3>Template parameters</h3>
<Table border>
<TR>
<TH>
Parameter
</TH>
<TH>
Description
</TH>
<TH>
Default
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>RandomAccessIterator</tt>
</TD>
<TD VAlign=top>
The base iterator class.  Incrementing an object of class
   <tt>reverse_iterator&lt;Iterator&gt;</tt> corresponds to decrementing 
   an object of class <tt>Iterator</tt>.
</TD>
<TD VAlign=top>
&nbsp;
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>T</tt>
</TD>
<TD VAlign=top>
The reverse iterator's value type.  This should always be the same
   as the base iterator's value type.
</TD>
<TD VAlign=top>
&nbsp;
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Reference</tt>
</TD>
<TD VAlign=top>
The reverse iterator's reference type.  This should always be the same
   as the base iterator's reference type.
</TD>
<TD VAlign=top>
<tt>T&amp;</tt>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Distance</tt>
</TD>
<TD VAlign=top>
The reverse iterator's distance type.  This should always be the
   same as the base iterator's distance type.
</TD>
<TD VAlign=top>
<tt>ptrdiff_t</tt>
</TD>
</tr>
</table>
<h3>Model of</h3>
<A href="RandomAccessIterator.html">Random Access Iterator</A>
<h3>Type requirements</h3>
The base iterator type (that is, the template parameter <tt>RandomAccessIterator</tt>)
must be a <tt><A href="RandomAccessIterator.html">Random Access Iterator</A></tt>.
The <tt>reverse_iterator</tt>'s value type, 
reference type, and distance type (that is, the template parameters
<tt>T</tt>, <tt>Reference</tt>, and <tt>Distance</tt>, respectively) must be the same as the
base iterator's value type, reference type, and distance type.
<h3>Public base classes</h3>
None.
<h3>Members</h3>
<Table border>
<TR>
<TH>
Member
</TH>
<TH>
Where defined
</TH>
<TH>
Description
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>self</tt>
</TD>
<TD VAlign=top>
<tt>reverse_iterator</tt>
</TD>
<TD VAlign=top>
See below
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>reverse_iterator</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="trivial.html">Trivial Iterator</A>
</TD>
<TD VAlign=top>
The default constructor
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>reverse_iterator</b>(const reverse_iterator&amp; x)</tt>
</TD>
<TD VAlign=top>
 <A href="trivial.html">Trivial Iterator</A>
</TD>
<TD VAlign=top>
The copy constructor
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator&amp; <b>operator=</b>(const reverse_iterator&amp; x)</tt>
</TD>
<TD VAlign=top>
 <A href="trivial.html">Trivial Iterator</A>
</TD>
<TD VAlign=top>
The assignment operator
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>reverse_iterator</b>(RandomAccessIterator x)</tt>
</TD>
<TD VAlign=top>
<tt>reverse_iterator</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>RandomAccessIterator <b>base</b>()</tt>
</TD>
<TD VAlign=top>
<tt>reverse_iterator</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Reference <b>operator*</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="trivial.html">Trivial Iterator</A>
</TD>
<TD VAlign=top>
The dereference operator
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator&amp; <b>operator++</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="ForwardIterator.html">Forward Iterator</A>
</TD>
<TD VAlign=top>
Preincrement
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator <b>operator++</b>(int)</tt>
</TD>
<TD VAlign=top>
 <A href="ForwardIterator.html">Forward Iterator</A>
</TD>
<TD VAlign=top>
Postincrement
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator&amp; <b>operator--</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="BidirectionalIterator.html">Bidirectional Iterator</A>
</TD>
<TD VAlign=top>
Predecrement
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator <b>operator--</b>(int)</tt>
</TD>
<TD VAlign=top>
 <A href="BidirectionalIterator.html">Bidirectional Iterator</A>
</TD>
<TD VAlign=top>
Postdecrement
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator <b>operator+</b>(Distance)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Iterator addition
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator&amp; <b>operator+=</b>(Distance)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Iterator addition
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator <b>operator-</b>(Distance)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Iterator subtraction
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator&amp; <b>operator-=</b>(Distance)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Iterator subtraction
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Reference <b>operator[]</b>(Distance)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Random access to an element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator <b>operator+</b>(Distance, reverse_iterator)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Iterator addition.  This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Distance <b>operator-</b>(const reverse_iterator&amp;, const reverse_iterator&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Finds the distance between two iterators.
  This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>bool <b>operator==</b>(const reverse_iterator&amp;, const reverse_iterator&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="trivial.html">Trivial Iterator</A>
</TD>
<TD VAlign=top>
Compares two iterators for equality.
  This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>bool <b>operator&lt;</b>(const reverse_iterator&amp;, const reverse_iterator&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessIterator.html">Random Access Iterator</A>
</TD>
<TD VAlign=top>
Determines whether the first argument precedes the second.
  This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>random_access_iterator_tag <b>iterator_category</b>(const reverse_iterator&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="iterator_tags.html">Iterator tags</A>
</TD>
<TD VAlign=top>
Returns the iterator's category.
  This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>T* <b>value_type</b>(const reverse_iterator&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="iterator_tags.html">Iterator tags</A>
</TD>
<TD VAlign=top>
Returns the iterator's value type.
  This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Distance* <b>distance_type</b>(const reverse_iterator&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="iterator_tags.html">Iterator tags</A>
</TD>
<TD VAlign=top>
Returns the iterator's distance type.
  This is a global function, not a member function.
</TD>
</tr>
</table>
<h3>New members</h3>
These members are not defined 
in the <A href="RandomAccessIterator.html">Random Access Iterator</A> requirements,
but are specific to <tt>reverse_iterator</tt>.
<Table border>
<TR>
<TH>
Member
</TH>
<TH>
Description
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>self</tt>
</TD>
<TD VAlign=top>
A typedef for <tt>reverse_iterator&lt;<A href="RandomAccessIterator.html">RandomAccessIterator</A>, T, Reference,
   Distance&gt;</tt>.        
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><A href="RandomAccessIterator.html">RandomAccessIterator</A> <b>base</b>()</tt>
</TD>
<TD VAlign=top>
Returns the current value of the <tt>reverse_iterator</tt>'s base iterator.
   If <tt>ri</tt> is a reverse iterator and <tt>i</tt> is any iterator, 
   the two fundamental identities of reverse iterators can be
   written as
   <tt>reverse_iterator(i).base() == i</tt> and <tt>&amp;*ri == &amp;*(ri.base() - 1)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>reverse_iterator</b>(<A href="RandomAccessIterator.html">RandomAccessIterator</A> i)</tt>
</TD>
<TD VAlign=top>
Constructs a <tt>reverse_iterator</tt> whose base iterator is <tt>i</tt>.
</TD>
</tr>
</table>
<h3>Notes</h3>
<P><A name="1">[1]</A>
There isn't really any good reason to have two separate classes:
this separation is purely because of a technical limitation in some of
today's C++ compilers.  If the two classes were combined into one, then there
would be no way to declare the return types of the <A href="iterator_tags.html">iterator tag</A>
functions <tt><A href="iterator_category.html">iterator_category</A></tt>, <tt><A href="distance_type.html">distance_type</A></tt> and
<tt><A href="value_type.html">value_type</A></tt> correctly.  The <i>iterator traits</i>
class solves this problem: it addresses the same issues as the iterator tag
functions, but in a cleaner and more flexible manner.  Iterator
traits, however, rely on <i>partial specialization</i>, and many
C++ compilers do not yet implement partial specialization.
Once compilers that support partial specialization become more common,
these two different reverse iterator classes will be combined into 
a single class.
<P><A name="2">[2]</A>
The declarations for <tt>rfirst</tt> and <tt>rlast</tt> are written in this
clumsy form simply as an illustration of how to declare a
<tt>reverse_iterator</tt>.  <tt><A href="Vector.html">Vector</A></tt> is a <A href="ReversibleContainer.html">Reversible Container</A>, so it
provides a typedef for the appropriate instantiation of
<tt>reverse_iterator</tt>.  The usual way of declaring these variables
is much simpler:
<pre>
    vector&lt;T&gt;::reverse_iterator rfirst = rbegin();
    vector&lt;T&gt;::reverse_iterator rlast = rend();
</pre>
<P><A name="3">[3]</A>
Note the implications of this remark.  The variable <tt>rfirst</tt> is
initialized as <tt>reverse_iterator&lt;...&gt; rfirst(V.end());</tt>.  The value
obtained when it is dereferenced, however, is <tt>*(V.end() - 1)</tt>.  This
is a general property: the fundamental identity of reverse iterators
is <tt>&amp;*(reverse_iterator(i)) == &amp;*(i - 1)</tt>.  This code sample shows why
this identity is important: if <tt>[f, l)</tt> is a valid range, then it
allows <tt>[reverse_iterator(l), reverse_iterator(f))</tt> to be a valid
range as well.  Note that the iterator <tt>l</tt> is not part of the range,
but it is required to be dereferenceable or past-the-end.  There is no
requirement that any such iterator precedes <tt>f</tt>.
<h3>See also</h3>
<A href="ReversibleContainer.html">Reversible Container</A>, <A href="ReverseBidirectionalIterator.html">reverse_bidirectional_iterator</A>,
<A href="RandomAccessIterator.html">Random Access Iterator</A>, <A href="iterator_tags.html">iterator tags</A>,
<A href="Iterators.html">Iterator Overview</A>

<!--start footer--> 
<HR SIZE="6">
<A href="http://www.sgi.com/"><IMG SRC="surf.gif" HEIGHT="54" WIDTH="54" 
        ALT="[Silicon Surf]"></A>
<A HREF="index.html"><IMG SRC="stl_home.gif" 
        HEIGHT="54" WIDTH="54" ALT="[STL Home]"></A>
<BR>
<FONT SIZE="-2">
<A href="http://www.sgi.com/Misc/sgi_info.html" TARGET="_top">Copyright &copy; 
1999 Silicon Graphics, Inc.</A> All Rights Reserved.</FONT>
<FONT SIZE="-3"><a href="http://www.sgi.com/Misc/external.list.html" TARGET="_top">TrademarkInformation</A>
</FONT>
<P>
</BODY>
</HTML>