Tracking Issue for arithmetic that panics on overflow (strict_* operations)

[rmehri01]

Feature gate: #![feature(strict_overflow_ops)]

This is a tracking issue for doing arithmetic that is guaranteed to panic on overflow, see the ACP for more details: rust-lang/libs-team#270.

Public API

For both signed and unsigned integers:

pub const fn strict_add(self, rhs: Self) -> Self;
pub const fn strict_sub(self, rhs: Self) -> Self;
pub const fn strict_mul(self, rhs: Self) -> Self;
pub const fn strict_div(self, rhs: Self) -> Self;
pub const fn strict_div_euclid(self, rhs: Self) -> Self;
pub const fn strict_rem(self, rhs: Self) -> Self;
pub const fn strict_rem_euclid(self, rhs: Self) -> Self;
pub const fn strict_neg(self) -> Self;
pub const fn strict_shl(self, rhs: u32) -> Self;
pub const fn strict_shr(self, rhs: u32) -> Self;
pub const fn strict_pow(self, exp: u32) -> Self;

Additionally, signed integers have:

pub const fn strict_add_unsigned(self, rhs: $UnsignedT) -> Self;
pub const fn strict_sub_unsigned(self, rhs: $UnsignedT) -> Self;
pub const fn strict_abs(self) -> Self;

And unsigned integers have:

pub const fn strict_add_signed(self, rhs: $SignedT) -> Self;

Steps / History

• Implementation: Implement strict integer operations that panic on overflow #116090
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Should we have strict_neg on unsigned types? It's basically identical to assert_ne!(x, 0).
• Should we have strict_div, strict_rem, strict_div_euclid and strict_rem_euclid on unsigned types? Those will never panic; they are identical to the non-strict versions.

Footnotes

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

[tspiteri]

I have implemented something similar to this in the fixed crate, for example FixedI32::unwrapped_add, together with an Unwrapped wrapper similar to Wrapping and Saturating.

I used the prefix unwrapped_ as I thought it can be interpreted mainly (a) as checked followed by unwrap, so that it is unwrapped, but also kinda (b) as not wrapping, since panicking is done instead of wrapping. I found this double interpretation amusing, which is why I stuck with that prefix.