nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-04-28 02:57:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #127252 - fitzgen:edge-cases-for-bitwise-operations, r=m-ou-se

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

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:
Matthias Krüger 2024-07-24 18:00:36 +02:00 committed by GitHub
commit 720c6f19b7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
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")]