Tracking Issue for `uint_bit_width`

[sorairolake]

Feature gate: #![feature(uint_bit_width)]

This is a tracking issue for the bit_width method that return the minimum number of bits required to represent an unsigned integer.

This method is implemented for the primitive unsigned integer types and unsigned NonZero<T>.

Public API

impl {u8,u16,u32,u64,u128,usize} {
    pub const fn bit_width(self) -> u32;
}

// For all unsigned `T`.
impl NonZero<T> {
    pub const fn bit_width(self) -> NonZero<u32>;
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: ACP: Add {u8,u16,u32,u64,u128,usize}::bit_len libs-team#598
• Implementation:
  • feat: Add bit_width for unsigned integer types #142328
  • feat: Add bit_width for unsigned NonZero<T> #148797
• Final comment period (FCP)¹
• Stabilization PR Stabilize feature uint_bit_width #155131

Unresolved Questions

• None yet.

Footnotes

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

[tgross35]

The name bit_width could be confused with a method that returns the width of set bits rather than the highest bit and the lsb. For example, with 0b0000_1010_u8, "bit width" could mean 3 (all set bits can be contained within a shifted mask with 3 set bits, 0b0111 << 1) or 4 (all set bits can be contained within a non-shifted mask with four set bits, 0b1111).

Not that I have any great suggestion for the bikeshed here. Maybe trailing_set_bits.

[sorairolake]

In other languages such as Python and C23, methods with the same purpose as this are named bit_length or bit_width. These names are very similar to this method, so I think it's unlikely that users will get confused.

[tgross35]

They most certainly can if they haven't used the bit_width method in one of those languages :)

[sorairolake]

The initial method name was derived from C23 and may be confusing to users unfamiliar with it. There may be more appropriate method name that is easier to understand for all users, including those who are not familiar with other languages such as Python and C23.

[okaneco]

For context, bit_width was originally called log2p1 (log2 plus 1, except when x == 0...) before being renamed along with the other bit manipulation functions new for C++20.
https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1956r1.pdf
C23 settled on similar names.
https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3022.htm#design-bit-stdc_bit_ceil

C++20	C23	Rust
bit_ceil	stdc_bit_ceil	next_power_of_two
bit_floor	stdc_bit_floor	isolate_most_significant_one (unstable)
bit_width	stdc_bit_width	bit_width

---

bit_width is more fitting in context with bit_ceil and bit_floor, but I don't have a better Rust-y name to suggest. count_occupied_bits comes to mind but could also be misinterpreted as a population count.

[ChrisDenton]

I think bit_width is fine. We often don't encode the full meaning into function names and I think the behaviour of this function is the far more commonly used one.

Sometimes people do just have to read the docs before using a function.

[hanna-kruppe]

I’m not saying the “span from most significant 1 to least significant 1” reading is unreasonable, but it does seem niche to me so the name seems like a fine compromise. I haven’t used bit_width in C23 or other languages that call it that (only Python’s bit_len) but in every other context where I talk or hear about the “bit width” of an integer, it refers to number of bits needed or used to fully represent a number, often with an “ignoring sign/zero extension to wider type” aspect but never with a “dropping trailing zeros” aspect. For example, I may call a number in 0..16 “four bits wide” even if I always store it in u8, but I don’t call 16 “one bit wide”.