Skip to main content

Chapter 44: Span

核心问题与阅读主线

本章导读5 个核心小节 · 附自检与总结

C++20 std::span(头文件 <span>,见 cppreference 的 std::span 页面)将“起始地址 + 元素个数”封装为轻量级非拥有连续内存视图,解决裸指针与长度分离易错、容器引用又将接口锁死在单一存储类型上的问题。全章围绕函数边界选型与底层存储生命周期风险展开。

全章共用场景样本

贯穿材料贯穿场景

本章的贯穿材料是一个音频样本处理场景:调用方可能将样本存放在 std::vector<float>、std::array<float, N> 或 C 接口给出的 float* 缓冲区中,而处理函数只关心一段连续 float——std::span<float> 表示可修改视图,std::span<const float> 表示只读视图,底层内存所有权始终留在调用方。

44.1 non-owning contiguous memory view​

std::span<T, Extent> 是面向连续内存的非拥有视图,核心语义如下:

  • 视图接口:通过 data()、size()、迭代器和 operator[] 暴露已有元素区间。
  • 非拥有语义:不分配内存,也不构造或销毁元素,底层对象的生命周期完全由外部持有者管理。
  • 连续性要求:要求元素落在单段连续地址区间内;std::vector、std::array 和原生数组满足该模型,std::list、std::forward_list 等节点容器不能直接构造 span。
#include <algorithm>
#include <array>
#include <cstddef>
#include <span>
#include <vector>

void clamp_samples(std::span<float> samples)
{
for (float& sample : samples) {
sample = std::clamp(sample, -1.0f, 1.0f);
}
}

float peak_value(std::span<const float> samples)
{
float peak = 0.0f;
for (float sample : samples) {
peak = std::max(peak, sample < 0.0f ? -sample : sample);
}
return peak;
}

int main()
{
std::vector<float> frame{-1.2f, 0.1f, 0.8f, 1.4f};
std::array<float, 4> fixed{-0.5f, 0.2f, 0.9f, 1.1f};
float c_buffer[4]{0.3f, -0.7f, 1.6f, 0.0f};

clamp_samples(std::span<float>{frame});
clamp_samples(std::span<float>{fixed});
clamp_samples(std::span<float>{c_buffer});
clamp_samples(std::span<float>{c_buffer, 4});

float peak = peak_value(std::span<const float>{frame});
(void)peak;
}

边界与误区

注意

const 必须写在元素类型上:std::span<const float> 才表达只读元素(如 peak_value);const std::span<float> 仅禁止视图对象自身重新绑定,仍可通过它修改底层数据。

关键事实

动态长度 span 常见实现为“指针 + 长度”,静态长度 span 通常仅保存指针,且 C++23 起所有 std::span 特化被要求为 trivially copyable。因此 span 应按值传参——复制 span 只复制视图状态,不复制底层元素。

44.2 dynamic extent 与 static extent​

std::span<T, Extent> 的第二个模板参数决定长度保存位置:std::span<T> 等价于 std::span<T, std::dynamic_extent>,而 std::span<T, N> 将编译期常量长度 N 编码进类型本身。

维度动态长度 std::span<T>静态长度 std::span<T, N>
模板参数默认 std::dynamic_extent显式指定编译期常量 N
长度位置保存在视图对象状态中(运行期 size())编入类型,不占对象运行期长度字段
检查时机运行期通过 size() 校验边界或拒空编译期参与类型检查、重载与概念约束
转换规则可由静态 span 隐式转换而来须显式构造或切片(如 first<N>())
典型场景音频帧、文件内容、网络包、C 缓冲区协议头、固定块、SIMD 块、固定维小数组

设备或解码器输出的音频帧长度随配置变化,入口适合接收动态长度 std::span<float>;长度固定为 2 的立体声帧则适合用 std::span<float, 2> 将契约写入签名:

#include <algorithm>
#include <array>
#include <span>

void apply_gain(std::span<float> samples, float gain)
{
for (float& sample : samples) {
sample *= gain;
}
}

void normalize_stereo_frame(std::span<float, 2> left_right)
{
float peak = std::max(left_right[0] < 0.0f ? -left_right[0] : left_right[0],
left_right[1] < 0.0f ? -left_right[1] : left_right[1]);
if (peak > 1.0f) {
left_right[0] /= peak;
left_right[1] /= peak;
}
}

int main()
{
std::array<float, 2> stereo{1.4f, -0.7f};
normalize_stereo_frame(std::span<float, 2>{stereo});
}

边界与误区

注意

std::span<float, 2> 与 std::span<float> 是不同类型,且静态长度不等于拥有数组——std::span<float, 2> 仍是视图,底层元素可来自 std::array<float, 2>、原生数组或更大缓冲区的子区间,不接管生命周期。选型关键在于:长度错误若属违反协议用静态长度,长度随数据变化用动态长度。

44.3 与 vector、array、raw pointer 的关系​

函数参数选型应在所有权、长度位置、连续性、元素可变性与底层变更影响五个维度上划清边界:

参数 / 对象形态所有权长度信息连续性典型接口职责底层变更影响
std::vector<T>&拥有动态元素与容量size() / capacity()连续需要 push_back、resize、reserve 等容器管理扩容重分配会使已有视图和指针失效
std::array<T, N>&拥有固定数量元素N 在拥有者类型中连续要求对象自身具有固定布局(如 16 字节头、4 通道色值)对象存活期内存地址稳定
T*(配长度)无(仅地址)需额外参数或约定调用方保证C API、系统调用、硬件 DMA、可空语义或旧 ABI 边界由调用方自行保障,无类型级边界绑定
std::span<T>无(非拥有视图)size() 随视图传递要求连续只读或原地修改已有连续元素,脱离具体容器类型仅在外部存储存活且未重分配时有效

下面两个签名将“容器管理”与“范围处理”拆开,调用方一眼即可分辨函数是否会改动容器长度:

#include <cstddef>
#include <span>
#include <vector>

void append_silence(std::vector<float>& samples, std::size_t count)
{
samples.insert(samples.end(), count, 0.0f);
}

void scale_in_place(std::span<float> samples, float factor)
{
for (float& sample : samples) {
sample *= factor;
}
}

注意 std::array<T, N>& 要求实参本身是 std::array 对象,而 std::span<T, N> 只约束“长度为 N 的连续窗口”,可兼容原生数组与大缓冲区的子切片。面对 C 接口或硬件 DMA,应在边界层立即把 T* 与长度封装为 span:

#include <cstddef>
#include <span>

extern "C" void read_samples(float* buffer, std::size_t count);
void clamp_samples(std::span<float> samples);

void process_from_c_api(float* buffer, std::size_t count)
{
if (buffer == nullptr && count > 0) {
return;
}
read_samples(buffer, count);
std::span<float> samples{buffer, count};
clamp_samples(samples);
}

核心判断

只在需要增删元素或管理容量时接收 std::vector<T>&,只在要求固定布局拥有者时接收 std::array<T, N>&;raw pointer 应压缩在 C/ABI 最外层边界,C++ 内部逻辑统一通过 span 接收连续范围。

44.4 生命周期问题​

span 的生命周期判断分为两层:span 对象自身与底层存储所有者。复制、传递或返回 span 只拷贝视图状态,绝不延长底层元素寿命;常见悬垂风险集中在三类场景。

风险一:绑定局部对象或临时容器​

局部 vector 在函数返回时析构(同理,用临时右值容器构造的 std::span<const float> 在语句结束后立即悬垂),返回的 span 只剩失效地址与旧长度:

#include <span>
#include <vector>

std::span<float> make_bad_samples()
{
std::vector<float> local{0.1f, 0.2f, 0.3f};
return std::span<float>{local};
}

风险二:vector 扩容触发重分配​

vector::push_back、reserve、resize 可能改变底层数组地址,导致此前绑定的 span 仍指向旧内存;std::array 与原生数组虽无重分配问题,但仍受作用域结束、越界窗口与外部释放约束:

#include <span>
#include <vector>

void reallocation_risk()
{
std::vector<float> samples{0.1f, 0.2f, 0.3f};
std::span<float> view{samples};

samples.push_back(0.4f);

// view 的可用性取决于 push_back 是否使 samples 重新分配。
// 工程代码应在容量改变后重新创建 view。
view = std::span<float>{samples};
}

风险三:类成员长期持有 span​

把 span 存进类成员意味着对象退化为外部存储的观察者,只适合生命周期严格短于外部所有者的临时分析窗口或解析上下文;异步任务、缓存项或跨线程载体应改存 std::vector、std::array 等拥有式对象:

#include <span>

class SampleWindow {
public:
explicit SampleWindow(std::span<const float> samples)
: samples_(samples)
{
}

float first() const
{
return samples_.empty() ? 0.0f : samples_[0];
}

private:
std::span<const float> samples_;
};

关键事实

C++20 Ranges 中 std::span 同时满足 view 与 borrowed_range。这只说明迭代器可以脱离 span 对象继续访问同一段存储,并不延长底层元素的生命周期。

排查顺序

  1. 定位所有者:确认底层元素由哪个容器、数组、内存池或外部系统持有。
  2. 核对覆盖期:确认所有者生命周期完整覆盖 span 及其派生视图的全部使用区间。
  3. 检查失效操作:确认期间未发生 push_back、resize、reserve 或外部释放;一旦改变容量或存储,立即丢弃旧视图并重新构造 span。

44.5 工程使用场景​

在音频帧、图像像素、网络包和序列化缓冲区的处理链路上,span 常见于三类工程用法。

字节视图与读写隔离​

std::span<const std::byte> 表达只读字节序列,用于校验、哈希与解析;std::span<std::byte> 表达可写缓冲区,用于填充、编码、解密和原地清零:

#include <cstddef>
#include <cstdint>
#include <span>

std::uint32_t checksum(std::span<const std::byte> bytes)
{
std::uint32_t value = 0;
for (std::byte byte : bytes) {
value = value * 131u + static_cast<unsigned char>(byte);
}
return value;
}

void zero_fill(std::span<std::byte> bytes)
{
for (std::byte& byte : bytes) {
byte = std::byte{0};
}
}

零拷贝切片​

first、last 与 subspan 从大缓冲区派生子视图,只调整起址与长度,不分配内存也不复制元素,适合协议解析逐段推进:

#include <cstddef>
#include <span>

struct PacketParts {
std::span<const std::byte> header;
std::span<const std::byte> payload;
};

PacketParts split_packet(std::span<const std::byte> packet)
{
constexpr std::size_t header_size = 8;
if (packet.size() < header_size) {
return {packet, {}};
}
return {packet.first(header_size), packet.subspan(header_size)};
}

边界与误区

注意

first(n)、last(n) 与 subspan(offset, count) 越界不会抛出异常,若 n 或 offset 超过 size() 属于未定义行为,切片前必须显式检查 size()。同时 PacketParts 仍引用原 packet 存储,长期保留结果须拷贝为拥有式对象。

C 接口边界与五步选型检查​

面对仍使用 void*、char*、std::byte* 或 T* 加长度的外部 C 接口,应在 C++ 入口处集中完成空指针检查及字节数与元素数的换算,并构造 span 交给下游算法。

落地一个新接口前,按以下五步依次检查:

  1. 所有权与尺寸变化:需拥有数据或增删元素时选拥有式容器引用或返回值,不选 span。
  2. 连续性:确认底层内存单段连续后再考虑 span。
  3. 可变性:只读用 std::span<const T>,原地修改用 std::span<T>。
  4. 长度约束:运行期变长用动态 span,编译期协议契约考虑静态 std::span<T, N>。
  5. 生命周期边界:跨越所有者作用域或发生容量变更后,必须重新建立 span。

最小自检任务​

动手自检先独立判断

阅读下面代码,分别判断 sum_prefix、view_after_resize 与 stored_window 三个位置的 span 行为:说明底层所有者、长度来源、可能导致视图失效的操作,以及只读/可写签名的合理性。

#include <array>
#include <span>
#include <vector>

float sum_prefix(std::span<const float> samples)
{
float total = 0.0f;
for (float sample : samples.first(2)) {
total += sample;
}
return total;
}

struct StoredWindow {
std::span<const float> view;
};

void demo()
{
std::vector<float> dynamic{1.0f, 2.0f, 3.0f};
std::array<float, 3> fixed{4.0f, 5.0f, 6.0f};

float a = sum_prefix(std::span<const float>{dynamic});
float b = sum_prefix(std::span<const float>{fixed});

std::span<float> view_after_resize{dynamic};
dynamic.push_back(4.0f);

StoredWindow stored_window{std::span<const float>{dynamic}};
(void)a;
(void)b;
(void)view_after_resize;
(void)stored_window;
}

本章知识点总结​

  • 非拥有连续视图

    std::span<T, Extent> 仅记录连续存储的起址与元素个数,不分配、构造或销毁元素,std::list 等节点容器无法构造 span。

  • 只读与按值传参

    std::span<const T> 限制元素只读,const std::span<T> 仅禁视图自身重绑定;span 轻量且 C++23 起要求 trivially copyable,参数应按值传递。

  • 动态与静态长度

    std::span<T> 在运行期保存 size(),适合变长数据与 C 缓冲区;std::span<T, N> 将协议长度编入类型,但同样不拥有底层数组。

  • 接口边界分工

    管理容量或增删元素用 std::vector<T>&,固定布局拥有者用 std::array<T, N>&,C ABI 的 T* 加长度在边界层尽早转为 span。

  • 零拷贝切片前置条件

    first、last、subspan 派生共享原存储的子视图而不复制元素,但越界属于未定义行为,切片前须校验 size()。

  • 悬垂与扩容失效

    严禁返回指向局部或临时容器的 span;容器发生 push_back、resize、reserve 等操作后必须抛弃旧视图并重建 span。

  • 成员保存与五步选型

    类成员保存 span 仅适用于生命周期短于外部存储的临时观察者;工程选型依次核对所有权、连续性、可变性、长度约束与失效边界。