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

• ACP: Add operations for easy arithmetic that panics on overflow libs-team#270
• Implementation: Implement strict integer operations that panic on overflow #116090
• Final comment period (FCP)¹
• Stabilization PR: Stabilize strict_overflow_ops #144682

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.

[daira]

Should we have strict_neg on unsigned types? It's basically identical to assert_ne!(x, 0).

You mean assert_eq!(x, 0). And no, it's pointless.

[thaliaarchi]

I'm interested in contributing to fix issues with this or championing stabilization. (However, I haven't stabilized something before.)

• I think unsigned checked_neg should be included. Although it's not terribly useful on it's own, there's a precedent for including it and it smooths out macro polymorphism. Unsigned checked_neg is stable with the same triviality. (Unsigned wrapping_neg and overflowing_neg use wrapping operations.)

• strict_{div,rem}_{ceil,floor} should be implemented for consistency.

  However, there still large gaps in division and modulo rounding for the other operations (Tracking Issue for int_roundings #88581): rem_{ceil,floor}, {checked,overflowing,strict,wrapping}_{div,rem}_{ceil,floor}, saturating_rem, saturating_{div,rem}_{ceil,euclid,floor} are not implemented. If the implementation of the strict ones is not straightforward, punting that to another PR with the others might make sense. I wrote a document tracking rounding of division and modulo operations across languages, which may be useful.

• I agree a Strict<T> wrapper would be good (in another PR).

What would a good next step be?

[pascaldekloe]

Any redundant strict_ methods on unsigned types can help with programming generics and traits sometimes. Considering the utilization of such primitives, that "sometimes" may add up to a huge number of usecases.

I'd love to see even better support for checked on language level like Zig does. For example, Rust could read +? as checked add, +| as saturating add, and +% as overflowing add.