<iterator> functions
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
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>
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;
}
next
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
prev
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.