From b45855032b3aad0ea0a48894f56cb9bb8fa361f2 Mon Sep 17 00:00:00 2001
From: Jim Turner <git@turner.link>
Date: Mon, 1 Mar 2021 16:19:59 -0500
Subject: [PATCH] Document panicking cases for integer remainder
The panic when the right operand is `0` is expected, but the
overflow-related panic (which occurs only for `MIN % -1`) is somewhat
surprising for two reasons: a return value of `0` would be reasonable
in this case, and, for most arithmetic operations, overflow results in
panic only when `debug_assertions` is enabled. As a result, it's
helpful to document this behavior.
---
library/core/src/ops/arith.rs | 13 ++++++++++---
1 file changed, 10 insertions(+), 3 deletions(-)
diff --git a/library/core/src/ops/arith.rs b/library/core/src/ops/arith.rs
index da0f038e44e..a0577b287ce 100644
--- a/library/core/src/ops/arith.rs
+++ b/library/core/src/ops/arith.rs
@@ -556,9 +556,13 @@ pub trait Rem<Rhs = Self> {
}
macro_rules! rem_impl_integer {
- ($($t:ty)*) => ($(
+ ($(($($t:ty)*) => $panic:expr),*) => ($($(
/// This operation satisfies `n % d == n - (n / d) * d`. The
/// result has the same sign as the left operand.
+ ///
+ /// # Panics
+ ///
+ #[doc = $panic]
#[stable(feature = "rust1", since = "1.0.0")]
impl Rem for $t {
type Output = $t;
@@ -568,10 +572,13 @@ macro_rules! rem_impl_integer {
}
forward_ref_binop! { impl Rem, rem for $t, $t }
- )*)
+ )*)*)
}
-rem_impl_integer! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
+rem_impl_integer! {
+ (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.",
+ (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or if `self / other` results in overflow."
+}
macro_rules! rem_impl_float {
($($t:ty)*) => ($(