Tracking Issue for integer_sign_cast

[Rua]

Feature gate: #![feature(integer_sign_cast)]

This is a tracking issue for explicit signedness casting methods for integer primitive types. Libs discussion: rust-lang/libs-team#359.

Public API

(for N in [8, 16, 32, 64, 128, size]):

impl uN {
    pub const fn cast_signed(self) -> iN {}
}

impl iN {
    pub const fn cast_unsigned(self) -> uN {}
}

impl NonZero<uN> {
    pub const fn cast_signed(self) -> NonZero<iN> {}
}

impl NonZero<iN> {
    pub const fn cast_unsigned(self) -> NonZero<uN> {}
}

Steps / History

• Implementation: Implement feature integer_sign_cast #125884
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

Mostly bikeshedding regarding naming, as mentioned in the Libs discussion. The current proposal follows the naming of cast_const and cast_mut for pointers.

Alternatively, these could be implemented as from_bits and to_bits methods for the signed types.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[tbu-]

Mostly bikeshedding regarding naming, as mentioned in the Libs discussion. The current proposal follows the naming of cast_const and cast_mut for pointers.

I think that cast_signed and cast_unsigned do not communicate intent on what to do on overflows. This is unlike cast_const and cast_mut where no such overflow can occur.

I think something like reinterpret_signed or the proposed from_bits/to_bits woul be more appropriate.

[electroCutie]

do not communicate intent on what to do on overflows

There wouldn't be any overflows, as I understand the term. The number of bits stays the same, which is expressly part of the design of the function.

[tbu-]

It does not communicate what happens to values of unsigned integers that do not fit into the target integer values.

We're reinterpreting the bits as an unsigned integer, but cast does not say that. E.g. casting from integer to float does not reinterpret the bits, casting from i8 to i32 does not solely reinterpret the bits either, it sign-extends them. So "cast" doesn't tell me what happens.

[electroCutie]

@tbu- ah now I see your meaning

Your suggestion of reinterpret_signed seems like a good way to phrase it

[Rua]

What about transmute_signed? That seems closer to Rust's typical jargon.

[aapoalas]

IMO: A consistent API is most important, so from_bits / to_bits should be chosen.

[Rua]

After thinking about this for a while, and looking at how I'm actually using this function, I think I agree with the suggestion to use from_bits and to_bits instead. Do others agree? If so, can I just make a PR to change the name?

[jhpratt]

I personally find from_bits/to_bits to be too similar to the {from|to}_{n|b|l}e_bytes methods. However from_bits and to_bits are present and have been stable for years, with the behavior equivalent to that of a transmute (i.e. the same as this proposal).

So as much as I don't care for the naming, it would be consistent with that. With that said, casting a sign and reinterpreting the type entirely feel like two different things that don't necessarily have precedential impact. An integer and a float share effectively zero in common when using from_bits/to_bits, while integers will share a value for the overlapping range.

[aapoalas]

After thinking about this for a while, and looking at how I'm actually using this function, I think I agree with the suggestion to use from_bits and to_bits instead. Do others agree? If so, can I just make a PR to change the name?

Do you happen to have any examples of this usage in public repositories?

[jhpratt]

@aapoalas While not using this feature directly, the time-rs/time repository uses an API from num-conv that is identical to the current proposal.

[SabrinaJewson]

I’m not too keen on from_bits and to_bits. While it works for the use-case of shuttling an i64 value in a u64-shaped container, it doesn’t look so nice for the dual operation (which I think I find myself doïng more often), since it implies that i64 is your real integer value and u64 is its bitwise representation, when it’s in fact the other way around.

(re some other suggestions: transmute_* reads a danger word in my head, so probably isn’t ideal for a safe method, while reinterpret_* is kinda verbose and doesn’t have precedent. I think that cast does carry a sufficient connotation of reinterpreting the bit values directly; it’s in line with pointers’ cast method too.)

[electroCutie]

What about something like bits_to_i / bits_to_u (and if desired the bits_from_* versions in associated functions)

Hints that it is bitwise and doesn't introduce a new term (I take it as a given that someone performing this operation already knows the term "bits"), doesn't try to put one or the other as the canonical representation, still uses the familiar from/to jargon, and is a bit less verbose than some other wordier proposals

[endrift]

I keep finding myself needing this for dealing with C APIs and ioctls. I don't like the to_bits/from_bits proposal because it's quite vague for people not familiar with 2's complement. May I suggest cast_wrapping or to_unsigned_wrapping/to_signed_wrapping, or similar?

[Rua]

I do like to_(un)signed_wrapping. I think including the destination signedness within the name is important, so that it's more robust against refactorings. If you change the signedness of the type it's called on, the compiler will immediately complain at you that the method is wrong.

[electroCutie]

@Rua I'm definitely not liking the "wrapping" or "unwrapping" terminology. They're not at all wrappers. They're just different ways of interpreting the same data

[Rua]

It's not wrappers as in wrapping around another thing. It's wrapping as in allowing integer wrap-around. The same as methods like wrapping_add, wrapping_neg etc.

[electroCutie]

I didn't think at all in that direction, I see what you mean but it doesn't immediately click

[vnghia]

Hi, I would like to ask is there something planned for NonZero as well since they are also integer and will work pretty much the same as normal integer in this cases.

[DarkKirb]

👍 for cast_signed, cast_unsigned because it’s more consistent with other uses of the word cast in std (bit-preserving reinterpretation) vs as or to (which in many cases don’t preserve the underlying representation)

[CodesInChaos]

I think it's likely that we will get similar functions with different overflow semantics (e.g. panicking, saturating, etc.), so I'd go with wrapping_to_(un)signed for these, strict_to_(un)signed for the panicking version. For consistency with methods like wrapping_add, wrapping should be in the beginning of the name.

[endrift]

Now that you mention it, I would love a saturating version as well and have written short implementations of that already, since it's more or less trivial in comparison (without unsafe code that is). Future proofing like that seems like a decent idea.

[joshtriplett]

These have been around for a while, they're useful for eliminating uses of as, and it seems like the only concern about them is whether they have the right name. The current cast_signed and cast_unsigned seem like reasonable names here.

Shall we stabilize these?

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Amanieu]

We discussed this in the libs-api meeting and decided to keep the names as-is (cast_[un]signed). "Cast" is well documented in the reference with regards to integers so it is clear that this simply re-interprets the bits. In any case this will be clearly described in the documentation.

[tgross35]

FCP includes the methods added to NonZero in #136511, correct? (top post needs to be updated)

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[jdahlstrom]

Uff, I missed the FCP, but I'm wondering a bit why as_signed and as_unsigned were not considered, at least in this discussion. Yes, as_foo often indicates stripping one layer of abstraction, but not nearly always. This is a cheap (indeed free) conversion, like as_ is supposed to be. People seem to have different opinions as to whether signed↔︎unsigned is more of a "full" reinterpretation of bits like f32::to_bits or something less severe – I'm definitely in the latter camp given the natural mathematical (and hardware-level) equivalence modulo 2^(n-1) that moreover preserves addition, subtraction, and (narrow) multiplication.

But I guess there's precedent in ptr::cast and cast_mut.

[GrigorenkoPV]

I've stalled the stabilization PR a bit. (I hope that was not an evil thing to do, after all, if not for me, it might not have even been opened yet.) Let's probably hear what t-libs-api has to say about this, and then I will update the PR accordingly.

Once again, apologies for violating the usual process, but I hope this is in spirit with what FCP's were intended for.

[joshtriplett]

Full support for as_signed and as_unsigned as alternatives; no objection.

[jhpratt]

Personally I'd still prefer cast given that it's reinterpreting bits.

(I don't feel strongly either way)

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting.

There were supporters for both as_* and cast_*, but:

• Some of the people favoring cast_* had blocking objections to as_* on the basis of not feeling those names clearly indicated the possibility of a semantic-value-changing conversion of negative-to-large-positive or vice versa.
• The people favoring as_* were willing to settle for cast_* in order to ship something that's better than the current status quo of writing things like as u64.

Based on that, we're continuing with the FCP as passed, for cast_.

@GrigorenkoPV, could you please go ahead with the PR?

[GrigorenkoPV]

Based on that, we're continuing with the FCP as passed, for cast_.

@GrigorenkoPV, could you please go ahead with the PR?

OK: #137026 (comment)

[scottmcm]

I like cast for the intentional-transmute one, as it sounds like you discussed.

It also means there's the possibility of as_unsigned() that has a debug check for negative or similar. (I don't know if it's worth having, or whether it should be checked or whatever, but space for it is interesting I think.)

[tbu-]

It also means there's the possibility of as_unsigned() that has a debug check for negative or similar.

as_* functions should not be used for failing conversions, so that's not an option.