Tracking issue for `wrapping` stabilization

[aturon]

The std::num::wrapping module provides a trait, OverflowingOps, that permits overflowing arithmetic on primitive types and tells whether an overflow occurred.

Other methods, like saturating_add and wrapping_add, are included directly as inherent methods on these types.

It's not clear whether the overflowing_foo methods are useful, and if so, whether there's any reason for them to live on a trait. Ideally, if we kept them, they'd move onto the primitive types, and the wrapping module would be removed.

[petrochenkov]

cc rust-lang/rfcs#1218 (comment)

[bmastenbrook]

I'm currently using the overflowing_* operations in a specialized bignum implementation, and it's a bit of a bother that they aren't stable. Given that these are implemented via LLVM intrinsics, is there any good reason for them to be removed? If they're not going to be removed, is there any way I can contribute to the stabilization?

[aturon]

Nominating for discussion at libs team meeting.

[alexcrichton]

🔔 This issue is now entering its final comment period for tweaked stabilization 🔔

In triage discussion yesterday it was decided that the trait in this module should move to inherent methods on all the primitives, and we should likely fill out all the checked_* and saturating_* methods as well. There are some missing (like saturating_mul or checked_neg), and making sure we've got a full suite everywhere would ensure consistency!

[petrochenkov]

I'd like to remind the libs team about existence of RFC 1218.
One of the main points of it is to stabilize integer casts together with other arithmetic operations.
A comment to the RFC, which I linked above, also suggests an alternative to making checked_* and friends inherent methods, namely traits like

// Possibly an unstable trait with stable methods
trait IntAdd<Rhs = Self>: Add<Rhs> {
    fn wrapping_add(self) -> Self::Output;
    fn checked_add(self) -> Option<Self::Output>;
    /* other add operations */
}

Casts can't be implemented as inherent methods without double dispatch through yet another trait. Arithmetic operations like checked_add can be inherent methods, if the operands are supposed to be always homogeneous, but I don't see motivation for preferring inherent methods to a trait in this case.
I'm against stabilizing arithmetic methods unless they are gathered together with casts and arranged in one coherent picture.

[glaebhoerl]

@petrochenkov I don't see the reason for preferring inherent methods over traits either (maybe it's just not having to import the trait?), but given that the existing wrapping_op methods have already been stabilized as inherent methods, doing likewise for the others would at least be consistent.

[SimonSapin]

Arithmetic operations like checked_add can be inherent methods, if the operands are supposed to be always homogeneous

Primitive numeric types only implement Add with homogeneous operands.

And yes, the advantage of inherent methods is to not require users to import the trait and not "pollute" the prelude.

[aturon]

To clarify, yes, part of the motivation of inherent methods was doing away with the large soup of traits we used to have (and as @SimonSapin says, this allows you to avoid an explicit import). For numerics, specifically, we tried to move in the direction of concrete types and inherent methods, leaving abstractions/numeric hierarchy to traits than can be built externally and perhaps added later.

This has been a general approach in the standard library: avoid premature abstraction. The trait system makes it easy to create abstractions after the fact, and we prefer to see strong use cases before committing to them.

Finally, as @glaebhoerl points out, the existing stable API surface already takes this approach.

I'm against stabilizing arithmetic methods unless they are gathered together with casts and arranged in one coherent picture.

Most arithmetic methods are already stable. I don't understand the concern about packaging them together; can you elaborate? As I mentioned above, we're shy about numeric abstractions, having tried several times before 1.0 to build a hierarchy, before ultimately ditching the whole thing. I continue to think this needs to be baked out of tree, and don't see why it can't be.

[petrochenkov]

Ok, I've reviewed this again (I haven't touched my RFC or used these methods for a long time) and changed my position from "mildly against" to "don't care". Inherent methods don't prevent having equivalent trait methods in the future and inconsistencies between casts and other operators are not the end of the world.

[SimonSapin]

This is maybe off-topic, but since casts were mentioned I’d like to have fallible casts like impl u64 { to_u32(self) -> Result<u32, ()>

[eddyb]

Is there any reason why Wrapping<T> doesn't implement Neg?

[aturon]

@eddyb Not that I know of. Probably just an oversight.

[huonw]

cc #23975

[alexcrichton]

The libs team discussed this in triage recently and the decision was to stabilize