Rollup merge of rust-lang#152179 - nickkuk:overflow-direction-note, r=jhpratt

Add documentation note about signed overflow direction

In rust-lang#151989 (comment) I noticed that signed overflow direction can be determined by returned wrapped value. It is not very obvious (especially, assuming additional `carry: bool` summand), but it is important if we want to add new leading (signed) limb to big integer in this case.

Examples for small summands `x, y: i8` with result extension:

| x     | y    | overflow | result as (u8, i8) |
| ----  | ---- | -------- | ------------------ |
| -1    | -128 | true     | (127, -1)          |
| 0     | -1   | false    | (255, -1)          |
| 2     | 2    | false    | (4, 0)             |
| 127   | 1    | true     | (128, 0)           |

Here is general proof.

1. Set $s=2^{N-1}$ and let's say `iN::carrying_add(x, y, c)` returns `(result, true)` then

$$
\mathrm{result}=\begin{cases}
x + y + c + 2s,& x + y + c \le -s-1,\\
x+y+c-2s,& x+y+c\ge s.
\end{cases}
$$

First case is overflowing below `iN::MIN` and we have

$$
\mathrm{result}\ge -s-s+0+2s =0;\qquad
\mathrm{result}=x + y + c + 2s\le -s-1+2s = s - 1,
$$

so we obtain $[0; s-1]$ which is exactly range of non-negative `iN`.

Second case is overflowing above `iN::MAX` and

$$
\mathrm{result}=x+y+c-2s\ge s-2s =-s;\qquad
\mathrm{result}\le s-1 + s-1+1-2s = -1,
$$

that is, $[-s,-1]$ which is exactly range of negative `iN`.

2. Now suppose that `iN::borrowing_sub(x,y,b)` returns `(result, true)` then

$$
\mathrm{result}=\begin{cases}
x - y - b + 2s,& x - y - b \le -s-1,\\
x - y - b - 2s,& x - y - b\ge s.
\end{cases}
$$

First case is overflowing below `iN::MIN` and we have

$$
\mathrm{result}\ge -s-(s-1)-1+2s =0;\qquad
\mathrm{result}=x - y - b + 2s\le -s-1+2s = s - 1.
$$

Second case is overflowing above `iN::MAX` and

$$
\mathrm{result}=x-y-b-2s\ge s-2s =-s;\qquad
\mathrm{result}\le s-1 - (-s) - 0 - 2s = -1.
$$

Author: jhpratt

library/core/src/num/int_macros.rs

@@ -2481,7 +2481,8 @@ macro_rules! int_impl {
         ///
         /// Returns a tuple of the addition along with a boolean indicating
         /// whether an arithmetic overflow would occur. If an overflow would have
-        /// occurred then the wrapped value is returned.
+        /// occurred then the wrapped value is returned (negative if overflowed
+        /// above [`MAX`](Self::MAX), non-negative if below [`MIN`](Self::MIN)).
         ///
         /// # Examples
         ///
@@ -2516,6 +2517,9 @@ macro_rules! int_impl {
         /// The output boolean returned by this method is *not* a carry flag,
         /// and should *not* be added to a more significant word.
         ///
+        /// If overflow occurred, the wrapped value is returned (negative if overflowed
+        /// above [`MAX`](Self::MAX), non-negative if below [`MIN`](Self::MIN)).
+        ///
         /// If the input carry is false, this method is equivalent to
         /// [`overflowing_add`](Self::overflowing_add).
         ///
@@ -2583,7 +2587,8 @@ macro_rules! int_impl {
         /// Calculates `self` - `rhs`.
         ///
         /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
-        /// would occur. If an overflow would have occurred then the wrapped value is returned.
+        /// would occur. If an overflow would have occurred then the wrapped value is returned
+        /// (negative if overflowed above [`MAX`](Self::MAX), non-negative if below [`MIN`](Self::MIN)).
         ///
         /// # Examples
         ///
@@ -2619,6 +2624,9 @@ macro_rules! int_impl {
         /// The output boolean returned by this method is *not* a borrow flag,
         /// and should *not* be subtracted from a more significant word.
         ///
+        /// If overflow occurred, the wrapped value is returned (negative if overflowed
+        /// above [`MAX`](Self::MAX), non-negative if below [`MIN`](Self::MIN)).
+        ///
         /// If the input borrow is false, this method is equivalent to
         /// [`overflowing_sub`](Self::overflowing_sub).
         ///