企业官网建设流程全解析

Rust 标准库指针减法详解：ptr::sub的语义、Safety 契约与源码实现

【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust

ptr::sub（以及*const T::sub、*mut T::sub、NonNull::sub）是 Rust 标准库中从指针减去无符号偏移量的核心方法，它只能让指针向后移动（或原地不动）。本文以 library/core/src/ptr/docs/sub.md 这一官方文档为主体，结合该文档被引用处的真实实现源码，完整讲解其单位语义、三条 Safety 契约、与offset/add/wrapping_sub的取舍，以及编译器在 debug 构建下如何做 UB 预检查，帮助你安全地在反向遍历、缓冲区尾指针回退等场景中写出既快又正确的指针算术代码。

一、方法定位：一份文档，三处生效

sub.md并不是独立发布的文章，而是通过#[doc = include_str!(...)]被三处方法定义同时复用的共享文档片段：

这意味着三份 API 文档共享同一份 Safety 契约，而它们的底层实现各有侧重（*const/*mut走intrinsics::offset取负，NonNull复用自身的offset方法），下文会分别剖析。与它配套的还有同目录下的 add.md（向前加）、offset.md（带符号偏移）等文档，共同构成标准库指针算术的文档族。

二、语义：单位是 T，方向只向后

文档开宗明义：sub从指针上减去一个无符号偏移量，只能把指针向后移动（或完全不移动）。若需要根据值的大小决定前进还是后退，应当改用接受有符号偏移量的offset。

count的单位是T：count = 3表示指针实际移动3 * size_of::<T>()个字节。也就是说，语义等价于先算字节偏移再做减法：

• 字节偏移：count * size_of::<T>()
• 结果地址：self.addr() - count * size_of::<T>()

正是因为单位是T而非字节，sub要求T: Sized。若按字节操作，标准库另提供了byte_sub（1.75.0 稳定，见 const_ptr.rs 附近的字节偏移族方法）。

三、三条 Safety 契约：违反即未定义行为

sub是unsafe fn，调用者必须自行保证以下三条条件全部成立，否则构成 Undefined Behavior（UB）：

1. 字节偏移必须能放进isize：count * size_of::<T>()在数学整数上计算（不允许“回绕”溢出），结果必须能装入isize。这是intrinsics::offset系操作的通用约束——LLVM 认为指针算术的字节跨度不能超过isize::MAX。
2. 结果地址必须能放进usize：设result = self.addr() - count * size_of::<T>()，该数学整数必须能装入usize。这排除了“减过头”导致负地址的情形。
3. 非零偏移时必须在同一分配内：若计算出的偏移非零，则self必须是从某个[分配（allocation）]派生（provenance）出的指针，且self与result之间的整个内存区间（即result..self.addr()）都必须落在该分配的边界之内。

文档还给出了一条重要的推论：任何分配都不可能大于isize::MAX字节，且其地址必须能被usize表示，因此第三条条件在技术上蕴含了前两条。这带来一个实用的安全保证：只要指针确实派生自某个合法分配、且减去的范围没有越出该分配，前两条数值约束就自动满足，无需单独检查。

3.1 与add/offset契约的对称性

对比同目录的 add.md：add的第三条要求区间self.addr()..result在分配内；offset.md（library/core/src/ptr/docs/offset.md）则写成min(self.addr(), result)..max(self.addr(), result)的通用形式。三份契约在“区间在界”这一点上完全一致，只是sub因为方向固定为后退，区间可以简写为result..self.addr()。

四、源码级实现：三处实现如何落地契约

4.1*const T::sub与*mut T::sub

两者的实现几乎相同，以 const_ptr.rs 为例：

pub const unsafe fn sub(self, count: usize) -> Self where T: Sized, { #[cfg(debug_assertions)] const fn runtime_sub_nowrap(this: *const (), count: usize, size: usize) -> bool { const_eval_select!( @capture { this: *const (), count: usize, size: usize } -> bool: if const { true } else { let Some(byte_offset) = count.checked_mul(size) else { return false; }; byte_offset <= (isize::MAX as usize) && this.addr() >= byte_offset } ) } #[cfg(debug_assertions)] // Expensive, and doesn't catch much in the wild. ub_checks::assert_unsafe_precondition!( check_language_ub, "ptr::sub requires that the address calculation does not overflow", (this, count, size) => runtime_sub_nowrap(this, count, size) ); if T::IS_ZST { // 指向零尺寸类型的指针，算术操作什么都不做。 self } else { // SAFETY: 调用者必须满足 `offset` 的安全契约。 // 因为目标类型不是 ZST，`count` 至多为 isize::MAX，取负不会溢出。 unsafe { intrinsics::offset(self, intrinsics::unchecked_sub(0, count as isize)) } } }

值得注意的实现细节：

• debug 构建的 UB 预检查：通过ub_checks::assert_unsafe_precondition!检查count.checked_mul(size)是否成功、byte_offset <= isize::MAX、以及self.addr() >= byte_offset。前两条对应文档契约 1，第三条对应“结果非负”（契约 2 的核心）。源码注释直言这类检查“昂贵，且在真实场景中捕获不到太多问题”（见 const_ptr.rs），因此只在 debug 断言下启用，release 构建不会为此付出任何开销。
• ZST 短路：当T::IS_ZST（如()、[u8; 0]）时直接返回self，不做任何指针运算——对零尺寸类型做算术没有意义，这是特意为 ZST 的边界情况兜底。
• 取负不溢出的论证：实现先把count转成isize再取负（unchecked_sub(0, count as isize)）。因为非 ZST 的size_of::<T>() >= 1，契约 1 已保证count * size_of::<T>() <= isize::MAX，所以count as isize本身必然不超过isize::MAX，取负不会溢出。这条论证在源码注释中（const_ptr.rs）被明确写出，是“Safety 契约 → 编译器可依赖性质”的典型例子。
• const fn支持：该方法从 1.61.0 起可在const上下文中使用（const_ptr_offset），与offset、add一致；const_eval_select!保证编译期求值不执行这些运行时 UB 检查。

*mut T::sub在 mut_ptr.rs 的实现与上述完全对称。

4.2NonNull<T>::sub

NonNull版本（non_null.rs）更简洁，直接复用自己的offset方法：

pub const unsafe fn sub(self, count: usize) -> Self where T: Sized, { if T::IS_ZST { self } else { // SAFETY: 调用者必须满足 `offset` 的安全契约； // 非 ZST 时 count 至多 isize::MAX，取负不会溢出。 unsafe { self.offset((count as isize).unchecked_neg()) } } }

它没有额外的 debug 预检查（offset自身的ub_checks会兜底），且因为NonNull保证非空，返回值通过offset直接构造也不会触碰空指针问题。此外，NonNull族的byte_sub（non_null.rs）与sub共享同一份安全契约，只是单位换成字节。

五、官方示例与典型用法

5.1 文档示例：从尾部向前逐个解引用

const_ptr.rs与mut_ptr.rs的 doc 示例演示了“先add到末尾，再sub回退”的经典组合（const_ptr.rs）：

let s: &str = "123"; unsafe { let end: *const u8 = s.as_ptr().add(3); assert_eq!(*end.sub(1), b'3'); // 倒数第 1 个字节 assert_eq!(*end.sub(2), b'2'); // 倒数第 2 个字节 }

NonNull版本（non_null.rs）几乎一致，只是多了NonNull::new(...).unwrap()的包装，并使用read()读取：

use std::ptr::NonNull; let s: &str = "123"; unsafe { let end: NonNull<u8> = NonNull::new(s.as_ptr().cast_mut()).unwrap().add(3); println!("{}", end.sub(1).read() as char); // '3' println!("{}", end.sub(2).read() as char); // '2' }

5.2 典型场景

• 反向遍历缓冲区：用end.sub(i)从末尾向前扫描，常见于解析器、栈式数据结构的逆序访问。
• 尾指针回退：维护“已填充末尾”指针后，sub(n)回到第 n 个元素，再配合read/write访问。
• 对齐与填充计算：在实现自定义内存池或对齐逻辑时，用sub修正指针到已知元素边界。

这些场景中，务必记住第三条契约：回退后的result以及result..self.addr()区间必须仍然落在原分配内，否则就是 UB。

六、与wrapping_sub的取舍

文档在sub的完整 doc 注释中明确补充了建议：如果难以满足上述约束，请考虑改用wrapping_sub；sub的唯一优势是能让编译器做更激进的优化（见 const_ptr.rs）。

wrapping_sub（const_ptr.rs）的实现证实了这一点——它完全不检查在界性，直接按位回绕：

pub const fn wrapping_sub(self, count: usize) -> Self where T: Sized, { self.wrapping_offset((count as isize).wrapping_neg()) }

两者的选择原则很明确：

简单说：能证明在界就用sub，证明不了就用wrapping_sub。对于“减过头回绕到分配外”的情形，wrapping_sub的结果是未定义语义的地址，仍需自行判断是否可用。

七、小结

ptr::sub是 Rust 指针算术中“向后移动”的唯一标准入口，其 Safety 契约可以概括为一句话：在数学整数上计算出的字节偏移能装入isize、结果地址能装入usize，且整个回退区间（非零偏移时）都在同一分配内。得益于“分配最大为isize::MAX字节”的强保证，第三条蕴含前两条，实际使用时只需重点确保“在界”。底层实现（intrinsics::offset取负）让编译器能基于不回绕语义做激进优化；debug 构建下的ub_checks预检查则为开发期提供了额外的 UB 防护。需要进一步阅读源码时，可以从 library/core/src/ptr/docs/sub.md 出发，对照 const_ptr.rs、mut_ptr.rs 与 non_null.rs 三处实现，并与 add.md、offset.md 的契约对比，即可完整掌握标准库指针算术的全貌。

【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust