Tracking Issue for `isolate_most_least_significant_one`

[okaneco]

Feature gate: #![feature(isolate_most_least_significant_one)]

This is a tracking issue for functions that return an integer with only the most significant set bit or only the least significant set bit masked from the input integer.

The functions are implemented for unsigned, signed, and NonZeroT integer types.

Public API

impl {u8, u16, u32, u64, u128, usize} {
    const fn isolate_highest_one(self) -> Self;
    const fn isolate_lowest_one(self) -> Self;
}
impl {i8, i16, i32, i64, i128, isize} {
    const fn isolate_highest_one(self) -> Self;
    const fn isolate_lowest_one(self) -> Self;
}
impl NonZeroT {
    const fn isolate_highest_one(self) -> Self;
    const fn isolate_lowest_one(self) -> Self;
}

Steps / History

• Implementation:
  • ACP Accepted ACP: add least_significant_one and most_significant_one to integer types and NonZero types libs-team#467
  • Implementation PR: Implement feature isolate_most_least_significant_one for integer types #136910
  • num: Rename isolate_most_least_significant_one functions #144971
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

Function name length

RESOLVED - #136909 (comment)
Functions have been renamed to isolate_highest_one/isolate_lowest_one

The initial function names are taken from the libs-api suggestions in the ACP, but they are quite verbose.

The names need to indicate that the integer being returned is the input with only the most/least significant set bit and not whether the most/least significant bit is 0 or 1. Hence, isolate is suggested as a prefix to disambiguate the meaning.

assert_eq!(u8::isolate_most_significant_one(0b01100100), 0b01000000);
assert_eq!(u8::isolate_least_significant_one(0b01100100), 0b00000100);

Possible names (non-exhaustive):

• isolate_least_significant_one / isolate_most_significant_one
• least_sig_one / most_sig_one
• lowest_one / highest_one
• lowest_bit_set / highest_bit_set
• isolate_lowest_one / isolate_highest_one
• trailing_one / leading_one

Footnotes

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

[joshtriplett]

We re-discussed the naming of these functions in today's @rust-lang/libs-api meeting.

We were favorable towards isolate_highest_one and isolate_lowest_one.

This came up in the context of rust-lang/libs-team#631 , which would provide highest_one and lowest_one (which return indexes, unlike these functions that return the bit).

[okaneco]

PR to rename these functions - #144971

I've updated the issue to reflect the decision to rename.