Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

advance

Increments an iterator by a specified number of positions.

template<class InputIterator, class Distance>
    void advance(
        InputIterator& InIt, 
        Distance Off
   );

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.

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.

// 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.

Header: <iterator>

Namespace: std

Show:
© 2015 Microsoft