Tracking Issue for unchecked_div_rem

[tgross35]

Feature gate: #![feature(unchecked_div_rem)]

This is a tracking issue for unchecked versions of / and % on integers. This is similar to existing methods like unchecked_mul.

Public API

// in core

impl {i8, u8, i16, u16, i32, u32, i64, u64, i128, u128} {
    // Same preconditions as the versions in intrinsics

    /// Performs an unchecked division, resulting in undefined behavior where y == 0 or x == T::MIN && y == -1.
    pub fn unchecked_div(self, rhs: Self) -> Self;

    /// Returns the remainder of an unchecked division, resulting in undefined behavior when y == 0 or x == T::MIN && y == -1.
    pub fn unchecked_rem(self, rhs: Self) -> Self;
}

Steps / History

• ACP: ACP: add {integer}::unchecked_div and {integer}::unchecked_rem libs-team#526
• Implementation: #...
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Signed and unsigned have different preconditions; should the names be different as a stumbling stone when changing between the two? Tracking Issue for unchecked_div_rem #136716 (comment)

Footnotes

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

[tgross35]

I won't be able to work on this for a little bit so if anyone wants,

@rustbot label +E-easy +E-help-wanted

[yegeunyang]

@rustbot claim

[the8472]

Those methods are a bit unusual in that the signed methods have more safety preconditions than the unsigned ones. So converting u8 code to i8 can have subtle consequences.
They also map to different instruction (DIV vs. IDIV on x86).

I think treating these differently would make sense and "consistency" is not a good argument. We do have some asymmetry between unsigned and signed types in other places too, for example unchecked_neg does not exist on unsigned types.

[yegeunyang]

@rustbot release-assignment

[Thrumbo33]

@rustbot claim

[tgross35]

Those methods are a bit unusual in that the signed methods have more safety preconditions than the unsigned ones. So converting u8 code to i8 can have subtle consequences. They also map to different instruction (DIV vs. IDIV on x86).

I think treating these differently would make sense and "consistency" is not a good argument. We do have some asymmetry between unsigned and signed types in other places too, for example unchecked_neg does not exist on unsigned types.

Do you think these should only exist on unsigned types then? Or not exist at all.

[Thrumbo33]

@rustbot release-assignment

[madhav-madhusoodanan]

@rustbot claim

[madhav-madhusoodanan]

Those methods are a bit unusual in that the signed methods have more safety preconditions than the unsigned ones. So converting u8 code to i8 can have subtle consequences. They also map to different instruction (DIV vs. IDIV on x86).

I think treating these differently would make sense and "consistency" is not a good argument. We do have some asymmetry between unsigned and signed types in other places too, for example unchecked_neg does not exist on unsigned types.

@the8472 @tgross35 Would it be a good idea to then implement 2 different versions of unchecked_div and unchecked_rem for the signed and unsigned types?

We could then tailor the failure condition being passed to assert_unsafe_precondition for the unsigned version (checking only for rhs == 0) and the signed version (checking for LHS (self) == type::MIN and RHS == -1 also).

I believe overflow_div handles the latter part. To handle the former (zero equality check) case we could return self itself when rhs == 0, in line with how overflow_div handles failure cases.