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.

[jdahlstrom]

I was looking for an unchecked_div the other day, as I was trying to get rid of a superfluous zero test, and was surprised that one doesn't exist even under this feature. Any particular reason it's not included (as in, why is it an unresolved question whether there should be one?) Sure, one can use NonZero* as a divisor even on stable to get a safe unchecked div, but still.

[scottmcm]

I think that if there's a reason, it's that there two kinds of unchecked-ness in signed unchecked_div, and it'd be very easy to trigger the INT_MIN / -1 UB when you only remembered to prove that the denominator is non-zero.

I definitely prefer an unsafe type invariant to an unsafe operation where possible, so I think I like the Div<NonZeroTTT> better. After all, with #100428 I think it's x / NonZero::new_unchecked(y), which is very competitive with x.unchecked_div(y), especially if the producer of y can just change to reflect the non-zeroness of its result.

But it might fine to add unchecked_div under this gate and leave it a stabilization question to figure it out if it's worth keeping. We'll see what libs-api has to say.

(Notably, the "the addition overflows" kind of UB is the only kind of UB for unchecked_add, and it's also something that can't be feasibly pre-checked and thus put into a type invariant, the way "it's not zero" can be.)

[ojeda]

For the signed cases, I think it is good to have it for consistency with the other operations and to avoid having to play with unreachable_unchecked() (and hope it gets optimized away) or intrinsics (unstable). Or is there another way to do it in stable?

For the unsigned cases, I think it would still be good to offer it for consistency with the signed case and with the other operations, even if one can use NonZero* (perhaps documenting that as an alternative).