std::span

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

功能特性测试宏(C++20)

语言支持库

概念库(C++20)

诊断库

内存管理库

元编程库(C++11)

通用工具库

容器库

迭代器库

范围库(C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库(C++17)

并发支持库(C++11)

执行控制库(C++26)

技术规范

符号索引

外部库

 

容器库

node-handle (C++17)

序列容器

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)

容器适配器

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)

表格

迭代器失效

成员函数表格

非成员函数表格

 

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> 定义
template<     class T,     std::size_t Extent =std::dynamic_extent >class span;		(C++20 起)

类模板 span 所描述的对象可以指代对象的连续序列，序列的首元素处于位置零。span 能拥有静态 长度，此时序列中的元素数在编译期已知并在类型中编码，也可以拥有动态 长度。

对于 spans，当有操作使得范围 [s.data(), s.data()+ s.size()) 中的指针失效时，到 s 的元素的指针、迭代器和引用也会失效。

std::span 的每个特化都可平凡复制(TriviallyCopyable) 。

(C++23 起)

模板形参

T	-	元素类型；必须是完整对象类型且非抽象类
Extent	-	序列中的元素数，span 拥有动态长度时是 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) 兼老式连续迭代器(LegacyContiguousIterator) ，它的 value_type 是 value_type
const_iterator(C++23 起)	std::const_iterator<iterator>
reverse_iterator	std::reverse_iterator<iterator>
const_reverse_iterator(C++23 起)	std::reverse_iterator<const_iterator>

容器(Container) 的迭代器类型上的所有要求同样适用于 span 的 iterator 类型。

数据成员

成员	描述
constexprstd::size_t extent [静态]	Extent (公开静态成员常量)
pointerdata_	指向底层序列的指针 (仅用于阐述的成员对象*)
size_typesize_ （仅当为动态 长度时提供）	元素个数 (仅用于阐述的成员对象*)

成员函数

(构造函数)	构造 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 个元素组成的子段 (公开成员函数)
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 > constexprboolranges::enable_borrowed_range<std::span<T, Extent>>=true;		(C++20 起)

ranges::enable_borrowed_range 的此特化使得 span 满足 borrowed_range。

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

ranges::enable_view 的此特化使零或动态长度的 span 满足 view。

注解

即使在 C++23 引入正式要求前，所有既存实现中 std::span 的特化都已经是可平凡复制类型。

功能特性测试宏	值	标准	功能特性
__cpp_lib_span	202002L	(C++20)	std::span
__cpp_lib_span_at	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]]constexprauto 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>constexprbool 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>constexprbool 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>constexprbool contains(std::span<T, N> span, std::span<T, M> sub){return std::ranges::search(span, sub).begin()!= span.end();}   void println(constauto& seq){for(constauto& elem : seq)std::cout<< elem <<' ';std::cout<<'\n';}   int main(){constexprint a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};constexprint b[]{8, 7, 6};constexprstaticstd::size_t width{6};   for(std::size_t offset{};;++offset)if(auto s = slide(std::span{a}, offset, width);!s.empty()) println(s);elsebreak;   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)	只读的字符串视图 (类模板)