<iterator>Функции
advance
Увеличивает итератор на указанное количество позиций.
template <class InputIterator, class Distance>
void advance(InputIterator& InIt, Distance Off);
Параметры
InIt
Итератор, который должен увеличен, должен удовлетворять требованиям для итератора ввода.
Off
Целочисленный тип, который можно преобразовать в тип отличия итератора, указывающий число приращений позиции итератора, необходимо сдвинуть вперед.
Замечания
Диапазон должен быть неуклюжаемым, где итераторы должны быть разыменовыванием или в конце.
Если требования InputIterator к двунаправленному итератору соответствуют требованиям, может Off быть отрицательным. Если InputIterator входной или переадресационный итератор является типом, Off он должен быть ненагрегативным.
Расширенная функция имеет постоянную сложность при InputIterator удовлетворении требований к итератору случайного доступа; в противном случае она имеет линейную сложность и поэтому потенциально дорого.
Пример
// 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.
back_inserter
Создает итератор, может вставлять элементы с обратной стороны указанного контейнера.
template <class Container>
back_insert_iterator<Container> back_inserter(Container& Cont);
Параметры
Cont
Контейнер, в который будет выполняться вставка с обратной стороны.
Возвращаемое значение
back_insert_iterator, связанный с объектом-контейнером Cont.
Замечания
В стандартной библиотеке C++ аргумент должен ссылаться на один из трех контейнеров последовательности, имеющих функцию-членpush_back:deque класс,list класс или vector класс.
Пример
// 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 ).
begin
Извлекает итератор для первого элемента в указанном контейнере.
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
Контейнер.
array
Массив объектов перечисления Ty.
Возвращаемое значение
Первые две функции шаблона возвращают cont.begin(). Первая функция не является константой; вторая является константой.
Третья функция шаблона возвращает array.
Пример
Рекомендуется использовать эту же функцию шаблона вместо члена контейнера begin(), если требуется более стандартное поведение.
// 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
Функция reverse_sort поддерживает контейнеры любого типа, кроме обычных массивов, поскольку она обращается к версиям begin(), не являющимся членами. Кодирование reverse_sort для использования члена begin()контейнера:
template <typename C>
void reverse_sort(C& c) {
using std::begin;
using std::end;
std::sort(c.begin(), c.end(), std::greater<>());
}
Затем отправка массива в него вызывает эту ошибку компилятора:
error C2228: left of '.begin' must have class/struct/union
cbegin
Извлекает итератор const (только для чтения) в первый элемент в указанном контейнере.
template <class Container>
auto cbegin(const Container& cont)
-> decltype(cont.begin());
Параметры
cont
Контейнер или initializer_list.
Возвращаемое значение
Константа cont.begin().
Замечания
Эта функция работает со всеми контейнерами стандартной библиотеки C++ и с initializer_list.
Эту функцию-член можно использовать вместо функции шаблона begin(), чтобы гарантировать, что возвращаемое значение будет const_iterator. Как правило, он используется с ключевым словом вычета auto типов, как показано в следующем примере. В этом примере предположим, что Container является изменяемым контейнером (не const) или initializer_list любого типа, который поддерживает begin() и cbegin().
auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();
// i2 is Container<T>::const_iterator
cend
Извлекает итератор const (только для чтения) в элемент, который следует последнему элементу в указанном контейнере.
template <class Container>
auto cend(const Container& cont)
-> decltype(cont.end());
Параметры
cont
Контейнер или initializer_list.
Возвращаемое значение
Константа cont.end().
Замечания
Эта функция работает со всеми контейнерами стандартной библиотеки C++ и с initializer_list.
Эту функцию-член можно использовать вместо функции шаблона end(), чтобы гарантировать, что возвращаемое значение будет const_iterator. Как правило, он используется с ключевым словом вычета auto типов, как показано в следующем примере. В этом примере предположим, что Container является изменяемым контейнером (не const) или initializer_list любого типа, который поддерживает end() и cend().
auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();
// i2 is Container<T>::const_iterator
crbegin
Получите обратный итератор только для чтения для элементов контейнера, начиная с конца контейнера.
template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));
Параметры
C
Тип контейнера.
c
Экземпляр контейнера.
Возвращаемое значение
Этот итератор возвращает элементы контейнера в обратном порядке, начиная с конца контейнера.
Пример: 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
crend
Получите sentinel в конце обратной последовательности элементов только для чтения.
template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));
Параметры
C
Тип контейнера.
c
Экземпляр контейнера.
Возвращаемое значение
Sentinel следует последнему элементу в обратном представлении контейнера.
Пример crend
#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
data
Получите указатель на первый элемент в контейнере.
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
Тип контейнера.
c
Экземпляр контейнера.
E
Тип элемента списка инициализатора.
il
Список инициализатора.
N
Количество элементов в массиве.
T
Тип данных в массиве.
Возвращаемое значение
1, 2) Указатель на основе типа контейнера на первый элемент. Например, если контейнер является вектором целых чисел, тип возвращаемого значения — это .int *
3) Указатель на первый элемент в виде массива.
4) Указатель на первый элемент списка инициализатора.
Пример: data.
#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
distance
Указывает количество приращений между позициями, которые адресуют два итератора.
template <class InputIterator>
typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);
Параметры
first
Первый итератор, для которого нужно определить расстояние до второго.
last
Второй итератор, для которого нужно определить расстояние от первого.
Возвращаемое значение
Число раз, которое должно увеличиваться до тех пор, first пока он не равен last.
Замечания
Функция расстояния имеет постоянную сложность при InputIterator удовлетворении требований к итератору случайного доступа; в противном случае она имеет линейную сложность и поэтому потенциально дорого.
Пример
// 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.
empty
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
Тип контейнера.
c
Экземпляр контейнера.
E
Тип элемента списка инициализатора.
il
Список инициализатора.
N
Количество элементов в массиве.
T
Тип данных в массиве.
Возвращаемое значение
Возвращает значение true , если контейнер не имеет элементов; в противном случае 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
end
Извлекает итератор для элемента, следующего за последним элементом в указанном контейнере.
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
Контейнер.
array
Массив объектов перечисления Ty.
Возвращаемое значение
Первые две функции шаблона возвращают cont.end() (первая не является константой, вторая является константой).
Третья функция шаблона возвращает array + Size.
Замечания
Пример кода см. в разделе begin.
front_inserter
Создает итератор, может вставлять элементы с передней стороны указанного контейнера.
template <class Container>
front_insert_iterator<Container> front_inserter(Container& Cont);
Параметры
Cont
Объект-контейнер, для которого выполняется вставка элемента в переднюю часть.
Возвращаемое значение
front_insert_iterator, связанный с объектом-контейнером Cont.
Замечания
Функция-член front_insert_iterator класса front_insert_iterator также может использоваться.
В стандартной библиотеке C++ аргумент должен ссылаться на один из двух контейнеров последовательности, которые имеют функцию-член push_back: класс deque или "класс list".
Пример
// 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 ).
inserter
Вспомогающая функция шаблона, которая позволяет использовать inserter(Cont, Where) вместо insert_iterator<Container>(Cont, Where)него.
template <class Container>
insert_iterator<Container>
inserter(
Container& Cont,
typename Container::iterator Where);
Параметры
Cont
Контейнер, в который будут добавляться новые элементы.
Where
Итератор, обнаруживающий точку вставки.
Замечания
Функция-шаблон возвращает 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 ).
make_checked_array_iterator
Создает checked_array_iterator, который может использоваться другими алгоритмами.
Примечание.
Эта функция — расширение Майкрософт для стандартной библиотеки C++. Код, реализованный с помощью этой функции, нельзя перенести в стандартные среды сборки C, не поддерживающие это расширение Microsoft.
template <class Iter>
checked_array_iterator<Iter>
make_checked_array_iterator(
Iter Ptr,
size_t Size,
size_t Index = 0);
Параметры
Ptr
Указатель на массив назначения.
Size
Размер массива назначения.
Index
Необязательный индекс массива.
Возвращаемое значение
Экземпляр checked_array_iterator.
Замечания
Функция make_checked_array_iterator задается в пространстве имен stdext.
Эта функция принимает необработанный указатель, который в обычном случае вызывает проблемы, связанные с выходом за границы, и помещает его в оболочку класса checked_array_iterator, который выполняет проверку. Так как этот класс помечен как проверенный, стандартная библиотека С++ не выдает предупреждение о нем. Дополнительные сведения и примеры кода см. в разделе Проверенные итераторы.
Пример
В следующем примере создается и заполняется 10 элементами вектор. Содержимое вектора копируется в массив с помощью алгоритма копирования, а затем make_checked_array_iterator используется для указания назначения. Затем осуществляется проверка на преднамеренное нарушение границ для активации сбоя подтверждения отладки.
// 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
Создает move iterator, содержащий предоставленный итератор в качестве итератора stored.
template <class Iterator>
move_iterator<Iterator>
make_move_iterator(const Iterator& It);
Параметры
It
Итератор, хранящийся в новом итераторе перемещения.
Замечания
Функция шаблона возвращается move_iterator <Iterator>(_It).
make_unchecked_array_iterator
Создает unchecked_array_iterator, который может использоваться другими алгоритмами.
Примечание.
Эта функция — расширение Майкрософт для стандартной библиотеки C++. Код, реализованный с помощью этой функции, нельзя перенести в стандартные среды сборки C, не поддерживающие это расширение Microsoft.
template <class Iter>
unchecked_array_iterator<Iter>
make_unchecked_array_iterator(Iter Ptr);
Параметры
Ptr
Указатель на массив назначения.
Возвращаемое значение
Экземпляр unchecked_array_iterator.
Замечания
Функция make_unchecked_array_iterator задается в пространстве имен stdext.
Эта функция принимает необработанный указатель и помещает его в класс, который не выполняет проверки, и поэтому оптимизирует к минимуму, но также подавляет предупреждения компилятора, например C4996. Соответственно, это целевой способ работы с предупреждениями непроверенных указателей без их глобального подавления или возникновения стоимости проверки. Дополнительные сведения и примеры кода см. в разделе Проверенные итераторы.
Пример
В следующем примере создается и заполняется 10 элементами вектор. Содержимое вектора копируется в массив с помощью алгоритма копирования, а затем make_unchecked_array_iterator используется для указания назначения.
// 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
next
Выполняет итерацию заданное число раз и возвращает новую позицию итератора.
template <class InputIterator>
InputIterator next(
InputIterator first,
typename iterator_traits<InputIterator>::difference_type off = 1);
Параметры
first
Текущая позиция.
off
Количество раз для прохода.
Возвращаемое значение
Возвращает новую позицию итератора после прохода off раз.
Замечания
Функция-шаблон возвращает next, приращенный off раз.
prev
Выполняет обратную итерацию заданное число раз и возвращает новую позицию итератора.
template <class BidirectionalIterator>
BidirectionalIterator prev(
BidirectionalIterator first,
typename iterator_traits<BidirectionalIterator>::difference_type off = 1);
Параметры
first
Текущая позиция.
off
Количество раз для прохода.
Замечания
Функция-шаблон возвращает next, уменьшенный off раз.
rbegin
Получите итератор, который возвращает элементы контейнера в обратном порядке.
template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
Параметры
C
Тип контейнера.
c
Экземпляр контейнера.
Возвращаемое значение
Возвращаемый итератор представляет элементы контейнера в обратном порядке, начиная с конца обратного диапазона.
Пример: 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
rend
Получите sentinel в конце обратной последовательности элементов.
template <class C> constexpr auto rend(C& c)-> decltype(c.rend());
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());
Параметры
C
Тип контейнера.
c
Экземпляр контейнера.
Возвращаемое значение
Обратный итератор в sentinel в конце контейнера. Sentinel следует последнему элементу в обратном представлении контейнера:
Пример rend
#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
size
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
Тип контейнера.
c
Экземпляр контейнера.
N
Количество элементов в массиве.
T
Тип данных в массиве.
Возвращаемое значение
Количество элементов в контейнере в виде целого числа без знака.
Пример: size.
#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