advance
Increments an iterator by a specified number of positions.
template<class InputIterator, class Distance>
void advance(
InputIterator& _InIt,
Distance _Off
);
Parameters
_InIt
The iterator that is to be incremented and that must satisfy the requirements for an input iterator._Off
An integral type that is convertible to the iterator's difference type and that specifies the number of increments the position of the iterator is to be advanced.
Remarks
The range advanced through must be nonsingular, where the iterators must be dereferenceable or past the end.
If the InputIterator satisfies the requirements for a bidirectional iterator type, then _Off may be negative. If InputIterator is an input or forward iterator type, _Off must be nonnegative.
The advance function has constant complexity when InputIterator satisfies the requirements for a random-access iterator; otherwise, it has linear complexity and so is potentially expensive.
Example
// iterator_advance.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>
int main( )
{
using namespace std;
int i;
list<int> L;
for ( i = 1 ; i < 9 ; ++i )
{
L.push_back ( i );
}
list <int>::iterator L_Iter, LPOS = L.begin ( );
cout << "The list L is: ( ";
for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter+)
cout << *L_Iter << " ";
cout << ")." << endl;
cout << "The iterator LPOS initially points to the first element: "
<< *LPOS << "." << endl;
advance ( LPOS , 4 );
cout << "LPOS is advanced 4 steps forward to point"
<< " to the fifth element: "
<< *LPOS << "." << endl;
advance ( LPOS , -3 );
cout << "LPOS is moved 3 steps back to point to the "
<< "2nd element: " << *LPOS << "." << endl;
}
The list L is: ( 1 2 3 4 5 6 7 8 ). The iterator LPOS initially points to the first element: 1. LPOS is advanced 4 steps forward to point to the fifth element: 5. LPOS is moved 3 steps back to point to the 2nd element: 2.
Requirements
Header: <iterator>
Namespace: std