<iterator> functions

Article
01/02/2018

The latest version of this topic can be found at <iterator> functions.

advance	back_inserter	begin
cbegin	cend	distance
end	front_inserter	inserter
make_checked_array_iterator	make_move_iterator	make_unchecked_array_iterator
next	prev

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.

back_inserter

Creates an iterator that can insert elements at the back of a specified container.

template <class Container>  
back_insert_iterator<Container> back_inserter(Container& _Cont);

Parameters

_Cont
The container into which the back insertion is to be executed.

Return Value

A back_insert_iterator associated with the container object _Cont.

Remarks

Within the Standard Template Library, the argument must refer to one of the three sequence containers that have the member function push_back: deque Class, list Class, or vector Class.

Example

// iterator_back_inserter.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <vector>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
  
   vector<int> vec;  
   for ( i = 0 ; i < 3 ; ++i )    
   {  
      vec.push_back ( i );  
   }  
  
   vector <int>::iterator vIter;  
   cout << "The initial vector vec is: ( ";  
   for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++)  
      cout << *vIter << " ";  
   cout << ")." << endl;  
  
   // Insertions can be done with template function  
   back_insert_iterator<vector<int> > backiter ( vec );  
 *backiter = 30;  
   backiter++;  
 *backiter = 40;  
  
   // Alternatively, insertions can be done with the  
   // back_insert_iterator member function  
   back_inserter ( vec ) = 500;  
   back_inserter ( vec ) = 600;  
  
   cout << "After the insertions, the vector vec is: ( ";  
   for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++ )  
      cout << *vIter << " ";  
   cout << ")." << endl;  
}

The initial vector vec is: ( 0 1 2 ).  
After the insertions, the vector vec is: ( 0 1 2 30 40 500 600 ).

begin

Retrieves an iterator to the first element in a specified container.

template <class Container>  
auto begin(Container& cont)  
 ->  
decltype(cont.begin());

template <class Container>  
auto begin(const Container& cont)   
 ->  
decltype(cont.begin());

template <class Ty, class Size>  
Ty *begin(Ty (& array)[Size]);

Parameters

cont
A container.

array
An array of objects of type Ty.

Return Value

The first two template functions return cont.begin(). The first function is non-constant; the second one is constant.

The third template function returns array.

Example

We recommend that you use this template function in place of container member begin() when more generic behavior is required.

// cl.exe /EHsc /nologo /W4 /MTd   
#include <algorithm>  
#include <functional>  
#include <iostream>  
#include <iterator>  
#include <vector>  
  
template <typename C> void reverse_sort(C& c) {  
    using std::begin;  
    using std::end;  
  
    std::sort(begin(c), end(c), std::greater<>());  
}  
  
template <typename C> void print(const C& c) {  
    for (const auto& e : c) {  
        std::cout << e << " ";  
    }  
  
    std::cout << "\n";  
}  
  
int main() {  
    std::vector<int> v = { 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1 };  
  
    print(v);  
    reverse_sort(v);  
    print(v);  
  
    std::cout << "--\n";  
  
    int arr[] = { 23, 70, 35, 106, 53, 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1 };  
  
    print(arr);  
    reverse_sort(arr);  
    print(arr);  
}

Output:  
11 34 17 52 26 13 40 20 10 5 16 8 4 2 1  
52 40 34 26 20 17 16 13 11 10 8 5 4 2 1  
--  
23 70 35 106 53 160 80 40 20 10 5 16 8 4 2 1  
160 106 80 70 53 40 35 23 20 16 10 8 5 4 2 1

The function reverse_sort supports containers of any kind, in addition to regular arrays, because it calls the non-member version of begin(). If reverse_sort were coded to use the container member begin():

template <typename C>  
void reverse_sort(C& c) {  
    using std::begin;  
    using std::end;  
 
    std::sort(c.begin(), c.end(), std::greater<>());

}

Then sending an array to it would cause this compiler error:

error C2228: left of '.begin' must have class/struct/union

cbegin

Retrieves a const iterator to the first element in a specified container.

template <class Container>  
auto cbegin(const Container& cont)   
 ->  
decltype(cont.begin());

Parameters

cont
A container or initializer_list.

Return Value

A constant cont.begin().

Remarks

This function works with all STL containers and with initializer_list.

You can use this member function in place of the begin() template function to guarantee that the return value is const_iterator. Typically, it's used in conjunction with the auto type deduction keyword, as shown in the following example. In the example, consider Container to be a modifiable (non- const) container or initializer_list of any kind that supports begin() and cbegin().

 
auto i1 = Container.begin();
// i1 is Container<T>::iterator  
auto i2 = Container.cbegin();

// i2 is Container<T>::const_iterator

cend

Retrieves a const iterator to the element that follows the last element in the specified container.

template <class Container>  
auto cend(const Container& cont)   
 ->  
decltype(cont.end());

Parameters

cont
A container or initializer_list.

Return Value

A constant cont.end().

Remarks

This function works with all STL containers and with initializer_list.

You can use this member function in place of the end() template function to guarantee that the return value is const_iterator. Typically, it's used in conjunction with the auto type deduction keyword, as shown in the following example. In the example, consider Container to be a modifiable (non- const) container or initializer_list of any kind that supports end() and cend().

 
auto i1 = Container.end();
// i1 is Container<T>::iterator  
auto i2 = Container.cend();

// i2 is Container<T>::const_iterator

distance

Determines the number of increments between the positions addressed by two iterators.

template <class InputIterator>  
typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);

Parameters

first
The first iterator whose distance from the second is to be determined.

last
The second iterator whose distance from the first is to be determined.

Return Value

The number of times that first must be incremented until it equal last.

Remarks

The distance 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_distance.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 ( 2 * 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 , 7 );  
   cout << "LPOS is advanced 7 steps forward to point "  
        << " to the eighth element: "  
        << *LPOS << "." << endl;  
  
   list<int>::difference_type Ldiff ;  
   Ldiff = distance ( L.begin ( ) , LPOS );  
   cout << "The distance from L.begin( ) to LPOS is: "  
        << Ldiff << "." << endl;  
}

The list L is: ( -2 0 2 4 6 8 10 12 14 16 ).  
The iterator LPOS initially points to the first element: -2.  
LPOS is advanced 7 steps forward to point  to the eighth element: 12.  
The distance from L.begin( ) to LPOS is: 7.

end

Retrieves an iterator to the element that follows the last element in the specified container.

template <class Container>  
auto end(Container& cont)   
 ->  
decltype(cont.end());

template <class Container>  
auto end(const Container& cont)   
 ->  
decltype(cont.end());

template <class Ty, class Size>  
Ty *end(Ty (& array)[Size]);

Parameters

cont
A container.

array
An array of objects of type Ty.

Return Value

The first two template functions return cont.end() (the first is non-constant and the second is constant).

The third template function returns array + Size.

Remarks

For a code example, see begin.

front_inserter

Creates an iterator that can insert elements at the front of a specified container.

template <class Container>  
front_insert_iterator<Container> front_inserter(Container& _Cont);

Parameters

_Cont
The container object whose front is having an element inserted.

Return Value

A front_insert_iterator associated with the container object _Cont.

Remarks

The member function front_insert_iterator of the front_insert_iterator class may also be used.

Within the Standard Template Library, the argument must refer to one of the two sequence containers that have the member function push_back: deque Class or "list Class".

Example

// iterator_front_inserter.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
   list <int>::iterator L_Iter;  
  
   list<int> L;  
   for ( i = -1 ; i < 9 ; ++i )  
   {  
      L.push_back ( i );  
   }  
  
   cout << "The list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++)  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
  
   // Using the template function to insert an element  
   front_insert_iterator< list < int> > Iter(L);  
 *Iter = 100;  
  
   // Alternatively, you may use the front_insert member function  
   front_inserter ( L ) = 200;  
  
   cout << "After the front insertions, the list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++)  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
}

The list L is:  
 ( -1 0 1 2 3 4 5 6 7 8 ).  
After the front insertions, the list L is:  
 ( 200 100 -1 0 1 2 3 4 5 6 7 8 ).

inserter

A helper template function that lets you use inserter(``_Cont``,``_Where``) instead of insert_iterator<Container>(``_Cont, _Where``).

template <class Container>  
insert_iterator<Container>  
inserter(
    Container& _Cont,  
    typename Container::iterator _Where);

Parameters

_Cont
The container to which new elements are to be added.

_Where
An iterator locating the point of insertion.

Remarks

The template function returns insert_iterator<Container>(``_Cont``, _Where``).

Example

// iterator_inserter.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
   list <int>::iterator L_Iter;  
  
   list<int> L;  
   for (i = 2 ; i < 5 ; ++i )    
   {  
      L.push_back ( 10 * i );  
   }  
  
   cout << "The list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ )  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
  
   // Using the template version to insert an element  
   insert_iterator<list <int> > Iter( L, L.begin ( ) );  
 *Iter = 1;  
  
   // Alternatively, using the member function to insert an element  
   inserter ( L, L.end ( ) ) = 500;  
  
   cout << "After the insertions, the list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++)  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
}

The list L is:  
 ( 20 30 40 ).  
After the insertions, the list L is:  
 ( 1 20 30 40 500 ).

make_checked_array_iterator

Creates a checked_array_iterator that can be used by other algorithms.

Note

This function is a Microsoft extension of the Standard C++ Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.

template <class Iter>  
checked_array_iterator<Iter> 
    make_checked_array_iterator(
 Iter Ptr,  
    size_t Size,  
    size_t Index = 0);

Parameters

Ptr
A pointer to the destination array.

Size
The size of the destination array.

Index
Optional index into the array.

Return Value

An instance of checked_array_iterator.

Remarks

The make_checked_array_iterator function is defined in the stdext namespace.

This function takes a raw pointer—which would ordinarily cause concern about bounds overrun—and wraps it in a checked_array_iterator class that does checking. Because that class is marked as checked, the STL doesn't warn about it. For more information and code examples, see Checked Iterators.

Example

In the following example, a vector is created and populated with 10 items. The contents of the vector are copied into an array by using the copy algorithm, and then make_checked_array_iterator is used to specify the destination. This is followed by an intentional violation of the bounds checking so that a debug assertion failure is triggered.

// make_checked_array_iterator.cpp  
// compile with: /EHsc /W4 /MTd  
  
#include <algorithm>  
#include <iterator> // stdext::make_checked_array_iterator  
#include <memory> // std::make_unique  
#include <iostream>  
#include <vector>  
#include <string>  
  
using namespace std;  
  
template <typename C> void print(const string& s, const C& c) {  
    cout << s;  
  
    for (const auto& e : c) {  
        cout << e << " ";  
    }  
  
    cout << endl;  
}  
  
int main()  
{  
    const size_t dest_size = 10;  
    // Old-school but not exception safe, favor make_unique<int[]>  
    // int* dest = new int[dest_size];  
    unique_ptr<int[]> updest = make_unique<int[]>(dest_size);  
    int* dest = updest.get(); // get a raw pointer for the demo  
  
    vector<int> v;  
  
    for (int i = 0; i < dest_size; ++i) {  
        v.push_back(i);  
    }  
    print("vector v: ", v);  
  
    copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size));  
  
    cout << "int array dest: ";  
    for (int i = 0; i < dest_size; ++i) {  
        cout << dest[i] << " ";  
    }  
    cout << endl;  
  
    // Add another element to the vector to force an overrun.  
    v.push_back(10);  
    // The next line causes a debug assertion when it executes.  
    copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size));  
}

make_move_iterator

Creates a move iterator that contains the provided iterator as the stored iterator.

template <class Iterator>  
move_iterator<Iterator>  
make_move_iterator(const Iterator& _It);

Parameters

_It
The iterator stored in the new move iterator.

Remarks

The template function returns move_iterator``<Iterator>(``_It``).

make_unchecked_array_iterator

Creates an unchecked_array_iterator that can be used by other algorithms.

Note

template <class Iter>  
unchecked_array_iterator<Iter> 
    make_unchecked_array_iterator(Iter Ptr);

Parameters

Ptr
A pointer to the destination array.

Return Value

An instance of unchecked_array_iterator.

Remarks

The make_unchecked_array_iterator function is defined in the stdext namespace.

This function takes a raw pointer and wraps it in a class that performs no checking and therefore optimizes away to nothing, but it also silences compiler warnings such as C4996. Therefore, this is a targeted way to deal with unchecked-pointer warnings without globally silencing them or incurring the cost of checking. For more information and code examples, see Checked Iterators.

Example

In the following example, a vector is created and populated with 10 items. The contents of the vector are copied into an array by using the copy algorithm, and then make_unchecked_array_iterator is used to specify the destination.

// make_unchecked_array_iterator.cpp  
// compile with: /EHsc /W4 /MTd  
  
#include <algorithm>  
#include <iterator> // stdext::make_unchecked_array_iterator  
#include <iostream>  
#include <vector>  
#include <string>  
  
using namespace std;  
  
template <typename C> void print(const string& s, const C& c) {  
    cout << s;  
  
    for (const auto& e : c) {  
        cout << e << " ";  
    }  
  
    cout << endl;  
}  
  
int main()  
{  
    const size_t dest_size = 10;  
    int *dest = new int[dest_size];  
    vector<int> v;  
  
    for (int i = 0; i < dest_size; ++i) {  
        v.push_back(i);  
    }  
    print("vector v: ", v);  
  
    // COMPILER WARNING SILENCED: stdext::unchecked_array_iterator is marked as checked in debug mode  
    // (it performs no checking, so an overrun will trigger undefined behavior)  
    copy(v.begin(), v.end(), stdext::make_unchecked_array_iterator(dest));  
  
    cout << "int array dest: ";  
    for (int i = 0; i < dest_size; ++i) {  
        cout << dest[i] << " ";  
    }  
    cout << endl;  
  
    delete[] dest;  
}

Iterates a specified number of times and returns the new iterator position.

template <class InputIterator>  
InputIterator next(
    InputIterator first,  
    typename iterator_traits<InputIterator>::difference_type _Off = 1);

Parameters

first
The current position.

_Off
The number of times to iterate.

Return Value

Returns the new iterator position after iterating _Off times.

Remarks

The template function returns next incremented _Off times

Iterates in reverse a specified number of times and returns the new iterator position.

template <class BidirectionalIterator>  
BidirectionalIterator prev(
    BidirectionalIterator first,  
    typename iterator_traits<BidirectionalIterator>::difference_type _Off = 1);

Parameters

first
The current position.

_Off
The number of times to iterate.

Remarks

The template function returns next decremented off times.

Share via

<iterator> functions

advance

Parameters

Remarks

Example

back_inserter

Parameters

Return Value

Remarks

Example

begin

Parameters

Return Value

Example

cbegin

Parameters

Return Value

Remarks

cend

Parameters

Return Value

Remarks

distance

Parameters

Return Value

Remarks

Example

end

Parameters

Return Value

Remarks

front_inserter

Parameters

Return Value

Remarks

Example

inserter

Parameters

Remarks

Example

make_checked_array_iterator

Parameters

Return Value

Remarks

Example

make_move_iterator

Parameters

Remarks

make_unchecked_array_iterator

Parameters

Return Value

Remarks

Example

next

Parameters

Return Value

Remarks

prev

Parameters

Remarks

See Also

Additional resources