Tracking Issue for int_roundings

[jhpratt]

Feature gate: #![feature(int_roundings)]

This is a tracking issue for the div_floor, div_ceil, next_multiple_of, and checked_multiple_of methods on all integer types.

Public API

impl {integer} {
    #[unstable]
    pub const fn div_floor(self, rhs: Self) -> Self;
}

impl {signed integer} {
    #[unstable]
    pub const fn div_ceil(self, rhs: Self) -> Self;

    #[unstable]
    pub const fn next_multiple_of(self, rhs: Self) -> Self;

    #[unstable]
    pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self>;
}

impl {unsigned integer} {
    #[stable(since = "1.73.0")]
    pub const fn div_ceil(self, rhs: Self) -> Self;

    #[stable(since = "1.73.0")]
    pub const fn next_multiple_of(self, rhs: Self) -> Self;

    #[stable(since = "1.73.0")]
    pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self>;
}

Steps / History

• Implement int_roundings (div_floor, div_ceil, next_multiple_of, checked_next_multiple_of) #88582
• regression: int_roundings conflicts with existing APIs #88971
• Temporarily rename int_roundings functions to avoid conflicts #89184
• Try all stable method candidates first before trying unstable ones #90329
• Revert "Temporarily rename int_roundings functions to avoid conflicts" #91141
• Update int_roundings methods from feedback #95359
• Partially stabilize int_roundings #94455

Unresolved Questions

• None yet.

[fourbytes]

Just updated to the latest nightly, looks like this feature breaks the num-bigint crate.

error[E0658]: use of unstable library feature 'int_roundings'

error[E0658]: use of unstable library feature 'int_roundings'
   --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint.rs:398:45
    |
398 |                 let root_scale = extra_bits.div_ceil(&n64);
    |                                             ^^^^^^^^
    |
    = note: see issue #88581 <https://github.com/rust-lang/rust/issues/88581> for more information
    = help: add `#![feature(int_roundings)]` to the crate attributes to enable

error[E0308]: mismatched types
   --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint.rs:398:54
    |
398 |                 let root_scale = extra_bits.div_ceil(&n64);
    |                                                      ^^^^ expected `u64`, found `&u64`
    |
help: consider removing the borrow
    |
398 -                 let root_scale = extra_bits.div_ceil(&n64);
398 +                 let root_scale = extra_bits.div_ceil(n64);
    |

error[E0658]: use of unstable library feature 'int_roundings'
  --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint/convert.rs:70:10
   |
70 |         .div_ceil(&big_digit::BITS.into())
   |          ^^^^^^^^
   |
   = note: see issue #88581 <https://github.com/rust-lang/rust/issues/88581> for more information
   = help: add `#![feature(int_roundings)]` to the crate attributes to enable

error[E0308]: mismatched types
  --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint/convert.rs:70:19
   |
70 |         .div_ceil(&big_digit::BITS.into())
   |                   ^^^^^^^^^^^^^^^^^^^^^^^ expected `u64`, found reference
   |
   = note:   expected type `u64`
           found reference `&_`
help: consider removing the borrow
   |
70 -         .div_ceil(&big_digit::BITS.into())
70 +         .div_ceil(big_digit::BITS.into())
   |

error[E0658]: use of unstable library feature 'int_roundings'
   --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint/convert.rs:585:10
    |
585 |         .div_ceil(&u64::from(bits))
    |          ^^^^^^^^
    |
    = note: see issue #88581 <https://github.com/rust-lang/rust/issues/88581> for more information
    = help: add `#![feature(int_roundings)]` to the crate attributes to enable

error[E0308]: mismatched types
   --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint/convert.rs:585:19
    |
585 |         .div_ceil(&u64::from(bits))
    |                   ^^^^^^^^^^^^^^^^ expected `u64`, found `&u64`
    |
help: consider removing the borrow
    |
585 -         .div_ceil(&u64::from(bits))
585 +         .div_ceil(u64::from(bits))
    |

error[E0658]: use of unstable library feature 'int_roundings'
   --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint/convert.rs:613:10
    |
613 |         .div_ceil(&u64::from(bits))
    |          ^^^^^^^^
    |
    = note: see issue #88581 <https://github.com/rust-lang/rust/issues/88581> for more information
    = help: add `#![feature(int_roundings)]` to the crate attributes to enable

error[E0308]: mismatched types
   --> /home/fourbytes/.cargo/registry/src/github.com-1ecc6299db9ec823/num-bigint-0.4.1/src/biguint/convert.rs:613:19
    |
613 |         .div_ceil(&u64::from(bits))
    |                   ^^^^^^^^^^^^^^^^ expected `u64`, found `&u64`
    |
help: consider removing the borrow
    |
613 -         .div_ceil(&u64::from(bits))
613 +         .div_ceil(u64::from(bits))
    |

Some errors have detailed explanations: E0308, E0658.
For more information about an error, try `rustc --explain E0308`.
error: could not compile `num-bigint` due to 8 previous errors
warning: build failed, waiting for other jobs to finish...
error: build failed

[jhpratt]

That is considered acceptable breakage. Per RFC 1105, adding an inherent impl is a minor change.

[aidanhs]

Though technically not a breaking change, I wonder if it's worth delaying it landing in stable for a bit? "Everything that uses num-bigint" feels kinda large. I guess we'll see the scope of the breakage on a release-based crater run.

[jhpratt]

num-bigint has already cut a release to fix it on their end. I suggested reverting the initial implementation on Zulip when that was pointed out. Definitely worth waiting a bit for stabilization to let things settle.

[leonardo-m]

Before stabilizing these functions let's see if enough people use them often enough (otherwise it's wiser to remove them).

[jhpratt]

There's a well-established use for them via the num crate. A number of algorithms would use div_floor and div_ceil, and next_multiple_of is useful for things like block sizes. The use case absolutely exists.

[jhpratt]

Now that FCP has completed, what is the actual API that was agreed upon? I can update the open PR (#94455), but I don't have the time to re-read this thread 😅

[joshtriplett]

Unsigned only, and without div_floor.

[jhpratt]

PR has been updated to that effect.

[lib-eramen]

I'm just stumbling on this feature right now and I can see that there's a tag that says FCP is completed (and conversation indicates that), so can we tick that one to-do item that's in the original comment? Just a nit-pick.

[jhpratt]

That FCP was for a partial stabilization.

[orlp]

I do not like that next_multiple_of goes in different directions based on the sign of the rhs for signed integers. I propose we add a second function, prev_multiple_of (which is generally useful for unsigned integers as well, and something I would like to add regardless).

Then I propose that next_multiple_of finds the multiple of rhs that is always greater or equal to lhs, and that prev_multiple_of finds the multiple of rhs that is always less than or equal to lhs, also for signed integers.

Note that this would mean nothing would change for unsigned::next_multiple_of, which is good since it's already stabilized, whereas signed::next_multiple_of is still unstable so can be changed.

[hsanzg]

Are there any plans to add a NonZero{unsigned} version of checked_next_multiple_of? Given two positive integers, the result of this method is also positive when the rounding does not overflow. On the other hand, the wrapping behavior of {unsigned}::next_multiple_of can lead to a zero result in release mode (because zero is the trivial multiple of every integer). Specifically, I propose to add

• An unsafe, NonZero-equivalent of {unsigned}::next_multiple_of called NonZero{unsigned}::unchecked_next_multiple_of that returns NonZero{unsigned}; and
• A safe NonZero-equivalent of {unsigned}::checked_next_multiple_of called NonZero{unsigned}::next_multiple_of that returns Option<NonZero{unsigned}>, being None on overflow.

Example application: I've been working on a stack allocator, and I would've liked to represent the size of a stack as a NonZeroUsize. The methods proposed above would have been really useful to do alignment calculations, but I finally went with a size: usize variable since the sprinkling of NonZeroUsize.get calls is a bit cleaner than the alternative (implementing next_multiple_of myself, as in this library).

I think any NonZero{signed} version of [checked_]next_multiple_of would see less use in practice, but it could would make the standard library more uniform/predictable. The same applies to div_floor and div_ceil.

(I'm sorry in advance if this is not the proper place to discuss this issue. It could also be part of the nonzero_ops feature #84186.)

[thaliaarchi]

I am interested in this being fleshed out, so I surveyed the methods. The following division/remainder methods are not implemented. For ceiling and floored rounding, there is no rem_* analogues to div_* and none of the versions that control overflow and wrapping. Additionally, there is no Euclidean saturating division or any saturating remainders.

• rem_{ceil,floor}
• saturating_rem, saturating_{div,rem}_{ceil,euclid,floor}
• wrapping_{div,rem}_{ceil,floor}
• checked_{div,rem}_{ceil,floor}
• overflowing_{div,rem}_{ceil,floor}
• strict_{div,rem}_{ceil,floor} (Tracking Issue for arithmetic that panics on overflow (strict_* operations) #118260)

I maintain a document tracking rounding of division and modulo across languages, which may be a useful reference.