Rust 标准库指针减法详解ptr::sub的语义、Safety 契约与源码实现【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rustptr::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!(...)]被三处方法定义同时复用的共享文档片段方法定义位置稳定版本*const T::sublibrary/core/src/ptr/const_ptr.rs1.26.0pointer_methods*mut T::sublibrary/core/src/ptr/mut_ptr.rs1.26.0pointer_methodsNonNullT::sublibrary/core/src/ptr/non_null.rs1.80.0non_null_convenience这意味着三份 API 文档共享同一份 Safety 契约而它们的底层实现各有侧重*const/*mut走intrinsics::offset取负NonNull复用自身的offset方法下文会分别剖析。与它配套的还有同目录下的 add.md向前加、offset.md带符号偏移等文档共同构成标准库指针算术的文档族。二、语义单位是 T方向只向后文档开宗明义sub从指针上减去一个无符号偏移量只能把指针向后移动或完全不移动。若需要根据值的大小决定前进还是后退应当改用接受有符号偏移量的offset。count的单位是Tcount 3表示指针实际移动3 * size_of::T()个字节。也就是说语义等价于先算字节偏移再做减法字节偏移count * size_of::T()结果地址self.addr() - count * size_of::T()正是因为单位是T而非字节sub要求T: Sized。若按字节操作标准库另提供了byte_sub1.75.0 稳定见 const_ptr.rs 附近的字节偏移族方法。三、三条 Safety 契约违反即未定义行为sub是unsafe fn调用者必须自行保证以下三条条件全部成立否则构成 Undefined BehaviorUB字节偏移必须能放进isizecount * size_of::T()在数学整数上计算不允许“回绕”溢出结果必须能装入isize。这是intrinsics::offset系操作的通用约束——LLVM 认为指针算术的字节跨度不能超过isize::MAX。结果地址必须能放进usize设result self.addr() - count * size_of::T()该数学整数必须能装入usize。这排除了“减过头”导致负地址的情形。非零偏移时必须在同一分配内若计算出的偏移非零则self必须是从某个[分配allocation]派生provenance出的指针且self与result之间的整个内存区间即result..self.addr()都必须落在该分配的边界之内。文档还给出了一条重要的推论任何分配都不可能大于isize::MAX字节且其地址必须能被usize表示因此第三条条件在技术上蕴含了前两条。这带来一个实用的安全保证只要指针确实派生自某个合法分配、且减去的范围没有越出该分配前两条数值约束就自动满足无需单独检查。3.1 与add/offset契约的对称性对比同目录的 add.mdadd的第三条要求区间self.addr()..result在分配内offset.mdlibrary/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 doesnt 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 的安全契约。 // 因为目标类型不是 ZSTcount 至多为 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.2NonNullT::subNonNull版本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_subnon_null.rs与sub共享同一份安全契约只是单位换成字节。五、官方示例与典型用法5.1 文档示例从尾部向前逐个解引用const_ptr.rs与mut_ptr.rs的 doc 示例演示了“先add到末尾再sub回退”的经典组合const_ptr.rslet s: str 123; unsafe { let end: *const u8 s.as_ptr().add(3); assert_eq!(*end.sub(1), b3); // 倒数第 1 个字节 assert_eq!(*end.sub(2), b2); // 倒数第 2 个字节 }NonNull版本non_null.rs几乎一致只是多了NonNull::new(...).unwrap()的包装并使用read()读取use std::ptr::NonNull; let s: str 123; unsafe { let end: NonNullu8 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_subsub的唯一优势是能让编译器做更激进的优化见 const_ptr.rs。wrapping_subconst_ptr.rs的实现证实了这一点——它完全不检查在界性直接按位回绕pub const fn wrapping_sub(self, count: usize) - Self where T: Sized, { self.wrapping_offset((count as isize).wrapping_neg()) }两者的选择原则很明确维度subwrapping_sub安全性unsafe违反契约即 UB安全方法无 UB方向只能向后向后可回绕越界行为不允许允许按位回绕结果可能无意义优化空间编译器可依赖“不回绕”做更激进优化无此假设简单说能证明在界就用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rust 标准库指针减法详解ptr::sub的语义、Safety 契约与源码实现【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rustptr::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!(...)]被三处方法定义同时复用的共享文档片段方法定义位置稳定版本*const T::sublibrary/core/src/ptr/const_ptr.rs1.26.0pointer_methods*mut T::sublibrary/core/src/ptr/mut_ptr.rs1.26.0pointer_methodsNonNullT::sublibrary/core/src/ptr/non_null.rs1.80.0non_null_convenience这意味着三份 API 文档共享同一份 Safety 契约而它们的底层实现各有侧重*const/*mut走intrinsics::offset取负NonNull复用自身的offset方法下文会分别剖析。与它配套的还有同目录下的 add.md向前加、offset.md带符号偏移等文档共同构成标准库指针算术的文档族。二、语义单位是 T方向只向后文档开宗明义sub从指针上减去一个无符号偏移量只能把指针向后移动或完全不移动。若需要根据值的大小决定前进还是后退应当改用接受有符号偏移量的offset。count的单位是Tcount 3表示指针实际移动3 * size_of::T()个字节。也就是说语义等价于先算字节偏移再做减法字节偏移count * size_of::T()结果地址self.addr() - count * size_of::T()正是因为单位是T而非字节sub要求T: Sized。若按字节操作标准库另提供了byte_sub1.75.0 稳定见 const_ptr.rs 附近的字节偏移族方法。三、三条 Safety 契约违反即未定义行为sub是unsafe fn调用者必须自行保证以下三条条件全部成立否则构成 Undefined BehaviorUB字节偏移必须能放进isizecount * size_of::T()在数学整数上计算不允许“回绕”溢出结果必须能装入isize。这是intrinsics::offset系操作的通用约束——LLVM 认为指针算术的字节跨度不能超过isize::MAX。结果地址必须能放进usize设result self.addr() - count * size_of::T()该数学整数必须能装入usize。这排除了“减过头”导致负地址的情形。非零偏移时必须在同一分配内若计算出的偏移非零则self必须是从某个[分配allocation]派生provenance出的指针且self与result之间的整个内存区间即result..self.addr()都必须落在该分配的边界之内。文档还给出了一条重要的推论任何分配都不可能大于isize::MAX字节且其地址必须能被usize表示因此第三条条件在技术上蕴含了前两条。这带来一个实用的安全保证只要指针确实派生自某个合法分配、且减去的范围没有越出该分配前两条数值约束就自动满足无需单独检查。3.1 与add/offset契约的对称性对比同目录的 add.mdadd的第三条要求区间self.addr()..result在分配内offset.mdlibrary/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 doesnt 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 的安全契约。 // 因为目标类型不是 ZSTcount 至多为 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.2NonNullT::subNonNull版本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_subnon_null.rs与sub共享同一份安全契约只是单位换成字节。五、官方示例与典型用法5.1 文档示例从尾部向前逐个解引用const_ptr.rs与mut_ptr.rs的 doc 示例演示了“先add到末尾再sub回退”的经典组合const_ptr.rslet s: str 123; unsafe { let end: *const u8 s.as_ptr().add(3); assert_eq!(*end.sub(1), b3); // 倒数第 1 个字节 assert_eq!(*end.sub(2), b2); // 倒数第 2 个字节 }NonNull版本non_null.rs几乎一致只是多了NonNull::new(...).unwrap()的包装并使用read()读取use std::ptr::NonNull; let s: str 123; unsafe { let end: NonNullu8 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_subsub的唯一优势是能让编译器做更激进的优化见 const_ptr.rs。wrapping_subconst_ptr.rs的实现证实了这一点——它完全不检查在界性直接按位回绕pub const fn wrapping_sub(self, count: usize) - Self where T: Sized, { self.wrapping_offset((count as isize).wrapping_neg()) }两者的选择原则很明确维度subwrapping_sub安全性unsafe违反契约即 UB安全方法无 UB方向只能向后向后可回绕越界行为不允许允许按位回绕结果可能无意义优化空间编译器可依赖“不回绕”做更激进优化无此假设简单说能证明在界就用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
