Standard C++ LibraryCopyright 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



privacy and legal statement