Tracking Issue for `uint_carryless_mul`

View all comments

Feature gate: #![feature(uint_carryless_mul)]

This is a tracking issue for functions that return the carryless product (XOR multiplication) of unsigned integers.
carryless_mul returns the low-order bits of the result, and widening_carryless_mul returns the full result in the next wider unsigned integer type.

Public API

widening_carryless_mul is not implemented for u128 because there is no larger integer type to return.

impl uN {
    /// Returns the low-order bits of the carryless product of `self` and `rhs`.
    pub const fn carryless_mul(self, rhs: Self) -> Self;
}

impl u8 {
    /// Returns the full carryless product result of `self` and `rhs` in the next wider power-of-two unsigned integer.
    pub const fn widening_carryless_mul(self, rhs: Self) -> u16;
}
impl u16 {
    pub const fn widening_carryless_mul(self, rhs: Self) -> u32;
}
impl u32 {
    pub const fn widening_carryless_mul(self, rhs: Self) -> u64;
}
impl u64 {
    pub const fn widening_carryless_mul(self, rhs: Self) -> u128;
}

Steps / History

• ACP: https://github.com/rust-lang/libs-team/issues/738
• Implementation: https://github.com/rust-lang/rust/pull/152132
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• carrying_carryless_mul?: In the ACP, there was a voicing of desire for a function that returned the product as a 2-sized tuple with the same sized integer, (Self, Self).
• Evaluate the quality of codegen before stabilization: Not all architectures have these operations as hardware instructions and the instructions are not uniform in their integer coverage, nor are the hardware instructions part of the baseline of some targets. However, even without hardware instructions, the intrinsics that these functions wrap should produce equal or better code than a (naive) user implementation.

Read the ACP in libs-team issue 738 and the implementation in pull request 152132, then review the feature-gated public API and the stabilization guidance linked in the issue. Done means resolving the carrying_carryless_mul and codegen questions and completing a stabilization PR after the final comment period.