From 434cb5e700b610be31464b6b93b84eeab2ab8c4d Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Tue, 4 Nov 2025 15:33:11 +0100 Subject: [PATCH] document behavior of rotations for n >= BITS --- library/core/src/num/int_macros.rs | 10 ++++++++++ library/core/src/num/uint_macros.rs | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index 16f85c71403a..d5e60f7cc81b 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -275,6 +275,10 @@ macro_rules! int_impl { /// Shifts the bits to the left by a specified amount, `n`, /// wrapping the truncated bits to the end of the resulting integer. /// + /// `rotate_left(n)` is equivalent to applying `rotate_left(1)` a total of `n` times. In + /// particular, a rotation by the number of bits in `self` returns the input value + /// unchanged. + /// /// Please note this isn't the same operation as the `<<` shifting operator! /// /// # Examples @@ -284,6 +288,7 @@ macro_rules! int_impl { #[doc = concat!("let m = ", $rot_result, ";")] /// #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")] + #[doc = concat!("assert_eq!(n.rotate_left(1024), n);")] /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] @@ -298,6 +303,10 @@ macro_rules! int_impl { /// wrapping the truncated bits to the beginning of the resulting /// integer. /// + /// `rotate_right(n)` is equivalent to applying `rotate_right(1)` a total of `n` times. In + /// particular, a rotation by the number of bits in `self` returns the input value + /// unchanged. + /// /// Please note this isn't the same operation as the `>>` shifting operator! /// /// # Examples @@ -307,6 +316,7 @@ macro_rules! int_impl { #[doc = concat!("let m = ", $rot_op, ";")] /// #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")] + #[doc = concat!("assert_eq!(n.rotate_right(1024), n);")] /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index 8cdc7e925b68..02b94a092b91 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -336,6 +336,10 @@ macro_rules! uint_impl { /// Shifts the bits to the left by a specified amount, `n`, /// wrapping the truncated bits to the end of the resulting integer. /// + /// `rotate_left(n)` is equivalent to applying `rotate_left(1)` a total of `n` times. In + /// particular, a rotation by the number of bits in `self` returns the input value + /// unchanged. + /// /// Please note this isn't the same operation as the `<<` shifting operator! /// /// # Examples @@ -345,6 +349,7 @@ macro_rules! uint_impl { #[doc = concat!("let m = ", $rot_result, ";")] /// #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")] + #[doc = concat!("assert_eq!(n.rotate_left(1024), n);")] /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_math", since = "1.32.0")] @@ -360,6 +365,10 @@ macro_rules! uint_impl { /// wrapping the truncated bits to the beginning of the resulting /// integer. /// + /// `rotate_right(n)` is equivalent to applying `rotate_right(1)` a total of `n` times. In + /// particular, a rotation by the number of bits in `self` returns the input value + /// unchanged. + /// /// Please note this isn't the same operation as the `>>` shifting operator! /// /// # Examples @@ -369,6 +378,7 @@ macro_rules! uint_impl { #[doc = concat!("let m = ", $rot_op, ";")] /// #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")] + #[doc = concat!("assert_eq!(n.rotate_right(1024), n);")] /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_math", since = "1.32.0")]