Tracking Issue for inherent unchecked integer methods

[clarfonthey]

This is a tracking issue for the unchecked_* methods on integers.

unchecked_math (stable as of #122520)

impl uN {
    pub const unsafe fn unchecked_add(self, rhs: uN) -> uN;
    pub const unsafe fn unchecked_sub(self, rhs: uN) -> uN;
    pub const unsafe fn unchecked_mul(self, rhs: uN) -> uN;
}
impl iN {
    pub const unsafe fn unchecked_add(self, rhs: iN) -> iN;
    pub const unsafe fn unchecked_sub(self, rhs: iN) -> iN;
    pub const unsafe fn unchecked_mul(self, rhs: iN) -> iN;
}

Steps / History

• Rework the std::iter::Step trait #69659 added unchecked_{add,sub,mul}
• Make unchecked_{add,sub,mul} inherent methods unstably const #85096
• Clean up unchecked_math, separate out unchecked_shifts #115626
• Stabilize unchecked_{add,sub,mul} #122520
• Add assert_unsafe_precondition to unchecked_{add,sub,neg,mul,shl,shr} methods #121571

unchecked_neg

impl iN {
    pub const unsafe fn unchecked_neg(self) -> iN;
}

Steps / History

• Clean up unchecked_math, separate out unchecked_shifts #115626 added unchecked_neg
• Add assert_unsafe_precondition to unchecked_{add,sub,neg,mul,shl,shr} methods #121571

unchecked_shifts

impl uN {
    pub const unsafe fn unchecked_shl(self, rhs: u32) -> uN;
    pub const unsafe fn unchecked_shr(self, rhs: u32) -> uN;
}
impl iN {
    pub const unsafe fn unchecked_shl(self, rhs: u32) -> iN;
    pub const unsafe fn unchecked_shr(self, rhs: u32) -> iN;
}

Steps / History

• Add inherent unchecked_shl, unchecked_shr to integers #85703
• unchecked_{shl|shr} should use u32 as the RHS #103456
• Clean up unchecked_math, separate out unchecked_shifts #115626
• Add assert_unsafe_precondition to unchecked_{add,sub,neg,mul,shl,shr} methods #121571

unchecked_* (aggregate)

impl uN {
    pub const unsafe fn unchecked_add(self, rhs: uN) -> uN;
    pub const unsafe fn unchecked_sub(self, rhs: uN) -> uN;
    pub const unsafe fn unchecked_mul(self, rhs: uN) -> uN;
    pub const unsafe fn unchecked_shl(self, rhs: u32) -> uN;
    pub const unsafe fn unchecked_shr(self, rhs: u32) -> uN;
}
impl iN {
    pub const unsafe fn unchecked_add(self, rhs: iN) -> iN;
    pub const unsafe fn unchecked_sub(self, rhs: iN) -> iN;
    pub const unsafe fn unchecked_mul(self, rhs: iN) -> iN;
    pub const unsafe fn unchecked_shl(self, rhs: u32) -> iN;
    pub const unsafe fn unchecked_shr(self, rhs: u32) -> iN;
    pub const unsafe fn unchecked_neg(self) -> iN;
}

Steps / History

• Rework the std::iter::Step trait #69659 added unchecked_{add,sub,mul}
• Make unchecked_{add,sub,mul} inherent methods unstably const #85096
• Add inherent unchecked_shl, unchecked_shr to integers #85703
• unchecked_{shl|shr} should use u32 as the RHS #103456
• Clean up unchecked_math, separate out unchecked_shifts #115626 added unchecked_neg
• Stabilize unchecked_{add,sub,mul} #122520
• Add assert_unsafe_precondition to unchecked_{add,sub,neg,mul,shl,shr} methods #121571
• Final commenting period (FCP)
• Stabilization PR

Unresolved Questions

• Should the other unchecked intrinsics like exact_div also get inherent versions?
• From Add inherent unchecked_shl, unchecked_shr to integers #85703, consider if distinguishing the different kinds of ub could be useful (UB from overflow like MIN/-1 or MAX+1, LLVM's n[us]w; UB from input range like x/0 or x << -1; UB from lossy like 2/4 or 3 >> 1, LLVM's exact)

Resolved unresolved questions:

• Is unchecked_* the best naming for these? We stabilised unchecked_{add,sub,mul} already, so, yes.

[jordens]

Thanks for this! We are seeing some noticeably faster code in on several embedded DSP applications in cortex-m7 with unchecked_sh[lr]. The additional masking has always bothered me as unnecessary in our case.

[jordens]

One question on consistency and API choice though:

#85703 adds unchecked_sh[rl](self, rhs: Self) while all the other take a u32 as rhs: {overflowing,wrapping,checked}_sh[rl](self, rhs: u32). Why is that?

[cmpute]

I vote for adding exact_div into the library! It could be heavily used in integer factorization and other applications. I'm also developing a checked version of exact division in my crate. I think unchecked_exact_div or unchecked_div_exact will be good names. (I personally prefer div_exact over exact_div as it follows the pattern of div_euclid)

Besides, I'm also thinking about a shorter name for unchecked_, something like raw_add, raw_shl may be easier to type?

[clarfonthey]

I don't think that "raw" is a good naming scheme, since in general, you should not be using these primitives directly. In general, they should be hidden behind other methods that are safe to call. So, I would say that the "unchecked" naming is, at best, not descriptive enough, and that "raw" would be further from the goal of being descriptive.

[scottmcm]

@jordens Agreed the different RHS type is incorrect. I've sent PR #103456.