languages/rust
languages/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust synced 2024-09-21 09:22:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #121155 - tspiteri:strict-doc-overflow, r=Nilstrieb

Browse source 
doc: add note about panicking examples for strict_overflow_ops

The first commit adds a note before the panicking examples for strict_overflow_ops to make it clearer that the following examples should panic and why, without needing the reader to hover the mouse over the information icon.

The second commit adds panicking examples for division by zero operations for strict division operations on unsigned numbers. The signed numbers already have two panicking examples each: one for division by zero and one for overflowing division (`MIN/-1`); this commit includes the division by zero examples for the unsigned numbers.
This commit is contained in:
Guillaume Gomez 2024-02-16 00:27:35 +01:00 committed by GitHub
parent e84a1dd87f 675d092e3e
commit 2a216bb53b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 79 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
library/core/src/num/int_macros.rs
View file

@ -472,6 +472,8 @@ pub const fn checked_add(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")]
@ -552,6 +554,8 @@ pub const fn checked_add_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_unsigned(2), 3);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add_unsigned(3);")]
@ -606,6 +610,8 @@ pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).strict_sub(1), ", stringify!($SelfT), "::MIN + 1);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub(3);")]
@ -686,6 +692,8 @@ pub const fn checked_sub_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub_unsigned(2), -1);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub_unsigned(3);")]
@ -740,6 +748,8 @@ pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.strict_mul(1), ", stringify!($SelfT), "::MAX);")]
/// ```
///
/// The following panics because of overflow:
///
/// ``` should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")]
@ -831,11 +841,15 @@ pub const fn checked_div(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div(-1), ", stringify!($Max), ");")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div(-1);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div(0);")]
@ -901,11 +915,15 @@ pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div_euclid(-1), ", stringify!($Max), ");")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div_euclid(-1);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div_euclid(0);")]
@ -970,11 +988,15 @@ pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem(2), 1);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem(0);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem(-1);")]
@ -1039,11 +1061,15 @@ pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem_euclid(2), 1);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem_euclid(0);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem_euclid(-1);")]
@ -1121,6 +1147,8 @@ pub const fn checked_neg(self) -> Option<Self> {
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_neg(), -5);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_neg();")]
@ -1175,6 +1203,8 @@ pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
#[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 0x1", stringify!($SelfT), ".strict_shl(129);")]
@ -1256,6 +1286,8 @@ pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(128);")]
@ -1340,6 +1372,8 @@ pub const fn checked_abs(self) -> Option<Self> {
#[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").strict_abs(), 5);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_abs();")]
@ -1414,6 +1448,8 @@ pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
#[doc = concat!("assert_eq!(8", stringify!($SelfT), ".strict_pow(2), 64);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")]

43
library/core/src/num/uint_macros.rs
View file

@ -480,6 +480,8 @@ pub const fn checked_add(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")]
@ -561,6 +563,8 @@ pub const fn checked_add_signed(self, rhs: $SignedT) -> Option<Self> {
#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_signed(2), 3);")]
/// ```
///
/// The following panic because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 1", stringify!($SelfT), ".strict_add_signed(-2);")]
@ -620,6 +624,8 @@ pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub(1), 0);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 0", stringify!($SelfT), ".strict_sub(1);")]
@ -700,6 +706,8 @@ pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_mul(1), 5);")]
/// ```
///
/// The following panics because of overflow:
///
/// ``` should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")]
@ -785,6 +793,13 @@ pub const fn checked_div(self, rhs: Self) -> Option<Self> {
/// #![feature(strict_overflow_ops)]
#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_div(10), 10);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div(0);")]
/// ```
#[unstable(feature = "strict_overflow_ops", issue = "118260")]
#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
#[must_use = "this returns the result of the operation, \
@ -840,6 +855,12 @@ pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
/// #![feature(strict_overflow_ops)]
#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_div_euclid(10), 10);")]
/// ```
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div_euclid(0);")]
/// ```
#[unstable(feature = "strict_overflow_ops", issue = "118260")]
#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
#[must_use = "this returns the result of the operation, \
@ -895,6 +916,13 @@ pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
/// #![feature(strict_overflow_ops)]
#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_rem(10), 0);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem(0);")]
/// ```
#[unstable(feature = "strict_overflow_ops", issue = "118260")]
#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
#[must_use = "this returns the result of the operation, \
@ -951,6 +979,13 @@ pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
/// #![feature(strict_overflow_ops)]
#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_rem_euclid(10), 0);")]
/// ```
///
/// The following panics because of division by zero:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem_euclid(0);")]
/// ```
#[unstable(feature = "strict_overflow_ops", issue = "118260")]
#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
#[must_use = "this returns the result of the operation, \
@ -1172,6 +1207,8 @@ pub const fn checked_neg(self) -> Option<Self> {
#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".strict_neg(), 0);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 1", stringify!($SelfT), ".strict_neg();")]
@ -1226,6 +1263,8 @@ pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
#[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shl(129);")]
@ -1307,6 +1346,8 @@ pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(129);")]
@ -1406,6 +1447,8 @@ pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".strict_pow(5), 32);")]
/// ```
///
/// The following panics because of overflow:
///
/// ```should_panic
/// #![feature(strict_overflow_ops)]
#[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")]