| description | title | ms.date | f1_keywords | helpviewer_keywords | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: <iterator> functions |
<iterator> functions |
11/04/2016 |
|
|
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 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;
list<int> L;
for (int i = 1; i < 9; ++i)
{
L.push_back(i);
}
list<int>::iterator LPOS = L.begin();
cout << "The list L is: ( ";
for (auto 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.
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);Cont
The container into which the back insertion is to be executed.
A back_insert_iterator associated with the container object Cont.
Within the C++ Standard 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.
// iterator_back_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main()
{
using namespace std;
vector<int> vec;
for (int i = 0; i < 3; ++i)
{
vec.push_back(i);
}
cout << "The initial vector vec is: ( ";
for (auto 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 (auto 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 ).
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]);cont
A container.
array
An array of objects of type Ty.
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.
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)
{
std::sort(std::begin(c), std::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);
}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(). Coding reverse_sort 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, causes this compiler error:
error C2228: left of '.begin' must have class/struct/union
Retrieves a const (read-only) iterator to the first element in a specified container.
template <class Container>
auto cbegin(const Container& cont)
-> decltype(cont.begin());cont
A container or initializer_list.
A constant cont.begin().
This function works with all C++ Standard Library 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 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_iteratorRetrieves a const (read-only) iterator to the element that follows the last element in the specified container.
template <class Container>
auto cend(const Container& cont)
-> decltype(cont.end());cont
A container or initializer_list.
A constant cont.end().
This function works with all C++ Standard Library 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 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_iteratorGet a reverse read-only iterator to the elements of the container, starting at the end of the container.
template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));C
The type of the container.
c
A container instance.
This iterator returns the elements of the container in reverse order, starting at the end of the container.
:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin().":::
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{10, 20, 30};
for (auto i = std::crbegin(v); i != std::crend(v); ++i)
{
std::cout << *i << ' '; // outputs 30 20 10
}
// v[1] = 100; // error because the iterator is const
}30 20 10
Get the sentinel at the end of a read-only reversed sequence of elements.
template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));C
The type of the container.
c
A container instance.
The sentinel follows the last element in a reversed view of the container.
:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin().":::
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{10, 20, 30};
auto vi = std::crend(v);
--vi; // get off the sentinel and onto the last element in the reversed range
std::cout << *vi; // outputs 10
// vi[0] = 300; // error because the iterator is const
}10
Get a pointer to the first element in the container.
1) template <class C> constexpr auto data(C& c) -> decltype(c.data());
2) template <class C> constexpr auto data(const C& c) -> decltype(c.data());
3) template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
4) template <class E> constexpr const E* data(initializer_list<E> il) noexcept;C
The type of the container.
c
An instance of a container.
E
The element type of the initializer list.
il
An initializer list.
N
The number of elements in the array.
T
The type of the data in the array.
1, 2) A pointer, based on the type of the container, to the first element. For example, if the container is a vector of integers, the type of the return value is an int *.
3) A pointer to the first element as an array.
4) A pointer to the first element of the initializer list.
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{ 10, 20, 30 };
std::string src{ "a string" };
const char *charPtr = std::data(src);
int* intPtr = std::data(v);
std::cout << charPtr << ", " << *intPtr << '\n'; // a string, 10
}a string, 10
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);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.
The number of times that first must be incremented until it equals last.
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.
// iterator_distance.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>
int main()
{
using namespace std;
list<int> L;
for (int 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.
template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
template <class E> constexpr bool empty(initializer_list<E> il) noexcept;C
The type of the container.
c
An instance of a container.
E
The element type of the initializer list.
il
An initializer list.
N
The number of elements in the array.
T
The type of the data in the array.
Returns true if the container has no elements; otherwise false.
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{ 10,20,30 };
std::vector<int> v2;
std::cout << std::boolalpha << std::empty(v); // outputs false
std::cout << std::boolalpha << ", " << std::empty(v2); // outputs true
}false, true
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]);cont
A container.
array
An array of objects of type Ty.
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.
For a code example, see begin.
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);Cont
The container object whose front is having an element inserted.
A front_insert_iterator associated with the container object Cont.
The member function front_insert_iterator of the front_insert_iterator class may also be used.
Within the C++ Standard Library, the argument must refer to one of the two sequence containers that have the member function push_back: deque Class or "list Class".
// iterator_front_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>
int main()
{
using namespace std;
list<int> L;
for (int i = -1; i < 9; ++i)
{
L.push_back(i);
}
cout << "The list L is:\n ( ";
for (auto 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 (auto 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 ).
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);Cont
The container to which new elements are to be added.
Where
An iterator locating the point of insertion.
The template function returns insert_iterator<Container>(Cont, Where).
// iterator_inserter.cpp
// compile with: /EHsc
#include <iterator>
#include <list>
#include <iostream>
int main()
{
using namespace std;
list<int> L;
for (int i = 2; i < 5; ++i)
{
L.push_back(10 * i);
}
cout << "The list L is:\n ( ";
for (auto 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 (auto 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 ).
Creates a checked_array_iterator that can be used by other algorithms.
Note
This function is a Microsoft extension of the C++ Standard 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);Ptr
A pointer to the destination array.
Size
The size of the destination array.
Index
Optional index into the array.
An instance of checked_array_iterator.
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 C++ Standard Library doesn't warn about it. For more information and code examples, see Checked Iterators.
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));
}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);It
The iterator stored in the new move iterator.
The template function returns move_iterator <Iterator>(_It).
Creates an unchecked_array_iterator that can be used by other algorithms.
Note
This function is a Microsoft extension of the C++ Standard 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);Ptr
A pointer to the destination array.
An instance of unchecked_array_iterator.
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.
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;
}vector v: 0 1 2 3 4 5 6 7 8 9
int array dest: 0 1 2 3 4 5 6 7 8 9
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);first
The current position.
off
The number of times to iterate.
Returns the new iterator position after iterating off times.
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);first
The current position.
off
The number of times to iterate.
The template function returns next decremented off times.
Get an iterator, which returns the elements of the container in reverse order.
template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());C
The type of the container.
c
A container instance.
The returned iterator presents the elements of the container in reverse order, starting at the end of the reversed range.
:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin().":::
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{ 10, 20, 30 };
for (auto e = std::rbegin(v); e != std::rend(v); ++e)
{
std::cout << *e << ' '; // outputs 30 20 10
}
}30 20 10
Get the sentinel at the end of a reversed sequence of elements.
template <class C> constexpr auto rend(C& c)-> decltype(c.rend());
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());C
The type of the container.
c
A container instance.
A reverse iterator to the sentinel at the end of the container. The sentinel follows the last element in the reversed view of the container:
:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin().":::
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{10, 20, 30};
auto vi = std::rend(v);
--vi; // get off the sentinel and onto the last element in the reversed range
std::cout << *vi; // outputs 10
}10
template <class C> constexpr auto size(const C& c)
-> decltype(c.size());
template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;C
The type of the container.
c
An instance of a container.
N
The number of elements in the array.
T
The type of the data in the array.
The number of elements in the container as an unsigned integer-like value.
#include <vector>
#include <iostream>
int main()
{
std::vector<int> v{ 10, 20, 30 };
size_t s = std::size(v);
std::cout << s; // outputs 3
}3