mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #82683 - jturner314:int-div-rem-doc-panic, r=nikomatsakis

Browse Source 
Document panicking cases for integer division and remainder

This PR documents the cases when integer division and remainder operations panic. These operations panic in two cases: division by zero and overflow.

It's surprising that these operations always panic on overflow, unlike most other arithmetic operations, which panic on overflow only when `debug_assertions` is enabled. The panic on overflow for the remainder is also surprising because a return value of `0` would be reasonable in this case. ("Overflow" occurs only for `MIN % -1`.) Since the panics on overflow are somewhat surprising, they should be documented.

I guess it's worth asking: is panic on overflow (even when `debug_assertions` is disabled) the intended behavior? If not, what's the best way forward?
This commit is contained in:
Dylan DPC 2021-03-22 15:21:24 +01:00 committed by GitHub
commit 83faac9da4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
library/core/src/ops/arith.rs
View File

@ -456,9 +456,13 @@ pub trait Div<Rhs = Self> {
}
macro_rules! div_impl_integer {
($($t:ty)*) => ($(
($(($($t:ty)*) => $panic:expr),*) => ($($(
/// This operation rounds towards zero, truncating any
/// fractional part of the exact result.
///
/// # Panics
///
#[doc = $panic]
#[stable(feature = "rust1", since = "1.0.0")]
impl Div for $t {
type Output = $t;
@ -468,10 +472,13 @@ fn div(self, other: $t) -> $t { self / other }
}
forward_ref_binop! { impl Div, div for $t, $t }
)*)
)*)*)
}
div_impl_integer! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
div_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 the division results in overflow."
}
macro_rules! div_impl_float {
($($t:ty)*) => ($(
@ -549,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;
@ -561,10 +572,13 @@ fn rem(self, other: $t) -> $t { self % other }
}
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)*) => ($(