Tracking Issue for `exact_div`

[newpavlov]

Feature gate: #![feature(exact_div)]

This is a tracking issue for exact division methods (i.e. for division without remainder) on primitive integer types.

Public API

/// Checked integer division without remainder. Computes `self / rhs`,
/// returning `None` if `rhs == 0` or if division remainder is not zero.
pub const fn checked_exact_div(self, rhs: Self) -> Option<Self> { ... }

/// Integer division without remainder. Computes `self / rhs`,
/// panics if `rhs == 0` or if division remainder is not zero.
pub const fn exact_div(self, rhs: Self) -> Self { ... }

/// Integer division without remainder.
/// Unchecked version of `exact_div`.
pub unsafe const fn unchecked_exact_div(self, rhs: Self) -> Self { ... }

Steps / History

• ACP: Add ((un)checked_)exact_div methods for integer types libs-team#337
• Implementation: TODO
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Concerns over usefulness of the panicking exact_div: Add ((un)checked_)exact_div methods for integer types libs-team#337 (comment)

[hanna-kruppe]

How do these handle overflow (iN::MIN / -1)?

[newpavlov]

They return None/panic/cause UB respectively, see here.

[hanna-kruppe]

For the safe version this makes sense but for unchecked_exact_div it’s not obvious to me that UB is the right choice. Having three distinct preconditions to check (no remainder, no division by zero, no overflow) is not great because it’s easy to forget one, especially the overflow edge case. Even for unsigned types, the precedent in stable Rust is handling division by zero via impl Div<NonZeroT> for T instead of an unsafe method that’s UB on zero RHS. This may be useful in this case as well. And overflow in signed division could panic even if the “no remainder” portion is unchecked under threat of UB.

[newpavlov]

The unsafe variant would be a simple wrapper around the exact_div intrinsic.

[hanna-kruppe]

Just because the perma-unstable intrinsic works this way doesn’t mean it’s also the best option for a stable user-facing API. We also have an unchecked_div intrinsic but as noted in my last comment, it’s not exposed as-is.

[newpavlov]

Any other behavior would be surprising. You could argue that we don't need unchecked_exact_div methods similarly to how we don't have unchecked_div, but there was an explicit interest in it during previous discussion. Personally, I think we should add unchecked_div methods instead.

[hanna-kruppe]

I’m not here to argue about whether the functionality is needed, just point out that there’s other ways to expose it that may be better (easier to use correctly), at least for unsigned integers. Similarly , there’s no need to add unsafe unchecked_div methods for unsigned integers because the safe Div implementations already achieves the same effect (those impls use the unchecked_div intrinsic internally, and callers that need to unsafely assert that the RHS is non-zero can combine it with NonZero::new_unchecked), and unchecked_div for signed integers could also take a NonZero RHS and only require callers to check the “no overflow” condition.

[abgros]

For the safe version this makes sense but for unchecked_exact_div it’s not obvious to me that UB is the right choice. Having three distinct preconditions to check (no remainder, no division by zero, no overflow) is not great because it’s easy to forget one, especially the overflow edge case.

No, there is only one unsafe precondition: a.exact_div_unchecked(b) is only allowed if there is a number c such that b * c == a (without overflow). The three cases are just a consequence of that.

An "unchecked" method panicking on some inputs would be quite surprising.

[hanna-kruppe]

This “single” precondition leaves a third of the work to the “(without overflow)” and isn’t even correct: a = b = 0 is UB but c = 0 satisfies b * c = a.

In any case: even if there is some clever way to subsume all three conditions in a single one, that’s of little use to unsafe code authors if the generality makes it easy to overlook edge cases or difficult to connect to the concrete facts available at the call site.

[abgros]

This “single” precondition leaves a third of the work to the “(without overflow)” and isn’t even correct: a = b = 0 is UB but c = 0 satisfies b * c = a.

You're right, it should be a unique number c.