Add `((un)checked_)exact_div` methods for integer types

[newpavlov]

Proposal

Problem statement

In some cases it desirable to get division result and ensure that the division has no remainder. For example, a function which works with memory mappings may accept size in bytes, but it requires that the size must be multiple of OS page size. Today we have to insert separate checks (e.g. assert_eq!(size / OS_PAGE_SIZE, 0)) somewhere near the division. It makes code less concise and not great at expressing intent.

Motivating examples or use cases

In our code we have code which works with pages and accepts size in bytes. It requires that the size should be multiple of the page size. The size is provided in bytes for user convenience and because page size can depend on OS and constants.

So we have a bunch of code like this:

const PAGE_SIZE: usize = 1 << 14;
const OS_PAGE_SIZE: usize = 1 << 12;

// somewhere else in the project
let os_pages: usize = pages_len * (PAGE_SIZE / OS_PAGE_SIZE);
// the constants defined in a separate faraway module,
// so to make correctness reasoning local, we assert it near the division
assert_eq(PAGE_SIZE % OS_PAGE_SIZE, 0);

// another place
let pages_to_map: usize = cfg.mapping_size / PAGE_SIZE;
if cfg.mapping_size / PAGE_SIZE {
    return Err(Error::NotPageMultiple);
}
let pages_to_map: u32 = pages_to_map.try_into().map_err(|_| Error::TooBig)?;

To simplify the code we can introduce a helper extension trait and implement it for necessary integer types, but we need to introduce the trait and import it every time the methods are used. Also in a multi-crate projects it becomes even more annoying. We either have to define the trait in each crate where it needed or introduce a whole separate crate for this small functionality.

Solution sketch

Introduce the following methods to all integers through int_impl! and uint_impl! macros:

/// 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 { ... }

For signed integer the conditions also include potential overflow when MIN is divided by -1.

Alternatives

Users may use explicit checks based on the remainder operator or custom traits as shown in the examples section. Arguably, the functionality is too small for a separate crate.

Links and related work

rust-lang/rust#116632

[pitaj]

For the const case, as in your example, it's best to do that assertion at compile time:

const PAGE_SIZE: usize = 1 << 14;
const OS_PAGE_SIZE: usize = 1 << 12;
const _: () = {
    assert!(PAGE_SIZE % OS_PAGE_SIZE == 0);
};

I recommend you provide a different example that shows how this method would be beneficial at runtime.

[newpavlov]

The point is that constant definitions with static assertions (we use them in our code, but they are not relevant here) can be quite far away from operations which depend on the assert. The motivation for the proposed methods is to clearly express that we expect that two numbers divide without remainder without any additional clutter associated with asserts or branches.

Also, the second part of the example is for runtime values.

[pitaj]

In that case, you should provide a const PAGES_PER_OS_PAGE or something that does the division (and remainder check) ahead of time, and use that everywhere instead.

I missed the runtime example cfg.mapping_size, but even in that case maybe you should do the division when you load the config and store the result in the cfg struct rather than having divisions all throughout your codebase.

All that said, this seems pretty niche. Also for the name, I'm not a fan of norem, maybe exact or factor instead?

[pitaj]

Here's another alternative. If we had a std version of div_rem then you could match on the result:

if let (quotient, 0) = whatever.div_rem(PAGE_SIZE) {
    // divides evenly
} else {
    // there was a remainder
}

[agausmann]

One usecase for this is a subproblem of Advent of Code 2024 day 13 (spoiler ahead).

The problem overall deals with integer systems of equations, and it is interested in whether or not the solution values are integers.

At the final step of my solver, it has integer equations of the form A*x = B and C*y = D where x,y are unknowns. The solution is x = B / A and y = D / C, but first it has to check B % A == 0 and D % C == 0.

if b % a == 0 && d % c == 0 {
    Some((b / a, d / c))
} else {
    None
}

With a function like checked_norem_div, it could be written simply as

b.checked_norem_div(a).zip(d.checked_norem_div(c))

Before finding this issue, the name that I thought of is exact_div - only return the result of a / b if it is exactly an integer (i.e., if a is exactly a multiple of b)

[tgross35]

Before finding this issue, the name that I thought of is exact_div - only return the result of a / b if it is exactly an integer (i.e., if a is divisible by b)

The name that popped into my head was div_exact, maybe this bikeshed is on to something :)

[agausmann]

At first, I did think of div_exact, but every math operation has the modifier before the root (checked_, overflowing_, wrapping_, strict_, etc)

[agausmann]

*Except for _euclid and _signed

[kennytm]

We already have std::intrinsics::exact_div at home¹. The stable API name should better follow this.

Footnotes

1. it is used to support as_chunks_unchecked and align_offset ↩

[shepmaster]

My AoC solution used:

fn evenly_divide(n: u64, d: u64) -> Option<u64> {
    (n % d == 0).then_some(n / d)
}

[scottmcm]

Note that the exact_div intrinsic is unsafe because we tell LLVM it's guaranteed.

Makes me wonder if it makes sense to have a safe -> Option<T> version and an unsafe -> T version.

(And I wonder if it's make sense to have at least the unsafe version take T, NonZero<T> to help emphasize the extra unsafety condition.)

[RalfJung]

We already have std::intrinsics::exact_div at home1. The stable API name should better follow this.

Unstable intrinsics are not a precedent for stable names by any means. They typically get added without much thought about the name.

So, we can take it as one data point, but it's completely fine if the stable API has a different name -- this happens all the time. Sometimes we rename the intrinsic, many times we do not bother.