Stabilize num_midpoint_signed feature

[Urgau]

This PR proposes that we stabilize the signed variants of iN::midpoint, the operation is equivalent to doing (a + b) / 2 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 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)

@scottmcm mentioned a drawback in #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 #110840
cc @rust-lang/libs-api
cc @scottmcm
r? @dtolnay

[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.

[Urgau]

@Amanieu @m-ou-se @BurntSushi could one of you take a look at the FCP above, there is only one checkbox missing.

[rfcbot]

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

[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.

This will be merged soon.

[scottmcm]

With the FCP having completed,
@bors r+ rollup=always

[bors]

📌 Commit 5914fb7 has been approved by scottmcm

It is now in the queue for this repository.