.\" ident @(#)advance.3
.\" Standard Template Library
.\" $$RW_INSERT_HEADER "slyrs.man"
.TH advance 3C++ "02 Apr 1998" "Rogue Wave Software" "-"
.ce2
Standard C++ Library   
Copyright 1998, Rogue Wave Software, Inc.   

.SH NAME

\f2advance\fP

\ - Moves an iterator forward or backward (if available) by a certain distance.



.SH  SYNOPSIS


.br
#include <iterator>
.br
template <class InputIterator, class Distance>
.br
void advance (InputIterator& i, Distance n);



.SH  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. For random access iterators, this function uses \f2operator+\fP and \f2operator-\fP for constant time implementations. For input, forward, and bidirectional iterators, advance uses \f2operator++\fP for linear time implementations. advance also uses \f2operator--\fP with bidirectional iterators for linear time implementations of negative distances. 

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



.SH  EXAMPLE



.br
//
.br
// advance.cpp
.br
//
.RE
.RS 1
#include<iterator>
.br
#include<list>
.br
#include<iostream>
.RE
.RS 0
using namespace std;
.br

.br
int main()
.RE
.RS 1
{
.RE
.RS 0

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

.RE
.RS 2
advance(itr, 4);
.br
cout << "After advance(itr,4), the iterator points to " 
.RE
.RS 8
<< *itr << endl;
.RE
.RS 2
return 0;
.RE
.RS 1
}

.br
.RE
.RS 0
Program Output :



.RE
.RS 0

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



.SH  WARNINGS


If your compiler does not support default template parameters, then you always need to supply the \f2Allocator\fP template argument. For instance, you have to write:

\f2vector<int,allocator<int> >\fP

instead of:

\f2vector<int>\fP

If your compiler does not support namespaces, then you do not need the using declaration for \f2std\fP.



.SH  SEE ALSO


Sequences, Random_Access_Iterators, distance