Stabilize unsigned and float variants of num_midpoint feature

[Urgau]

This PR proposes that we stabilize the unsigned variants of the num_midpoint feature as well as the floats variants, since they are not subject to any unresolved questions, which is equivalent to doing (a + b) / 2 (and (a + b) >> 1) in a sufficiently large number.

The stabilized API surface would be:

/// Calculates the middle point of `self` and `rhs`.
///
/// `midpoint(a, b)` is `(a + b) / 2` as if it were performed in a sufficiently-large unsigned integral type.
/// This implies that the result is always rounded towards negative infinity and that no overflow will ever occur.

impl u{8,16,32,64,128,size} {
    pub const fn midpoint(self, rhs: Self) -> Self;
}

impl NonZeroU{8,16,32,64,size} {
    pub const fn midpoint(self, rhs: Self) -> Self;
}

impl f{32,64} {
    pub const fn midpoint(self, rhs: Self) -> Self;
}

The signed variants u{8,16,32,64,128,size} would remain gated, until a decision is made about the rounding mode, in other words that the unresolved questions are resolved.

cc @rust-lang/libs-api
cc @scottmcm
r? libs-api

[dtolnay]

@rfcbot fcp merge

[rfcbot]

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

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

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.

[scottmcm]

This absolutely is 👍 from me. (Thanks for the ping!)

I'm a fan of it as described here where it's consistent with (a + b) / 2, like the discussion of this in https://devblogs.microsoft.com/oldnewthing/20220207-00/?p=106223 . I like midpoint(5, 10) == 7 == midpoint(10, 5). To me, being consistent with what people wrote for small values that are in-range is good, and that it being symmetric is also good.

That said, I feel obliged to mention that in the tracking issue that some people want midpoint(5, 10) == 7 but midpoint(10, 5) == 8, where it's consistent with a + (b - a) / 2 instead, so wanted to make sure that libs-api discusses the rounding explicitly.

[scottmcm]

Actually, @Urgau , consider putting "and float" in the title & OP here. To me the "stabilize the unsigned variants" text wouldn't include floats, since they're obviously signed.

[tgross35]

Float midpoint should probably get a const gate, either here or separately. Bit unfortunate that it doesn't already have one to get stabilized at the same time.

[Urgau]

Float midpoint should probably get a const gate, either here or separately.

Good point, updated the PR to include the const stabilization of f{32,64}::midpoint since there is nothing preventing it.

[joshtriplett]

That said, I feel obliged to mention that in the tracking issue that some people want midpoint(5, 10) == 7 but midpoint(10, 5) == 8, where it's consistent with a + (b - a) / 2 instead, so wanted to make sure that libs-api discusses the rounding explicitly.

I would advocate the behavior that a.midpoint(b) == b.midpoint(a) for all a and b.

[RalfJung]

@bors r=dtolnay

[bors]

📌 Commit b88478f has been approved by dtolnay

It is now in the queue for this repository.