From e1c833eb076efc5aef95d5c8ec9a410d8738def4 Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Sat, 4 May 2024 01:38:42 -0700 Subject: [PATCH] Docs: suggest `uN::checked_sub` instead of check-then-unchecked As of 124114 it's exactly the same in codegen, so might as well not use `unsafe`. Note that this is only for *unsigned*, since the overflow conditions for `iN::checked_sub` are more complicated. --- library/core/src/num/uint_macros.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index 9effa279b48..e925dd0874b 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -636,6 +636,31 @@ macro_rules! uint_impl { /// If you're just trying to avoid the panic in debug mode, then **do not** /// use this. Instead, you're looking for [`wrapping_sub`]. /// + /// If you find yourself writing code like this: + /// + /// ``` + /// # let foo = 30_u32; + /// # let bar = 20; + /// if foo >= bar { + /// // SAFETY: just checked it will not overflow + /// let diff = unsafe { foo.unchecked_sub(bar) }; + /// // ... use diff ... + /// } + /// ``` + /// + /// Consider changing it to + /// + /// ``` + /// # let foo = 30_u32; + /// # let bar = 20; + /// if let Some(diff) = foo.checked_sub(bar) { + /// // ... use diff ... + /// } + /// ``` + /// + /// As that does exactly the same thing -- including telling the optimizer + /// that the subtraction cannot overflow -- but avoids needing `unsafe`. + /// /// # Safety /// /// This results in undefined behavior when