mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add edge-case examples to {count,leading,trailing}_{ones,zeros} methods

Browse Source 
Some architectures (i386) do not define a "count leading zeros" instruction,
they define a "find first set bit" instruction (`bsf`) whose result is undefined
when given zero (ie none of the bits are set). Of this family of bitwise
operations, I always forget which of these things is potentially undefined for
zero, and I'm also not 100% sure that Rust provides a hard guarantee for the
results of these methods when given zero. So I figured there are others who have
these same uncertainties, and it would be good to resolve them and answer the
question via extending these doc examples/tests.

See https://en.wikipedia.org/wiki/Find_first_set#Hardware_support for more info
on i386 and `bsf` on zero.
This commit is contained in:
Nick Fitzgerald 2024-07-02 15:00:09 -07:00
parent 49ff3909fb
commit 91af6b5122
1 changed files with 35 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
library/core/src/num/uint_macros.rs
View File

@ -65,8 +65,13 @@ macro_rules! uint_impl {
///
/// ```
#[doc = concat!("let n = 0b01001100", stringify!($SelfT), ";")]
///
/// assert_eq!(n.count_ones(), 3);
///
#[doc = concat!("let max = ", stringify!($SelfT),"::MAX;")]
#[doc = concat!("assert_eq!(max.count_ones(), ", stringify!($BITS), ");")]
///
#[doc = concat!("let zero = 0", stringify!($SelfT), ";")]
/// assert_eq!(zero.count_ones(), 0);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
@ -86,7 +91,11 @@ macro_rules! uint_impl {
/// Basic usage:
///
/// ```
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 0);")]
#[doc = concat!("let zero = 0", stringify!($SelfT), ";")]
#[doc = concat!("assert_eq!(zero.count_zeros(), ", stringify!($BITS), ");")]
///
#[doc = concat!("let max = ", stringify!($SelfT),"::MAX;")]
/// assert_eq!(max.count_zeros(), 0);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
@ -108,8 +117,13 @@ macro_rules! uint_impl {
///
/// ```
#[doc = concat!("let n = ", stringify!($SelfT), "::MAX >> 2;")]
///
/// assert_eq!(n.leading_zeros(), 2);
///
#[doc = concat!("let zero = 0", stringify!($SelfT), ";")]
#[doc = concat!("assert_eq!(zero.leading_zeros(), ", stringify!($BITS), ");")]
///
#[doc = concat!("let max = ", stringify!($SelfT),"::MAX;")]
/// assert_eq!(max.leading_zeros(), 0);
/// ```
#[doc = concat!("[`ilog2`]: ", stringify!($SelfT), "::ilog2")]
#[stable(feature = "rust1", since = "1.0.0")]
@ -130,8 +144,13 @@ macro_rules! uint_impl {
///
/// ```
#[doc = concat!("let n = 0b0101000", stringify!($SelfT), ";")]
///
/// assert_eq!(n.trailing_zeros(), 3);
///
#[doc = concat!("let zero = 0", stringify!($SelfT), ";")]
#[doc = concat!("assert_eq!(zero.trailing_zeros(), ", stringify!($BITS), ");")]
///
#[doc = concat!("let max = ", stringify!($SelfT),"::MAX;")]
#[doc = concat!("assert_eq!(max.trailing_zeros(), 0);")]
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
@ -150,8 +169,13 @@ macro_rules! uint_impl {
///
/// ```
#[doc = concat!("let n = !(", stringify!($SelfT), "::MAX >> 2);")]
///
/// assert_eq!(n.leading_ones(), 2);
///
#[doc = concat!("let zero = 0", stringify!($SelfT), ";")]
/// assert_eq!(zero.leading_ones(), 0);
///
#[doc = concat!("let max = ", stringify!($SelfT),"::MAX;")]
#[doc = concat!("assert_eq!(max.leading_ones(), ", stringify!($BITS), ");")]
/// ```
#[stable(feature = "leading_trailing_ones", since = "1.46.0")]
#[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
@ -171,8 +195,13 @@ macro_rules! uint_impl {
///
/// ```
#[doc = concat!("let n = 0b1010111", stringify!($SelfT), ";")]
///
/// assert_eq!(n.trailing_ones(), 3);
///
#[doc = concat!("let zero = 0", stringify!($SelfT), ";")]
/// assert_eq!(zero.trailing_ones(), 0);
///
#[doc = concat!("let max = ", stringify!($SelfT),"::MAX;")]
#[doc = concat!("assert_eq!(max.trailing_ones(), ", stringify!($BITS), ");")]
/// ```
#[stable(feature = "leading_trailing_ones", since = "1.46.0")]
#[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]