Compartilhar via

Funções <ranges>

  • Artigo

O cabeçalho <ranges>C++20 inclui as funções aulixiares não membro a seguir.

Funções de não membro Descrição
beginC++20 Obtenha um iterador para o primeiro elemento no intervalo.
cbeginC++20 Obtenha um iterador const para o primeiro elemento no intervalo.
cendC++20 Obtenha o sentinela no final do intervalo qualificado por const.
cdataC++20 Obtenha um ponteiro const para o primeiro elemento no intervalo contíguo.
crbeginC++20 Obtenha um iterador reverso const para o início do intervalo.
crendC++20 Obtenha o sentinela no final do que crbegin() retorna.
dataC++20 Obtenha um ponteiro para o primeiro elemento no intervalo contíguo.
emptyC++20 Teste se o intervalo está vazio.
endC++20 Obtenha o sentinela no final do intervalo.
rbeginC++20 Obtenha um iterador reverso para o início do intervalo.
rendC++20 Obtenha um iterador reverso para o sentinela no final do intervalo.
sizeC++20 Obtenha o tamanho do intervalo como um valor sem sinal.
ssizeC++20 Obtenha o tamanho do intervalo como um valor com sinal.

Muitas dessas 'funções' são implementadas como objetos de ponto de personalização. Um objeto de ponto de personalização é um objeto de função que pode ser sobrecarregado em tipos definidos pelo usuário, ao mesmo tempo em que impõe restrições sobre quais tipos de tipos podem ser passados para o objeto de função. O efeito final é que o compilador descobre se há uma função personalizada válida para chamar o tipo passado ou se a implementação padrão deve ser usada ou se a chamada está mal formada.

Muitas dessas funções têm funções correspondentes no namespace std. No entanto, ao trabalhar com intervalos, use essas funções auxiliares em vez disso. Essas funções usam conceitos do C++20, que fornecem erros melhores de tempo de compilação. Como eles são implementados como pontos de personalização, problemas relacionados à ADL (pesquisa dependente de argumento) e à exatidão de const são evitados.

begin

Obtenha um iterador para o primeiro elemento no intervalo.

template<class T>
constexpr std::input_or_output_iterator auto begin(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um iterador para o primeiro elemento no intervalo:

Figura de um vetor com os elementos 10, 20 e 30. O primeiro elemento contém 10 e está rotulado como 'begin()'. O último elemento contém 30 e está rotulado como 'last element'. Uma caixa imaginária após o último elemento indica o sentinela e está rotulado como end().

Se o intervalo for uma matriz, retornará o equivalente a rg + 0. Se auto(rg.begin()) gerar um iterador, retornará o equivalente a auto(rg.begin()). Se essa expressão estiver mal formada, auto(begin(rg)) será usada se essa expressão produzir um iterador.

Comentários

ranges::begin() funciona em todos os intervalos, enquanto std::begin() talvez não funcione.

Exemplo: begin

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto vi = std::ranges::begin(v);
    std::cout << *vi << ' ' << *++vi; // outputs 10 20
}

cbegin

Obtenha um iterador const para o primeiro elemento em um intervalo. O iterador pode acessar os elementos no intervalo, mas não pode modificá-los.

template<class T>
constexpr std::input_or_output_iterator auto cbegin(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um iterador const para o primeiro elemento no intervalo:

Figura de um vetor com os elementos 10, 20 e 30. O primeiro elemento contém 10 e está rotulado como 'cbegin()'. O último elemento contém 30 e está rotulado como 'last element'. Uma caixa imaginária após o último elemento indica o sentinela e está rotulado como cend().

Se o intervalo for uma matriz, retornará o equivalente a rg + 0. Se auto(rg.cbegin()) gerar um iterador, retornará o equivalente a auto(rg.cbegin()). Se essa expressão estiver mal formada, auto(cbegin(rg)) será usada se essa expressão produzir um iterador.

Comentários

ranges::cbegin() funciona em todos os intervalos, enquanto std::cbegin() talvez não funcione.

Exemplo: cbegin

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto vi = std::ranges::cbegin(v);
    std::cout << *vi; // outputs 10
    // *vi = 100; // error because the iterator is const
}

cdata

Obtenha um ponteiro const para o primeiro elemento no intervalo contíguo.

template<class T>
constexpr std::add_pointer_t<ranges::range_reference_t<const T>> cdata(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um ponteiro const, com base no tipo do intervalo, para o primeiro elemento no intervalo contíguo. Por exemplo, se o intervalo for um vetor de inteiros, o tipo do valor retornado será um const int *.

Exemplo: cdata

#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    std::string src{ "a string" };
   
    auto c_charPtr = std::ranges::cdata(src); // ptr is a const char *
    auto c_intPtr = std::ranges::cdata(v); // ptr2 is a const int *
    std::cout << c_charPtr << ", " << *c_intPtr << '\n'; // outputs a string, 10

    // *c_intPtr = 100; // error - cannot assign to a const pointer
    // *charPtr = 'A'; // error - cannot assign to a const pointer
}

cend

Obtenha o sentinela no final do intervalo qualificado por const. O iterador pode acessar os elementos no intervalo, mas não pode modificá-los.

template<class T>
constexpr std::sentinel_for<decltype(ranges::cbegin(std::declval<T>()))> auto cend(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

O sentinel que segue o último elemento no intervalo qualificado por const:

Figura de um vetor com os elementos 10, 20 e 30. O primeiro elemento contém 10 e está rotulado como cbegin(). O último elemento contém 30 e está rotulado como 'last element'. Uma caixa imaginária após o último elemento indica o sentinela e está rotulado como cend().

Comentários

ranges::cend() funciona em todos os intervalos, enquanto std::cend() talvez não funcione.

Exemplo: cend

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto i = std::ranges::cend(v);
    --i; // get off the sentinel and onto the last element in the range
    std::cout << *i; // outputs 30
    // *i = 300 // error because the iterator is const
}

crbegin

Obtenha um iterador const reverso para primeiro elemento em uma cadeia invertida. Um iterador reverso retorna os elementos do intervalo em ordem inversa. O intervalo em si não está invertido; o acesso a ele está.

template<class T>
constexpr std::input_or_output_iterator auto crbegin(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um iterador const reverso para o primeiro elemento no intervalo. Esse iterador retorna os elementos do intervalo em ordem inversa, começando no final do intervalo:

Figura de um vetor com os elementos 10, 20 e 30. Há uma caixa imaginária antes do elemento mais à esquerda (o elemento mais à esquerda contém o número 10) que representa o sentinela. Ele está rotulado como crend(). O primeiro elemento do vetor contém o número 10 e está rotulado como 'last element'. O elemento mais à direita no vetor contém 30 e está rotulado como crbegin().

Se o intervalo for uma matriz, retornará o equivalente de reverse_iterator{rg + n} em que n é o número de elementos na matriz. Se auto(rg.crbegin()) gerar um iterador, retornará o equivalente a auto(rg.crbegin()). Se essa expressão estiver mal formada, auto(crbegin(rg)) será usada se essa expressão produzir um iterador.

Comentários

ranges::crbegin() funciona em todos os intervalos bidirecionais, enquanto std::crbegin() talvez não funcione.

Exemplo: crbegin

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::crbegin(v);
    std::cout << *vi << ' ' << *++vi << ' ' << *++vi; // outputs 30 20 10
    // vi[1] = 100; // error because the iterator is const
}

crend

Obtenha o sentinela no final do que crbegin() retorna. Um iterador reverso retorna os elementos do intervalo em ordem inversa. O intervalo em si não está invertido; o acesso a ele está.

template<class T>
std::sentinel_for<decltype(ranges::crbegin(declval<T>()))> auto crend(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

O sentinela no final do que cbegin() retorna. O sentinela segue o último elemento em uma exibição invertida do intervalo:

Figura de um vetor com os elementos 10, 20 e 30. Há uma caixa imaginária antes do elemento mais à esquerda (o elemento mais à esquerda contém o número 10) que representa o sentinela. Ele está rotulado como crend(). O primeiro elemento do vetor contém o número 10 e está rotulado como 'last element'. O elemento mais à direita no vetor contém 30 e está rotulado como crbegin().

Comentários

ranges::crend() funciona em todos os intervalos bidirecionais, enquanto std::crend() talvez não funcione.

Exemplo do crend

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::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    
    std::cout << *vi << ' ' << *--vi << ' ' << *--vi; // outputs 10, 20, 30
}

data

Obtenha um ponteiro para o primeiro elemento em um intervalo contíguo.

template<class T>
constexpr std::add_pointer_t<ranges::range_reference_t<T>> data(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um ponteiro, com base no tipo do intervalo, para o primeiro elemento no intervalo contíguo. Por exemplo, se o intervalo for um vetor de inteiros, o tipo do valor retornado será um int *.

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    std::string src{ "a string" };
   
    auto charPtr = std::ranges::data(src); // charPtr is a char *
    auto intPtr = std::ranges::data(v); // intPtr is an int *
    std::cout << charPtr << ", " << *intPtr << '\n'; // outputs a string, 10
    *intPtr = 100;
    *charPtr = 'A';
    std::cout << charPtr << ", " << *intPtr; // outputs A string, 100
}

empty

Teste se o intervalo está vazio.

template<class T>
constexpr bool empty(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Retorna true se o intervalo não tiver elementos; caso contrário false, .

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
        std::vector v{10,20,30};
    std::vector<int> v2;

    std::cout << std::boolalpha << std::ranges::empty(v); // outputs false
    std::cout << std::boolalpha << ", " << std::ranges::empty(v2); // outputs true
}

end

Obtenha o sentinela no final do intervalo.

template<class T>
std::sentinel_for<ranges::iterator_t<T>> auto end(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

O sentinela que vem após o último elemento no intervalo:

Imagem de um vetor com os elementos 10, 20 e 30. O primeiro elemento contém 10 e é rotulado begin(). O último elemento contém 30 e é rotulado como 'último elemento'. Uma caixa imaginária após o último elemento indica o sentinela e é rotulada como end().

Comentários

ranges::end() funciona em todos os intervalos, enquanto std::end() talvez não funcione.

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector<int> v = {10, 20, 30};
    auto i = std::ranges::end(v);
    --i; // get off the sentinel and onto the last element in the range
    std::cout << *i; // outputs 30
}

rbegin

Obtenha um iterador reverso para o primeiro elemento em um intervalo invertido. Um iterador reverso retorna os elementos do intervalo em ordem inversa. O intervalo em si não está invertido; o acesso a ele está.

template<class T>
constexpr std::input_or_output_iterator auto rbegin(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um iterador reverso para o primeiro elemento no intervalo. Esse iterador retorna os elementos do intervalo em ordem inversa, começando no final do intervalo invertido:

Figura de um vetor com os elementos 10, 20 e 30. Há uma caixa imaginária antes do elemento mais à esquerda (o elemento mais à esquerda contém o número 10) que representa o sentinela. Ele está rotulado como rend(). O primeiro elemento do vetor contém o número 10 e está rotulado como 'last element'. O elemento mais à direita no vetor contém 30 e está rotulado como rbegin().

Se o intervalo for uma matriz, retornará o equivalente de reverse_iterator{rg + n} em que n é o número de elementos na matriz. Se auto(rg.rbegin()) gerar um iterador, retornará o equivalente a auto(rg.rbegin()). Se essa expressão estiver mal formada, auto(rbegin(rg)) será usada se essa expressão produzir um iterador.

Comentários

ranges::rbegin() funciona em todos os intervalos bidirecionais, enquanto std::rbegin() talvez não funcione.

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::rbegin(v);
    std::cout << *vi << ' ' << *++vi << ' ' << *++vi; // outputs 30 20 10
}

rend

Obtenha um iterador reverso para o sentinela no final de uma exibição invertida do intervalo. Um iterador reverso retorna os elementos do intervalo em ordem inversa. O intervalo em si não está invertido; o acesso a ele está.

template<class T>
constexpr 
std::sentinel_for<decltype(ranges::rbegin(std::declval<T>()))> auto rend(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

Um iterador reverso para o sentinela no final do intervalo. O sentinela segue o último elemento em uma exibição invertida do intervalo:

Figura de um vetor com os elementos 10, 20 e 30. Há uma caixa imaginária antes do elemento mais à esquerda (o elemento mais à esquerda contém o número 10) que representa o sentinela. Ele está rotulado como rend(). O primeiro elemento do vetor contém o número 10 e está rotulado como 'last element'. O elemento mais à direita no vetor contém 30 e está rotulado como rbegin().

Comentários

ranges::rend() funciona em todos os intervalos bidirecionais, enquanto std::rend() talvez não funcione.

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto vi = std::ranges::rend(v);
    --vi; // get off the sentinel and onto the last element in the reversed range
    std::cout << *vi; // outputs 10
    std::cout << *vi << ' ' << *--vi << ' ' << *--vi; // outputs 10, 20, 30
}

size

Obtenha o número de elementos no intervalo como um valor sem sinal.

template<class T>
constexpr /*unsigned integer-like type */ size(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

O número de elementos no intervalo como um valor de tipo inteiro sem sinal.

Comentários

Essa função é executada em tempo constante.

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto s = std::ranges::size(v); // s is a size_t
    std::cout << s; // outputs 3
}

ssize

Obtenha o tamanho do intervalo como um valor com sinal.

template<class T>
constexpr /* signed-integer-like type */ ssize(T&& rg);

Parâmetros

T
O tipo do intervalo.

rg
Um intervalo.

Valor retornado

O número de elementos no intervalo como um valor de tipo inteiro com sinal.

Comentários

Essa função é executada em tempo constante.

Exemplo

// requires /std:c++20 or later
#include <vector>
#include <ranges>
#include <iostream>

int main()
{
    std::vector v{10, 20, 30};
    auto s = std::ranges::ssize(v);
    std::cout << s; // outputs 3
}

Confira também

<ranges>
O que são objetos de personalização