Standard C++	Library
 		 Copyright 1996, Rogue Wave Software, Inc.

 NAME

   advance  - Move an iterator forward or backward (if available) by a
   certain distance.

 SYNOPSIS

   #include <iterator>

   template <class InputIterator, class Distance>
   void advance (InputIterator& i, Distance n);

 DESCRIPTION

   The advance template function	allows an iterator to be advanced
   through a container by some arbitrary distance.	 For
   bidirectional  and random access iterators, this distance may be
   negative.  This  function uses	operator+ and operator- for
   random access iterators,  which provides	a constant time
   implementation.  For input,  forward, and bidirectional iterators,
   advance uses operator++ to  provide linear time implementations.
   advance also	uses operator--  with bidirectional	iterators to
   provide linear time implementations	of negative distances.

   If n is positive, advance increments iterator	reference i by n.  For
   negative n, advance decrements reference i.  Remember that advance
   accepts a negative argument n for random access	and
   bidirectional  iterators only.

 EXAMPLE

   //
   // advance.cpp
   //
    #include<iterator>
    #include<list>
    #include<iostream.h>

   int main()
    {

      //
      //Initialize a list using an array
      //
     int	arr[6] = {3,4,5,6,7,8};
     list<int> l(arr,arr+6);
      //
      //Declare a list iterator,	s.b. a ForwardIterator
      //
     list<int>::iterator	itr = l.begin();
      //
      //Output the original list
      //
     cout << "For the list: ";
     copy(l.begin(),l.end(),
 	 ostream_iterator<int,char>(cout," "));
     cout << endl << endl;
     cout << "When the iterator is initialized to l.begin(),"
 	  << endl << "it points	to " <<	*itr <<	endl <<	endl;
      //
      //	operator+ is not available for a ForwardIterator,
      //	so use advance.
      //

     advance(itr, 4);
     cout << "After advance(itr,4), the iterator	points to "
 	  << *itr << endl;
     return 0;
    }

   Output :
   For the list:	3 4 5 6	7 8
   When the iterator is initialized to l.begin(),
   it points to 3
   After	advance(itr,4),	the iterator points to 7

 WARNINGS

   If your compiler does	not support default template parameters	then
   you need to always supply the Allocator template argument.  For
   instance you'll have to write:

   vector<int,allocator<int> >

   instead of:

   vector<int>

 SEE ALSO

   sequence, random_iterator, distance

 STANDARDS CONFORMANCE
   ANSI X3J16/ISO WG21 Joint C++	Committee