Add missing integer casts

[orlp]

Proposal

Problem statement

Currently the default way when converting between integer types is using as, if into() doesn't do what you want. However so many behaviors are encoded in this one little word. There long have been calls for dedicated functions which encode intent better.

Some recent work has gone into this problem:

• extend / truncate
• *_cast_signed / *_cast_unsigned in integer_cast_extras

But I think this is not enough.

1. I think what is missing is a saturating conversion between all integer types, full stop. There is no reason this should be limited to specific pairs of types, the conversion is always infallible and unambiguous.

2. What is technically not entirely missing (due to the existence of TryInto and unwrap/unwrap_unchecked) but would be nice to have is checked/strict/unchecked conversion between all integer types, full stop. There is no reason this should be limited to specific pairs of types, the conversion is always unambiguous and the error condition (out-of-bounds) is always the same.

   The reason for this is two-fold:

   1. the lack of type ascription and it not coming any time soon makes using TryInto awkward.
   2. TryInto is too generic and can be more than just a numeric conversion.

Motivating examples or use cases

Honestly, these conversions are so ubiquitous and uncontroversial I don't think they need further motivation, especially the saturating_cast which has no viable alternative for a lot of data type pairings currently. That said, the motivation of the checked_cast API over try_into is again two-fold:

1. It's just a lot nicer. E.g. compare these two:

   // Today:
   let signed_len: i64 = ...;
   let len: usize = signed_len.try_into().unwrap();
   array[len / 2]
   
   // With this proposal:
   let signed_len: i64 = ...;
   array[signed_len.strict_cast::<usize>() / 2]

2. (Unsafe) code can not comfortably rely on it being a numeric conversion. E.g. in foo(x.try_into().unwrap()) there's no direct way to know without inspecting foo what the try_into might do, and the definition of foo might change after inspection. With this proposal you rest assured that foo(x.strict_cast()) is always a numeric conversion.

Solution sketch

I propose the following set of functions to be added to all primitive integer types (both signed and unsigned):

mod convert {
    trait IntCast<Int> : Sealed<Int> { ... }
}

impl T {
    /// Converts `self` to the target integer type, saturating at the nearest edge
    /// of the target type's domain if the value does not lie in within it.
    fn saturating_cast<Int>(self) -> Int where Self: IntCast<Int>;

    /// Converts `self` to the target integer type, returning `None` if the value
    /// does not lie in the target type's domain.
    fn checked_cast<Int>(self) -> Option<Int> where Self: IntCast<Int>;

    /// Equivalent to `self.checked_cast::<Int>().unwrap()`.
    fn strict_cast<Int>(self) -> Int where Self: IntCast<Int>;

    /// Equivalent to `self.checked_cast::<Int>().unwrap_unchecked()`.
    unsafe fn unchecked_cast<Int>(self) -> Int where Self: IntCast<Int>;
}

The implementation of IntCast trait is not shown here. It ought to be implemented for all combinations of primitive integer types. This trait is considered an implementation detail as a permanently-unstable sealed trait. A later proposal may consider stabilizing it for the use in generics, but I consider that out-of-scope for this ACP. I do not think this trait should ever be unsealed, so that unsafe code can rely on it.

Then, I propose the removal of the following unstable functions from integer types:

// Removed integer_extend_truncate:
fn saturating_truncate<Target>(self) -> Target where Self: TruncateTarget<Target>;
fn checked_truncate<Target>(self) -> Option<Target> where Self: TruncateTarget<Target>;
// strict_truncate is already absent.
// Note that I'm **not** proposing the removal of the infallible truncate / extend.

// integer_cast_extras (removed entirely)
fn checked_cast_signed(self) -> Option<iN>;
fn saturating_cast_signed(self) -> iN;
fn strict_cast_signed(self) -> iN;
fn checked_cast_unsigned(self) -> Option<uN>;
fn saturating_cast_unsigned(self) -> uN;
fn strict_cast_unsigned(self) -> uN;

These are all directly covered by this proposal.

Open questions

• Which code pattern should these functions follow?

  fn saturating_cast<Int>(self) -> Int where Self: IntCastTarget<Int>;
  fn saturating_cast<Int: IntCastFrom<Self>>(self) -> Int;

  In this proposal I followed the example of integer_extend_truncate, but it's unclear to me which of these two is better.

• Should cast also be added? It would be implemented whenever the cast is infallible. This overlaps with the unstable extend, but can also cross signedness (e.g. infallibly convert u8 to i16). If added, should extend be removed, or should it remain a method that's only implemented when the conversion is actually widening within the same signedness?

• Should wrapping_cast also be added? It overlaps with truncate but follows the saturating_, checked_, wrapping_, etc, pattern better, and allows direct two's complement conversions between signed and unsigned types of different sizes (e.g. i8 to usize conversion). If this is added, should truncate be removed entirely, or should it remain as a method that's only implemented when the conversion is actually narrowing within the same signedness?

• Should the NonZero types be included? If so saturating_cast and wrapping_cast (if added) need to go on dedicated traits rather than IntCast, as a * -> NonZero<Int> saturating/wrapping cast can not be infallible.

Alternatives

• As mentioned above, there is some overlap with other proposed/unstable APIs, which means they're technically an alternative. However in my opinion those are unnecessarily restrictive in the type combinations they support, when the proposed operations are wholly unambiguous/uncontroversial to support on the full spectrum of types.

  For example, take checked_truncate and checked_cast_unsigned. If I'm checking that the numeric conversion is successful anyway, does it really matter whether the would-be-invalid conversion was a truncation or a signed -> unsigned conversion? I think it adds unnecessary friction in picking the 'correct' function when it doesn't matter in either the outcome or code pattern.

  Similarly take saturating_truncate and saturating_cast_unsigned, if I'm saturating on the supported domain anyway, do we really need two separate APIs for a saturating truncation, and a saturating signed conversion?

  Plus, even the combination of all those above APIs still doesn't cover something as simple and useful as a saturating conversion of i64 to usize.

• TryInto is an alternative to checked_cast, but is less convenient due to a lack of type ascription, and can be dangerous because TryInto can be implemented by anyone for anything. checked_cast is always between integers.

Links and related work

An implementation of this ACP can be found at https://docs.rs/int-cast/.

• Tracking Issue for integer extension and truncation methods rust#154330
• Tracking Issue for integer_cast_extras rust#154650
• https://crates.io/crates/saturating_cast

[programmerjake]

big +1 from me for adding wrapping_cast that always works regardless of the input/output integer types.

[okaneco]

I would like to see some way of doing saturating_cast, checked_cast, strict_cast, and wrapping_cast in std.

Other than the saturating functionality, this is another case where num-traits is missing from std, specifically the cast module.

Unless there's an optimization benefit, I don't see a reason for unchecked_cast to exist as it seems to have the same functionality of as casts or wrapping_cast but with potential for UB. It's not covered in this ACP, but that seems more appropriate for float->int conversions (to_int_unchecked on floats today).

For example, take checked_truncate and checked_cast_unsigned. If I'm checking that the numeric conversion is successful anyway, does it really matter whether the would-be-invalid conversion was a truncation or a signed -> unsigned conversion? I think it adds unnecessary friction in picking the 'correct' function when it doesn't matter in either the outcome or code pattern.

If you don't care about the errors, then you only need the equivalent of a TryFrom. However, these are two different modes of failure and they indicate two different intents depending on the order of truncation and conversion.

Checked i32->u32->u16 has a different range of accepted values than checked i32->i16->u16. The same idea applies to the differing results for saturating truncation and casting order. I don't think this proposal completely supersedes the existing unstable methods.

[programmerjake]

Unless there's an optimization benefit

there is an optimization benefit since LLVM can express the unchecked casts as nuw/nsw flags on the trunc instruction for larger to smaller conversions, or zext nneg for smaller signed to larger unsigned. those flags let LLVM assume the input value is also in range¹, which can help with some optimizations.

Footnotes

1. technically the output of those instructions for out-of-range inputs is poison which isn't immediate UB, but its UB to use it later in many instructions. ↩

[orlp]

@okaneco

Unless there's an optimization benefit, I don't see a reason for unchecked_cast to exist as it seems to have the same functionality of as casts or wrapping_cast but with potential for UB. It's not covered in this ACP, but that seems more appropriate for float->int conversions (to_int_unchecked on floats today).

I added unchecked_cast because pretty much all numeric operations have unchecked_ variants to indicate overflow is impossible (e.g. unchecked_add). I don't feel too strongly about it, but as @programmerjake already mentioned, there are performance benefits sometimes when declaring to the compiler that overflow is not possible.

However, these are two different modes of failure and they indicate two different intents depending on the order of truncation and conversion. Checked i32->u32->u16 has a different range of accepted values than checked i32->i16->u16. The same idea applies to the differing results for saturating truncation and casting order. I don't think this proposal completely supersedes the existing unstable methods.

I don't understand what the relevance of this is to my proposal to remove the overlapping methods. In case you are under the belief that signed.strict_cast::<Unsigned>() or unsigned.saturating_cast::<Signed>() or other mixed-sign operations would go through two conversion steps in a row, you are mistaken. It is a singular operation that converts the integer value to a new type, not a chain of conversions.

To be specific, the source type is actually completely irrelevant for the definition of these operations. The only thing that matters is that we have a mathematical integer, and a target type. For example, I might want to convert the value 260 in a saturating way to i8. This is above the maximum of this type (127), therefore we return 127_i8. It does not matter whether the source of the integer 260 was a 260_u16 or 260_i32, the operation is defined in the exact same way.

[hanna-kruppe]

Having these methods for literally all pairs of src/dest types doesn't seem like a good idea to me. At least when a From/Into impl exists, it's very misleading to write the lossless conversion with methods that talk about how to handle the impossible case of the value not fitting in the destination types. If we had those methods, rustc or clippy should warn about using them instead of From/Into.

I realize there are some advantages to having the full matrix (macros, generic code if the trait is stabilized, papering over "how many bits does usize have?" issues) but it doesn't seem worth it. Any concrete use of the methods would be clearer using From/Into. Any usage behind generic/macro could probably benefit from exposing the case of infallible conversions separately for the same reason.

[orlp]

@hanna-kruppe I strongly disagree. Obviously if an infallible method exists it is preferable to use it over a fallible one, but one should not cripple a generic API to force this. Macros/generics are an important use case, and they are just not covered right now, just like a lot of combinations of types are simply not covered right now. Your suggestion could just as well be applied to TryInto, saying that TryFrom<u8> for u16 shouldn't be implemented because it might as well be done infallibly. Doing so would hugely devalue the TryInto trait.

Note that clippy already warns for unnecessary usage of TryInto:

warning: use of a fallible conversion when an infallible one could be used
 --> src/main.rs:3:20
  |
3 |     let b: u16 = a.try_into().unwrap();
  |                    ^^^^^^^^^^^^^^^^^^^
  |
  = note: converting `u8` to `u16` cannot fail
  = help: for further information visit https://rust-lang.github.io/rust-clippy/rust-1.95.0/index.html#unnecessary_fallible_conversions
  = note: `#[warn(clippy::unnecessary_fallible_conversions)]` on by default
help: use
  |
3 -     let b: u16 = a.try_into().unwrap();
3 +     let b: u16 = a.into();

I have no doubt the clippy developers could add similar warnings for unnecessary usage of these proposed _cast methods.

---

Any concrete use of the methods would be clearer using From/Into.

Actually, I gave two reasons (lack of type ascription and uncertainty of the exact conversion being used) why using Into gives a worse experience in my motivation. My argument was on TryInto but the same logic applies to Into. I would not be opposed to adding the following:

fn cast<Int>(self) -> Int where Self: InfallibleIntCast<Int>;

which would be the preferred conversion when there is no more specific infallible method, for example conversion from u8 to i16. extend() (or my preferred name widen() which was recently suggested) which can't change signs would be preferred over this when possible, but again, clippy could do this.

---

I realize there are some advantages to having the full matrix [...] but it doesn't seem worth it.

I must admit, I really fail to see why "the code could be written in a better way" should block actual real needs not being met, especially when the detection for "it could be done better" can be done completely automatically by clippy. It is absolutely worth it.

[hanna-kruppe]

I don't think the TryFrom blanket impl for infallible conversions is the same. Those traits so general that generic code using From/Into can usually be converted to using TryFrom/TryInto by simply propagating any errors, and it'll end up the same in the infallible case: usage that could've used From/Into before still get Result<T, Infallible>. In contrast, a generic API that uses checked_cast introduces fallibility even in cases that are infallible. I believe any generic / macro you can write with checked_cast can already be written with TryFrom/TryInto today (should be implemented for all pairs of integer types) without losing the information whether the conversion can fail.

For {saturating,strict,unchecked}_cast, I suppose it's possible that there is some generic/macro-ful code that makes just as much sense for the fallible and infallible cases, because the error cases are prevented/handled internally and the caller doesn't need to care whether they can happen. But I struggle to imagine use cases that doesn't reduce either to "implementing some specific computation generically over all integers" (which needs far more than conversion) or to implementing abstractions for the former (e.g., implementing some sort of Integer trait for all primitive integers). Do you have a specific example?

Actually, I gave two reasons (lack of type ascription and uncertainty of the exact conversion being used) why using Into gives a worse experience in my motivation. My argument was on TryInto but the same logic applies to Into. I would not be opposed to adding the following:

The type ascription problem is a general one that IMO should be solved once and for all, not by adding more and more inherent methods that only re-export conversion trait impls. I'm not sure what you mean by "uncertainty of the conversion being used" in the infallible case. Is it that From/Into apply to far more than int->int conversions? I have some sympathy for this (I've argued for <[T]>::as_array and friends on similar basis in the past) but in monomorphic contexts it can be fixed by writing something like u32::from(...), and in generic code a marker trait for integers would suffice.

[orlp]

I believe any generic / macro you can write with checked_cast can already be written with TryFrom/TryInto today (should be implemented for all pairs of integer types) without losing the information whether the conversion can fail.

Absolutely, you can. The implementation of checked_cast, strict_cast and unchecked_cast could literally be a blanket implementation with TryFrom + an Integer marker trait. But I don't feel you're acknowledging the bigger picture:

1. Again, the type ascription. A general solution is still very far away, if it ever comes.

2. The understandability at a glance. cast is always a numeric conversion rather than literally any kind of conversion.

3. The power of the ensemble. Essentially all numeric methods come in checked_, strict_, unchecked_, saturating_, and wrapping_ variants. Why would cast be any different? Why would wrapping_cast and saturating_cast be an exception and not come with the other variants when they are unambiguous and useful?

4. The serious boost in readability. Again, allow me to refer to the example from the motivation:

   array[signed_len.strict_cast::<usize>() / 2]

   There are thousands of matches for let ident: Int = expr.try_into().unwrap() on Github. All of those could simply be written as expr.strict_cast::<Int>() without the need for intermediate variables.

Do you have a specific example?

Almost any generic function that currently uses TryInto<Int> would be better off written using CastIntTarget<Int> (if we ignore the stabilized trait name bikeshedding for the moment). Just do a search for TryInto<usize> for example. In almost all cases the signature would be better described as "any primitive type you could use to index" rather than "literally any frigging thing that could potentially convert to an index".

I'm not sure what you mean by "uncertainty of the conversion being used" in the infallible case. Is it that From/Into apply to far more than int->int conversions?

Yes. Again, as explained in the motivation of the ACP:

(Unsafe) code can not comfortably rely on it being a numeric conversion. E.g. in foo(x.try_into().unwrap()) there's no direct way to know without inspecting foo what the try_into might do, and the definition of foo might change after inspection. With this proposal you rest assured that foo(x.strict_cast()) is always a numeric conversion.

---

On top the above, I think in general TryInto / Into are a massive anti-pattern. I firmly believe they really have no place in code outside of generics. They are far too powerful, and therefore dangerous. You need advanced tooling to even figure out what an (try_)into() call actually ends up calling. Up until recently even rust-analyzer couldn't tell you. And if you are e.g. reviewing code on Github or some other scenario where you're not in an IDE without a LSP running, good luck.

If you object to the matrix of all integer types being 'too much' for something as specific as Int::checked_cast, surely you'll agree that the matrix of literally anything anyone might add to TryFrom is too much (which is in fact a strict superset of the proposed checked_cast).

People suggest using (try_)into() for numeric conversions not because it's good, but just because it's better than as. That's not saying much. The proposed cast() family for integer conversions is far superior to (try_)into() for both readability and preventing misuse.

[hanna-kruppe]

I don't have any issue with the saturating/checked/wrapping trifecta, only with providing it for cases that can't actually saturate / fail / wrap. So far the standard library doesn't give any support for code trying to be generic over integer/numeric types, and only makes mild concessions for macro duck-typing (e.g., uN::checked_neg is almost trivial). Integer methods aren't provided just for completeness or macro duck-typing when they would be completely redundant (e.g., only signed types have abs(), only unsigned types have *_{add,sub}_signed). These casts would break those design pattern.

So I get the feeling that this ACP has a much bigger bone to pick with the standard library's existing approach (w.r.t. concrete uses of TryFrom and w.r.t. writing code generic over integers). I don't want to get dragged into that broader discussion, so I'll not comment on those aspects. Just two small clarifications of what I wrote before:

1. I don't mean literally type ascription ($expr : $ty) as the solution for the conversion traits turbofish problem. That language feature is indeed unlikely to happen. Extension methods like fn into_bikeshed<U>(self) -> U where Self: Into<U> { self.into() } would suffice. I saw discussion about this before but can't find it right now.
2. I don't think there's a problem with "too many" possible conversions per se. That's what super-generic vocabulary traits like TryFrom are for. But since those traits already exist, inherent methods on integer types should focus on the concrete uses that make sense, not try to cover generic code as well.

[programmerjake]

imo wrapping_cast should support any integer to any integer conversions, even if they couldn't "wrap", since that lets you use it for any integer types without having to know which one is bigger (very important when we get generic integer types (like u<N> where const N: usize) where you'd have to use where N < M bounds otherwise. I don't expect we'll get those bounds for a very long time). it's always the exact same operation when using intermediate unlimited-range integers:

impl<T: PrimInt> WrappingCast for T {
    fn wrapping_cast<U: PrimInt>(self) -> U {
        let mut value = self as UnlimitedInteger;
        value %= 2.pow(U::BITS);
        if value < 0 {
            value += 2.pow(U::BITS);
        }
        // now 0 <= value < 2^U::BITS
        if value > U::MAX { // can only happen if U is signed
            value -= 2.pow(U::BITS);
        }
        // now U::MIN <= value <= U::MAX, so the `as` is lossless
        value as U
    }
}

[orlp]

@hanna-kruppe Suppose we do limit the implementation of these cast methods to only those pairs of integer types where the cast is fallible. How do you propose we handle usize and isize? On some platforms it would be fallible, on others it would not be. Would you follow Into and consider the only subtypes of usize to be u8/u16 and the only subtypes of isize to be u8/i8/i16? Effectively making it a !Into bound?

[hanna-kruppe]

Yes, I think this should be consistent with the set of (Try)From/Into impls. This might raise some interesting questions if we eventually, finally, gain some way for crates to opt into limiting supported usize widths (e.g., most code could probably assume usize is either 32 or 64 bits so u32 -> usize -> u64 is infallible). But I hope that whatever mechanism enables this for (Try)From/Into can also handle the trait(s) underlying the cast() methods.

[quaternic]

@hanna-kruppe

So far the standard library doesn't give any support for code trying to be generic over integer/numeric types, and only makes mild concessions for macro duck-typing (e.g., uN::checked_neg is almost trivial). Integer methods aren't provided just for completeness or macro duck-typing when they would be completely redundant (e.g., only signed types have abs(), only unsigned types have *_{add,sub}_signed).

uN::wrapping_div and u/iN::wrapping_rem (and their _euclid variants) do exist, and never wrap. (They still panic for div-by-zero.) The docs for the former state: "This function exists so that all operations are accounted for in the wrapping operations."

Mind you, I don't think those should exist, so you do have a point there.

However, especially for a method with a generic output type, restricting to only those outputs that actually might sometimes wrap seems clearly unnecessary. That is, surely i32::checked_cast<T: Integer>(self) -> Option<T> shouldn't require i32: NotSubsetOf<T>?

---

With regards to wrapping_cast, it's worth pointing out that all integer-to-integer as-casts have exactly those wrapping semantics: The numeric value of the input, wrapped to the output type. I personally find as-casts between integers fine and generally useful, with some issues:

1. no generics
2. can also do other kinds of casts, like ptr-to-int
3. semantics are not obvious from syntax

A generic wrapping_cast could be an improvement for all of those.