From 724fe8fcfb030372527182ed9c861bc8104e98a4 Mon Sep 17 00:00:00 2001 From: Nicholas Thompson Date: Fri, 19 Jan 2024 15:23:58 -0500 Subject: [PATCH 1/3] Adjust Attributes of Integer Division Methods --- library/core/src/num/int_macros.rs | 9 +++++---- library/core/src/num/uint_macros.rs | 16 +++++++++++++--- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index fd01f1b2610..a0e275412e7 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -1913,6 +1913,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] + #[track_caller] pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) { if unlikely!(rhs == -1) { (0, self == Self::MIN) @@ -2172,7 +2173,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn div_euclid(self, rhs: Self) -> Self { let q = self / rhs; if self % rhs < 0 { @@ -2211,7 +2212,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn rem_euclid(self, rhs: Self) -> Self { let r = self % rhs; if r < 0 { @@ -2258,7 +2259,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn div_floor(self, rhs: Self) -> Self { let d = self / rhs; let r = self % rhs; @@ -2298,7 +2299,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn div_ceil(self, rhs: Self) -> Self { let d = self / rhs; let r = self % rhs; diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index 11a53aaf122..ad084a5c330 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -1141,6 +1141,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] + #[track_caller] pub const fn saturating_div(self, rhs: Self) -> Self { // on unsigned types, there is no overflow in integer division self.wrapping_div(rhs) @@ -1275,6 +1276,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] + #[track_caller] pub const fn wrapping_div(self, rhs: Self) -> Self { self / rhs } @@ -1304,6 +1306,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] + #[track_caller] pub const fn wrapping_div_euclid(self, rhs: Self) -> Self { self / rhs } @@ -1331,6 +1334,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] + #[track_caller] pub const fn wrapping_rem(self, rhs: Self) -> Self { self % rhs } @@ -1361,6 +1365,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] + #[track_caller] pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self { self % rhs } @@ -1743,6 +1748,7 @@ macro_rules! uint_impl { #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] #[must_use = "this returns the result of the operation, \ without modifying the original"] + #[track_caller] pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) { (self / rhs, false) } @@ -1773,6 +1779,7 @@ macro_rules! uint_impl { #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] #[must_use = "this returns the result of the operation, \ without modifying the original"] + #[track_caller] pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) { (self / rhs, false) } @@ -1800,6 +1807,7 @@ macro_rules! uint_impl { #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] #[must_use = "this returns the result of the operation, \ without modifying the original"] + #[track_caller] pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) { (self % rhs, false) } @@ -1830,6 +1838,7 @@ macro_rules! uint_impl { #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] #[must_use = "this returns the result of the operation, \ without modifying the original"] + #[track_caller] pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) { (self % rhs, false) } @@ -2065,7 +2074,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn div_euclid(self, rhs: Self) -> Self { self / rhs } @@ -2094,7 +2103,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn rem_euclid(self, rhs: Self) -> Self { self % rhs } @@ -2119,6 +2128,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] + #[track_caller] pub const fn div_floor(self, rhs: Self) -> Self { self / rhs } @@ -2146,7 +2156,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline] - #[rustc_inherit_overflow_checks] + #[track_caller] pub const fn div_ceil(self, rhs: Self) -> Self { let d = self / rhs; let r = self % rhs; From 6b8eae0d243258f616562395be0b4dd5d5f23acf Mon Sep 17 00:00:00 2001 From: Nicholas Thompson Date: Fri, 19 Jan 2024 15:27:26 -0500 Subject: [PATCH 2/3] Make `saturating_div` Docs Consistent with Others --- library/core/src/num/int_macros.rs | 9 ++++----- library/core/src/num/uint_macros.rs | 9 ++++----- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index a0e275412e7..4b7daa1aafd 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -1121,6 +1121,10 @@ macro_rules! int_impl { /// Saturating integer division. Computes `self / rhs`, saturating at the /// numeric bounds instead of overflowing. /// + /// # Panics + /// + /// This function will panic if `rhs` is 0. + /// /// # Examples /// /// Basic usage: @@ -1131,11 +1135,6 @@ macro_rules! int_impl { #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")] /// /// ``` - /// - /// ```should_panic - #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")] - /// - /// ``` #[stable(feature = "saturating_div", since = "1.58.0")] #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")] #[must_use = "this returns the result of the operation, \ diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index ad084a5c330..4d9aff8287b 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -1123,6 +1123,10 @@ macro_rules! uint_impl { /// Saturating integer division. Computes `self / rhs`, saturating at the /// numeric bounds instead of overflowing. /// + /// # Panics + /// + /// This function will panic if `rhs` is 0. + /// /// # Examples /// /// Basic usage: @@ -1131,11 +1135,6 @@ macro_rules! uint_impl { #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")] /// /// ``` - /// - /// ```should_panic - #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")] - /// - /// ``` #[stable(feature = "saturating_div", since = "1.58.0")] #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")] #[must_use = "this returns the result of the operation, \ From 76659ae74324d52627a6911ca27e5ef02f3e79ef Mon Sep 17 00:00:00 2001 From: Nicholas Thompson Date: Fri, 19 Jan 2024 15:33:19 -0500 Subject: [PATCH 3/3] Clarify Panicking Behavior in Integer Division Docs --- library/core/src/num/int_macros.rs | 22 ++++++++-------------- library/core/src/num/uint_macros.rs | 5 ----- 2 files changed, 8 insertions(+), 19 deletions(-) diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index 4b7daa1aafd..19f3ed68124 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -2152,7 +2152,8 @@ macro_rules! int_impl { /// /// # Panics /// - /// This function will panic if `rhs` is 0 or the division results in overflow. + /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is + /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. /// /// # Examples /// @@ -2190,7 +2191,8 @@ macro_rules! int_impl { /// /// # Panics /// - /// This function will panic if `rhs` is 0 or the division results in overflow. + /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is + /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. /// /// # Examples /// @@ -2233,12 +2235,8 @@ macro_rules! int_impl { /// /// # Panics /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// On overflow, this function will panic if overflow checks are enabled (default in debug - /// mode) and wrap if overflow checks are disabled (default in release mode). + /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is + /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. /// /// # Examples /// @@ -2273,12 +2271,8 @@ macro_rules! int_impl { /// /// # Panics /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// On overflow, this function will panic if overflow checks are enabled (default in debug - /// mode) and wrap if overflow checks are disabled (default in release mode). + /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is + /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. /// /// # Examples /// diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index 4d9aff8287b..9876eaf6f04 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -2138,11 +2138,6 @@ macro_rules! uint_impl { /// /// This function will panic if `rhs` is zero. /// - /// ## Overflow behavior - /// - /// On overflow, this function will panic if overflow checks are enabled (default in debug - /// mode) and wrap if overflow checks are disabled (default in release mode). - /// /// # Examples /// /// Basic usage: