Rollup merge of rust-lang#134340 - Urgau:stabilize-num_midpoint_signe…

…d, r=scottmcm

Stabilize `num_midpoint_signed` feature

This PR proposes that we stabilize the signed variants of [`iN::midpoint`](rust-lang#110840 (comment)), 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 rust-lang#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 rust-lang#132191 (comment):
> 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 rust-lang#110840
cc `@rust-lang/libs-api`
cc `@scottmcm`
r? `@dtolnay`

library/core/src/num/mod.rs

@@ -163,14 +163,14 @@ macro_rules! midpoint_impl {
         /// # Examples
         ///
         /// ```
-        /// #![feature(num_midpoint_signed)]
         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")]
         #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").midpoint(2), 0);")]
         #[doc = concat!("assert_eq!((-7", stringify!($SelfT), ").midpoint(0), -3);")]
         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(-7), -3);")]
         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(7), 3);")]
         /// ```
-        #[unstable(feature = "num_midpoint_signed", issue = "110840")]
+        #[stable(feature = "num_midpoint_signed", since = "CURRENT_RUSTC_VERSION")]
+        #[rustc_const_stable(feature = "num_midpoint_signed", since = "CURRENT_RUSTC_VERSION")]
         #[must_use = "this returns the result of the operation, \
                       without modifying the original"]
         #[inline]
@@ -215,14 +215,14 @@ macro_rules! midpoint_impl {
         /// # Examples
         ///
         /// ```
-        /// #![feature(num_midpoint_signed)]
         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")]
         #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").midpoint(2), 0);")]
         #[doc = concat!("assert_eq!((-7", stringify!($SelfT), ").midpoint(0), -3);")]
         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(-7), -3);")]
         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(7), 3);")]
         /// ```
-        #[unstable(feature = "num_midpoint_signed", issue = "110840")]
+        #[stable(feature = "num_midpoint_signed", since = "CURRENT_RUSTC_VERSION")]
+        #[rustc_const_stable(feature = "num_midpoint_signed", since = "CURRENT_RUSTC_VERSION")]
         #[must_use = "this returns the result of the operation, \
                       without modifying the original"]
         #[inline]

library/coretests/tests/lib.rs

@@ -63,7 +63,6 @@
 #![feature(maybe_uninit_write_slice)]
 #![feature(min_specialization)]
 #![feature(never_type)]
-#![feature(num_midpoint_signed)]
 #![feature(numfmt)]
 #![feature(pattern)]
 #![feature(pointer_is_aligned_to)]