Skip to content

Commit

Permalink
Rollup merge of #121155 - tspiteri:strict-doc-overflow, r=Nilstrieb
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@GuillaumeGomez
GuillaumeGomez committed Feb 15, 2024
2 parents cafa1ae + 675d092 commit 35f8b3d
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 0 deletions.
36 changes: 36 additions & 0 deletions library/core/src/num/int_macros.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -552,6 +554,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -606,6 +610,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -686,6 +692,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -740,6 +748,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -831,11 +841,15 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -901,11 +915,15 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -970,11 +988,15 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -1039,11 +1061,15 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -1121,6 +1147,8 @@ macro_rules! int_impl {
#[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();")]
Expand Down Expand Up @@ -1175,6 +1203,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -1256,6 +1286,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down Expand Up @@ -1340,6 +1372,8 @@ macro_rules! int_impl {
#[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();")]
Expand Down Expand Up @@ -1414,6 +1448,8 @@ macro_rules! int_impl {
#[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);")]
Expand Down
43 changes: 43 additions & 0 deletions library/core/src/num/uint_macros.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down Expand Up @@ -561,6 +563,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down Expand Up @@ -620,6 +624,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down Expand Up @@ -700,6 +706,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down Expand Up @@ -785,6 +793,13 @@ macro_rules! uint_impl {
/// #![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, \
Expand Down Expand Up @@ -840,6 +855,12 @@ macro_rules! uint_impl {
/// #![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, \
Expand Down Expand Up @@ -895,6 +916,13 @@ macro_rules! uint_impl {
/// #![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, \
Expand Down Expand Up @@ -951,6 +979,13 @@ macro_rules! uint_impl {
/// #![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, \
Expand Down Expand Up @@ -1172,6 +1207,8 @@ macro_rules! uint_impl {
#[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();")]
Expand Down Expand Up @@ -1226,6 +1263,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down Expand Up @@ -1307,6 +1346,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down Expand Up @@ -1406,6 +1447,8 @@ macro_rules! uint_impl {
#[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);")]
Expand Down

0 comments on commit 35f8b3d

Please sign in to comment.