std::span

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

容器庫

序列

陣列 (C++11)

向量

vector<bool>

就地向量 (C++26)

蜂巢 (C++26)

雙端佇列

前向列表 (C++11)

列表

關聯

集合

多重集合

對映

多重對映

無序關聯

無序集合 (C++11)

無序多重集合 (C++11)

無序對映 (C++11)

無序多重對映 (C++11)

介面卡

棧

佇列

優先佇列

平面集合 (C++23)

平面多重集合 (C++23)

平面對映 (C++23)

平面多重對映 (C++23)

檢視

span (C++20)

mdspan (C++23)

表格

迭代器失效

成員函式表格

非成員函式表格

 

std::span

成員函式

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

子檢視

span::first

span::last

span::subspan

非成員函式

as_bytesas_writable_bytes

非成員常量

dynamic_extent

推導指引

 

在標頭檔案 <span> 中定義
模板<     類 T,     std::size_t Extent = std::dynamic_extent > 類 span;		(C++20 起)

類模板 span 描述了一個物件，該物件可以引用一個連續的物件序列，序列的第一個元素位於位置零。span 可以具有靜態範圍，在這種情況下，序列中的元素數量在編譯時已知並編碼在型別中，或者具有動態範圍。

對於一個 span s，當某個操作使範圍 [s.data(), s.data() + s.size()) 內的指標失效時，指向 s 元素的指標、迭代器和引用也會失效。

std::span 的每個特化都是一個 TriviallyCopyable 型別。

(C++23 起)

典型的實現持有指向 T 的指標，如果範圍是動態的，實現還會持有一個大小。

模板引數

T	-	元素型別；必須是完整的物件型別，且不是抽象類型別
Extent	-	序列中的元素數量，如果是動態的，則為 std::dynamic_extent

成員型別

成員型別	定義
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 和 contiguous_iterator，其 value_type 為 value_type
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 (public static 成員常量)

成員函式

(建構函式)	構造一個 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	檢查序列是否為空 (公共成員函式)
子檢視
first	獲取由序列前 N 個元素組成的子 span (公共成員函式)
last	獲取由序列後 N 個元素組成的子 span (公共成員函式)
subspan	獲取一個子 span (公共成員函式)

非成員函式

as_bytesas_writable_bytes (C++20)

將 `span` 轉換為其底層位元組的檢視 (函式模板)

非成員常量

dynamic_extent (C++20)

型別為 std::size_t 的常量，表示 span 具有動態範圍 (常量)

輔助模板

模板< 類 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。

模板< 類 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
	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++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
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)	只讀字串檢視 (類模板)