Funções <iterator>
advance
Aumenta um iterador por um número especificado de posições.
template <class InputIterator, class Distance>
void advance(InputIterator& InIt, Distance Off);
Parâmetros
InIt
O iterador que deverá ser incrementado e atender aos requisitos de um iterador de entrada.
Off
Um tipo integral que pode ser convertido no tipo de diferença do iterador e que especifica o número de incrementos a ser avançado na posição do iterador.
Comentários
O intervalo deve ser não singular, onde os iteradores devem ser desreferenciáveis ou passados do final.
Se o InputIterator atender aos requisitos para um tipo de iterador bidirecional, poderá Off ser negativo. Se InputIterator for um tipo de iterador de entrada ou encaminhamento, Off deve ser não negativo.
A função de avanço tem complexidade constante quando InputIterator atende aos requisitos de um iterador de acesso aleatório. Caso contrário, ela terá complexidade linear e, portanto, poderá ser cara.
Exemplo
// 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
Cria um iterador que pode inserir elementos no fim de um contêiner especificado.
template <class Container>
back_insert_iterator<Container> back_inserter(Container& Cont);
Parâmetros
Cont
O contêiner no qual a inserção no final deve ser executada.
Valor de retorno
Um back_insert_iterator associado ao objeto de contêiner Cont.
Comentários
Na Biblioteca Padrão do C++, o argumento deve se referir a um dos três contêineres de sequência que têm a função push_backde membro: deque Classe, list Classe ou vector Classe.
Exemplo
// 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
Recupera um iterador para o primeiro elemento em um contêiner especificado.
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]);
Parâmetros
cont
Um contêiner.
array
Uma matriz de objetos do tipo Ty.
Valor de retorno
As duas primeiras funções de modelo retornam cont.begin(). A primeira função é não constante; a segunda é constante.
A terceira função de modelo retorna array.
Exemplo
É recomendável usar essa função de modelo no lugar do membro de contêiner begin() quando comportamento mais genérico for exigido.
// 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
A função reverse_sort oferece suporte a contêineres de qualquer tipo, além das matrizes regulares, pois ela chama a versão não membro de begin(). Codificando reverse_sort para usar o membro begin()do contêiner:
template <typename C>
void reverse_sort(C& c) {
using std::begin;
using std::end;
std::sort(c.begin(), c.end(), std::greater<>());
}
Em seguida, enviar uma matriz para ele causa este erro do compilador:
error C2228: left of '.begin' must have class/struct/union
cbegin
Recupera um iterador const (somente leitura) para o primeiro elemento em um contêiner especificado.
template <class Container>
auto cbegin(const Container& cont)
-> decltype(cont.begin());
Parâmetros
cont
Um contêiner ou initializer_list.
Valor de retorno
Uma constante cont.begin().
Comentários
Essa função funciona com todos os contêineres da Biblioteca Padrão do C++ e com initializer_listo .
Você pode usar essa função membro no lugar da função de modelo begin(), de modo a garantir que o valor de retorno seja const_iterator. Normalmente, ela é usada com a palavra-chave de dedução de tipo auto, conforme mostrado no exemplo a seguir. No exemplo, considere que Container será um contêiner (não const) modificável ou initializer_list de qualquer tipo que dê suporte a begin() e cbegin().
auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();
// i2 is Container<T>::const_iterator
cend
Recupera um iterador const (somente leitura) para o elemento que segue o último elemento no contêiner especificado.
template <class Container>
auto cend(const Container& cont)
-> decltype(cont.end());
Parâmetros
cont
Um contêiner ou initializer_list.
Valor de retorno
Uma constante cont.end().
Comentários
Essa função funciona com todos os contêineres da Biblioteca Padrão do C++ e com initializer_listo .
Você pode usar essa função membro no lugar da função de modelo end(), de modo a garantir que o valor de retorno seja const_iterator. Normalmente, ela é usada com a palavra-chave de dedução de tipo auto, conforme mostrado no exemplo a seguir. No exemplo, considere que Container será um contêiner (não const) modificável ou initializer_list de qualquer tipo que dê suporte a end() e cend().
auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();
// i2 is Container<T>::const_iterator
crbegin
Obtenha um iterador somente leitura reverso para os elementos do contêiner, começando no final do contêiner.
template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));
Parâmetros
C
O tipo do recipiente.
c
Uma instância de contêiner.
Valor retornado
Esse iterador retorna os elementos do contêiner na ordem inversa, começando no final do contêiner.
Exemplo: 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
Obtenha o sentinela no final de uma sequência invertida somente leitura de elementos.
template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));
Parâmetros
C
O tipo do recipiente.
c
Uma instância de contêiner.
Valor retornado
A sentinela segue o último elemento em uma visão invertida do contêiner.
Exemplo do 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
Obtenha um ponteiro para o primeiro elemento no contêiner.
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;
Parâmetros
C
O tipo do recipiente.
c
Uma instância de um contêiner.
E
O tipo de elemento da lista de inicializadores.
il
Uma lista de inicializadores.
N
O número de elementos na matriz.
T
O tipo de dados na matriz.
Valor retornado
1, 2) Um ponteiro, com base no tipo do contêiner, para o primeiro elemento. Por exemplo, se o contêiner for um vetor de números inteiros, o tipo do valor retornado será um int *.
3) Um ponteiro para o primeiro elemento como uma matriz.
4) Um ponteiro para o primeiro elemento da lista de inicializadores.
Exemplo 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
Determina o número de incrementos entre as posições tratadas por dois iteradores.
template <class InputIterator>
typename iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);
Parâmetros
first
O primeiro iterador cuja distância do segundo deve ser determinada.
last
O segundo iterador cuja distância do primeiro deve ser determinada.
Valor de retorno
O número de vezes que deve ser incrementado até ser first igual a last.
Comentários
A função de distância tem complexidade constante quando InputIterator atende aos requisitos de um iterador de acesso aleatório. Caso contrário, ela terá complexidade linear e, portanto, poderá ser cara.
Exemplo
// 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;
Parâmetros
C
O tipo do recipiente.
c
Uma instância de um contêiner.
E
O tipo de elemento da lista de inicializadores.
il
Uma lista de inicializadores.
N
O número de elementos na matriz.
T
O tipo de dados na matriz.
Valor retornado
Retorna true se o contêiner não tiver elementos; caso contrário false, .
Exemplo
#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
Recupera um iterador para o elemento que segue o último elemento no contêiner especificado.
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]);
Parâmetros
cont
Um contêiner.
array
Uma matriz de objetos do tipo Ty.
Valor de retorno
As duas primeiras funções de modelo retornam cont.end() (a primeira é não constante e a segunda é constante).
A terceira função de modelo retorna array + Size.
Comentários
Para obter um exemplo de código, consulte begin.
front_inserter
Cria um iterador que pode inserir elementos na frente de um contêiner especificado.
template <class Container>
front_insert_iterator<Container> front_inserter(Container& Cont);
Parâmetros
Cont
O objeto de contêiner na frente do qual um elemento será inserido.
Valor de retorno
Um front_insert_iterator associado ao objeto de contêiner Cont.
Comentários
A função de membro front_insert_iterator da classe front_insert_iterator também pode ser usada.
Dentro da Biblioteca Padrão do C++, o argumento deve se referir a um dos dois contêineres de sequência que têm a função membro push_back: Classe deque ou "Classe list".
Exemplo
// 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
Uma função de modelo auxiliar que permite usar inserter(Cont, Where) em vez de insert_iterator<Container>(Cont, Where).
template <class Container>
insert_iterator<Container>
inserter(
Container& Cont,
typename Container::iterator Where);
Parâmetros
Cont
O contêiner ao qual novos elementos serão adicionados.
Where
Um iterador que localiza o ponto de inserção.
Comentários
A função do modelo retorna insert_iterator<Container>(Cont, Where).
Exemplo
// 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
Cria um checked_array_iterator que pode ser usado por outros algoritmos.
Observação
Essa função é uma extensão da Biblioteca Padrão do C++ da Microsoft. O código implementado usando essa função não é portátil para ambientes de criação do C++ Standard que não oferecem suporte a essa extensão da Microsoft.
template <class Iter>
checked_array_iterator<Iter>
make_checked_array_iterator(
Iter Ptr,
size_t Size,
size_t Index = 0);
Parâmetros
Ptr
Um ponteiro para a matriz de destino.
Size
O tamanho da matriz de destino.
Index
O índice opcional na matriz.
Valor de retorno
Uma instância de checked_array_iterator.
Comentários
A função make_checked_array_iterator é definida no namespace stdext.
Essa função usa um ponteiro bruto – que normalmente geraria preocupação sobre estouro de limites – e o encapsula em uma classe checked_array_iterator que faz a verificação. Como essa classe é marcada como verificada, a Biblioteca Padrão do C++ não avisa sobre isso. Para obter mais informações e exemplos de código, consulte Iteradores verificados.
Exemplo
No exemplo a seguir, um vetor é criado e populado com 10 itens. O conteúdo do vetor é copiado em uma matriz usando o algoritmo de cópia e, em seguida, make_checked_array_iterator é usado para especificar o destino. Isso é seguido por uma violação intencional da verificação dos limites, de modo que uma falha de asserção de depuração é acionada.
// 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
Cria um move iterator que contém o iterador fornecido como o iterador stored.
template <class Iterator>
move_iterator<Iterator>
make_move_iterator(const Iterator& It);
Parâmetros
It
O iterador armazenado no novo iterador de movimentação.
Comentários
A função de modelo retorna move_iterator <Iterator>(_It).
make_unchecked_array_iterator
Cria um unchecked_array_iterator que pode ser usado por outros algoritmos.
Observação
Essa função é uma extensão da Biblioteca Padrão do C++ da Microsoft. O código implementado usando essa função não é portátil para ambientes de criação do C++ Standard que não oferecem suporte a essa extensão da Microsoft.
template <class Iter>
unchecked_array_iterator<Iter>
make_unchecked_array_iterator(Iter Ptr);
Parâmetros
Ptr
Um ponteiro para a matriz de destino.
Valor de retorno
Uma instância de unchecked_array_iterator.
Comentários
A função make_unchecked_array_iterator é definida no namespace stdext.
Essa função usa um ponteiro bruto e o encapsula em uma classe que não executa verificação e, portanto, a otimização não serve para nada, mas ela também silencia os avisos do compilador, como o C4996. Desse modo, essa é uma maneira direcionada de lidar com avisos de ponteiro não verificado, sem silenciá-los globalmente ou incorrer no custo da verificação. Para obter mais informações e exemplos de código, consulte Iteradores verificados.
Exemplo
No exemplo a seguir, um vetor é criado e populado com 10 itens. O conteúdo do vetor é copiado em uma matriz usando o algoritmo de cópia e, em seguida, make_unchecked_array_iterator é usado para especificar o destino.
// 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
Itera um número de vezes especificado e retorna a nova posição do iterador.
template <class InputIterator>
InputIterator next(
InputIterator first,
typename iterator_traits<InputIterator>::difference_type off = 1);
Parâmetros
first
A posição atual.
off
O número de vezes que a iteração deve ser executada.
Valor de retorno
Retorna a nova posição do iterador após iterar off vezes.
Comentários
A função de modelo retorna next incrementado off vezes
prev
Itera em ordem inversa um número de vezes especificado e retorna a nova posição do iterador.
template <class BidirectionalIterator>
BidirectionalIterator prev(
BidirectionalIterator first,
typename iterator_traits<BidirectionalIterator>::difference_type off = 1);
Parâmetros
first
A posição atual.
off
O número de vezes que a iteração deve ser executada.
Comentários
A função de modelo retorna next decrementado off vezes.
rbegin
Obtenha um iterador, que retorna os elementos do contêiner na ordem inversa.
template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
Parâmetros
C
O tipo do recipiente.
c
Uma instância de contêiner.
Valor retornado
O iterador retornado apresenta os elementos do contêiner em ordem inversa, começando no final do intervalo invertido.
Exemplo 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
Obtenha a sentinela no final de uma sequência inversa de elementos.
template <class C> constexpr auto rend(C& c)-> decltype(c.rend());
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());
Parâmetros
C
O tipo do recipiente.
c
Uma instância de contêiner.
Valor retornado
Um iterador reverso para a sentinela no final do contêiner. A sentinela segue o último elemento na visão invertida do contêiner:
Exemplo do 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;
Parâmetros
C
O tipo do recipiente.
c
Uma instância de um contêiner.
N
O número de elementos na matriz.
T
O tipo de dados na matriz.
Valor retornado
O número de elementos no contêiner como um valor semelhante a um inteiro sem sinal.
Exemplo 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