Rollup merge of #134340 - Urgau:stabilize-num_midpoint_signed, r=scottmcm

Stabilize `num_midpoint_signed` feature

This PR proposes that we stabilize the signed variants of [`iN::midpoint`](https://github.com/rust-lang/rust/issues/110840#issue-1684506201), the operation is equivalent to doing `(a + b) / 2` in a sufficiently large number.

The stabilized API surface would be:

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

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

T-libs-api previously stabilized the unsigned (and float) variants in #131784, the signed variants were left out because of the rounding that should be used in case of negative midpoint.

This stabilization proposal proposes that we round towards zero because:
 - it makes the obvious `(a + b) / 2` in a sufficiently-large number always true
   - using another rounding for the positive result would be inconsistent with the unsigned variants
 - it makes `midpoint(-a, -b)` == `-midpoint(a, b)` always true
 - it is consistent with `midpoint(a as f64, b as f64) as i64`
 - it makes it possible to always suggest `midpoint` as a replacement for `(a + b) / 2` expressions *(which we may want to do as a future work given the 21.2k hits on [GitHub Search](https://github.com/search?q=lang%3Arust+%2F%5C%28%5Ba-zA-Z_%5D*+%5C%2B+%5Ba-zA-Z_%5D*%5C%29+%5C%2F+2%2F&type=code&p=1))*

`@scottmcm` mentioned a drawback in https://github.com/rust-lang/rust/pull/132191#issuecomment-2439891200:
> I'm torn, because rounding towards zero makes it "wider" than other values, which `>> 1` avoids -- `(a + b) >> 1` has the nice behaviour that `midpoint(a, b) + 2 == midpoint(a + 2, b + 2)`.
>
> But I guess overall sticking with `(a + b) / 2` makes sense as well, and I do like the negation property 🤷

Which I think is outweigh by the advantages cited above.

Closes #110840
cc `@rust-lang/libs-api`
cc `@scottmcm`
r? `@dtolnay`

0 files changed, 0 insertions, 0 deletions