Classe `span` (Biblioteca Padrão C++)

Artigo
01/05/2024

Fornece uma exibição leve de uma sequência contígua de objetos. Um span fornece uma maneira segura de iterar e indexar objetos que são organizados sequencialmente na memória. Isso é semelhante a objetos armazenados em uma matriz interna, std::arrayou std::vector.

Se você normalmente acessa uma sequência de objetos sequenciais usando um ponteiro e um índice, um span será uma alternativa mais segura e leve.

O tamanho de um span pode ser definido em tempo de compilação especificando-o como um argumento de modelo ou em runtime especificando dynamic_extent.

Sintaxe

template<class T, size_t Extent = dynamic_extent>
class span;

Parâmetros de modelo

T
O tipo dos elementos no span.

Extent
O número de elementos no span se especificado em tempo de compilação. Caso contrário, std::dynamic_extent se o número de elementos for especificado em tempo de execução.

Guia de dedução

Membros

Definições de tipo	Descrição
`const_pointer`	O tipo de um ponteiro para um elemento `const`.
`const_reference`	O tipo de uma referência a um elemento `const`.
`difference_type`	O tipo de uma distância com sinal entre dois elementos.
`element_type`	O tipo de um elemento `span`.
`iterator`	O tipo de um iterador para um `span`.
`pointer`	O tipo de um ponteiro para um elemento.
`reference`	O tipo de uma referência para um elemento.
`reverse_iterator`	O tipo de um iterador reverso para um `span`.
`size_type`	O tipo para o resultado da distância sem sinal entre dois elementos no `span`.
`value_type`	O tipo de um elemento, sem as qualificações `const` ou `volatile`.
Construtor	Descrição
`span`	Construa um `span`.
Suporte ao iterador	Descrição
`begin`	Obter um iterador que aponta para o primeiro elemento no `span`.
`end`	Obter um iterador que aponta para o final do `span`.
`rbegin`	Obter um iterador reverso que aponta para o último elemento do `span`; ou seja, o início do `span` invertido.
`rend`	Obter um iterador reverso que aponta para a frente do `span`; ou seja, o final do `span` invertido.
Acessar elementos	Descrição
`back`	Obter o último elemento no `span`.
`data`	Obter o endereço do primeiro elemento no `span`.
`front`	Obter o primeiro elemento no `span`.
`operator[]`	Acessar um elemento em uma posição especificada.
Observadores	Descrição
`empty`	Testar se o `span` está vazio.
`size`	Obter o número de elementos no `span`.
`size_bytes`	Obter o tamanho do `span` em bytes.
Exibições secundárias	Descrição
`first`	Obter um intervalo secundário da frente do `span`.
`last`	Obter um intervalo secundário da parte de trás do `span`.
`subspan`	Obter um intervalo secundário de qualquer lugar no `span`.
Operadores	Descrição
`span::operator=`	Substituir o `span`.
`span::operator[]`	Obter o elemento na posição especificada.

Comentários

Todas as funções membro span têm complexidade de tempo constante.

Diferente de array ou vector, um span não é "proprietário" dos elementos dentro dele. Um span não libera nenhum armazenamento para os itens dentro dele porque não é o proprietário do armazenamento desses objetos.

Requisitos

Cabeçalho: <span> (desde C++20)

Namespace: std

Opção do compilador: /std:c++20 ou posterior é necessária.

`span::back`

Obter o último elemento no span.

constexpr reference back() const noexcept;

Valor retornado

Uma referência ao último elemento no span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    cout << mySpan.back();
}

`span::begin`

Obter um iterador que aponta para o primeiro elemento no span.

constexpr iterator begin() const noexcept;

Valor retornado

Um iterador que aponta para o primeiro elemento no span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    auto i = mySpan.begin();
    cout << *i;
}

`span::data`

Obter um ponteiro para o início dos dados span.

constexpr pointer data() const noexcept;

Valor retornado

Um ponteiro para o primeiro item armazenado no span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);
    auto i = mySpan.data();
    cout << *i;
}

`span::difference_type`

O número de elementos entre dois elementos em um span.

using difference_type = std::ptrdiff_t;

Exemplo

#include <span>
#include <iostream>

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    span<int>::difference_type distance = mySpan.end() - mySpan.begin();
    cout << distance << std::endl;
}

`span::element_type`

O tipo dos elementos no span.

using element_type = T;

Comentários

O tipo é obtido do parâmetro de modelo T quando um span é criado.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    span<int>::element_type et = mySpan[2];
    cout << et << endl;
}

`span::empty`

Se o span contém elementos.

constexpr bool empty() const noexcept;

Valor retornado

Retornará true se this->size() == 0. Caso contrário, false.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);
    bool isEmpty = mySpan.empty(); // isEmpty == false
}

`span::end`

Obter um iterador para o final do span.

constexpr iterator end() const noexcept;

Valor retornado

Um iterador que aponta para o fim do span.

Comentários

end é usado para testar se um iterador passou do fim de seu intervalo.

Não desreferencie o valor retornado por esse iterador. Use-o para identificar se o iterador foi além do último elemento no span.

Exemplo

// Iteration
for (auto it = s1.begin(); it != s1.end(); ++it)
{
    cout << *it;
}

`span::first`

Obter um intervalo secundário retirado da frente deste span.

constexpr auto first(size_type count) const noexcept;
template <size_t count> constexpr auto first() const noexcept;

Parâmetros

count
O número de elementos da frente deste span a serem colocados no intervalo secundário.
O número de elementos é especificado como um parâmetro para o modelo ou para a função, conforme ilustrado a seguir.

Valor retornado

Um span que contém elementos count da frente deste span.

Comentários

Use a versão de modelo dessa função quando possível para validar o count em tempo de compilação e preservar informações sobre o span, uma vez que ele retorna um span de extensão fixa.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    auto first2 = mySpan.first(2);
    cout << "mySpan.first(2): ";
    for (auto& i : first2)
    {
        cout << i;
    }

    cout << "\nmySpan.first<2>: ";
    auto viewSpan = mySpan.first<2>();
    for (auto& i : viewSpan)
    {
        cout << i;
    }
}

mySpan.first(2): 01
mySpan.first<2>: 01

`span::front`

Obter o primeiro elemento no span.

constexpr reference front() const noexcept;

Valor retornado

Uma referência para o primeiro elemento no span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    auto i = mySpan.front();
    cout << i;
}

`span::iterator`

O tipo de um iterator em elementos span.

using iterator = implementation-defined-iterator-type;

Comentários

Esse tipo serve como um iterator nos elementos em um span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    span<int>::iterator it = mySpan.begin();
    cout << *it++ << *it++ << *it;
}

`span::last`

Obter um intervalo secundário retirado do final deste span.

constexpr span<element_type, dynamic_extent> last(const size_type count) const noexcept;
template <size_t count> constexpr span<element_type, count> last() const noexcept;

Parâmetros

count
O número de elementos do final deste span a serem colocados no intervalo secundário. O número pode ser especificado como um parâmetro para o modelo ou para a função, conforme ilustrado a seguir.

Valor retornado

Um span que contém os últimos count elementos deste span.

Comentários

Use a versão de modelo dessa função quando possível para validar o count em tempo de compilação e preservar informações sobre o span, uma vez que ele retorna um span de extensão fixa.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    auto first2 = mySpan.last(2);
    cout << "mySpan.last(2): ";
    for (auto& i : last2)
    {
        cout << i;
    }

    cout << "\nmySpan.last<2>: ";
    auto viewSpan = mySpan.last<2>();
    for (auto& i : viewSpan)
    {
        cout << i;
    }
}

mySpan.last(2): 12
mySpan.last<2>: 12

`span::operator[]`

Obter o elemento no span em uma posição especificada.

constexpr reference operator[](size_type offset) const;

Parâmetros

offset
Elemento baseado em zero no span a ser acessado.

Valor retornado

Uma referência ao elemento na posição offset. Se a posição for inválida, o comportamento será indefinido.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);
    cout << mySpan[1];
}

`span::operator=`

Atribuir outro span a este.

constexpr span& operator=(const span& other) noexcept = default;

Parâmetros

other
O span a ser atribuído a este.

Valor retornado

*this

Comentários

A atribuição faz uma cópia superficial do ponteiro de dados e do tamanho. Uma cópia superficial é segura porque um span não aloca memória para os elementos que contém.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);
    span<int> mySpan2;
    mySpan2 = mySpan;
    for (auto &i : mySpan2)
    {
        cout << it;
    }
}

`span::pointer`

Os tipos de um ponteiro, e o ponteiro const, para um elemento span.

using pointer = T*;
using const_pointer = const T*;

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    // pointer
    span<int>::pointer ptr = &mySpan[2];
    *ptr = 9;
    cout << mySpan[2];

    // const pointer
    span<int>::const_pointer cPtr = &mySpan[0];
    // *cPtr = 9; error - const
    cout << *cPtr;
}

`span::rbegin`

Obter um iterador reverso que aponta para o último elemento deste span.

constexpr reverse_iterator rbegin() const noexcept;

Valor retornado

Um iterador que aponta para o início do span invertido.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    for (auto rIt = s1.rbegin(); rIt != s1.rend(); ++rIt)
    {
        cout << *rIt;
    }
}

`span::reference`

Os tipos de uma referência, e uma referência const, a um elemento span.

using reference = T&;
using const_reference = const T&;

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    // reference
    span<int>::reference ref = mySpan[0];
    ref = 9;
    cout << mySpan[0];
    // const reference
    span<int>::const_reference cRef = mySpan[1];
    // cRef = 9; error because const
    cout << cRef;
}

`span::rend`

Obter um iterador de acesso aleatório que aponta para além do fim do span invertido.

constexpr reverse_iterator rend() const noexcept;

Valor retornado

Um iterador invertido para o espaço reservado seguindo o último elemento no span invertido, ou seja, o espaço reservado antes do primeiro elemento no span não invertido.

Comentários

rend é usado com um span invertido, assim como span::end é usado com um span. Use-o para testar se um iterador invertido alcançou o final de seu span.

O valor retornado por rend não deve ser desreferenciado.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    for (auto rIt = s1.rbegin(); rIt != s1.rend(); ++rIt)
    {
        cout << *rIt;
    }
}

`span::reverse_iterator`

O tipo de um iterador reverso para um span.

using reverse_iterator = std::reverse_iterator<iterator>;

Exemplo

#include <span>
#include <iostream>

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    span<int>::reverse_iterator rIt = mySpan.rbegin();
    cout << *rIt++ << *rIt++ << *rIt;
}

`span::size`

Obter o número de elementos no span.

constexpr size_t size() const noexcept;

Valor retornado

O número de elementos em span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);
    cout << mySpan.size();
}

`span::size_bytes`

Obter o tamanho dos elementos no span em bytes.

constexpr size_type size_bytes() const noexcept;

Valor retornado

O número de bytes que todos os elementos em span ocupam, ou seja, sizeof(element_type) multiplicado pelo número de elementos em span.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);
    cout << mySpan.size_bytes(); // 3 elements * 4 (size of an int)
}

`span::size_type`

Um tipo sem sinal, adequado para armazenar o número de elementos em um span.

using size_type = size_t;

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    span<int>::size_type szType = mySpan.size();
    cout << szType;
}

`span::span`

Construtores span.

constexpr span() noexcept
requires (Extent == 0 || Extent == dynamic_extent) = default;

template <class It>
constexpr explicit(Extent != dynamic_extent)
span(It first, size_type count) noexcept

template <class It, class End>
constexpr explicit(Extent != dynamic_extent)
span(It first, End last) noexcept(noexcept(last - first))

template <class T, size_t N>
requires (Extent == dynamic_extent || Extent == N) && is_convertible_v<T (*)[], T (*)[]>
constexpr span(array<T, N>& arr) noexcept

template <class T, size_t N>
requires (Extent == dynamic_extent || Extent == N) && is_convertible_v<const T (*)[], T (*)[]>
constexpr span(const array<T, N>& arr) noexcept

template <size_t N>
requires (Extent == dynamic_extent || Extent == N)
constexpr span(type_identity_t<T> (&arr)[N]) noexcept

template <class R>
constexpr explicit(Extent != dynamic_extent)
span(R&& r)

// default copy ctor
constexpr span(const span& other) noexcept = default;

// converting  ctor
template <class T, size_t OtherExtent>
requires (Extent == dynamic_extent || OtherExtent == dynamic_extent ||
              Extent == OtherExtent) && is_convertible_v<T (*)[], T (*)[]>
constexpr explicit(Extent != dynamic_extent && OtherExtent == dynamic_extent)
span(const span<T, OtherExtent>& other) noexcept

Parâmetros

arr
Construir um span com base em uma matriz.

count
Número de elementos que estarão no span.

first
Iterador até o primeiro elemento no span.

last
Iterador até logo após o último elemento no span.

N
O número de elementos que estarão no span.

other
Fazer uma cópia deste span.

r
Construir um span com base no intervalo R.

Comentários

Um span não libera armazenamento para itens no span porque não é proprietário do armazenamento dos objetos dentro dele.

Construtor	Descrição
`span()`	Construir um `span` vazio. Considerado somente durante a resolução da sobrecarga quando o parâmetro de modelo `Extent` é `0` ou `dynamic_extent`.
`span(It first, size_type count)`	Construir um `span` com base nos primeiros elementos `count` do iterador `first`. Considerado somente durante a resolução da sobrecarga quando o parâmetro de modelo `Extent` não é `dynamic_extent`.
`span(It first, End last)`	Construir um `span` com base nos elementos no iterador `first` até que o final de `last` seja atingido. Considerado somente durante a resolução da sobrecarga quando o parâmetro de modelo `Extent` não é `dynamic_extent`. `It` deve ser um `contiguous_iterator`.
`span(array<T, N>& arr) noexcept;` `span(const array<T, N>& arr) noexcept;` `span(type_identity_t<element_type> (&arr)[N]) noexcept;`	Construir um `span` com base em elementos `N` da matriz especificada. Considerado somente durante a resolução da sobrecarga quando o parâmetro de modelo `Extent` ou `dynamic_extent` é igual a `N`.
`span(R&& r)`	Construir um `span` com base em um intervalo. Só participará da resolução da sobrecarga se o parâmetro de modelo `Extent` não for `dynamic_extent`.
`span(const span& other)`	O construtor de cópia gerado pelo compilador. Uma cópia superficial do ponteiro de dados é segura porque o `span` não aloca a memória para manter os elementos.
`span(const span<OtherElementType, OtherExtent>& s) noexcept;`	Construtor de conversão: construa um `span` com base em outro `span`. Só participará da resolução da sobrecarga se o parâmetro de modelo `Extent` for `dynamic_extent`, ou se `N` for `dynamic_extent` ou for igual a `Extent`.

Exemplo

#include <span>

using namespace std;

int main()
{
    const int MAX=10;

    int x[MAX];
    for (int i = 0; i < MAX; i++)
    {
        x[i] = i;
    }

    span<int, MAX> span1{ x }; // fixed-size span: compiler error if size of x doesn't match template argument MAX
    span<int> span2{ x }; // size is inferred from x
    span<const int> span3 = span2; // converting constructor
    span<int> span4( span2 ); // copy constructor
}

`span::subspan`

Obter um intervalo secundário deste span.

constexpr auto subspan(size_type offset, size_type count = dynamic_extent) const noexcept;

template <size_t offset, size_t count = dynamic_extent>
constexpr auto subspan() const noexcept

Parâmetros

count
O número de elementos a serem colocados no intervalo secundário. Se count for dynamic_extent (o valor padrão), o intervalo secundário será levado de offset até o final deste span.

offset
O local neste span no qual iniciar o intervalo secundário.

Valor retornado

Um span que começa em offset neste span. Contém elementos count.

Comentários

Há uma versão de modelo dessa função que verifica a contagem em tempo de compilação, o que preserva informações sobre o span retornando um span com extensão fixa.

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    cout << "mySpan.subspan(1,2): ";
    for (auto& i : mySpan.subspan(1,2))
    {
        cout << i;
    }
    cout << "\nmySpan.subspan<1,2>: ";
    for (auto& i : mySpan.subspan<1,2>())
    {
        cout << i;
    }
    cout << "\nmySpan.subspan<1>: ";
    for (auto& i : mySpan.subspan<1>)
    {
        cout << i;
    }
}

mySpan.subspan(1,2): 12
mySpan.subspan<1,2>: 12
mySpan.subspan<1>: 12

`span::value_type`

O tipo do elemento no span, sem as qualificações const ou volatile.

using value_type = std::remove_cv_t<T>;

Exemplo

#include <span>
#include <iostream>

using namespace std;

int main()
{
    int a[] = { 0,1,2 };
    span<int> mySpan(a);

    span<int>::value_type vType = mySpan[2];
    cout << vType;
}

Guias de dedução

Os guias de dedução a seguir são fornecidos para span.

// Allows the extent to be deduced from std::array and C++ built-in arrays

template <class T, size_t Extent>
span(T (&)[Extent]) -> span<T, Extent>;

template <class T, size_t Size>
span(array<T, Size>&) -> span<T, Size>;

template <class T, size_t Size>
span(const array<T, Size>&) -> span<const T, Size>;

// Allows the element type to be deduced from the iterator and the end of the span.
// The iterator must be contiguous

template <contiguous_iterator It, class End>
span(It, End) -> span<remove_reference_t<iter_reference_t<It>>>;

// Allows the element type to be deduced from a range.
// The range must be contiguous

template <ranges::contiguous_range Rng>
span(Rng &&) -> span<remove_reference_t<ranges::range_reference_t<Rng>>>;

Confira também

<span>
Como usar a dedução de argumento de modelo de classe

Partilhar via

Classe span (Biblioteca Padrão C++)

Sintaxe

Parâmetros de modelo

Membros

Comentários

Requisitos

span::back

Valor retornado

Exemplo

span::begin

Valor retornado

Exemplo

span::data

Valor retornado

Exemplo

span::difference_type

Exemplo

span::element_type

Comentários

Exemplo

span::empty

Valor retornado

Exemplo

span::end

Valor retornado

Comentários

Exemplo

span::first

Parâmetros

Valor retornado

Comentários

Exemplo

span::front

Valor retornado

Exemplo

span::iterator

Comentários

Exemplo

span::last

Parâmetros

Valor retornado

Comentários

Exemplo

span::operator[]

Parâmetros

Valor retornado

Exemplo

span::operator=

Parâmetros

Valor retornado

Comentários

Exemplo

span::pointer

Exemplo

span::rbegin

Valor retornado

Exemplo

span::reference

Exemplo

span::rend

Valor retornado

Comentários

Exemplo

span::reverse_iterator

Exemplo

span::size

Valor retornado

Exemplo

span::size_bytes

Valor retornado

Exemplo

span::size_type

Exemplo

span::span

Parâmetros

Comentários

Exemplo

span::subspan

Parâmetros

Classe `span` (Biblioteca Padrão C++)

`span::back`

`span::begin`

`span::data`

`span::difference_type`

`span::element_type`

`span::empty`

`span::end`

`span::first`

`span::front`

`span::iterator`

`span::last`

`span::operator[]`

`span::operator=`

`span::pointer`

`span::rbegin`

`span::reference`

`span::rend`

`span::reverse_iterator`

`span::size`

`span::size_bytes`

`span::size_type`

`span::span`

`span::subspan`

`span::value_type`