std::span

定義於標頭檔 `<span>`
template< class T, std::size_t Extent = std::dynamic_extent > class span;		(自 C++20 起)

類別樣板 span 描述了一個可以參照連續物件序列的物件，其中序列的第一個元素位於位置零。span 可以具有「靜態」範圍（此時序列中的元素數量在編譯時已知並編碼於型別中），或具有「動態」範圍。

對於 span s，若某項操作導致 [s.data(), s.data() + s.size()) 範圍內的指標失效，則指向 s 元素的指標、迭代器和參考也會失效。

std::span 的每個特化皆為 TriviallyCopyable（可平凡複製）型別。

(自 C++23 起)

典型的實作會持有指向 T 的指標；若範圍為動態，實作還會持有大小資訊。

成員型別	定義
`element_type`	`T`
`value_type`	std::remove_cv_t<T>
`size_type`	std::size_t
`difference_type`	std::ptrdiff_t
`pointer`	T*
`const_pointer`	const T*
`reference`	T&
`const_reference`	const T&
`iterator`	由實作定義的 LegacyRandomAccessIterator、ConstexprIterator，以及 `value_type` 為 `value_type` 的 `contiguous_iterator`
`const_iterator` (自 C++23 起)	std::const_iterator<iterator>
`reverse_iterator`	std::reverse_iterator<iterator>
`const_reverse_iterator` (自 C++23 起)	std::const_iterator<reverse_iterator>

注意：若 T 未經 const 限定，則 iterator 為可變迭代器。

針對 Container（容器）迭代器型別的所有要求，同樣適用於 span 的 iterator 型別。

[編輯] 成員常數

名稱	數值
constexpr std::size_t extent [靜態]	Extent (公開靜態成員常數)

[編輯] 成員函式

(建構子)	建構一個 `span` (公開成員函式) [編輯]
operator=	指派一個 `span` (公開成員函式) [編輯]
(解構函式) (隱式宣告)	解構一個 `span` (公開成員函式)
迭代器
begincbegin (C++23)	回傳指向起點的反覆器 (公開成員函式) [編輯]
endcend (C++23)	回傳指向終點的反覆器 (公開成員函式) [編輯]
rbegincrbegin (C++23)	回傳指向起點的反向反覆器 (公開成員函式) [編輯]
rendcrend (C++23)	回傳指向終點的反向反覆器 (公開成員函式) [編輯]
元素存取
front	存取第一個元素 (公開成員函式) [編輯]
back	存取最後一個元素 (公開成員函式) [編輯]
at (C++26)	存取指定元素，並進行邊界檢查 (公開成員函式) [編輯]
operator[]	存取指定元素 (公開成員函式) [編輯]
data	直接存取底層連續儲存空間 (公開成員函式) [編輯]
觀察器
size	回傳元素個數 (公開成員函式) [編輯]
size_bytes	回傳序列的位元組大小 (公開成員函式) [編輯]
empty	檢查序列是否為空 (公開成員函式) [編輯]
子視圖 (Subviews)
first	取得包含序列前 `N` 個元素的子區間 (公開成員函式) [編輯]
last	取得包含序列最後 `N` 個元素的子區間 (公開成員函式) [編輯]
subspan	取得一個子區間 (公開成員函式) [編輯]

[編輯] 非成員函式

as_bytesas_writable_bytes

(C++20)

將 span 轉換為其底層位元組的視圖
(函式樣板) [編輯]

[編輯] 非成員常數

dynamic_extent

(C++20)

一個型別為 std::size_t 的常數，表示該 span 具有動態範圍
(常數) [編輯]

[編輯] 輔助樣板

template< class T, std::size_t Extent > constexpr bool ranges::enable_borrowed_range<std::span<T, Extent>> = true;		(自 C++20 起)

此 ranges::enable_borrowed_range 的特化使 span 滿足 borrowed_range 要求。

template< class T, std::size_t Extent > constexpr bool ranges::enable_view<std::span<T, Extent>> = true;		(自 C++20 起)

此 ranges::enable_view 的特化使 span 滿足 view 要求。

[編輯] 推導指引

[編輯] 備註

std::span 的特化在所有現有的實作中皆已是可平凡複製的型別，即使在 C++23 引入正式要求之前亦然。

功能測試巨集	數值	標準	功能
`__cpp_lib_span`	`202002L`	(C++20)	`std::span`
`__cpp_lib_span`	`202311L`	(C++26)	std::span::at
`__cpp_lib_span_initializer_list`	`202311L`	(C++26)	從 std::initializer_list 建構 `std::span`

[編輯] 範例

此範例使用 std::span 來實作一些針對連續範圍的操作演算法。

執行此程式碼

#include <algorithm>
#include <cstddef>
#include <iostream>
#include <span>
 
template<class T, std::size_t N>
[[nodiscard]]
constexpr auto slide(std::span<T, N> s, std::size_t offset, std::size_t width)
{
    return s.subspan(offset, offset + width <= s.size() ? width : 0U);
}
 
template<class T, std::size_t N, std::size_t M>
constexpr bool starts_with(std::span<T, N> data, std::span<T, M> prefix)
{
    return data.size() >= prefix.size()
        && std::equal(prefix.begin(), prefix.end(), data.begin());
}
 
template<class T, std::size_t N, std::size_t M>
constexpr bool ends_with(std::span<T, N> data, std::span<T, M> suffix)
{
    return data.size() >= suffix.size()
        && std::equal(data.end() - suffix.size(), data.end(),
                      suffix.end() - suffix.size());
}
 
template<class T, std::size_t N, std::size_t M>
constexpr bool contains(std::span<T, N> span, std::span<T, M> sub)
{
    return std::ranges::search(span, sub).begin() != span.end();
}
 
void println(const auto& seq)
{
    for (const auto& elem : seq)
        std::cout << elem << ' ';
    std::cout << '\n';
}
 
int main()
{
    constexpr int a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};
    constexpr int b[]{8, 7, 6};
    constexpr static std::size_t width{6};
 
    for (std::size_t offset{}; ; ++offset)
        if (auto s = slide(std::span{a}, offset, width); !s.empty())
            println(s);
        else
            break;
 
    static_assert(""
        && starts_with(std::span{a}, std::span{a, 4})
        && starts_with(std::span{a + 1, 4}, std::span{a + 1, 3})
        && !starts_with(std::span{a}, std::span{b})
        && !starts_with(std::span{a, 8}, std::span{a + 1, 3})
        && ends_with(std::span{a}, std::span{a + 6, 3})
        && !ends_with(std::span{a}, std::span{a + 6, 2})
        && contains(std::span{a}, std::span{a + 1, 4})
        && !contains(std::span{a, 8}, std::span{a, 9})
    );
}

輸出

0 1 2 3 4 5
1 2 3 4 5 6
2 3 4 5 6 7
3 4 5 6 7 8

[編輯] 缺陷報告

下列更改行為的缺陷報告追溯應用於之前的 C++ 標準。

DR	應用於	出版時的行為	正確的行為
LWG 3203	C++20	指向 `span` 元素的指標、迭代器和參考何時失效並不明確	現已明確化
LWG 3903	C++20	`span` 的解構子宣告是不必要的	移除該宣告
P2325R3	C++20	非零靜態範圍的 `span` 不是 `view`	任何 `span` 皆為 `view`

[編輯] 參見

mdspan (C++23)	多維非擁有型陣列視圖 (類別樣板) [編輯]
ranges::subrange (C++20)	將一個迭代器-哨兵對結合成一個 `view` (類別範本) [編輯]
initializer_list (C++11)	引用在列表初始化中建立的暫存陣列 (類別模板) [編輯]
basic_string_view (C++17)	唯讀字串檢視 (string view) (類別樣板) [編輯]

編譯器支援
獨立式與託管式
語言
標準函式庫
標準函式庫標頭檔
具名要求
特性測試巨集 (C++20)
語言支援函式庫
概念函式庫 (C++20)
診斷函式庫
記憶體管理函式庫
元編程函式庫 (C++11)
通用公用程式函式庫
容器函式庫
疊代器函式庫
Ranges 函式庫 (C++20)
演算法函式庫
字串函式庫
文本處理函式庫
數值函式庫
日期與時間函式庫
輸入/輸出函式庫
檔案系統函式庫 (C++17)
並行支援函式庫 (C++11)
執行控制函式庫 (C++26)
技術規範
符號索引
外部函式庫

序列
array (C++11)
vector
vector<bool>
inplace_vector (C++26)
hive (C++26)
deque
forward_list (C++11)
list
關聯
set
multiset
map
multimap
無序關聯
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
適配器 (Adaptors)
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
檢視
span (C++20)
mdspan (C++23)
表格
迭代器失效
成員函式表
非成員函式表

成員函式
span::span
span::operator=
元素存取
span::front
span::back
span::at (C++26)
span::operator[]
span::data
迭代器
span::beginspan::cbegin (C++23)
span::endspan::cend (C++23)
span::rbeginspan::crbegin (C++23)
span::rendspan::crend (C++23)
觀察器
span::empty
span::size
span::size_bytes
子視圖 (Subviews)
span::first
span::last
span::subspan
非成員函式
as_bytesas_writable_bytes
非成員常數
dynamic_extent
推導指引

cppreference.com

命名空間

變體

檢視

動作