Tracking Issue for `int_lowest_highest_one`

[Gnurou]

Feature gate: #![feature(int_lowest_highest_one)]

This is a tracking issue for the lowest_one and highest_one methods on primitive integer types and their NonZero counterparts.

These methods provide an efficient way to find the index of the least significant (lowest) and most significant (highest) set bit in an integer. They are common, low-level operations often supported directly by hardware (e.g. BSF/BSR on x86) and frequently used in systems programming, such as in OS kernels for managing bitmasks.

Public API

impl {u8, i8, u16, i16, u32, i32, u64, i64, u128, i128, usize, isize} {
    const fn lowest_one(self) -> Option<u32>;
    const fn highest_one(self) -> Option<u32>;
}

// For all `T` in the impl block above.
impl NonZero<T> {
    const fn lowest_one(self) -> u32;
    const fn highest_one(self) -> u32;
}

Steps / History

• Implementation:
  • ACP Accepted with amendments: first_set_bit and last_set_bit for integer types libs-team#631
  • Implementation PR: Implement feature int_lowest_highest_one for integer and NonZero types #145381
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

None.

Resolved Questions

• Methods name
  • Although the general agreement is to use lowest_one and highest_one, we want to maintain consistency with ACP: add least_significant_one and most_significant_one to integer types and NonZero types libs-team#467 (Tracking Issue for isolate_most_least_significant_one #136909).
  • Renaming done by PR num: Rename isolate_most_least_significant_one functions #144971, which seems to confirm lowest_one and highest_one for this feature.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[tgross35]

(Updated the ACP link, #631 is a very different issue on this repo compared to rust-lang/libs-team#631 :) )

[okaneco]

There was one other naming concern that I think should be considered before stabilization, whether these functions should be {highest,lowest}_one_index rather than {highest,lowest}_one.

rust-lang/libs-team#631 (comment)

For the bikeshed: the parallels with the isolate_* methods seem neat but I can already see myself writing x.highest_one() where I meant x.isolate_highest_one() . Perhaps both sets of methods should have an extra word to disambiguate them from each other isolate_{highest,lowest}_one/{highest,lowest}_one_index. I'll probably feel the same about most alternatives as long as they maintain the parallels with isolate_*.

[hanna-kruppe]

I have mellowed on this since originally posting it because I realized these pairs of methods never have the same return type for any Self type:

• $int::highest_one returns Option<u32>, while $int::isolate_highest_one returns $int
• NonZero<$int>::highest_one returns $int while NonZero<$int>::isolate_highest_one returns NonZero<$int>

This doesn't prevent every possible confusion but it does insert a compiler-error-shaped speedbump into many of the most plausible ones.