Add cast function to primitive integers

[alexcrichton]

This commit is a result of the libs team's discussion of #33417 and how it
affects integral types. The conclusion was that the motivation for converting
integral types, working in a cross-platform code that uses platform-specific
integer types, was different enough from the intent of TryFrom that it doesn't
make sense to unify the paths. As a result this is a proposal for the
alternative version of the API which purely works with integral types.

An unstable Cast trait is added as the implementation detail of this API, and
otherwise with this you should be able to call i32::cast(0u8) at will. The
intention is then to call this in platform-specific contexts like:

// Convert from C to Rust
let a: c_int = ...;
let b: u32 = u32::cast(a)?;

// Convert from Rust to C
let a: u32 = ...;
let b: c_int = <c_int>::cast(a)?;

Everything here is unstable for now, but the intention is that this will
stabilize sooner than TryFrom.

[rust-highfive]

r? @sfackler

(rust_highfive has picked a reviewer for you, use r? to override)

[alexcrichton]

cc @rust-lang/libs

Note I haven't allocated a tracking issue for this yet, wanted to discuss a bit to make sure we're all on board and then I'll open a tracking issue!

[est31]

Is this separate error really needed? Why not an option based API? The ? operator is about to work with options as well, no?

[alexcrichton]

The intention is that you can define From<CastError> for MyError and have ? work in result-based functions, whereas in option base dfunctions you can just use cast(..).ok()?

[est31]

IDK, for me the operation feels similar to checked_add and that returns an option as well. Or is the policy to return Result everywhere for new APIs?

[alexcrichton]

It's pretty difficult to create a blanket policy that works everywhere, but this is intended for use in APIs that are already dealing with calls to libc and such and are almost guaranteed to already be returning Result.

[est31]

Instead of using u128 here I think we should rather implement a (non public) trait Signed for each unsigned type that has an assoc type with the corresponding unsigned type, and then perform conversion via <$signed>::Unsigned. At least as long as we can't prove that the u128 conversion is optimized away.

[alexcrichton]

This is currently just copying the implementation for TryFrom which has been in use for quite some time.

[nagisa]

IMO cast as a name sounds fairly weird when it is not a method that casts Self into something else. It is doubly weird that although we have as (which is a language construct for casting) which can convert from floats, this function, being named cast, cannot.

[petrochenkov]

The conclusion was that the motivation for converting
integral types, working in a cross-platform code that uses platform-specific
integer types, was different enough from the intent of TryFrom that it doesn't
make sense to unify the paths.

My personal take on the a fallible conversion trait is that I think it'd almost replace the need for these methods altogether.
TryFrom and TryInto should help tie us over with fallible conversions in the meantime

An unstable Cast trait is added as the implementation detail of this API

I don't think I've frequently really wanted a trait here so much as just some methods. Sure a trait is pretty nice for generic programming, but the standard library is exceptionally conservative in generic programming over numerics today already, so we may want to continue that trend.

Are you sure you are the same @alexcrichton and library team as year ago?

---

@nagisa

IMO cast as a name sounds fairly weird when it is not a method that casts Self into something else. It is doubly weird that although we have as (which is a language construct for casting) which can convert from floats, this function, being named cast, cannot.

rust-lang/rfcs#1218 contains some detailed discussion about this stuff (see the commit history as well), and methods that cast Self. Maybe another year later the design will finally converge to what that RFC proposed.

[alexcrichton]

@nagisa I'm not in love with the name, I'd be down for other suggestions!

[steveklabnik]

Are you sure you are the same @alexcrichton and library team as year ago?

A year is a long time, and people can certainly change opinions in that amount of time.

[sfackler]

@petrochenkov What is the purpose of that comment? What action would you like to see taken?

[nagisa]

@alexcrichton how about new? That name would make me a lot of sense :)

[aturon]

@petrochenkov Indeed, it's seeming like your RFC had it right. It's not the first time we've ended up long delaying one proposal on the basis of thinking that something more general would suffice, only to have it not really work out in the end. And I'm sure it won't be the last!

To be honest, by this point I had totally forgotten about your RFC, and am glad you've re-raised it! We should definitely revisit the API you proposed as an alternative before landing this one. I'm particularly curious about the choice of having cast panic on debug builds, as you proposed, versus only providing the checked variant, as this PR does.

cc @rust-lang/libs

[nagisa]

These functions want an #[inline]. I’ve observed in my Range specialisation PR that the casts won’t get inlined and inlining is able to get rid of the unnecessary code resulting in one or two instructions per cast.

[alexcrichton]

Good point, forgot this originally, added now.

[scottmcm]

Since this is number-specific, I rather expected the checked/overflowing/wrapping/saturating methods, like @petrochenkov linked, for consistency with the other mathy methods.

For example, Range::size_hint wants (usize::saturating_cast(delta), usize::checked_cast(delta)). (In stable today it just gives up and always returns (0, None) for large types, which is rather suboptimal.)

[bors]

☔ The latest upstream changes (presumably #42644) made this pull request unmergeable. Please resolve the merge conflicts.

[alexcrichton]

@scottmcm my personal hope is that we can make progress here as this feature has been stalled for years at this point now. Along those lines while I think such future additions may affect naming today I'd prefer to focus solely on one use case for now, FFI conversions. Those want the checked versions 99% of the time and to be usable also want them to be ergonomic.

I'm just wary of continuing to bog down progress in the endless bikeshed of what methods, what names, and what signatures we want. My hope is that this strikes a right balance for ergonomics (usable with ? and short name like cast) and also covers the use case at hand (all integral types can be casted to all other integral types)

[alexcrichton]

@nagisa I personally feel new is not the right name here as a fallible conversion is happening, whereas that's sort of operation is typically not dubbed "new"

[scottmcm]

@alexcrichton I'm totally onboard with not having the saturating_ and other variants immediately.

Let's see if I can better phrase as motivational statements:

• Having the additional variants in the future gives this a sustainable justification for its existence. (I understand the short-term value of having this, but even in the FFI case it'll be a subset of try_from eventually: you write the one From to your error type, and the other error type is ! that you won't need to write. And it's arguably worse ergonomically as there's no method-syntax version like there is with try_into.)
• Calling this cast feels confusing with how as is called "cast". For example, the book and the reference currently say "A type cast expression is denoted with the binary operator as." (https://github.com/rust-lang/book/blob/master/second-edition/src/appendix-02-operators.md#type-cast-expressions https://github.com/rust-lang/book/blob/master/first-edition/src/casting-between-types.md#numeric-casts https://doc.rust-lang.org/reference/expressions.html#type-cast-expressions) I'd like to avoid a "No, cast isn't a cast" discussion. (If there's a goal of deprecating as, which I'd definitely support, then I'd like the cast name better.)
• checked_cast feels the most consistent with checked_add and such, as well as clearly describing how it differs from "a cast".

[bors]

☔ The latest upstream changes (presumably #42430) made this pull request unmergeable. Please resolve the merge conflicts.

[carols10cents]

Merge conflicts!

[alexcrichton]

Rebased

[bors]

☔ The latest upstream changes (presumably #42780) made this pull request unmergeable. Please resolve the merge conflicts.

[Mark-Simulacrum]

@alexcrichton Not sure if this is legitimate. May just need to delete something? Either way, I believe this potentially need to be rebased -- not super clear about the current status.

[00:45:18] An error occured:
[00:45:18] '/checkout/obj/build/x86_64-unknown-linux-gnu/md-doc/unstable-book/src/library-features/num-cast.md' referenced from SUMMARY.md does not exist.
[00:45:18] 
[00:45:18] 
[00:45:18] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools/x86_64-unknown-linux-gnu/release/rustbook" "build" "/checkout/obj/build/x86_64-unknown-linux-gnu/md-doc/unstable-book" "-d" "/checkout/obj/build/x86_64-unknown-linux-gnu/doc/unstable-book"
[00:45:18] expected success, got: exit code: 101

[est31]

@Mark-Simulacrum SUMMARY.MD should be autogenerated now, and create links on its own. One will probably have to rebase in order to get this autogeneration though.

[arielb1]

Are you still working on this @alexcrichton? Friendly ping to keep this on your radar.

[briansmith]

Which RFC is this based on? Which specific conversions are to be supported: signed -> unsigned, unsigned -> signed, potentially-lossy narrowing conversions? As was discussed in the RFC I'm aware of (rust-lang/rfcs#1218), each type of conversion should have a different name. In particular, potentially-lossy narrowing conversions should be called something like narrow() and signed/unsigned conversions should be called something like signed()/unsigned(). This way, the writer of the code can indicate exactly what kind of conversion they want and the readers/reviewers of the code can more quickly verify that that kind of conversion makes sense.

I also don't think there's anything special about FFI types. usize/isize vs fixed-width types have the same issues.

[est31]

Which RFC is this based on?

I'm not sure about the procedure, but afaik smaller lib apis like this one can be added without an RFC.

[SimonSapin]

The closest in https://github.com/rust-lang/rfcs/blob/master/libs_changes.md#is-an-rfc-required is:

Obvious API hole patch, such as adding an API from one type to a symmetric type. e.g. Vec<T> -> Box<[T]> clearly motivates adding String -> Box<str>

I think a new inherent method to primitive types is not a "hole patch", and @briansmith listed more than enough questions to show that details of this API are not obvious.

I’ve seen and had RFCs be asked for much less than this.

[CryZe]

Yeah I agree. This at least needs more discussions as to why there's no methods for all the different kinds of possible casts you would want. This exists for overflow on all kinds of different operations, but here there's just the "checked" version available.

[alexcrichton]

Ok, I don't believe I have the time or energy to push this over the hump, so closing.

[aturon]

@petrochenkov, are you interested in revisiting your RFC on this topic, now that the TryFrom story has shaken out? This is clearly still important functionality.

[petrochenkov]

@aturon
No, sorry.
If someone is interested, feel free to reuse the old RFC's text.

[briansmith]

If nobody volunteers for this beforehand, I will pick up redoing the RFC in mid-August.

[kennytm]

@briansmith @petrochenkov Hi. Any update on the RFC?

[petrochenkov]

@kennytm
Nothing new from me.
If you want to resurrect it yourself, please do!

[briansmith]

@kennytm Sure, I will write a new RFC for this. Am I correct in understanding that it won't even be considered by the libs team until after January, though? Not sure how the "impl period" thing is working.

[kennytm]

@briansmith I think that depends on whether stabilizing TryFrom is considered part of the 2017 roadmap or not. (cc @aturon)

Recently #44174 is submitted, so the FFI issue #33417 (comment) is becoming a real problem, which is the original reason why this PR exists. But it seems not definite that TryFrom will be stabilized before the end of the impl period (2017 Dec 17th).

[aturon]

@briansmith The plan is to put our primary focus on implementation work during the impl period, so the question probably comes down to how much shepherding work would be required on the ensuing discussion. I'd suggest trying to get one open in the next ~week, which would leave some time for shepherding discussion prior to the impl period, and thus put us in a place where FCP shouldn't be too hard to reach.