Meta-ACP: Integer cast methods

[clarfonthey]

This is based upon the meeting discussion on these various active tracking issues:

• Tracking Issue for integer_casts rust#157388
• Tracking Issue for integer extension and truncation methods rust#154330
• Tracking Issue for integer_cast_extras rust#154650

And these ACPs: (just one atm)

• ACP: convenient numeric conversions dependent on overflow-checks #811

And these stable methods:

• iN::cast_unsigned
• uN::cast_signed

I've generated a table which unfortunately has to be raw HTML because GHM tables are fragile and awful. (Meta point: if you want to make your own table you can just ignore the top row and post it as GFM if it's difficult otherwise. I just wanted to have the nicer headers.)

Hopefully things are easy to read, but specifically for the sizes, the notation of i2N and u2N are used to indicate which integer in a conversion is larger, and X indicates a conversion that is not possible. (Note that 2N is a placeholder here and it's fine to do higher powers of two, e.g. iN → i2N includes i8 → i32, etc.)

The remaining cell contents indicate either whether an operation is lossless or the rounding mode if it's lossy. Note that "default" refers to the default overflow behaviour and not the default casting behaviour, since the default casting behaviour is always wrapping whereas the default overflow behaviour panics in debug mode.

	tracked	signed ↔ signed			unsigned ↔ unsigned			signed ↔ unsigned
		i2N→iN	iN→iN	iN→i2N	u2N→uN	uN→uN	uN→u2N	i2N→uN	iN→uN	uN→i2N	uN→iN	u2N→iN
widen	154330	X	noop	noop	X	noop	noop	X	X	X	X	X
truncate	154330	wrap	noop	X	wrap	noop	X	X	X	X	X	X
saturating_truncate	154330	saturate	noop	X	saturate	noop	X	X	X	X	X	X
checked_truncate	154330	check	noop	X	check	noop	X	X	X	X	X	X
saturating_cast	157388	saturate	noop	noop	saturate	noop	noop	saturate	saturate	noop	saturate	saturate
wrapping_cast	157388	wrap	noop	noop	wrap	noop	noop	wrap	wrap	noop	wrap	wrap
checked_cast	157388	check	noop	noop	check	noop	noop	check	check	noop	check	check
strict_cast	157388	strict	noop	noop	strict	noop	noop	strict	strict	noop	strict	strict
unchecked_cast	157388	UB	noop	noop	UB	noop	noop	UB	UB	noop	UB	UB
cast	libs811	default	noop	noop	default	noop	noop	default	default	noop	default	default
checked_cast_signed	154650	X	X	X	X	X	X	X	X	X	check	X
saturating_cast_signed	154650	X	X	X	X	X	X	X	X	X	saturate	X
strict_cast_signed	154650	X	X	X	X	X	X	X	X	X	strict	X
cast_signed	stable	X	X	X	X	X	X	X	X	X	wrap	X
checked_cast_unsigned	154650	X	X	X	X	X	X	check	check	X	X	X
saturating_cast_unsigned	154650	X	X	X	X	X	X	saturate	saturate	X	X	X
strict_cast_unsigned	154650	X	X	X	X	X	X	strict	strict	X	X	X
cast_unsigned	stable	X	X	X	X	X	X	X	wrap	X	X	X

Adding notes in a few dedicated sections:

Truncate naming bikeshed

We used "narrowing" a lot in the meeting and I don't think this is necessarily the right name, but I'm going to use "narrow" just because the connotation of "truncate" is very confusing.

Personally, I think that "shrinking" would be better than narrowing since we're talking about the range of the type, although this is mostly a hill I don't think we should die on.

Note that naming wrapping_narrow versus wrapping_shrink is the main point of contention, since otherwise methods like saturating_narrow and saturating_shrink seem fine. We could also just accept that wrapping_narrow is truncate and use e.g. saturating_narrow for everything else.

Widen/Narrow overlap

Right now, widen and narrow overlap on same-type conversions; both allow identity conversions, I think this probably shouldn't be the case. To me, it would make sense for widen to always be a lossless conversion and for narrow to always be a lossy conversion, which means that widen would allow >= size but narrow would require < instead of <= (current behaviour).

Widen/Narrow signed/unsigned interplay

Right now, widen/narrow never change signedness, but I think this should be allowed for conversions which strictly increase or decrease the range of the type. So, in our table, we would allow uN → i2N for widening unsigned to signed integers, and i2N → uN for truncating signed to unsigned integers, but everything else remains the same. (Note: iN → uN would be adding range, so, not strictly narrowing the range.)

Missing narrowing/explicit signedness conversions

narrow is missing strict, unchecked, and a default overflow version; the default is currently wrapping, which should probably be renamed to wrapping_narrow. See bikeshed above for more info on that particular method.

This also applies for the explicit _signed and _unsigned methods, although more on those later.

"Default" overflow method

There is some genuine confusion to be had with the default overflow method not being the default casting method (as), and maybe it might be worth considering a change to this on an edition boundary to pair with this. That would require lang to get involved, but personally, it makes sense that x.cast() and x as _ do the same thing and that is not what we're proposing at the moment, unless we were to propose that on an edition boundary and just make x.cast() do edition-default behaviour.

(From my understanding, this is feasible, just, it would require an RFC and a lot of questions to be resolved on how to configure this. My guess is it would just split off of overflow checks into a separate flag to be configured, and we would have to explicitly decide how we want to configure that. Note that the main proposal here is this being a cargo edition, not a crate edition, with cargo defaulting the flag for the debug/release profiles and not different crates having different overflow behaviours, which feels wrong.)

As an alternative to (gestures) we could just call this "lax" and name accordingly. (But, I think lax_cast instead of cast is annoying.)

Explicit signedness methods

Personally: I don't like these at all. The way it currently works is the casts normally allow all interplay between signedness, and the dedicated signedness methods only work for integers of the same size.

I would instead expect this to actually be reversed: instead of having cast_signed methods on unsigned and cast_unsigned methods on signed, have cast_signed methods on signed and cast_unsigned methods on unsigned which explicitly prevent the signedness from changing. To me, there doesn't seem much value in limiting the casts otherwise, since if there can be rounding going from i32 to u32, then I don't know why you don't let me go from i32 to u16, for example. The only argument against would be having to specify the type, but I kind of expect that to never matter since the only real case we're optimising for is e.g. being able to cast from uN to iN, perform some maths, then cast back to uN, which… what are you even doing?

My recommended table

This is based upon the combination of feedback above, and what I think would be best to stabilise. Mostly to reference for later. It removes the tracking issues.

It does not resolve the narrowing naming bikeshed.

Differences from above table are marked ❗.

	signed ↔ signed			unsigned ↔ unsigned			signed ↔ unsigned
	i2N→iN	iN→iN	iN→i2N	u2N→uN	uN→uN	uN→u2N	i2N→uN	iN→uN	uN→i2N	uN→iN	u2N→iN
widen	X	noop	noop	X	noop	noop	X	X	noop❗	X	X
saturating_narrow	saturate	X❗	X	saturate	X❗	X	saturate❗	X	X	X	X
wrapping_narrow	wrap	X	X	wrap	X	X	wrap	X	X	X	X
checked_narrow	check	X❗	X	check	X❗	X	check❗	X	X	X	X
strict_narrow	strict	X	X	strict	X	X	strict	X	X	X	X
unchecked_narrow	UB	X	X	UB	X	X	UB	X	X	X	X
narrow	default❗	X❗	X	default❗	X❗	X	default❗	X	X	X	X
saturating_cast	saturate	noop	noop	saturate	noop	noop	saturate	saturate	noop	saturate	saturate
wrapping_cast	wrap	noop	noop	wrap	noop	noop	wrap	wrap	noop	wrap	wrap
checked_cast	check	noop	noop	check	noop	noop	check	check	noop	check	check
strict_cast	strict	noop	noop	strict	noop	noop	strict	strict	noop	strict	strict
unchecked_cast	UB	noop	noop	UB	noop	noop	UB	UB	noop	UB	UB
cast	default	noop	noop	default	noop	noop	default	default	noop	default	default
saturating_cast_signed	saturate❗	noop❗	noop❗	X	X	X	X	X	X	X❗	X
wrapping_cast_signed	wrap	noop	noop	X	X	X	X	X	X	X	X
checked_cast_signed	check❗	noop❗	noop❗	X	X	X	X	X	X	X❗	X
strict_cast_signed	strict❗	noop❗	noop❗	X	X	X	X	X	X	X❗	X
unchecked_cast_signed	UB	noop	noop	X	X	X	X	X	X	X	X
cast_signed	default❗	noop❗	noop❗	X	X	X	X	X	X	default❗	X
saturating_cast_unsigned	X	X	X	saturate❗	noop❗	noop❗	X❗	X❗	X	X	X
wrapping_cast_unsigned	X	X	X	wrap	noop	noop	X	X	X	X	X
checked_cast_unsigned	X	X	X	check❗	noop❗	noop❗	X❗	X❗	X	X	X
strict_cast_unsigned	X	X	X	strict❗	noop❗	noop❗	X❗	X❗	X	X	X
unchecked_cast_unsigned	X	X	X	UB	noop	noop	X	X	X	X	X
cast_unsigned	X	X	X	default❗	noop❗	noop❗	X	default❗	X	X	X

[okaneco]

For the explicit signedness methods, cast_signed and cast_unsigned were already stabilized in 1.87 for reinterpreting bits as signed/unsigned which clashes with the proposal in the second table.

[RalfJung]

I like names that encourage one to think about integers as integers, not bit vectors. The semantics of as can be fully described without ever talking about bits being (re)interpreted: take the mathematical integer represented by the input value, and return the unique integer that satisfies both of the following properties:

• it lies in the range of the output type
• it is equivalent to the input modulo 2^output-size

I think that's the level of abstraction we should use for these methods. So in that sense I do not like "truncate".

[clarfonthey]

For the explicit signedness methods, cast_signed and cast_unsigned were already stabilized in 1.87 for reinterpreting bits as signed/unsigned which clashes with the proposal in the second table.

Oops, I should have totally checked the rustdoc for stable methods too. I'll update the table later.

[jdahlstrom]

I also find "truncate" confusing because it's also used with floats. Even though it's in principle the same operation, removing/zeroing digits, I agree with Ralf that that's not really the best or most intuitive way to think about it.

[clarfonthey]

Table updated: cast_signed and cast_unsigned now list the currently stable versions.

[joshtriplett]

Bug in the table of our current state: the *_cast_unsigned methods are listed as existing for "i2N→uN", which they don't and shouldn't.

[joshtriplett]

I don't think we should make any change to the cast_signed/cast_unsigned methods (leaving aside the fact that they're stable). cast_signed should only exist on unsigned, and vice versa, and they should have only one target, the same-size target that just reinterprets the bits.

No objection to adding the methods proposed by 154650, but they should likewise be same-size only and only exist on the opposite signedness.

[joshtriplett]

Widen/Narrow overlap

I don't think we should change this. It's useful to support the no-op case in both cases.

Widen/Narrow signed/unsigned interplay

The point of widen and narrow is precisely that they do only the one thing. If you want to do multiple things at once, call cast instead. These should only exist within the same signedness.

[joshtriplett]

Here's what I'd recommend we do:

	i2N→iN	iN→iN	iN→i2N	u2N→uN	uN→uN	uN→u2N	i2N→uN	iN→uN	uN→i2N	uN→iN	u2N→iN
widen	X	noop	noop	X	noop	noop	X	X	X	X	X
saturating_narrow	saturate	noop	X	saturate	noop	X	X	X	X	X	X
wrapping_narrow	wrap	noop	X	wrap	noop	X	X	X	X	X	X
checked_narrow	check	noop	X	check	noop	X	X	X	X	X	X
strict_narrow	strict	noop	X	strict	noop	X	X	X	X	X	X
unchecked_narrow	UB	noop	X	UB	noop	X	X	X	X	X	X
narrow	default	noop	X	default	noop	X	X	X	X	X	X
saturating_cast	saturate	noop	noop	saturate	noop	noop	saturate	saturate	noop	saturate	saturate
wrapping_cast	wrap	noop	noop	wrap	noop	noop	wrap	wrap	noop	wrap	wrap
checked_cast	check	noop	noop	check	noop	noop	check	check	noop	check	check
strict_cast	strict	noop	noop	strict	noop	noop	strict	strict	noop	strict	strict
unchecked_cast	UB	noop	noop	UB	noop	noop	UB	UB	noop	UB	UB
cast	default	noop	noop	default	noop	noop	default	default	noop	default	default
saturating_cast_signed	X	X	X	X	X	X	X	X	X	saturate	X
checked_cast_signed	X	X	X	X	X	X	X	X	X	check	X
strict_cast_signed	X	X	X	X	X	X	X	X	X	strict	X
unchecked_cast_signed	X	X	X	X	X	X	X	X	X	UB	X
cast_signed	X	X	X	X	X	X	X	X	X	wrap	X
saturating_cast_unsigned	X	X	X	X	X	X	X	saturate	X	X	X
checked_cast_unsigned	X	X	X	X	X	X	X	check	X	X	X
strict_cast_unsigned	X	X	X	X	X	X	X	strict	X	X	X
unchecked_cast_unsigned	X	X	X	X	X	X	X	UB	X	X	X
cast_unsigned	X	X	X	X	X	X	X	wrap	X	X	X

[programmerjake]

cast_signed/cast_unsigned are already defined to wrap on stable

[joshtriplett]

cast_signed/cast_unsigned are already defined to wrap on stable

Ah, sorry, that was an error in the table; I should have written wrap. Fixed (and dropped wrapping_ as redundant).

[Amanieu]

Here's my table of recommendations:

	i2N→iN	iN→iN	iN→i2N	u2N→uN	uN→uN	uN→u2N	i2N→uN	iN→uN	uN→i2N	uN→iN	u2N→iN
widen	X	noop	noop	X	noop	noop	X	X	noop	X	X
saturating_cast	saturate	noop	noop	saturate	noop	noop	saturate	saturate	noop	saturate	saturate
wrapping_cast	wrap	noop	noop	wrap	noop	noop	wrap	wrap	noop	wrap	wrap
checked_cast	check	noop	noop	check	noop	noop	check	check	noop	check	check
strict_cast	strict	noop	noop	strict	noop	noop	strict	strict	noop	strict	strict
unchecked_cast	UB	noop	noop	UB	noop	noop	UB	UB	noop	UB	UB
cast	default	noop	noop	default	noop	noop	default	default	noop	default	default
saturating_cast_signed	X	X	X	X	X	X	X	X	X	saturate	X
checked_cast_signed	X	X	X	X	X	X	X	X	X	check	X
strict_cast_signed	X	X	X	X	X	X	X	X	X	strict	X
unchecked_cast_signed	X	X	X	X	X	X	X	X	X	UB	X
cast_signed	X	X	X	X	X	X	X	X	X	wrap	X
saturating_cast_unsigned	X	X	X	X	X	X	X	saturate	X	X	X
checked_cast_unsigned	X	X	X	X	X	X	X	check	X	X	X
strict_cast_unsigned	X	X	X	X	X	X	X	strict	X	X	X
unchecked_cast_unsigned	X	X	X	X	X	X	X	UB	X	X	X
cast_unsigned	X	X	X	X	X	X	X	wrap	X	X	X

The differences from @joshtriplett's table are:

• I don't think there is value in having narrow operations: these are just a subset of cast which don't allow value-preserving widening and don't allow signedness changes even when this would preserve values. In both cases the return type is generic, which means you either need to turbofish it or ensure that the destination is a fixed type. This is unlike the sign-casts which have a fixed output type which allows method chaining.
• In the same vein, I would extend widen to allow value-preserving widening from a smaller unsigned integer to a larger signed integer.

[tgross35]

I haven't seen it linked on these issues so pointing out some prior art in @tspiteri's az crate, which provides traits for the checked/saturating/strict/wrapping conversions https://docs.rs/az/latest/az/. (Overflowing as well but I don't think we're discussing that.)

[jhpratt]

I don't think there is value in having narrow operations: these are just a subset of cast which don't allow value-preserving widening and don't allow signedness changes even when this would preserve values.

I've got to push back on this. In your table, it would be permitted to call wrapping_cast from u8 to u32 and the inverse. That means it is not possible to know from the method name alone whether the operation is lossy. That is critical to my mental model of what this API should be designed for.