CppCoreGuidelines 之 Guidelines Support Library（GSL）入门：gsl::span 与窄化转换实战指南

CppCoreGuidelines 之 Guidelines Support Library（GSL）入门：gsl::span 与窄化转换实战指南

【免费下载链接】CppCoreGuidelinesThe C++ Core Guidelines are a set of tried-and-true guidelines, rules, and best practices about coding in C++项目地址: https://gitcode.com/gh_mirrors/cp/CppCoreGuidelines

本文以 CppCoreGuidelines 仓库中 Herb Sutter 撰写的 docs/gsl-intro.md 为骨架，结合 CppCoreGuidelines.md 正文中的 GSL 章节与相关规则，系统讲解 C++ Core Guidelines 配套支持库 GSL 的核心组件：无所有权、自带边界检查的gsl::span视图类型，以及narrow/narrow_cast等窄化转换工具。读完本文，你将掌握如何用span替换易出错的(指针, 长度)参数对、如何通过span<const T>表达只读语义、如何切分子区间、如何与 STL 算法互操作，以及何时使用byte、narrow与narrow_cast，并理解这些设施与标准库std::span的渊源。

一、背景：GSL 是什么，为什么要用

GSL（Guidelines Support Library，准则支持库）是 CppCoreGuidelines.md 的配套支持库，用来落实 C++ Core Guidelines 中的核心建议。CppCoreGuidelines 正文指出："The GSL is a small library of facilities designed to support this set of guidelines. Without these facilities, the guidelines would have to be far more restrictive on language details."（GSL: Guidelines support library），也就是说，没有这套设施，准则将不得不在语言细节上做出更多限制。

在正式动手之前，需要先明确 GSL 的定位与使用方法：

• 先选准则，再引入 GSL：如 docs/gsl-intro.md 所述，先阅读 CppCore Guidelines 正文，挑选一组你想要采纳的准则，再按这些准则的指引引入 GSL 中对应的组件，而不是把整个 GSL 一次性倒入代码。
• 配套参考实现：文档中的示例可以在主流编译器和平台上通过微软的 GSL 参考实现（github.com/microsoft/gsl）实际编译运行。
• GSL 是纯头文件库：CppCore Guidelines 正文明确说明 GSL "is header only"（GSL: Guidelines support library），只需将头文件加入包含路径即可使用，无需链接库文件。
• 命名空间与设计原则：所有组件定义在gsl命名空间内，很多名字可能是标准库或其他知名库名称的别名；通过gsl命名空间的（编译期）间接层，便于实验和局部变体。这些设施被设计为极其轻量（零开销），与使用传统替代方案相比不引入额外负担，必要时可以被"插桩"（如增加检查）用于调试（GSL: Guidelines support library）。

GSL 在 CppCore Guidelines 正文中的完整组件清单如下（GSL: Guidelines support library）：

• GSL.view：视图（span、span_p、owner、not_null等）
• GSL.owner：所有权指针（unique_ptr、shared_ptr、stack_array、dyn_array等）
• GSL.assert：断言（Expects、Ensures）
• GSL.util：工具（finally、narrow_cast、narrow、joining_thread、index等）
• GSL.concept：概念（类型谓词）

其中，本文主角span位于 GSL.view 部分。正文对它的定义是："Aspan<T>refers to zero or more mutableTs unlessTis aconsttype. All accesses to elements of the span, notably viaoperator[], are guaranteed to be bounds-checked by default."（GSL.view 组件清单）——即span<T>引用零个或多个可变的T（除非T是const类型），并且对元素的所有访问（尤其是operator[]）默认保证进行边界检查。这正是span相对裸指针的核心价值所在。

二、gsl::span 是什么

2.1 核心概念

gsl::span是对(pointer, length)这种"指针 + 长度"二元组的替代品，用于引用一段连续对象序列。它本质上是一个"知道自身边界的指向数组的指针"。

例如，span<int, 7>引用的是七个连续整数构成的序列。

两个关键性质必须牢记：

• 不拥有元素：span不拥有它所指向的元素，它不是一个像array或vector那样的容器，而是这类容器内容的视图（view）。
• 零开销：正文 F.24 指出，span<T>对象不拥有其元素且足够小，可以按值传递；"Passing aspanobject as an argument is exactly as efficient as passing a pair of pointer arguments or passing a pointer and an integer count."——按值传递一个span与传递一对指针参数或"指针 + 整数计数"在效率上完全一致。

2.2 与 std::span 的关系

值得说明的是，GSL 的span（最初名为array_view）曾被提议纳入 C++ 标准库，最终以改名和调整接口的形式被采纳为std::span，唯一的例外是标准版不提供保证的边界检查。因此 GSL 的span改名并调整接口以追踪std::span，两者应完全相同，唯一区别是 GSL 的span默认完全边界安全（bounds-safe）；若未来std::span增加了边界检查，gsl::span甚至可以被移除（GSL.view 组件清单的 Note）。这解释了为什么gsl::span的接口与std::span高度一致，但访问带检查。

三、参数设计：用 span 替换（ptr, length）

3.1 传统（指针, 长度）参数的危害

CppCore Guidelines 的 F.24 指出：非形式化/隐式的范围是错误之源。给定一对参数(p, n)表示数组[p:p+n)，通常根本无法知道*p之后是否真的有n个元素可访问。

docs/gsl-intro.md 给出了一个典型的危险示例：

// Error-prone: Process n contiguous ints starting at *p void dangerous_process_ints(const int* p, size_t n);

这个接口极难被正确使用，很容易写出越界访问：

int a[100]; dangerous_process_ints(a, 1000); // oops: buffer overflow vector<int> v(200); dangerous_process_ints(v.data(), 1000); // oops: buffer overflow auto remainder = find(v.begin(), v.end(), some_value); // now call dangerous_process_ints() to fill the rest of the container from *remainder to the end dangerous_process_ints(&*remainder, v.end() - remainder); // correct but convoluted

问题显而易见：长度参数与容器实际大小完全脱节，调用者需要手工维护指针和长度的配对关系，一旦写错就是缓冲区溢出或未定义行为。

3.2 用 span 封装指针与长度

改用span之后，指针与长度被封装为一个对象：

// BETTER: Read s.size() contiguous ints starting at s[0] void process_ints(span<const int> s);

这使得process_ints更容易被正确使用，因为span可以方便地从常见类型推导出长度：

int a[100]; process_ints(a); // deduces correct length: 100 (constructs the span from a container) vector<int> v(200); process_ints(v); // deduces correct length: 200 (constructs the span from a container)

当调用代码确实持有分离的指针和长度参数时，span也支持现代 C++ 的参数初始化语法：

auto remainder = find(v.begin(), v.end(), some_value); // now call process_ints() to fill the rest of the container from *remainder to the end process_ints({remainder, v.end()}); // correct and clear (constructs the span from an iterator pair)

这里{remainder, v.end()}利用花括号初始化从迭代器对构造span。从实现角度看，span的构造来源包括：{p, q}（两个指针/迭代器）和{p, n}（指针 + 个数）（GSL.view 组件清单），容器与数组则通过隐式构造自动推导。

要点记忆：

• 优先使用span而非(指针, 长度)对；
• 像传指针一样传递span（即"入参"按值传递），把它当作指针区间对待。

正文 F.24 还给出了相应的静态检查建议：(Complex) 当发现某个指针参数的访问受另一个整数类型参数约束时，发出警告并建议改用span——这正是dangerous_process_ints(const int* p, size_t n)这类签名可被工具自动识别的模式。

3.3 数组参数场景：R.14 与 ES.85

在 CppCore Guidelines 中，span还被反复推荐用于替换"裸数组参数"：

• 规则 R.14: Avoid[]parameters, preferspan：数组在作为参数传递时容易退化为指针并丢失大小信息，"Usespanto preserve size information"，推荐的写法是void f(gsl::span<int>); // good, recommended，并建议对[]参数进行标记。
• 规则 ES.85（访问数组元素时使用span）也强调："Usegsl::spaninstead"——span是访问数组数据时带边界检查的安全类型（ES.85 相关段落），例如将void f(int a[], int pos)改为void f1(span<int, 10> a, int pos)，或增加局部spanspan<int> a = {arr.data(), pos};（ES.85 修复示例）。

四、const 语义：span<const T> 与 const span<T>

这两个写法的含义截然不同，务必区分：

• span<const T>：表示T对象是只读的。如果不修改T，默认（尤其是作为参数时）优先使用它。
• const span<T>：表示span本身不能被改为指向不同的目标（即指针部分不可重新绑定），但所指向的T仍然可修改。
• const span<const T>：两者兼具——既不能换目标，内容也只读。

要点记忆：除非确实需要读写访问，否则默认优先使用span<const T>来表达"内容只读"。

这与 C++ 惯例（如const std::string&参数）一脉相承，也是 GSL 接口设计上"用类型表达意图"的体现：span<const T>在调用侧就能显式声明只读契约，同时允许从vector<T>、const vector<T>、数组等不同来源隐式构造。

五、遍历：range-for 与 begin/end

span是一个封装好的区间（range），因此可以直接用基于范围的for循环访问。

对比两种写法。使用(指针, 长度)对时，遍历每个对象需要显式维护索引：

void dangerous_process_ints(int* p, size_t n) { for (auto i = 0; i < n; ++i) { p[i] = next_character(); } }

使用span时可以直接 range-for，注意这是零开销的，且不需要执行任何范围检查——因为 range-for 循环在构造上就保证不会超出区间的边界：

void process_ints(span<int> s) { for (auto& c : s) { c = next_character(); } }

span也支持使用.begin()和.end()进行普通迭代。正文 F.24 展示了同一函数的多种遍历方式，可对照参考：

void f(span<int> s) { // range traversal (guaranteed correct) for (int x : s) cout << x << '\n'; // C-style traversal (potentially checked) for (gsl::index i = 0; i < s.size(); ++i) cout << s[i] << '\n'; // random access (potentially checked) s[7] = 9; // extract pointers (potentially checked) std::sort(&s[0], &s[s.size() / 2]); }

这里gsl::index是 GSL.util 中用于所有容器和数组索引的类型（当前是ptrdiff_t的别名）（GSL.util: Utilities）。

遍历时还需要注意两条迭代器规则：

• 不能比较来自不同span的迭代器，即使它们引用同一个数组；
• 迭代器只在它所遍历的span存活期间有效（与std::vector迭代器失效语义类似，span本身销毁后迭代器即失效）。

六、元素访问与子区间

6.1 单元素访问

使用myspan[offset]进行下标访问，或等价地使用iter + offset（其中iter是span<T>::iterator）。两者都是带范围检查的——这是gsl::span与std::span的关键差异，也是 GSL 版本默认开启边界安全的体现。

6.2 子区间：first / last / subspan

需要引用span的子区间时，使用first、last或subspan：

void process_ints(span<widget> s) { if (s.length() > 10) { read_header(s.first(10)); // first 10 entries read_rest(s.subspan(10)); // remaining entries // ... } }

在较少见的情况下，如果你在编译期就知道子区间的元素个数，并且希望span支持constexpr使用，可以把子区间长度作为模板实参传入：

constexpr int process_ints(span<widget> s) { if (s.length() > 10) { read_header(s.first<10>()); // first 10 entries read_rest(s.subspan<10>()); // remaining entries // ... } return s.size(); }

注意s.first<10>()与s.first(10)的差别：前者把长度编码进类型（编译期已知），从而支持constexpr上下文；后者在运行期确定。正文在 F.24 中也有用迭代器对构造span的类似示例：find({vec.begin(), vec.end()}, X{})，说明span的构造与子区间操作共同构成完整的"范围切分"工具集。

七、与 STL 算法互操作

7.1 传给 [begin, end) 风格接口

span像任何 STL 区间一样可迭代，要调用 STL 的[begin,end)风格接口，默认使用begin和end，如果你不想传整个区间，也可以传其他合法迭代器：

void f(span<widget> s) { // ... auto found = find_if(s.begin(), s.end(), some_value); // ... }

7.2 传给 range 风格算法

如果使用基于范围的算法库（如 Range-V3），可以直接把span当作 range 传入：

void f(span<widget> s) { // ... auto found = find_if(s, some_value); // ... }

这得益于span完整实现了"可迭代区间"所需的接口（begin/end），可以无缝适配 STL 与 range 两类算法生态。正文在 SL.con 范围相关规则 中也提到："The standard-library functions that apply to ranges of elements all have (or could have) bounds-safe overloads that takespan"——即作用于元素范围的标准库函数都有（或可以有）接受span的边界安全重载。

八、比较语义：比内容还是比指针

比较两个span<T>时，比较的是T的值。要看两个span是否指向同一处内存（同一性比较），使用.data()：

int a[] = { 1, 2, 3}; span<int> sa{a}; vector<int> v = { 1, 2, 3 }; span<int> sv{v}; assert(sa == sv); // sa and sv both point to contiguous ints with values 1, 2, 3 assert(sa.data() != sv.data()); // but sa and sv point to different memory areas

要点记忆：比较span比较的是内容，而不是它们是否指向同一位置。

九、空 vs 空指针：要不要显式判空

通常不需要显式检查span是否为 null，因为你真正想检查的往往是"非空"（size 不为零）。即使span是 null，测试它的 size 也是安全的。

对span s而言，下面几种写法含义完全一致：

• !s.empty()
• s.size() != 0
• s.data() != nullptr && s.size() != 0（第一个条件实际上是多余的）

下面这个写法在功能上也等价，因为它只是在测试是否有零个元素：

• s != nullptr（将s与一个 null 构造的空span比较）

举例说明：

void f(span<const int> s) { if (s != nullptr && s.size() > 0) { // bad: redundant, overkill // ... } if (s.size() > 0) { // good: not redundant // ... } if (!s.empty()) { // good: same as "s.size() > 0" // ... } }

要点记忆：通常你不应该检查span是否为 null。对于span s，如果你正在写s != nullptr或s.data() != nullptr，请检查一下是否应该直接问!s.empty()。

十、as_bytes：类型安全的字节视图

10.1 传统做法的脆弱性

as_bytes用于把span转换为span<const byte>，这是获取对象字节的类型安全只读视图。

没有span时，要查看对象的字节需要写脆弱的 cast：

void serialize(char* p, int length); // bad: forgot const void f(widget* p, int length) { // serialize one object's bytes (incl. padding) serialize(p, 1); // bad: copies just the first byte, forgot sizeof(widget) }

这里的两个经典错误是：忘记const（char*而不是const char*），以及忘记乘以sizeof(widget)（serialize(p, 1)只复制了第一个字节）。

10.2 用 as_bytes 重写

使用span后，代码更安全、更清晰：

void serialize(span<const byte>); // can't forget const, the first test call site won't compile void f(span<widget> s) { // ... // serialize one object's bytes (incl. padding) serialize(as_bytes(s)); // ok }

要点：as_bytes(s)产生span<const byte>后，参数签名中的const无法被省略——如果调用侧试图把它传给span<byte>（可变字节视图），第一个测试调用点就无法编译，从而在编译期就拦截了"忘记 const"的错误。

另外，span<T>允许你区分.size()（元素个数）与.size_bytes()（字节数），请利用这个区分，而不是手写size * sizeof(T)。

要点记忆：优先使用span<T>的.size_bytes()而不是.size() * sizeof(T)。

从 C++ 语言层面看，std::byte（C++17 引入）是专门用于操作对象原始表示的类型，正文建议用它替代unsigned char或char来做这类操作（ES.48 相关说明）；GSL 进一步建议在访问原始内存块时使用gsl::span<std::byte>。

十一、三个 span 相关提示

以下提示虽然不直接属于span本身，但在使用span时经常出现：

11.1 处理内存一律用 byte

凡是处理内存（而非字符或整数）的地方，都用byte。也就是说，访问一块原始内存时，使用gsl::span<std::byte>。

11.2 用 narrow() 应对无法承受的意外收窄

当你不能承受转换到更小范围时值发生变化带来的意外时，使用narrow()。这包括在有符号的span大小/索引与当前 STL 容器的无符号.size()之间转换的情形——不过span从容器构造时已经很好地封装了许多这类转换。

11.3 用 narrow_cast() 明确表达"确信不会收窄"

当你确信转换到更小范围不会发生值变化带来的意外时，使用narrow_cast()。

11.4 GSL 中窄化转换工具的底层定义

CppCore Guidelines 正文对这两个工具的定义如下（GSL.util: Utilities）：

• narrow_cast<T>(x)就是static_cast<T>(x)，纯粹的编译期转换，不做检查；
• narrow<T>(x)是"窄化即检查"：如果static_cast<T>(x) == x且没有符号性提升，则返回转换结果；否则抛出narrowing_error（例如narrow<unsigned>(-42)会抛异常）。

正文规则 ES.46: Avoid lossy (narrowing, truncating) arithmetic conversions 给出了对照示例，非常直观：

double d = 7.9; int i = d; // bad: narrowing: i becomes 7 i = (int) d; // bad: we're going to claim this is still not explicit enough void f(int x, long y, double d) { char c1 = x; // bad: narrowing char c2 = y; // bad: narrowing char c3 = d; // bad: narrowing }

改用 GSL 工具后：

i = gsl::narrow_cast<int>(d); // OK (you asked for it): narrowing: i becomes 7 i = gsl::narrow<int>(d); // OK: throws narrowing_error

以及涉及负数与无符号类型的有损转换：

double d = -7.9; unsigned u = 0; u = d; // bad: narrowing u = gsl::narrow_cast<unsigned>(d); // OK (you asked for it): u becomes 4294967289 u = gsl::narrow<unsigned>(d); // OK: throws narrowing_error

这两组示例精确体现了三个工具的语义差异：普通转换是静默有损的，narrow_cast是"你确认过、发生损失你负责"，narrow则是"发生损失就抛narrowing_error异常"。

十二、实战清单与进一步阅读

12.1 一张图记住 span 的取舍

12.2 仓库内延伸阅读入口

• 本文主体：docs/gsl-intro.md（Herb Sutter 撰写的 GSL 教程与 FAQ）
• GSL 完整规范章节：CppCoreGuidelines.md 的 "GSL: Guidelines support library"，涵盖视图、所有权、断言、工具、概念五类组件
• 函数参数规则：F.24: Use aspan<T>or aspan_p<T>to designate a half-open sequence，含span的四种遍历/访问方式示例
• 数组相关规则：R.14: Avoid[]parameters, preferspan与 ES.85 使用span访问数组
• 窄化规则：ES.46: Avoid lossy (narrowing, truncating) arithmetic conversions，含narrow/narrow_cast的完整示例

12.3 上手方式

GSL 是纯头文件库，使用时只需：

1. 将 GSL 参考实现的include目录加入编译器的头文件搜索路径；
2. 在源码中#include <gsl/span>等所需头文件；
3. 全部组件位于gsl命名空间，按需引入即可。

需要说明的是，gsl::span的接口追踪std::span，若你的工具链已支持 C++20 且不需要默认边界检查，两者接口基本一致；但若需要"默认全边界安全"的保证，应选用 GSL 版本（GSL.view 组件清单的 Note）。

12.4 小结

gsl::span把"指针 + 长度"这对容易失配的参数封装为一个自带边界信息、不拥有元素、零开销的视图对象，与 C++ Core Guidelines 中 F.24、R.14、ES.85 等规则形成呼应；配合span<const T>表达只读意图、first/last/subspan切分子区间、begin/end对接 STL 与 range 算法，以及as_bytes、byte、narrow/narrow_cast等周边工具，开发者可以在类型系统和编译期就把"越界访问、忘记 const、静默收窄"这三类经典内存错误挡在门外。

【免费下载链接】CppCoreGuidelinesThe C++ Core Guidelines are a set of tried-and-true guidelines, rules, and best practices about coding in C++项目地址: https://gitcode.com/gh_mirrors/cp/CppCoreGuidelines