std::span

来自cppreference.com
< cpp‎ | container
 
C++
 
容器库
 
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 的指针，如果长度是动态的，那么还会保有一个长度。

模板形参

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>

注意：如果 T 没有 const 限定，那么 iterator 是可变迭代器。

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

成员常量

名称 值
constexpr std::size_t extent
[静态]
 Extent
(公开静态成员常量)

成员函数

 构造 span
(公开成员函数)
赋值 span
(公开成员函数)
(析构函数)
(隐式声明)
 析构 span
(公开成员函数)
迭代器
(C++23)
 返回指向起始的迭代器
(公开成员函数)
(C++23)
 返回指向末尾的迭代器
(公开成员函数)
(C++23)
 返回指向起始的逆向迭代器
(公开成员函数)
(C++23)
 返回指向末尾的逆向迭代器
(公开成员函数)
元素访问
访问第一个元素
(公开成员函数)
访问最后一个元素
(公开成员函数)
(C++26)
 带越界检查访问指定的元素
(公开成员函数)
访问指定的元素
(公开成员函数)
直接访问底层连续存储
(公开成员函数)
观察器
返回元素数
(公开成员函数)
返回以字节计的序列大小
(公开成员函数)
检查序列是否为空
(公开成员函数)
子视图
获得由序列前 N 个元素组成的子段
(公开成员函数)
获得由序列末 N 个元素组成的子段
(公开成员函数)
获得子段
(公开成员函数)

非成员函数

(C++20)
 转换 span 为对其底层字节的视图
(函数模板)

非成员常量

(C++20)
 std::size_t 类型的常量，指明 span 拥有动态长度
(常量)

辅助模板

template< class T, std::size_t Extent >
inline 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 >
inline constexpr bool ranges::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]] 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();
}
 
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};
 
    auto print = [](const auto &container) {
        for (const auto &element : container)
        {
            std::cout << element << " ";
        }
        std::cout << '\n';
    };
 
    // slide 函数： 切出指定大小的序列
    for (std::size_t offset{};; ++offset)
        if (auto s = slide(std::span{a}, offset, width); !s.empty())
            print(s);
        else
            break;
 
    // starts_with 前缀匹配：底层是std::equal
    // contains 底层是 std::ranges::search
    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

参阅

(C++23)
 多维非拥有数组视图
(类模板)
(C++20)
 将迭代器/哨位对结合为一个 view
(类模板)
(C++11)
 在列表初始化中创建临时数组然后引用它
(类模板)
(C++17)
 只读的字符串视图
(类模板)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/container/span&oldid=94124”