Add `uNN::checked_sub_nonzero`

Proposal

Problem statement

It's really nice now that uNN::checked_sub gives you a safe way to get a uNN::unchecked_sub.

However, that's only a smooth replacement for code doing if a >= b { process(a - b) }.

It would also be nice to have a smooth replacement for code doing if a > b { process(a - b) }, especially if you want a NonZero.

Motivating examples or use cases

This is particularly common when implementing Iterator::advance_by, where the return type includes a NonZero, and the usual implementation involves comparing the passed-in n to the iterator's length, but what you want is essentially if n > len { self.exhaust(); return Err(n-len); }, but those types don't work out.

Solution sketch

impl u8/u16/... {
    pub const fn checked_sub_nonzero(self, subtrahend: Self) -> Option<NonZero<Self>> {
        if self > subtrahend { Some(unsafe { NonZero::new_unchecked(self.unchecked_sub(subtrahend)) }) }
        else { None }
    }
}

That encapsulates both unsafe calls in a useful safe API.

Alternatives

• People can continue to write if n > len { foo(NonZero::new(n - len).unwrap()) } and count on the optimizer to remove the panic path.
• Give a three-sized version of this that would work more like cmp, giving Greater(NonZero<T>)/Equal/Less(NonZero<T>), which could work on signed types too.
• Use something other than Option as a return type, so maybe you could have Result<u32, NonZeroU32> or Result<NonZeroU32, u32> as a return type (so you'd a.foo(b) or b.foo(a) depending which side you want the zero to be included on)
• Have other kinds of safe NonZero constructors, perhaps something like |a: u32, b: u32| if a > b { NonZero::new_unchecked(a) } that can work because for any value of b, if a is greater then it must be non-zero.
• Other names, like maybe checked_nonzero_sub would be more consistent with other ones like checked_signed_diff, or some other thing I'm not thinking of right now.
• Making this an associated thing on NonZero, like <NonZero<u32>>::checked_sub(len, n), rather than it being on the integer types.

Links and related work

https://github.com/rust-lang/rust/pull/124114 made checked_sub use unchecked_sub internally for unsigned integers, and https://github.com/rust-lang/rust/pull/124701 suggests it in the docs as a situational alternative to calling unchecked_sub directly.

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

Start by reading the existing uNN checked_sub and unchecked_sub APIs, then examine the Iterator::advance_by use case described here. Review the linked PRs and the libs-api feature lifecycle before deciding whether the proposed Option<NonZero> API is accepted; done means an agreed API direction, not an implementation, because this proposal remains under review.