Skip to content

Commit 7d7c225

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #119726 - NCGThompson:div-overflow-doc, r=Nilstrieb
Tweak Library Integer Division Docs Improved the documentation and diagnostics related to panicking in the division-like methods in std: * For signed methods that can overflow, clarified "results in overflow" to "self is -1 and rhs is Self::MIN." This is more concise than saying "results in overflow" and then explaining how it could overflow. * For floor/ceil_div, corrected the documentation and made it more like the documentation in other methods. * For signed methods that can overflow, explicitly mention that they are not affected by compiler flags. * Removed all unused rustc_inherit_overflow_checks attributes. The non-division-like operations will never overflow. * Added track_caller attributes to all methods that can panic. The panic messages will always be correct. For example, division methods all have / before %. * Edited the saturating_div documentation to be consistent with similar methods.
2 parents 72dddea + 76659ae commit 7d7c225

File tree

2 files changed

+34
-36
lines changed

2 files changed

+34
-36
lines changed

‎library/core/src/num/int_macros.rs‎

Lines changed: 17 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1643,6 +1643,10 @@ macro_rules! int_impl {
16431643
/// Saturating integer division. Computes `self / rhs`, saturating at the
16441644
/// numeric bounds instead of overflowing.
16451645
///
1646+
/// # Panics
1647+
///
1648+
/// This function will panic if `rhs` is 0.
1649+
///
16461650
/// # Examples
16471651
///
16481652
/// Basic usage:
@@ -1653,11 +1657,6 @@ macro_rules! int_impl {
16531657
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")]
16541658
///
16551659
/// ```
1656-
///
1657-
/// ```should_panic
1658-
#[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
1659-
///
1660-
/// ```
16611660
#[stable(feature = "saturating_div", since = "1.58.0")]
16621661
#[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
16631662
#[must_use = "this returns the result of the operation, \
@@ -2435,6 +2434,7 @@ macro_rules! int_impl {
24352434
#[must_use = "this returns the result of the operation, \
24362435
without modifying the original"]
24372436
#[inline]
2437+
#[track_caller]
24382438
pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
24392439
if unlikely!(rhs == -1) {
24402440
(0, self == Self::MIN)
@@ -2674,7 +2674,8 @@ macro_rules! int_impl {
26742674
///
26752675
/// # Panics
26762676
///
2677-
/// This function will panic if `rhs` is 0 or the division results in overflow.
2677+
/// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is
2678+
/// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag.
26782679
///
26792680
/// # Examples
26802681
///
@@ -2694,7 +2695,7 @@ macro_rules! int_impl {
26942695
#[must_use = "this returns the result of the operation, \
26952696
without modifying the original"]
26962697
#[inline]
2697-
#[rustc_inherit_overflow_checks]
2698+
#[track_caller]
26982699
pub const fn div_euclid(self, rhs: Self) -> Self {
26992700
let q = self / rhs;
27002701
if self % rhs < 0 {
@@ -2712,7 +2713,8 @@ macro_rules! int_impl {
27122713
///
27132714
/// # Panics
27142715
///
2715-
/// This function will panic if `rhs` is 0 or the division results in overflow.
2716+
/// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is
2717+
/// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag.
27162718
///
27172719
/// # Examples
27182720
///
@@ -2733,7 +2735,7 @@ macro_rules! int_impl {
27332735
#[must_use = "this returns the result of the operation, \
27342736
without modifying the original"]
27352737
#[inline]
2736-
#[rustc_inherit_overflow_checks]
2738+
#[track_caller]
27372739
pub const fn rem_euclid(self, rhs: Self) -> Self {
27382740
let r = self % rhs;
27392741
if r < 0 {
@@ -2755,12 +2757,8 @@ macro_rules! int_impl {
27552757
///
27562758
/// # Panics
27572759
///
2758-
/// This function will panic if `rhs` is zero.
2759-
///
2760-
/// ## Overflow behavior
2761-
///
2762-
/// On overflow, this function will panic if overflow checks are enabled (default in debug
2763-
/// mode) and wrap if overflow checks are disabled (default in release mode).
2760+
/// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is
2761+
/// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag.
27642762
///
27652763
/// # Examples
27662764
///
@@ -2780,7 +2778,7 @@ macro_rules! int_impl {
27802778
#[must_use = "this returns the result of the operation, \
27812779
without modifying the original"]
27822780
#[inline]
2783-
#[rustc_inherit_overflow_checks]
2781+
#[track_caller]
27842782
pub const fn div_floor(self, rhs: Self) -> Self {
27852783
let d = self / rhs;
27862784
let r = self % rhs;
@@ -2795,12 +2793,8 @@ macro_rules! int_impl {
27952793
///
27962794
/// # Panics
27972795
///
2798-
/// This function will panic if `rhs` is zero.
2799-
///
2800-
/// ## Overflow behavior
2801-
///
2802-
/// On overflow, this function will panic if overflow checks are enabled (default in debug
2803-
/// mode) and wrap if overflow checks are disabled (default in release mode).
2796+
/// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is
2797+
/// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag.
28042798
///
28052799
/// # Examples
28062800
///
@@ -2820,7 +2814,7 @@ macro_rules! int_impl {
28202814
#[must_use = "this returns the result of the operation, \
28212815
without modifying the original"]
28222816
#[inline]
2823-
#[rustc_inherit_overflow_checks]
2817+
#[track_caller]
28242818
pub const fn div_ceil(self, rhs: Self) -> Self {
28252819
let d = self / rhs;
28262820
let r = self % rhs;

‎library/core/src/num/uint_macros.rs‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1531,6 +1531,10 @@ macro_rules! uint_impl {
15311531
/// Saturating integer division. Computes `self / rhs`, saturating at the
15321532
/// numeric bounds instead of overflowing.
15331533
///
1534+
/// # Panics
1535+
///
1536+
/// This function will panic if `rhs` is 0.
1537+
///
15341538
/// # Examples
15351539
///
15361540
/// Basic usage:
@@ -1539,16 +1543,12 @@ macro_rules! uint_impl {
15391543
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
15401544
///
15411545
/// ```
1542-
///
1543-
/// ```should_panic
1544-
#[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
1545-
///
1546-
/// ```
15471546
#[stable(feature = "saturating_div", since = "1.58.0")]
15481547
#[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
15491548
#[must_use = "this returns the result of the operation, \
15501549
without modifying the original"]
15511550
#[inline]
1551+
#[track_caller]
15521552
pub const fn saturating_div(self, rhs: Self) -> Self {
15531553
// on unsigned types, there is no overflow in integer division
15541554
self.wrapping_div(rhs)
@@ -1683,6 +1683,7 @@ macro_rules! uint_impl {
16831683
#[must_use = "this returns the result of the operation, \
16841684
without modifying the original"]
16851685
#[inline(always)]
1686+
#[track_caller]
16861687
pub const fn wrapping_div(self, rhs: Self) -> Self {
16871688
self / rhs
16881689
}
@@ -1712,6 +1713,7 @@ macro_rules! uint_impl {
17121713
#[must_use = "this returns the result of the operation, \
17131714
without modifying the original"]
17141715
#[inline(always)]
1716+
#[track_caller]
17151717
pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
17161718
self / rhs
17171719
}
@@ -1739,6 +1741,7 @@ macro_rules! uint_impl {
17391741
#[must_use = "this returns the result of the operation, \
17401742
without modifying the original"]
17411743
#[inline(always)]
1744+
#[track_caller]
17421745
pub const fn wrapping_rem(self, rhs: Self) -> Self {
17431746
self % rhs
17441747
}
@@ -1769,6 +1772,7 @@ macro_rules! uint_impl {
17691772
#[must_use = "this returns the result of the operation, \
17701773
without modifying the original"]
17711774
#[inline(always)]
1775+
#[track_caller]
17721776
pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
17731777
self % rhs
17741778
}
@@ -2151,6 +2155,7 @@ macro_rules! uint_impl {
21512155
#[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
21522156
#[must_use = "this returns the result of the operation, \
21532157
without modifying the original"]
2158+
#[track_caller]
21542159
pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
21552160
(self / rhs, false)
21562161
}
@@ -2181,6 +2186,7 @@ macro_rules! uint_impl {
21812186
#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
21822187
#[must_use = "this returns the result of the operation, \
21832188
without modifying the original"]
2189+
#[track_caller]
21842190
pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
21852191
(self / rhs, false)
21862192
}
@@ -2208,6 +2214,7 @@ macro_rules! uint_impl {
22082214
#[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
22092215
#[must_use = "this returns the result of the operation, \
22102216
without modifying the original"]
2217+
#[track_caller]
22112218
pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
22122219
(self % rhs, false)
22132220
}
@@ -2238,6 +2245,7 @@ macro_rules! uint_impl {
22382245
#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
22392246
#[must_use = "this returns the result of the operation, \
22402247
without modifying the original"]
2248+
#[track_caller]
22412249
pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
22422250
(self % rhs, false)
22432251
}
@@ -2473,7 +2481,7 @@ macro_rules! uint_impl {
24732481
#[must_use = "this returns the result of the operation, \
24742482
without modifying the original"]
24752483
#[inline(always)]
2476-
#[rustc_inherit_overflow_checks]
2484+
#[track_caller]
24772485
pub const fn div_euclid(self, rhs: Self) -> Self {
24782486
self / rhs
24792487
}
@@ -2502,7 +2510,7 @@ macro_rules! uint_impl {
25022510
#[must_use = "this returns the result of the operation, \
25032511
without modifying the original"]
25042512
#[inline(always)]
2505-
#[rustc_inherit_overflow_checks]
2513+
#[track_caller]
25062514
pub const fn rem_euclid(self, rhs: Self) -> Self {
25072515
self % rhs
25082516
}
@@ -2527,6 +2535,7 @@ macro_rules! uint_impl {
25272535
#[must_use = "this returns the result of the operation, \
25282536
without modifying the original"]
25292537
#[inline(always)]
2538+
#[track_caller]
25302539
pub const fn div_floor(self, rhs: Self) -> Self {
25312540
self / rhs
25322541
}
@@ -2537,11 +2546,6 @@ macro_rules! uint_impl {
25372546
///
25382547
/// This function will panic if `rhs` is zero.
25392548
///
2540-
/// ## Overflow behavior
2541-
///
2542-
/// On overflow, this function will panic if overflow checks are enabled (default in debug
2543-
/// mode) and wrap if overflow checks are disabled (default in release mode).
2544-
///
25452549
/// # Examples
25462550
///
25472551
/// Basic usage:
@@ -2554,7 +2558,7 @@ macro_rules! uint_impl {
25542558
#[must_use = "this returns the result of the operation, \
25552559
without modifying the original"]
25562560
#[inline]
2557-
#[rustc_inherit_overflow_checks]
2561+
#[track_caller]
25582562
pub const fn div_ceil(self, rhs: Self) -> Self {
25592563
let d = self / rhs;
25602564
let r = self % rhs;

0 commit comments

Comments
 (0)