<!--
    Licensed to the Apache Software  Foundation (ASF) under one or more
    contributor  license agreements.  See  the NOTICE  file distributed
    with  this  work  for  additional information  regarding  copyright
    ownership.   The ASF  licenses this  file to  you under  the Apache
    License, Version  2.0 (the  License); you may  not use  this file
    except in  compliance with the License.   You may obtain  a copy of
    the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the  License is distributed on an  "AS IS" BASIS,
    WITHOUT  WARRANTIES OR CONDITIONS  OF ANY  KIND, either  express or
    implied.   See  the License  for  the  specific language  governing
    permissions and limitations under the License.

    Copyright 1999-2007 Rogue Wave Software, Inc.
-->

<HTML>
<HEAD>
<TITLE>Varieties of Iterators</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="2-1.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="2-3.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library User's Guide</B></DIV>
<H2>2.2 Varieties of Iterators</H2>
<A NAME="idx16"><!></A>
<P>As shown in <A HREF="2-2.html#Table&nbsp;3">Table&nbsp;3</A>, there are five basic forms of iterators used in the C++ Standard Library:</P>
<H4><A NAME="Table&nbsp;3">Table&nbsp;3: Iterator forms in the C++ Standard Library&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B><B>Iterator form</B></B>
</td><td valign=top><B><B>Description</B></B>
</td></tr>
<tr><td valign=top><P CLASS="TABLE">input iterator </P>
</td><td valign=top><P CLASS="TABLE">Read only, forward moving </P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE">output iterator </P>
</td><td valign=top><P CLASS="TABLE">Write only, forward moving </P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE">forward iterator</P>
</td><td valign=top><P CLASS="TABLE">Both read and write, forward moving </P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE">bidirectional iterator </P>
</td><td valign=top><P CLASS="TABLE">Read and write, forward and backward moving </P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE">random access iterator</P>
</td><td valign=top><P CLASS="TABLE">Read and write, random access </P>
</td></tr>
</TABLE>
<A NAME="idx17"><!></A>
<P>Iterator categories are hierarchical. <I>Forward iterators</I> can be used wherever input or output iterators are required, <I>bidirectional iterators</I> can be used in place of forward iterators, and <I>random access iterators</I> can be used in situations requiring bidirectionality. </P>
<A NAME="idx18"><!></A>
<P>A second characteristic of iterators is whether or not they can be used to modify the values held by their associated container. A <I>constant iterator</I> is one that can be used for access only, and cannot be used for modification. <I>Output iterators</I> are never constant, and <I>input iterators</I> always are. Other iterators may or may not be constant, depending upon how they are created. There are both constant and non-constant bidirectional iterators, both constant and non-constant random access iterators, and so on.</P>
<P><A HREF="2-2.html#Table&nbsp;4">Table&nbsp;4</A> summarizes specific ways that various categories of iterators are generated by the containers in the C++ Standard Library.</P>
<H4><A NAME="Table&nbsp;4">Table&nbsp;4: Iterators generated in the C++ Standard Library&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Iterator form</B>
</td><td valign=top><B> Produced by</B>
</td></tr>
<A NAME="idx19"><!></A>
<tr><td valign=top><P CLASS="TABLE">input iterator</P>
</td><td valign=top><P CLASS="TABLE"><SAMP>istream_iterator</SAMP></P>
</td></tr>
<A NAME="idx20"><!></A>
<tr><td valign=top><P CLASS="TABLE">output iterator </P>
</td><td valign=top><P CLASS="TABLE"><SAMP>ostream_iterator</SAMP></P>
<P CLASS="TABLE"><SAMP>inserter()</SAMP></P>
<P CLASS="TABLE"><SAMP>front_inserter()</SAMP></P>
<P CLASS="TABLE"><SAMP>back_inserter()</SAMP></P>
</td></tr>
<A NAME="idx21"><!></A>
<tr><td valign=top><P CLASS="TABLE">bidirectional iterator </P>
</td><td valign=top><P CLASS="TABLE"><B><I><A HREF="../stdlibref/list.html">list</A></I></B>   </P>
<P CLASS="TABLE"><B><I><A HREF="../stdlibref/set.html">set</A></I></B> and <B><I><A HREF="../stdlibref/multiset.html">multiset</A></I></B>   </P>
<P CLASS="TABLE"><B><I><A HREF="../stdlibref/map.html">map</A></I></B> and <B><I><A HREF="../stdlibref/multimap.html">multimap</A></I></B></P>
</td></tr>
<A NAME="idx22"><!></A>
<tr><td valign=top><P CLASS="TABLE">random access iterator </P>
</td><td valign=top><P CLASS="TABLE">ordinary pointers    </P>
<P CLASS="TABLE"><B><I><A HREF="../stdlibref/vector.html">vector</A></I></B>   </P>
<P CLASS="TABLE"><B><I><A HREF="../stdlibref/deque.html">deque</A></I></B></P>
</td></tr>
</TABLE>
<P>In the following sections we describe the capabilities and construction of each form of iterator.</P>
<A NAME="221"><H3>2.2.1 Input Iterators</H3></A>
<A NAME="idx23"><!></A>
<P>Input iterators are the simplest form of iterator. To understand their capabilities, consider an example algorithm: </P>

<UL><PRE>
template &lt;class InputIterator, class T&gt;
InputIterator 
find (InputIterator first, InputIterator last,
      const T&amp; value)
{
  while (first != last &amp;&amp; *first != value) 
    ++first;
  return first;
}

</PRE></UL>
<P>This algorithm, which is similar to the <SAMP>std::find()</SAMP> generic algorithm (<A HREF="13-3.html#1331">Section&nbsp;13.3.1</A>), performs a simple linear search, looking for a specific value being held within a container. The contents of the container are described using two iterators, <SAMP>first</SAMP> and <SAMP>last</SAMP>. While <SAMP>first</SAMP> is not equal to <SAMP>last</SAMP>, the element denoted by <SAMP>first</SAMP> is compared to the test value.  If this element is equal to the test value, the iterator, which now denotes the located element, is returned.  If it is not equal, the <SAMP>first</SAMP> iterator is incremented and the loop cycles once more.  If the entire region of memory is examined without finding the desired value, then the algorithm returns the end-of-range iterator.</P>
<P>This algorithm illustrates three features of an <I>input iterator</I>:</P>
<UL>
<LI><P CLASS="LIST">An input iterator can be compared for equality to another iterator.  They are equal when they point to the same position, and not equal otherwise.</P></LI>
<LI><P CLASS="LIST">An input iterator can be dereferenced, using <SAMP>operator*()</SAMP> to obtain the value being denoted by the iterator.</P></LI>
<LI><P CLASS="LIST">An input iterator can be incremented, so that it refers to the next element in sequence, using <SAMP>operator++()</SAMP>.</P></LI>
</UL>
<P>Notice that these features can all be provided with new meanings in a C++ program, since the behavior of the given functions can all be modified by overloading the appropriate operators.  Because of this overloading, iterators are possible.  </P>
<A NAME="221-1"><H4>2.2.1.1 Kinds of Input Iterators</H4></A>
<A NAME="idx24"><!></A>
<P>There are three main kinds of input iterators: ordinary pointers, container iterators, and input streams iterators.</P>
<A NAME="idx25"><!></A>
<P><B>Ordinary pointers</B>. Ordinary pointers can be used as input iterators. In fact, since we can subscript and add to ordinary pointers, they are random access values, and thus can be used either as input or output iterators. The end-of-range pointer describes the end of a contiguous region of memory, and the dereference and increment operators have their conventional meanings. For example, the following code searches for the value 7 in an array of integers:</P>

<UL><PRE>
int data[100];
   ...
int* where = std::find(data, data+100, 7);
</PRE></UL>
<P>Note that constant pointers, which do not permit the underlying array to be modified, can be created by simply placing the keyword <SAMP>const</SAMP> in a declaration:</P>

<UL><PRE>
const int* first = data;
const int* last  = data + 100;
   // can't modify location returned by the following
const int* where = std::find(first, last, 7);
</PRE></UL>
<P>Because ordinary pointers have the same functionality as random access iterators, most of the generic algorithms in the C++ Standard Library can be used with conventional C++ arrays, as well as with the containers provided by the C++ Standard Library.</P>
<A NAME="idx26"><!></A>
<P><B>Container iterators</B>. All of the iterators constructed for the various containers provided by the C++ Standard Library are at <I>least</I> as general as input iterators. The iterator for the first element in a collection is always constructed by the member function<SAMP> begin()</SAMP>, while the iterator that denotes the past-the-end location is generated by the member function <SAMP>end()</SAMP>. For example, the following iterator searches for the value 7 in a list of integers:</P>

<UL><PRE>
std::list&lt;int&gt;::iterator where =
  std::find(aList.begin(), aList.end(), 7);
</PRE></UL>
<P>Each container that supports iterators provides a type with the name <SAMP>iterator </SAMP>within the class declaration. Using this type, iterators can uniformly be declared in the fashion shown. If the container being accessed is constant, or if the description <SAMP>const_iterator</SAMP> is used, then the iterator is a constant iterator.</P>
<A NAME="idx27"><!></A>
<P><B>Input stream iterators</B>. The C++ Standard Library provides a mechanism to operate on an input stream using an input iterator. This ability is provided by the class <B><I><A HREF="../stdlibref/istream-iterator.html">istream_iterator</A></I></B>, described in more detail in <A HREF="2-3.html#231">Section&nbsp;2.3.1</A>.</P>
<A NAME="222"><H3>2.2.2 Output Iterators</H3></A>
<A NAME="idx28"><!></A>
<P>An <I>output iterator</I> has the opposite function of an input iterator. Output iterators can be used to assign values in a sequence, but cannot be used to access values. For example, we can use an output iterator in a generic algorithm that copies values from one sequence into another:</P>

<UL><PRE>
template &lt;class InputIterator, class OutputIterator&gt;
OutputIterator copy
   (InputIterator first, InputIterator last, OutputIterator result) 
{
    while (first != last) 
      *result++ = *first++;
    return result;
}
</PRE></UL>
<P>A number of the generic algorithms manipulate two parallel sequences. Frequently the second sequence is described using only a beginning iterator, rather than an iterator pair. It is assumed, but not checked, that the second sequence has at least as many elements as the first.</P>
<P>In the algorithm shown here, two ranges are being manipulated: the range of source values specified by a pair of input iterators, and the destination range. The latter, however, is specified by only a single argument. It is assumed that the destination is large enough to include all values, and errors will ensue if this is not the case.</P>
<P>As illustrated by this algorithm, an output iterator can modify the element to which it points by being used as the target for an assignment. Output iterators can use the dereference operator only in this fashion; they cannot be used to return or to access the elements they denote. </P>
<P>As we noted earlier, ordinary pointers, like all iterators constructed by containers in the C++ Standard Library, can be used as output iterators. (Ordinary pointers are random access iterators, which are a superset of output iterators.) For example, in this code fragment elements from an ordinary C-style array are copied into a C++ Standard Library vector:</P>

<UL><PRE>
int data[100];
std::vector&lt;int&gt; newdata(100);
   ...
std::copy(data, data+100, newdata.begin());
</PRE></UL>
<P>Just as the <SAMP>istream_iterator</SAMP> provides a way to operate on an input stream using the input iterator mechanism, the C++ Standard Library provides a datatype, <SAMP>ostream_iterator</SAMP>, that permits values to be written to an output stream in an iterator-like fashion (<A HREF="2-3.html#232">Section&nbsp;2.3.2</A>).</P>
<P>Yet another form of output iterator is an <I>insert iterator </I>(<A HREF="2-4.html">Section&nbsp;2.4</A>). An insert iterator changes the output iterator operations of dereferencing/assignment and increment into insertions into a container. This permits operations such as <SAMP>copy()</SAMP> to be used with variable length containers, such as <B><I><A HREF="../stdlibref/list.html">list</A></I></B>s and <B><I><A HREF="../stdlibref/set.html">set</A></I></B>s.</P>
<A NAME="223"><H3>2.2.3 Forward Iterators</H3></A>
<A NAME="idx29"><!></A>
<P>A <I>forward iterator </I>combines the features of an input iterator and an output iterator. It permits values to be both accessed and modified. One function that uses forward iterators is the <SAMP>replace()</SAMP> generic algorithm, which replaces occurrences of specific values with other values. This algorithm could be written as follows:</P>

<UL><PRE>
template &lt;class ForwardIterator, class T&gt;
void
replace(ForwardIterator first, ForwardIterator last, 
        const T&amp; old_value, const T&amp; new_value)
{
   while (first != last) 
   {
      if (*first == old_value) 
          *first = new_value;
      ++first;
   }
}
</PRE></UL>
<P>Ordinary pointers, like all iterators produced by containers in the C++ Standard Library, can be used as forward iterators. For example, in the following code instances of the value 7 are replaced with the value 11 in a vector of integers:</P>

<UL><PRE>
std::replace(aVec.begin(), aVec.end(), 7, 11);
</PRE></UL>
<A NAME="224"><H3>2.2.4 Bidirectional Iterators</H3></A>
<A NAME="idx30"><!></A>
<P><I>Bidirectional iterators</I> are similar to forward iterators, except that bidirectional iterators support the decrement operator,  <SAMP>operator--()</SAMP>, permitting movement in either a forward or a backward direction through the elements of a container. For example, we can use bidirectional iterators in a function that reverses the values of a container, placing the results into a new container:</P>

<UL><PRE>
template &lt;class BidirectionalIterator, class OutputIterator&gt;
OutputIterator 
reverse_copy(BidirectionalIterator first,
             BidirectionalIterator last,
             OutputIterator result) 
{
   while (first != last) 
      *result++ = *--last;
   return result;
}
</PRE></UL>
<P>As always, the value initially denoted by the <SAMP>last</SAMP> argument is not considered part of the collection.</P>
<A NAME="idx31"><!></A>
<P>The <SAMP>reverse_copy()</SAMP> function could be used, for example, to reverse the values of a linked list, and place the result into a vector:</P>

<UL><PRE>
std::list&lt;int&gt; aList;
 ....
std::vector&lt;int&gt; aVec (aList.size());
std::reverse_copy(aList.begin(), aList.end(), aVec.begin() );
</PRE></UL>
<A NAME="225"><H3>2.2.5 Random Access Iterators</H3></A>
<A NAME="idx32"><!></A>
<P>Some algorithms require more functionality than simply accessing values in either a forward or backward direction. Random access iterators permit values to be accessed by subscript, subtracted one from another (to yield the number of elements between their respective values), or modified by arithmetic operations, all in a manner similar to conventional pointers.</P>
<P>With conventional pointers, arithmetic operations can be related to the underlying memory; that is, <SAMP>x+10</SAMP> is the memory ten elements after the beginning of <SAMP>x</SAMP>. With iterators the logical meaning is preserved (<SAMP>x+10</SAMP> is the tenth element after <SAMP>x</SAMP>), however different the physical addresses being described.</P>
<P>Algorithms that use random access iterators include generic operations like sorting and binary search. For example, the following algorithm randomly shuffles the elements of a container. This is similar to, although simpler than, the function <SAMP>std::random_shuffle()</SAMP> provided by the C++ Standard Library.</P>

<UL><PRE>
template &lt;class RandomAccessIterator&gt;
void
mixup(RandomAccessIterator first, RandomAccessIterator last)
{
   while (first &lt; last) 
   {
      std::iter_swap(first, first + randomInteger(last - first));
      ++first;
   }
}
</PRE></UL>
<BLOCKQUOTE><HR><B>
NOTE -- The function randomInteger described here appears in a number of the example programs presented in later sections.
</B><HR></BLOCKQUOTE>
<A NAME="idx33"><!></A>
<P>The program will cycle as long as <SAMP>first</SAMP> denotes a position that occurs earlier in the sequence than the one denoted by <SAMP>last</SAMP>. Only random access iterators can be compared using relational operators; all other iterators can be compared only for equality or inequality. On each cycle through the loop, the expression <br><SAMP>last - first</SAMP> yields the number of elements between the two limits. The function <SAMP>randomInteger()</SAMP> is assumed to generate a random number between 0 and the argument. Using the standard random number generator, this function could be written as follows:</P>

<UL><PRE>
unsigned int randomInteger(unsigned int n)
// return random integer greater than
// or equal to 0 and less than n
{
   return std::rand() % n;
}
</PRE></UL>
<P>This random value is added to the iterator <SAMP>first</SAMP>, resulting in an iterator to a randomly selected value in the container. This value is then swapped with the element denoted by the iterator <SAMP>first</SAMP>.</P>
<A NAME="226"><H3>2.2.6 Reverse Iterators</H3></A>
<A NAME="idx34"><!></A>
<P>An iterator naturally imposes an order on an underlying container of values. For a <B><I><A HREF="../stdlibref/vector.html">vector</A></I></B> or a <B><I><A HREF="../stdlibref/map.html">map</A></I></B>, the order is imposed by increasing index values; for a <B><I><A HREF="../stdlibref/set.html">set</A></I></B>, by the increasing order of the elements held in the container. For a <B><I><A HREF="../stdlibref/list.html">list</A></I></B>, the order is explicitly derived from the way values are inserted.</P>
<P>A <I>reverse iterator</I> yields values in exactly the reverse order of values given by the standard iterators. For a vector or a list, a reverse iterator generates the last element first, and the first element last. For a set it generates the largest element first, and the smallest element last. Strictly speaking, reverse iterators do not constitute a new category of iterator, but an adaptation of another iterator type. Consequently, we have reverse bidirectional iterators and reverse random access iterators. Any bidirectional or random access iterator can be adapted by the <SAMP>reverse_iterator</SAMP> template.</P>
<P>The <B><I><A HREF="../stdlibref/list.html">list</A></I></B>, <B><I><A HREF="../stdlibref/set.html">set</A></I></B>, and <B><I><A HREF="../stdlibref/map.html">map</A></I></B> datatypes provide a pair of member functions that produce reverse bidirectional iterators. The functions <SAMP>rbegin()</SAMP> and <SAMP>rend()</SAMP> generate iterators that cycle through the underlying container in reverse order. Increments to such iterators move backward, and decrements move forward through the sequence.</P>
<P>Similarly, the <B><I><A HREF="../stdlibref/vector.html">vector</A></I></B> and <B><I><A HREF="../stdlibref/deque.html">deque</A></I></B> datatypes provide functions, also named <SAMP>rbegin()</SAMP> and <SAMP>rend()</SAMP>, that produce reverse random access iterators. Subscript and addition operators, as well as increments to such iterators, move backward within the sequence.</P>

<BR>
<HR>
<A HREF="2-1.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="2-3.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
    _uacct = "UA-1775151-1";
    urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->

</BODY>
</HTML>