From 723336d835a567f8087e640871e1b61ae085bc6f Mon Sep 17 00:00:00 2001
From: Stepan Koltsov <stepan.koltsov@gmail.com>
Date: Sat, 27 Jul 2024 00:06:16 +0100
Subject: [PATCH] Document int.checked_shl(BITS - 1)

Not obvious.
---
 library/core/src/num/int_macros.rs  | 2 ++
 library/core/src/num/mod.rs         | 8 ++++++++
 library/core/src/num/uint_macros.rs | 3 +++
 3 files changed, 13 insertions(+)

diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs
index d40e02352a1d0..591ae586c73c0 100644
--- a/library/core/src/num/int_macros.rs
+++ b/library/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 --git a/library/core/src/num/mod.rs b/library/core/src/num/mod.rs
index 4e8e0ecdde998..dc3614871a05e 100644
--- a/library/core/src/num/mod.rs
+++ b/library/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 --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs
index e6bdc4d450d4a..dec444428cae8 100644
--- a/library/core/src/num/uint_macros.rs
+++ b/library/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")]