Tracking Issue for `integer_casts`

[orlp]

Feature gate: #![feature(integer_casts)]

This is a tracking issue for the addition of saturating, wrapping, checked, unchecked, and strict casts between integer types.

Public API

For each built-in integer type T the following methods are added:

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<T: BoundedCastFromInt<Self>>(self) -> T;
    
    /// Converts `self` to the target integer type, wrapping around at the
    /// boundary of the target type.
    fn wrapping_cast<T: BoundedCastFromInt<Self>>(self) -> T;

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

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

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

Steps / History

• ACP: Add missing integer casts libs-team#788
• Implementation: Implement feature integer_casts #157402
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• What should happen to the current unstable narrow/truncate API?
• Should the NonZero types be included?

Footnotes

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

[orlp]

I can't assign myself but I will try to port the implementation from the int-cast crate to std this week.

[Apersoma]

The BoundedCastFromInt trait would need to be split into a saturating and wrapping variants for NonZero<uint> to ever be supported by the saturating cast since you can't implement the wrapping cast for it (except for converting between signed and unsigned nonzeros of the same size but cast_signed and cast_unsigned already exist).

[orlp]

@Apersoma I would never implement a wrapping variant for NonZero as it's unclear what it means. Saturating somewhat makes sense for NonZero<uint> but makes no sense for NonZero<int>.

Personally I think it's better if we implement neither operation with NonZero as the output type.

NonZero is fine as source type for BoundedCastFromInt, and always fine for CheckedCastFromInt both as source and target.