Auto merge of #87921 - kellerkindt:master, r=kennytm

Add Saturating type (based on Wrapping type)

Tracking #87920

### Unresolved Questions
<!--
Include any open questions that need to be answered before the feature can be
stabilised.
-->

 - [x] ~`impl Div for Saturating<T>` falls back on inner integer division - which seems alright?~
    - [x] add `saturating_div`? (to respect division by `-1`)
 - [x] There is no `::saturating_shl` and `::saturating_shr`. (How to) implement `Shl`, `ShlAssign`, `Shr` and `ShrAssign`?
   - [naively](3f7d2ce)
 - [x] ~`saturating_neg` is only implemented on [signed integer types](https://doc.rust-lang.org/std/?search=saturating_n)~
 - [x] Is the implementation copied over from the `Wrapping`-type correct for `Saturating`?
   - [x] `Saturating::rotate_left`
   - [x] `Saturating::rotate_right`
   - [x] `Not`
   - [x] `BitXorOr` and `BitXorOrAssign`
   - [x] `BitOr` and `BitOrAssign`
   - [x] `BitAnd` and `BitAndAssign`
   - [x] `Saturating::swap_bytes`
   - [x] `Saturating::reverse_bits`

Author: bors

library/core/src/num/int_macros.rs

@@ -918,6 +918,40 @@ macro_rules! int_impl {
             }
         }
 
+        /// Saturating integer division. Computes `self / rhs`, saturating at the
+        /// numeric bounds instead of overflowing.
+        ///
+        /// # Examples
+        ///
+        /// Basic usage:
+        ///
+        /// ```
+        /// #![feature(saturating_div)]
+        ///
+        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
+        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_div(-1), ", stringify!($SelfT), "::MIN + 1);")]
+        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")]
+        ///
+        /// ```
+        ///
+        /// ```should_panic
+        /// #![feature(saturating_div)]
+        ///
+        #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
+        ///
+        /// ```
+        #[unstable(feature = "saturating_div", issue = "87920")]
+        #[rustc_const_unstable(feature = "saturating_div", issue = "87920")]
+        #[must_use = "this returns the result of the operation, \
+                      without modifying the original"]
+        #[inline]
+        pub const fn saturating_div(self, rhs: Self) -> Self {
+            match self.overflowing_div(rhs) {
+                (result, false) => result,
+                (_result, true) => Self::MAX, // MIN / -1 is the only possible saturating overflow
+            }
+        }
+
         /// Saturating integer exponentiation. Computes `self.pow(exp)`,
         /// saturating at the numeric bounds instead of overflowing.
         ///

library/core/src/num/mod.rs

@@ -43,8 +43,12 @@ mod uint_macros; // import uint_impl!
 mod error;
 mod int_log10;
 mod nonzero;
+#[unstable(feature = "saturating_int_impl", issue = "87920")]
+mod saturating;
 mod wrapping;
 
+#[unstable(feature = "saturating_int_impl", issue = "87920")]
+pub use saturating::Saturating;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use wrapping::Wrapping;
 

library/core/src/num/saturating.rs

@@ -1041,6 +1041,36 @@ macro_rules! uint_impl {
             }
         }
 
+        /// Saturating integer division. Computes `self / rhs`, saturating at the
+        /// numeric bounds instead of overflowing.
+        ///
+        /// # Examples
+        ///
+        /// Basic usage:
+        ///
+        /// ```
+        /// #![feature(saturating_div)]
+        ///
+        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
+        ///
+        /// ```
+        ///
+        /// ```should_panic
+        /// #![feature(saturating_div)]
+        ///
+        #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
+        ///
+        /// ```
+        #[unstable(feature = "saturating_div", issue = "87920")]
+        #[rustc_const_unstable(feature = "saturating_div", issue = "87920")]
+        #[must_use = "this returns the result of the operation, \
+                      without modifying the original"]
+        #[inline]
+        pub const fn saturating_div(self, rhs: Self) -> Self {
+            // on unsigned types, there is no overflow in integer division
+            self.wrapping_div(rhs)
+        }
+
         /// Saturating integer exponentiation. Computes `self.pow(exp)`,
         /// saturating at the numeric bounds instead of overflowing.
         ///

library/core/src/num/uint_macros.rs

@@ -310,6 +310,8 @@
 #![feature(ptr_internals)]
 #![feature(rustc_attrs)]
 #![feature(rustc_private)]
+#![feature(saturating_div)]
+#![feature(saturating_int_impl)]
 #![feature(slice_concat_ext)]
 #![feature(slice_internals)]
 #![feature(slice_ptr_get)]

library/std/src/lib.rs

@@ -12,6 +12,8 @@ mod tests;
 #[cfg(test)]
 mod benches;
 
+#[unstable(feature = "saturating_int_impl", issue = "87920")]
+pub use core::num::Saturating;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::num::Wrapping;
 #[stable(feature = "rust1", since = "1.0.0")]