`span` class （C++標準連結庫）

發行項
01/05/2024

提供對象連續序列的輕量型檢視。 span提供一種安全的方式，以逐一查看和編製索引到記憶體中排列回溯的物件。例如儲存在內建陣列、 std::array或 std::vector中的物件。

如果您通常會使用指標和索引來存取一連串的背對背物件，則 span 是更安全、輕量型的替代方法。

可以藉由將它指定為樣板自變數，或在運行時間指定 dynamic_extent來設定的大小span。

語法

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

範本參數

T
span 中的項目類型。

Extent
如果在編譯時間指定，則為中的 span 項目數目。否則 std::dynamic_extent ，如果在運行時間指定項目數目。

扣減指南

成員

型別定義	說明
`const_pointer`	項目指標 `const` 的類型。
`const_reference`	項目的參考 `const` 型別。
`difference_type`	兩個項目之間帶正負號距離的類型。
`element_type`	專案的型 `span` 別。
`iterator`	的反覆運算器 `span`型別。
`pointer`	項目的指標類型。
`reference`	項目的參考類型。
`reverse_iterator`	的 `span`反向反覆運算器型別。
`size_type`	中兩個項目之間不帶正負號距離之結果的 `span`型別。
`value_type`	項目的類型，不含 `const` 或 `volatile` 限定性。
建構函式	說明
`span`	`span`建構。
Iterator 支援	說明
`begin`	取得指向中第一個專案的 `span`反覆運算器。
`end`	取得指向結尾的 `span`反覆運算器。
`rbegin`	取得指向之最後一個專案的 `span`反向反覆運算器，也就是反轉 `span`的開頭。
`rend`	取得指向前端的 `span`反向反覆運算器，也就是反轉 `span`的結尾。
Access 元素	說明
`back`	取得中的 `span`最後一個專案。
`data`	取得中第一個項目的 `span`位址。
`front`	取得中的 `span`第一個專案。
`operator[]`	存取位於指定位置的專案。
觀察員	說明
`empty`	測試是否 `span` 為空白。
`size`	取得中的 `span`項目數目。
`size_bytes`	取得位元組大小 `span` 。
子檢視	說明
`first`	從前面 `span`取得子窗格。
`last`	從的後面 `span`取得子窗格。
`subspan`	從中的任何 `span`位置取得子窗格。
運算子	說明
`span::operator=`	`span`取代。
`span::operator[]`	取得位於指定位置的專案。

備註

所有 span 成員函式都有常數時間複雜度。

與或 vector不同array，不會span「擁有」其中的專案。 span不會釋放其內專案的任何儲存空間，因為它不會擁有這些對象的記憶體。

需求

標頭： <span> （自C++20起）

命名空間：std

需要編譯程式選項：/std:c++20或更新版本。

`span::back`

取得中的 span最後一個專案。

constexpr reference back() const noexcept;

傳回值

中最後一個項目的 span參考。

範例

#include <span>
#include <iostream>

using namespace std;

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

    cout << mySpan.back();
}

`span::begin`

取得指向中第一個專案的 span反覆運算器。

constexpr iterator begin() const noexcept;

傳回值

指向中第一個專案的 span反覆運算器。

範例

#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`

取得數據開頭的 span 指標。

constexpr pointer data() const noexcept;

傳回值

儲存在第一個專案的 span指標。

範例

#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`

中兩個專案 span之間的項目數目。

using difference_type = std::ptrdiff_t;

範例

#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`

span 中的項目類型。

using element_type = T;

備註

建立時span，型別會取自樣板參數T。

範例

#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`

是否 span 包含專案。

constexpr bool empty() const noexcept;

傳回值

如果 this->size() == 0傳true回。否則 false為。

範例

#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`

取得反覆運算器到的 span結尾。

constexpr iterator end() const noexcept;

傳回值

指向結尾 span之外的反覆運算器。

備註

end 用來測試迭代器是否已超過其範圍結尾。

請勿取值這個反覆運算器所傳回的值。使用它來識別反覆運算器是否已超過中的 span最後一個專案。

範例

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

`span::first`

取得子窗格，取自這個 span的前面。

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

參數

count
要放入子窗格的這個 span 前面的項目數目。
元素數目會指定為範本的參數，或指定為函式，如下所示。

傳回值

span，包含count這個 span前面的專案。

備註

如果可能的話，請使用此函式的範本版本，在編譯時期驗證 count ，並保留自傳回span固定範圍以來的相關信息span。

範例

#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`

取得中的 span第一個專案。

constexpr reference front() const noexcept;

傳回值

中第一個項目的 span參考。

範例

#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`

over span 專案的型iterator別。

using iterator = implementation-defined-iterator-type;

備註

這個型別在中的span項目上做為 iterator 。

範例

#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`

取得子範圍，取自這個 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;

參數

count
要放入子窗格的結尾 span 元素數目。數位可以指定為範本的參數或函式，如下所示。

傳回值

span，包含這個 span中的最後一count個專案。

備註

如果可能的話，請使用此函式的範本版本，在編譯時期驗證 count ，並保留自傳回span固定範圍以來的相關信息span。

範例

#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[]`

取得位於 span 指定位置的專案。

constexpr reference operator[](size_type offset) const;

參數

offset
要存取的 span 中以零起始的專案。

傳回值

位於之 offset項目的參考。如果位置無效，則行為未定義。

範例

#include <span>
#include <iostream>

using namespace std;

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

`span::operator=`

將另一個 span 指派給這個。

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

參數

other
span要指定這個的。

傳回值

*this

備註

指派會執行數據指標和大小的淺層複本。淺層複本是安全的，因為 span 不會為其所包含的專案配置記憶體。

範例

#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`

項目指標和 const 指標的類型 span 。

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

範例

#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`

取得指向這個 span最後一個專案的反向反覆運算器。

constexpr reverse_iterator rbegin() const noexcept;

傳回值

指向反轉 span之開頭的反覆運算器。

範例

#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`

項目的參考型別和 const 參考 span 。

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

範例

#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`

取得隨機存取反覆運算器，指向反轉 span的結尾以外。

constexpr reverse_iterator rend() const noexcept;

傳回值

反轉中最後一個元素 span後面的佔位元反轉反覆運算器，也就是未反 span轉的第一個專案之前佔位元。

備註

rend與反轉span搭配使用，就像搭配使用一span樣span::end。使用它來測試反向反覆運算器是否已到達其 span結尾。

所 rend 傳回的值不應該取值。

範例

#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`

的 span反向反覆運算器型別。

using reverse_iterator = std::reverse_iterator<iterator>;

範例

#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`

取得中的 span項目數目。

constexpr size_t size() const noexcept;

傳回值

span 中的項目數。

範例

#include <span>
#include <iostream>

using namespace std;

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

`span::size_bytes`

取得以位元組為單位的專案 span 大小。

constexpr size_type size_bytes() const noexcept;

傳回值

佔用中所有元素 span 的位元元組數， sizeof(element_type) 也就是乘以中的 span項目數目。

範例

#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`

不帶正負號的類型，適合將項目數目儲存在中 span。

using size_type = size_t;

範例

#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`

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

參數

arr
span從數組建建構。

count
將位於中的 span項目數目。

first
反覆運算器至中的 span第一個專案。

last
反覆運算器要剛好超過中的 span最後一個專案。

N
將位於中的 span項目數目。

other
製作這個 span的複本。

r
span從範圍 R建構。

備註

span不會釋放中span專案的儲存空間，因為它不會擁有其中對象的儲存空間。

建構函式	描述
`span()`	建構空 `span`的。只有在樣板參數 `Extent` 為 `0` 或 `dynamic_extent`時，才會在多載解析期間考慮。
`span(It first, size_type count)`	`span`從反覆運算器 `first`的第一個項目`count`建構。只有在範本參數 `Extent` 不是 `dynamic_extent`時，才會在多載解析期間考慮。
`span(It first, End last)`	`span`從反覆運算器`first`中的專案建構，直到到達結尾`last`為止。只有在範本參數 `Extent` 不是 `dynamic_extent`時，才會在多載解析期間考慮。 `It` 必須是 `contiguous_iterator`。
`span(array<T, N>& arr) noexcept;` `span(const array<T, N>& arr) noexcept;` `span(type_identity_t<element_type> (&arr)[N]) noexcept;`	`span`從`N`指定陣列的項目建構。只有在樣板參數 `Extent` 為 `dynamic_extent` 或等於 `N`時，才會在多載解析期間考慮。
`span(R&& r)`	`span`從範圍建構。只有在範本參數 `Extent` 不是 `dynamic_extent`時，才會參與多載解析。
`span(const span& other)`	編譯程式產生的複製建構函式。數據指標的淺層複本是安全的，因為 `span` 不會配置記憶體來保存元素。
`span(const span<OtherElementType, OtherExtent>& s) noexcept;`	轉換建構函式：從另一個 `span` `span`建構。只有在樣板參數 `Extent` 為 `dynamic_extent`或 `N` 等於 `dynamic_extent` `Extent`時，才會參與多載解析。

範例

#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`

取得這個 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

參數

count
要放入子範圍中的項目數目。如果 count 是 dynamic_extent （預設值），則子範圍會從到 offset 這個 span的結尾。

offset
要啟動子窗格的這個 span 位置。

傳回值

span從offset這個 span開始的。包含 count 專案。

備註

此函式的範本版本可在編譯時間檢查計數，藉由傳回span固定範圍來保留相關信息span。

範例

#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`

中 span專案的型別，不含 const 或 volatile 限定性。

using value_type = std::remove_cv_t<T>;

範例

#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;
}

扣減指南

提供下列扣減指南 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>>>;

另請參閱

<span>
如何使用類別範本自變數推算

共用方式為

span class （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

參數