Tracking Issue for integer extension and truncation methods

[Amanieu]

Feature gate: #![feature(integer_extend_truncate)]

This is a tracking issue for integer extension and truncation methods.

Public API

impl iX {
    // `Target` is a signed integer with size >= Self
    fn extend<Target>(self) -> Target
        where Self: ExtendTarget<Target>;

    // `Target` is a signed integer with size <= Self
    fn truncate<Target>(self) -> Target
        where Self: TruncateTarget<Target>;
    fn saturating_truncate<Target>(self) -> Target
        where Self: TruncateTarget<Target>;
    fn checked_truncate<Target>(self) -> Option<Target>
        where Self: TruncateTarget<Target>;
}

impl uX {
    // `Target` is an unsigned integer with size >= Self
    fn extend<Target>(self) -> Target
        where Self: ExtendTarget<Target>;

    // `Target` is an unsigned integer with size <= Self
    fn truncate<Target>(self) -> Target
        where Self: TruncateTarget<Target>;
    fn saturating_truncate<Target>(self) -> Target
        where Self: TruncateTarget<Target>;
    fn checked_truncate<Target>(self) -> Option<Target>
        where Self: TruncateTarget<Target>;
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: Integer Manipulation API libs-team#204
• Implementation: Add integer truncation and extension methods #154356
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

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

[jhpratt]

I believe the trait bounds are backwards. In num-conv, they're Self: ExtendTarget<T> in order to permit accepting a parameter that is extensible into a certain type (hence the trait name).

If you agree that it should match num-conv, I can create a PR uplifting the crate (with inherent methods) later tonight. If you don't agree, I'm curious as to why :)

For unresolved questions, I still think the handling of usize and isize could use consideration. I haven't found a nice way to handle them, unfortunately.

[Amanieu]

I believe @joshtriplett is already working on a PR based on num-conv.

Regarding the trait bounds, I don't think this matters since the traits are sealed. Could you clarify what you mean by "accepting a parameter that is extensible into a certain type"?

Regarding usize, we're currently keeping the impls conservative which matches the current convention for the stdlib. Relaxing this would be part of a wider conversation which may also affect From impls.

[jhpratt]

fn foo(x: impl ExtendTarget<i32>) {
    let x = x.extend(); // x is now i32
}

This function would accept i8, i16, and i32. I would be able to accept parameters based on the target, not whatever Self happens to be.

If the trait is intended to be wholly inaccessible or perma-unstable, then sure, I guess it doesn't matter the way it's written. This was my thinking when writing num-conv, although I did admittedly keep the method on the target traits private.

[tgross35]

Is there any reason not to include widening unsigned->signed conversions as part of ExtendTarget? E.g. u8 to i16 is lossless.

[joshtriplett]

Is there any reason not to include widening unsigned->signed conversions as part of ExtendTarget? E.g. u8 to i16 is lossless.

We discussed this in the @rust-lang/libs-api meeting, and felt that either code should write these as separate conversions (e.g. .extend().cast_signed()) or use .into() which already provides "conversion via multiple operations at once".

[jhpratt]

Not doing so ensures the methods serve exactly one purpose. It's trivial to chain that and .cast_signed() (already stable) in that situation. Imo it's more explicit about what is happening.

Last I checked, time is the only code base using num-conv, so check that out if you want to see real world code. Otherwise it's just examples, realistically.

[joshtriplett]

fn foo(x: impl ExtendTarget<i32>) {
    let x = x.extend(); // x is now i32
}

This function would accept i8, i16, and i32. I would be able to accept parameters based on the target, not whatever Self happens to be.

If the trait is intended to be wholly inaccessible or perma-unstable, then sure, I guess it doesn't matter the way it's written. This was my thinking when writing num-conv, although I did admittedly keep the method on the target traits private.

The way we wrote the traits, they're consistent with that usage. The trait is unstable and sealed for now, but we could consider making it public and/or unsealed in the future; that seems like a reasonable usage.

I'm curious, and would love to know: what would be the motivation to write impl ExtendTarget<i32> rather than impl Into<i32>?

[jhpratt]

Clarity? Personally I would use Into (or nothing at all), but I have no doubt people will write code like that if allowed.

By having it as proposed, you'd need to introduce another generic in order to target an i32, no? How else would you write i32: ExtendTarget<?>? I'd also think that it should be ExtensibleFrom given the ordering, but that's a simple naming nit.

Though for what it's worth, I think it should remain sealed, just accessible and eventually stabilized.

[joshtriplett]

Clarity? Personally I would use Into (or nothing at all), but I have no doubt people will write code like that if allowed.

By having it as proposed, you'd need to introduce another generic in order to target an i32, no? How else would you write i32: ExtendTarget<?>? I'd also think that it should be ExtensibleFrom given the ordering, but that's a simple naming nit.

Though for what it's worth, I think it should remain sealed, just accessible and eventually stabilized.

The current planned implementation is that i32: ExtendTarget<i64> means "i32 can be extended to i64". So if you want "anything that can be extended to i32", that's impl ExtendTarget<i32>.

Possibly the trait should have a different name to make the direction more obvious.

[jhpratt]

The current planned implementation is that i32: ExtendTarget<i64> means "i32 can be extended to i64". So if you want "anything that can be extended to i32", that's impl ExtendTarget<i32>.

Possibly the trait should have a different name to make the direction more obvious.

That's not what it looks like in the top post?

impl iX {
    // T is a signed integer with size >= Self
    fn extend<T: ExtendTarget<Self>>(self) -> T;
}

[joshtriplett]

@jhpratt Fixed.