Add impl Div<NonZeroU{0}> for u{0} which cannot panic

[ohadravid]

Dividing an unsigned int by a NonZeroUxx requires a user to write (for example, in this SO question):

pub fn safe_div(x: u32, y: std::num::NonZeroU32) -> u32 {
    x / y.get()
}

which generates a panicking-checked-div assembly.
Avoiding the panic currently requires unsafe code.

This PR adds an impl Div<NonZeroU{0}> for u{0} (and impl Rem<NonZeroU{0}> for u{0}) which calls the unchecked_div (and unchecked_rem) intrinsic without any additional checks,
making the following code compile:

pub fn safe_div(x: u32, y: std::num::NonZeroU32) -> u32 {
    x / y
}

pub fn safe_rem(x: u32, y: std::num::NonZeroU32) -> u32 {
    x % y
}

The doc is set to match the regular div impl docs.

I've marked these as stable because (as I understand it) trait impls are automatically stable. I'm happy to change it to unstable if needed.

Following @dtolnay template from a similar issue:
this adds the following stable impls, which rely on dividing unsigned integers by nonzero integers being well defined and previously would have involved unsafe code to encode that knowledge:

impl Div<NonZeroU8> for u8 {
    type Output = u8;
}

impl Rem<NonZeroU8> for u8 {
    type Output = u8;
}

and equivalent for u16, u32, u64, u128, usize, but not for i8, i16, i32, i64, i128, isize (since -1/MIN is undefined).

r? @dtolnay

[leonardo-m]

I could use % (Rem) too...

[leonardo-m]

See also: #72762

[bors]

☔ The latest upstream changes (presumably #79167) made this pull request unmergeable. Please resolve the merge conflicts.

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

[dtolnay]

@rust-lang/libs:
@rfcbot fcp merge

This PR adds the following stable impls as a zero-overhead safe API around std::intrinsics::unchecked_div and std::intrinsics::unchecked_rem. They allow dividing unsigned integers by nonzero integers in a way that is statically known to be non-panicking. Previously it would have taken unsafe code to encode that knowledge.

impl Div<NonZeroU8> for u8 {
    type Output = u8;
}

impl Rem<NonZeroU8> for u8 {
    type Output = u8;
}

// and equivalent for u16, u32, u64, u128, usize

but not for i8, i16, i32, i64, i128, isize (since MIN/-1 is fallible).

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @KodrAus
• @dtolnay
• @m-ou-se
• @sfackler
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[ohadravid]

ping @Amanieu / @BurntSushi ? 🙏

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[mqudsi]

Just because I got the notification for the final comment period: I opened an RFC in advance of a pull request to do exactly the same just a week ago - this issue had flown under the radar and slipped through my searches.

This is basically identical to the same findings and implementation I had come up with and is a pretty obvious win.

(Nitpick: There are a few comments that are hard-wrapped after just a few words, and "checked by because" -> "checked because")

👍

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

[dtolnay]

@bors r+

[bors]

📌 Commit 9586643 has been approved by dtolnay

[bors]

⌛ Testing commit 9586643 with merge 2fab321...

[bors]

☀️ Test successful - checks-actions
Approved by: dtolnay
Pushing 2fab321 to master...

[leonardo-m]

It doesn't work in const functions:

const fn safe_div(x: u32, y: std::num::NonZeroU32) -> u32 { x / y }

[jplatte]

@leonardo-m This is not at all specific to these new trait implementations, you can't use trait methods at all in const fn right now. There's an RFC for allowing this here: rust-lang/rfcs#2632

The only reason any arithmetic works in const fn is that the desugaring of arithmetic operators to trait methods is somewhat of a lie: The compiler does a different translation for most (all?) operators applied to only primitive types. Since the NonZero* types are not primitives, that doesn't apply in this case.

[leonardo-m]

You may add a TODO, so once that RFC is usable in the std lib, you can improve this code.

By the way, this more efficient Mod has improved the performance of some functions in my code almost by 10% (those division by zero tests take some time).

[leonardo-m]

Also DivAssign<NonZeroUxx> is missing.