Auto merge of rust-lang#128255 - stepancheg:doc-shl, r=scottmcm

Document 0x10.checked_shl(BITS - 1) does not overflow

Not obvious.

Author: bors

Diff for: core/src/num/int_macros.rs

@@ -1223,6 +1223,7 @@ macro_rules! int_impl {
         /// ```
         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);")]
+        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(", stringify!($BITS_MINUS_ONE), "), Some(0));")]
         /// ```
         #[stable(feature = "wrapping", since = "1.7.0")]
         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
@@ -2600,6 +2601,7 @@ macro_rules! int_impl {
         /// ```
         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")]
         /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));
+        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shl(", stringify!($BITS_MINUS_ONE), "), (0, false));")]
         /// ```
         #[stable(feature = "wrapping", since = "1.7.0")]
         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]

Diff for: core/src/num/mod.rs

@@ -483,6 +483,7 @@ impl u8 {
         ActualT = u8,
         SignedT = i8,
         BITS = 8,
+        BITS_MINUS_ONE = 7,
         MAX = 255,
         rot = 2,
         rot_op = "0x82",
@@ -1097,6 +1098,7 @@ impl u16 {
         ActualT = u16,
         SignedT = i16,
         BITS = 16,
+        BITS_MINUS_ONE = 15,
         MAX = 65535,
         rot = 4,
         rot_op = "0xa003",
@@ -1145,6 +1147,7 @@ impl u32 {
         ActualT = u32,
         SignedT = i32,
         BITS = 32,
+        BITS_MINUS_ONE = 31,
         MAX = 4294967295,
         rot = 8,
         rot_op = "0x10000b3",
@@ -1168,6 +1171,7 @@ impl u64 {
         ActualT = u64,
         SignedT = i64,
         BITS = 64,
+        BITS_MINUS_ONE = 63,
         MAX = 18446744073709551615,
         rot = 12,
         rot_op = "0xaa00000000006e1",
@@ -1191,6 +1195,7 @@ impl u128 {
         ActualT = u128,
         SignedT = i128,
         BITS = 128,
+        BITS_MINUS_ONE = 127,
         MAX = 340282366920938463463374607431768211455,
         rot = 16,
         rot_op = "0x13f40000000000000000000000004f76",
@@ -1216,6 +1221,7 @@ impl usize {
         ActualT = u16,
         SignedT = isize,
         BITS = 16,
+        BITS_MINUS_ONE = 15,
         MAX = 65535,
         rot = 4,
         rot_op = "0xa003",
@@ -1240,6 +1246,7 @@ impl usize {
         ActualT = u32,
         SignedT = isize,
         BITS = 32,
+        BITS_MINUS_ONE = 31,
         MAX = 4294967295,
         rot = 8,
         rot_op = "0x10000b3",
@@ -1264,6 +1271,7 @@ impl usize {
         ActualT = u64,
         SignedT = isize,
         BITS = 64,
+        BITS_MINUS_ONE = 63,
         MAX = 18446744073709551615,
         rot = 12,
         rot_op = "0xaa00000000006e1",

Diff for: core/src/num/uint_macros.rs

@@ -9,6 +9,7 @@ macro_rules! uint_impl {
         // literal is fine if they need to be multiple code tokens.
         // In non-comments, use the associated constants rather than these.
         BITS = $BITS:literal,
+        BITS_MINUS_ONE = $BITS_MINUS_ONE:literal,
         MAX = $MaxV:literal,
         rot = $rot:literal,
         rot_op = $rot_op:literal,
@@ -1413,6 +1414,7 @@ macro_rules! uint_impl {
         /// ```
         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);")]
+        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(", stringify!($BITS_MINUS_ONE), "), Some(0));")]
         /// ```
         #[stable(feature = "wrapping", since = "1.7.0")]
         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
@@ -2541,6 +2543,7 @@ macro_rules! uint_impl {
         /// ```
         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));")]
         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));")]
+        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shl(", stringify!($BITS_MINUS_ONE), "), (0, false));")]
         /// ```
         #[stable(feature = "wrapping", since = "1.7.0")]
         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]