library/core/src/num/saturating.rs

   1 //! Definitions of `Saturating<T>`.
   2
   3 use crate::fmt;
   4 use crate::ops::{Add, AddAssign, BitAnd, BitAndAssign, BitOr, BitOrAssign};
   5 use crate::ops::{BitXor, BitXorAssign, Div, DivAssign};
   6 use crate::ops::{Mul, MulAssign, Neg, Not, Rem, RemAssign};
   7 use crate::ops::{Shl, ShlAssign, Shr, ShrAssign, Sub, SubAssign};
   8
   9 /// Provides intentionally-wrapped arithmetic on `T`.
  10 ///
  11 /// Operations like `+` on `u32` values are intended to never overflow,
  12 /// and in some debug configurations overflow is detected and results
  13 /// in a panic. While most arithmetic falls into this category, some
  14 /// code explicitly expects and relies upon saturating arithmetic.
  15 ///
  16 /// Saturating arithmetic can be achieved either through methods like
  17 /// `saturating_add`, or through the `Saturating<T>` type, which says that
  18 /// all standard arithmetic operations on the underlying value are
  19 /// intended to have saturating semantics.
  20 ///
  21 /// The underlying value can be retrieved through the `.0` index of the
  22 /// `Saturating` tuple.
  23 ///
  24 /// # Examples
  25 ///
  26 /// ```
  27 /// #![feature(saturating_int_impl)]
  28 /// use std::num::Saturating;
  29 ///
  30 /// let max = Saturating(u32::MAX);
  31 /// let one = Saturating(1u32);
  32 ///
  33 /// assert_eq!(u32::MAX, (max + one).0);
  34 /// ```
  35 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  36 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)]
  37 #[repr(transparent)]
  38 pub struct Saturating<T>(#[unstable(feature = "saturating_int_impl", issue = "87920")] pub T);
  39
  40 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  41 impl<T: fmt::Debug> fmt::Debug for Saturating<T> {
  42     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  43         self.0.fmt(f)
  44     }
  45 }
  46
  47 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  48 impl<T: fmt::Display> fmt::Display for Saturating<T> {
  49     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  50         self.0.fmt(f)
  51     }
  52 }
  53
  54 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  55 impl<T: fmt::Binary> fmt::Binary for Saturating<T> {
  56     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  57         self.0.fmt(f)
  58     }
  59 }
  60
  61 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  62 impl<T: fmt::Octal> fmt::Octal for Saturating<T> {
  63     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  64         self.0.fmt(f)
  65     }
  66 }
  67
  68 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  69 impl<T: fmt::LowerHex> fmt::LowerHex for Saturating<T> {
  70     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  71         self.0.fmt(f)
  72     }
  73 }
  74
  75 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  76 impl<T: fmt::UpperHex> fmt::UpperHex for Saturating<T> {
  77     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  78         self.0.fmt(f)
  79     }
  80 }
  81 #[allow(unused_macros)]
  82 macro_rules! sh_impl_signed {
  83     ($t:ident, $f:ident) => {
  84         #[unstable(feature = "saturating_int_impl", issue = "87920")]
  85         impl Shl<$f> for Saturating<$t> {
  86             type Output = Saturating<$t>;
  87
  88             #[inline]
  89             fn shl(self, other: $f) -> Saturating<$t> {
  90                 if other < 0 {
  91                     Saturating(self.0.shr((-other & self::shift_max::$t as $f) as u32))
  92                 } else {
  93                     Saturating(self.0.shl((other & self::shift_max::$t as $f) as u32))
  94                 }
  95             }
  96         }
  97         forward_ref_binop! { impl Shl, shl for Saturating<$t>, $f,
  98         #[unstable(feature = "saturating_int_impl", issue = "87920")] }
  99
 100         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 101         impl ShlAssign<$f> for Saturating<$t> {
 102             #[inline]
 103             fn shl_assign(&mut self, other: $f) {
 104                 *self = *self << other;
 105             }
 106         }
 107         forward_ref_op_assign! { impl ShlAssign, shl_assign for Saturating<$t>, $f }
 108
 109         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 110         impl Shr<$f> for Saturating<$t> {
 111             type Output = Saturating<$t>;
 112
 113             #[inline]
 114             fn shr(self, other: $f) -> Saturating<$t> {
 115                 if other < 0 {
 116                     Saturating(self.0.shl((-other & self::shift_max::$t as $f) as u32))
 117                 } else {
 118                     Saturating(self.0.shr((other & self::shift_max::$t as $f) as u32))
 119                 }
 120             }
 121         }
 122         forward_ref_binop! { impl Shr, shr for Saturating<$t>, $f,
 123         #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 124
 125         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 126         impl ShrAssign<$f> for Saturating<$t> {
 127             #[inline]
 128             fn shr_assign(&mut self, other: $f) {
 129                 *self = *self >> other;
 130             }
 131         }
 132         forward_ref_op_assign! { impl ShrAssign, shr_assign for Saturating<$t>, $f }
 133     };
 134 }
 135
 136 macro_rules! sh_impl_unsigned {
 137     ($t:ident, $f:ident) => {
 138         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 139         impl Shl<$f> for Saturating<$t> {
 140             type Output = Saturating<$t>;
 141
 142             #[inline]
 143             fn shl(self, other: $f) -> Saturating<$t> {
 144                 Saturating(self.0.shl((other & self::shift_max::$t as $f) as u32))
 145             }
 146         }
 147         forward_ref_binop! { impl Shl, shl for Saturating<$t>, $f,
 148         #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 149
 150         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 151         impl ShlAssign<$f> for Saturating<$t> {
 152             #[inline]
 153             fn shl_assign(&mut self, other: $f) {
 154                 *self = *self << other;
 155             }
 156         }
 157         forward_ref_op_assign! { impl ShlAssign, shl_assign for Saturating<$t>, $f }
 158
 159         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 160         impl Shr<$f> for Saturating<$t> {
 161             type Output = Saturating<$t>;
 162
 163             #[inline]
 164             fn shr(self, other: $f) -> Saturating<$t> {
 165                 Saturating(self.0.shr((other & self::shift_max::$t as $f) as u32))
 166             }
 167         }
 168         forward_ref_binop! { impl Shr, shr for Saturating<$t>, $f,
 169         #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 170
 171         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 172         impl ShrAssign<$f> for Saturating<$t> {
 173             #[inline]
 174             fn shr_assign(&mut self, other: $f) {
 175                 *self = *self >> other;
 176             }
 177         }
 178         forward_ref_op_assign! { impl ShrAssign, shr_assign for Saturating<$t>, $f }
 179     };
 180 }
 181
 182 // FIXME (#23545): uncomment the remaining impls
 183 macro_rules! sh_impl_all {
 184     ($($t:ident)*) => ($(
 185         //sh_impl_unsigned! { $t, u8 }
 186         //sh_impl_unsigned! { $t, u16 }
 187         //sh_impl_unsigned! { $t, u32 }
 188         //sh_impl_unsigned! { $t, u64 }
 189         //sh_impl_unsigned! { $t, u128 }
 190         sh_impl_unsigned! { $t, usize }
 191
 192         //sh_impl_signed! { $t, i8 }
 193         //sh_impl_signed! { $t, i16 }
 194         //sh_impl_signed! { $t, i32 }
 195         //sh_impl_signed! { $t, i64 }
 196         //sh_impl_signed! { $t, i128 }
 197         //sh_impl_signed! { $t, isize }
 198     )*)
 199 }
 200
 201 sh_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize }
 202
 203 // FIXME(30524): impl Op<T> for Saturating<T>, impl OpAssign<T> for Saturating<T>
 204 macro_rules! saturating_impl {
 205     ($($t:ty)*) => ($(
 206         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 207         impl Add for Saturating<$t> {
 208             type Output = Saturating<$t>;
 209
 210             #[inline]
 211             fn add(self, other: Saturating<$t>) -> Saturating<$t> {
 212                 Saturating(self.0.saturating_add(other.0))
 213             }
 214         }
 215         forward_ref_binop! { impl Add, add for Saturating<$t>, Saturating<$t>,
 216                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 217
 218         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 219         impl AddAssign for Saturating<$t> {
 220             #[inline]
 221             fn add_assign(&mut self, other: Saturating<$t>) {
 222                 *self = *self + other;
 223             }
 224         }
 225         forward_ref_op_assign! { impl AddAssign, add_assign for Saturating<$t>, Saturating<$t> }
 226
 227         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 228         impl Sub for Saturating<$t> {
 229             type Output = Saturating<$t>;
 230
 231             #[inline]
 232             fn sub(self, other: Saturating<$t>) -> Saturating<$t> {
 233                 Saturating(self.0.saturating_sub(other.0))
 234             }
 235         }
 236         forward_ref_binop! { impl Sub, sub for Saturating<$t>, Saturating<$t>,
 237                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 238
 239         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 240         impl SubAssign for Saturating<$t> {
 241             #[inline]
 242             fn sub_assign(&mut self, other: Saturating<$t>) {
 243                 *self = *self - other;
 244             }
 245         }
 246         forward_ref_op_assign! { impl SubAssign, sub_assign for Saturating<$t>, Saturating<$t> }
 247
 248         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 249         impl Mul for Saturating<$t> {
 250             type Output = Saturating<$t>;
 251
 252             #[inline]
 253             fn mul(self, other: Saturating<$t>) -> Saturating<$t> {
 254                 Saturating(self.0.saturating_mul(other.0))
 255             }
 256         }
 257         forward_ref_binop! { impl Mul, mul for Saturating<$t>, Saturating<$t>,
 258                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 259
 260         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 261         impl MulAssign for Saturating<$t> {
 262             #[inline]
 263             fn mul_assign(&mut self, other: Saturating<$t>) {
 264                 *self = *self * other;
 265             }
 266         }
 267         forward_ref_op_assign! { impl MulAssign, mul_assign for Saturating<$t>, Saturating<$t> }
 268
 269         /// # Examples
 270         ///
 271         /// Basic usage:
 272         ///
 273         /// ```
 274         /// #![feature(saturating_int_impl, saturating_div)]
 275         /// use std::num::Saturating;
 276         ///
 277         #[doc = concat!("assert_eq!(Saturating(2", stringify!($t), "), Saturating(5", stringify!($t), ") / Saturating(2));")]
 278         #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MAX), Saturating(", stringify!($t), "::MAX) / Saturating(1));")]
 279         #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN), Saturating(", stringify!($t), "::MIN) / Saturating(1));")]
 280         /// ```
 281         ///
 282         /// ```should_panic
 283         /// #![feature(saturating_int_impl, saturating_div)]
 284         /// use std::num::Saturating;
 285         ///
 286         #[doc = concat!("let _ = Saturating(0", stringify!($t), ") / Saturating(0);")]
 287         /// ```
 288         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 289         impl Div for Saturating<$t> {
 290             type Output = Saturating<$t>;
 291
 292             #[inline]
 293             fn div(self, other: Saturating<$t>) -> Saturating<$t> {
 294                 Saturating(self.0.saturating_div(other.0))
 295             }
 296         }
 297         forward_ref_binop! { impl Div, div for Saturating<$t>, Saturating<$t>,
 298                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 299
 300         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 301         impl DivAssign for Saturating<$t> {
 302             #[inline]
 303             fn div_assign(&mut self, other: Saturating<$t>) {
 304                 *self = *self / other;
 305             }
 306         }
 307         forward_ref_op_assign! { impl DivAssign, div_assign for Saturating<$t>, Saturating<$t> }
 308
 309         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 310         impl Rem for Saturating<$t> {
 311             type Output = Saturating<$t>;
 312
 313             #[inline]
 314             fn rem(self, other: Saturating<$t>) -> Saturating<$t> {
 315                 Saturating(self.0.rem(other.0))
 316             }
 317         }
 318         forward_ref_binop! { impl Rem, rem for Saturating<$t>, Saturating<$t>,
 319                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 320
 321         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 322         impl RemAssign for Saturating<$t> {
 323             #[inline]
 324             fn rem_assign(&mut self, other: Saturating<$t>) {
 325                 *self = *self % other;
 326             }
 327         }
 328         forward_ref_op_assign! { impl RemAssign, rem_assign for Saturating<$t>, Saturating<$t> }
 329
 330         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 331         impl Not for Saturating<$t> {
 332             type Output = Saturating<$t>;
 333
 334             #[inline]
 335             fn not(self) -> Saturating<$t> {
 336                 Saturating(!self.0)
 337             }
 338         }
 339         forward_ref_unop! { impl Not, not for Saturating<$t>,
 340                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 341
 342         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 343         impl BitXor for Saturating<$t> {
 344             type Output = Saturating<$t>;
 345
 346             #[inline]
 347             fn bitxor(self, other: Saturating<$t>) -> Saturating<$t> {
 348                 Saturating(self.0 ^ other.0)
 349             }
 350         }
 351         forward_ref_binop! { impl BitXor, bitxor for Saturating<$t>, Saturating<$t>,
 352                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 353
 354         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 355         impl BitXorAssign for Saturating<$t> {
 356             #[inline]
 357             fn bitxor_assign(&mut self, other: Saturating<$t>) {
 358                 *self = *self ^ other;
 359             }
 360         }
 361         forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for Saturating<$t>, Saturating<$t> }
 362
 363         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 364         impl BitOr for Saturating<$t> {
 365             type Output = Saturating<$t>;
 366
 367             #[inline]
 368             fn bitor(self, other: Saturating<$t>) -> Saturating<$t> {
 369                 Saturating(self.0 | other.0)
 370             }
 371         }
 372         forward_ref_binop! { impl BitOr, bitor for Saturating<$t>, Saturating<$t>,
 373                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 374
 375         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 376         impl BitOrAssign for Saturating<$t> {
 377             #[inline]
 378             fn bitor_assign(&mut self, other: Saturating<$t>) {
 379                 *self = *self | other;
 380             }
 381         }
 382         forward_ref_op_assign! { impl BitOrAssign, bitor_assign for Saturating<$t>, Saturating<$t> }
 383
 384         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 385         impl BitAnd for Saturating<$t> {
 386             type Output = Saturating<$t>;
 387
 388             #[inline]
 389             fn bitand(self, other: Saturating<$t>) -> Saturating<$t> {
 390                 Saturating(self.0 & other.0)
 391             }
 392         }
 393         forward_ref_binop! { impl BitAnd, bitand for Saturating<$t>, Saturating<$t>,
 394                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 395
 396         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 397         impl BitAndAssign for Saturating<$t> {
 398             #[inline]
 399             fn bitand_assign(&mut self, other: Saturating<$t>) {
 400                 *self = *self & other;
 401             }
 402         }
 403         forward_ref_op_assign! { impl BitAndAssign, bitand_assign for Saturating<$t>, Saturating<$t> }
 404
 405     )*)
 406 }
 407
 408 saturating_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 409
 410 macro_rules! saturating_int_impl {
 411     ($($t:ty)*) => ($(
 412         impl Saturating<$t> {
 413             /// Returns the smallest value that can be represented by this integer type.
 414             ///
 415             /// # Examples
 416             ///
 417             /// Basic usage:
 418             ///
 419             /// ```
 420             /// #![feature(saturating_int_impl)]
 421             /// use std::num::Saturating;
 422             ///
 423             #[doc = concat!("assert_eq!(<Saturating<", stringify!($t), ">>::MIN, Saturating(", stringify!($t), "::MIN));")]
 424             /// ```
 425             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 426             pub const MIN: Self = Self(<$t>::MIN);
 427
 428             /// Returns the largest value that can be represented by this integer type.
 429             ///
 430             /// # Examples
 431             ///
 432             /// Basic usage:
 433             ///
 434             /// ```
 435             /// #![feature(saturating_int_impl)]
 436             /// use std::num::Saturating;
 437             ///
 438             #[doc = concat!("assert_eq!(<Saturating<", stringify!($t), ">>::MAX, Saturating(", stringify!($t), "::MAX));")]
 439             /// ```
 440             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 441             pub const MAX: Self = Self(<$t>::MAX);
 442
 443             /// Returns the size of this integer type in bits.
 444             ///
 445             /// # Examples
 446             ///
 447             /// Basic usage:
 448             ///
 449             /// ```
 450             /// #![feature(saturating_int_impl)]
 451             /// use std::num::Saturating;
 452             ///
 453             #[doc = concat!("assert_eq!(<Saturating<", stringify!($t), ">>::BITS, ", stringify!($t), "::BITS);")]
 454             /// ```
 455             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 456             pub const BITS: u32 = <$t>::BITS;
 457
 458             /// Returns the number of ones in the binary representation of `self`.
 459             ///
 460             /// # Examples
 461             ///
 462             /// Basic usage:
 463             ///
 464             /// ```
 465             /// #![feature(saturating_int_impl)]
 466             /// use std::num::Saturating;
 467             ///
 468             #[doc = concat!("let n = Saturating(0b01001100", stringify!($t), ");")]
 469             ///
 470             /// assert_eq!(n.count_ones(), 3);
 471             /// ```
 472             #[inline]
 473             #[doc(alias = "popcount")]
 474             #[doc(alias = "popcnt")]
 475             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 476             pub const fn count_ones(self) -> u32 {
 477                 self.0.count_ones()
 478             }
 479
 480             /// Returns the number of zeros in the binary representation of `self`.
 481             ///
 482             /// # Examples
 483             ///
 484             /// Basic usage:
 485             ///
 486             /// ```
 487             /// #![feature(saturating_int_impl)]
 488             /// use std::num::Saturating;
 489             ///
 490             #[doc = concat!("assert_eq!(Saturating(!0", stringify!($t), ").count_zeros(), 0);")]
 491             /// ```
 492             #[inline]
 493             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 494             pub const fn count_zeros(self) -> u32 {
 495                 self.0.count_zeros()
 496             }
 497
 498             /// Returns the number of trailing zeros in the binary representation of `self`.
 499             ///
 500             /// # Examples
 501             ///
 502             /// Basic usage:
 503             ///
 504             /// ```
 505             /// #![feature(saturating_int_impl)]
 506             /// use std::num::Saturating;
 507             ///
 508             #[doc = concat!("let n = Saturating(0b0101000", stringify!($t), ");")]
 509             ///
 510             /// assert_eq!(n.trailing_zeros(), 3);
 511             /// ```
 512             #[inline]
 513             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 514             pub const fn trailing_zeros(self) -> u32 {
 515                 self.0.trailing_zeros()
 516             }
 517
 518             /// Shifts the bits to the left by a specified amount, `n`,
 519             /// saturating the truncated bits to the end of the resulting
 520             /// integer.
 521             ///
 522             /// Please note this isn't the same operation as the `<<` shifting
 523             /// operator!
 524             ///
 525             /// # Examples
 526             ///
 527             /// Basic usage:
 528             ///
 529             /// ```
 530             /// #![feature(saturating_int_impl)]
 531             /// use std::num::Saturating;
 532             ///
 533             /// let n: Saturating<i64> = Saturating(0x0123456789ABCDEF);
 534             /// let m: Saturating<i64> = Saturating(-0x76543210FEDCBA99);
 535             ///
 536             /// assert_eq!(n.rotate_left(32), m);
 537             /// ```
 538             #[inline]
 539             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 540             pub const fn rotate_left(self, n: u32) -> Self {
 541                 Saturating(self.0.rotate_left(n))
 542             }
 543
 544             /// Shifts the bits to the right by a specified amount, `n`,
 545             /// saturating the truncated bits to the beginning of the resulting
 546             /// integer.
 547             ///
 548             /// Please note this isn't the same operation as the `>>` shifting
 549             /// operator!
 550             ///
 551             /// # Examples
 552             ///
 553             /// Basic usage:
 554             ///
 555             /// ```
 556             /// #![feature(saturating_int_impl)]
 557             /// use std::num::Saturating;
 558             ///
 559             /// let n: Saturating<i64> = Saturating(0x0123456789ABCDEF);
 560             /// let m: Saturating<i64> = Saturating(-0xFEDCBA987654322);
 561             ///
 562             /// assert_eq!(n.rotate_right(4), m);
 563             /// ```
 564             #[inline]
 565             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 566             pub const fn rotate_right(self, n: u32) -> Self {
 567                 Saturating(self.0.rotate_right(n))
 568             }
 569
 570             /// Reverses the byte order of the integer.
 571             ///
 572             /// # Examples
 573             ///
 574             /// Basic usage:
 575             ///
 576             /// ```
 577             /// #![feature(saturating_int_impl)]
 578             /// use std::num::Saturating;
 579             ///
 580             /// let n: Saturating<i16> = Saturating(0b0000000_01010101);
 581             /// assert_eq!(n, Saturating(85));
 582             ///
 583             /// let m = n.swap_bytes();
 584             ///
 585             /// assert_eq!(m, Saturating(0b01010101_00000000));
 586             /// assert_eq!(m, Saturating(21760));
 587             /// ```
 588             #[inline]
 589             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 590             pub const fn swap_bytes(self) -> Self {
 591                 Saturating(self.0.swap_bytes())
 592             }
 593
 594             /// Reverses the bit pattern of the integer.
 595             ///
 596             /// # Examples
 597             ///
 598             /// Please note that this example is shared between integer types.
 599             /// Which explains why `i16` is used here.
 600             ///
 601             /// Basic usage:
 602             ///
 603             /// ```
 604             /// #![feature(saturating_int_impl)]
 605             /// use std::num::Saturating;
 606             ///
 607             /// let n = Saturating(0b0000000_01010101i16);
 608             /// assert_eq!(n, Saturating(85));
 609             ///
 610             /// let m = n.reverse_bits();
 611             ///
 612             /// assert_eq!(m.0 as u16, 0b10101010_00000000);
 613             /// assert_eq!(m, Saturating(-22016));
 614             /// ```
 615             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 616             #[rustc_const_stable(feature = "const_reverse_bits", since = "1.37.0")]
 617             #[inline]
 618             #[must_use]
 619             pub const fn reverse_bits(self) -> Self {
 620                 Saturating(self.0.reverse_bits())
 621             }
 622
 623             /// Converts an integer from big endian to the target's endianness.
 624             ///
 625             /// On big endian this is a no-op. On little endian the bytes are
 626             /// swapped.
 627             ///
 628             /// # Examples
 629             ///
 630             /// Basic usage:
 631             ///
 632             /// ```
 633             /// #![feature(saturating_int_impl)]
 634             /// use std::num::Saturating;
 635             ///
 636             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 637             ///
 638             /// if cfg!(target_endian = "big") {
 639             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_be(n), n)")]
 640             /// } else {
 641             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_be(n), n.swap_bytes())")]
 642             /// }
 643             /// ```
 644             #[inline]
 645             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 646             pub const fn from_be(x: Self) -> Self {
 647                 Saturating(<$t>::from_be(x.0))
 648             }
 649
 650             /// Converts an integer from little endian to the target's endianness.
 651             ///
 652             /// On little endian this is a no-op. On big endian the bytes are
 653             /// swapped.
 654             ///
 655             /// # Examples
 656             ///
 657             /// Basic usage:
 658             ///
 659             /// ```
 660             /// #![feature(saturating_int_impl)]
 661             /// use std::num::Saturating;
 662             ///
 663             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 664             ///
 665             /// if cfg!(target_endian = "little") {
 666             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_le(n), n)")]
 667             /// } else {
 668             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_le(n), n.swap_bytes())")]
 669             /// }
 670             /// ```
 671             #[inline]
 672             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 673             pub const fn from_le(x: Self) -> Self {
 674                 Saturating(<$t>::from_le(x.0))
 675             }
 676
 677             /// Converts `self` to big endian from the target's endianness.
 678             ///
 679             /// On big endian this is a no-op. On little endian the bytes are
 680             /// swapped.
 681             ///
 682             /// # Examples
 683             ///
 684             /// Basic usage:
 685             ///
 686             /// ```
 687             /// #![feature(saturating_int_impl)]
 688             /// use std::num::Saturating;
 689             ///
 690             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 691             ///
 692             /// if cfg!(target_endian = "big") {
 693             ///     assert_eq!(n.to_be(), n)
 694             /// } else {
 695             ///     assert_eq!(n.to_be(), n.swap_bytes())
 696             /// }
 697             /// ```
 698             #[inline]
 699             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 700             pub const fn to_be(self) -> Self {
 701                 Saturating(self.0.to_be())
 702             }
 703
 704             /// Converts `self` to little endian from the target's endianness.
 705             ///
 706             /// On little endian this is a no-op. On big endian the bytes are
 707             /// swapped.
 708             ///
 709             /// # Examples
 710             ///
 711             /// Basic usage:
 712             ///
 713             /// ```
 714             /// #![feature(saturating_int_impl)]
 715             /// use std::num::Saturating;
 716             ///
 717             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 718             ///
 719             /// if cfg!(target_endian = "little") {
 720             ///     assert_eq!(n.to_le(), n)
 721             /// } else {
 722             ///     assert_eq!(n.to_le(), n.swap_bytes())
 723             /// }
 724             /// ```
 725             #[inline]
 726             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 727             pub const fn to_le(self) -> Self {
 728                 Saturating(self.0.to_le())
 729             }
 730
 731             /// Raises self to the power of `exp`, using exponentiation by squaring.
 732             ///
 733             /// # Examples
 734             ///
 735             /// Basic usage:
 736             ///
 737             /// ```
 738             /// #![feature(saturating_int_impl)]
 739             /// use std::num::Saturating;
 740             ///
 741             #[doc = concat!("assert_eq!(Saturating(3", stringify!($t), ").pow(4), Saturating(81));")]
 742             /// ```
 743             ///
 744             /// Results that are too large are wrapped:
 745             ///
 746             /// ```
 747             /// #![feature(saturating_int_impl)]
 748             /// use std::num::Saturating;
 749             ///
 750             /// assert_eq!(Saturating(3i8).pow(5), Saturating(127));
 751             /// assert_eq!(Saturating(3i8).pow(6), Saturating(127));
 752             /// ```
 753             #[inline]
 754             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 755             pub fn pow(self, exp: u32) -> Self {
 756                 Saturating(self.0.saturating_pow(exp))
 757             }
 758         }
 759     )*)
 760 }
 761
 762 saturating_int_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 763
 764 macro_rules! saturating_int_impl_signed {
 765     ($($t:ty)*) => ($(
 766         impl Saturating<$t> {
 767             /// Returns the number of leading zeros in the binary representation of `self`.
 768             ///
 769             /// # Examples
 770             ///
 771             /// Basic usage:
 772             ///
 773             /// ```
 774             /// #![feature(saturating_int_impl)]
 775             /// use std::num::Saturating;
 776             ///
 777             #[doc = concat!("let n = Saturating(", stringify!($t), "::MAX >> 2);")]
 778             ///
 779             /// assert_eq!(n.leading_zeros(), 3);
 780             /// ```
 781             #[inline]
 782             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 783             pub const fn leading_zeros(self) -> u32 {
 784                 self.0.leading_zeros()
 785             }
 786
 787             /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self == MIN`
 788             /// instead of overflowing.
 789             ///
 790             /// # Examples
 791             ///
 792             /// Basic usage:
 793             ///
 794             /// ```
 795             /// #![feature(saturating_int_impl)]
 796             /// use std::num::Saturating;
 797             ///
 798             #[doc = concat!("assert_eq!(Saturating(100", stringify!($t), ").abs(), Saturating(100));")]
 799             #[doc = concat!("assert_eq!(Saturating(-100", stringify!($t), ").abs(), Saturating(100));")]
 800             #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating((", stringify!($t), "::MIN + 1).abs()));")]
 801             #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating(", stringify!($t), "::MIN.saturating_abs()));")]
 802             #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating(", stringify!($t), "::MAX));")]
 803             /// ```
 804             #[inline]
 805             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 806             pub fn abs(self) -> Saturating<$t> {
 807                 Saturating(self.0.saturating_abs())
 808             }
 809
 810             /// Returns a number representing sign of `self`.
 811             ///
 812             ///  - `0` if the number is zero
 813             ///  - `1` if the number is positive
 814             ///  - `-1` if the number is negative
 815             ///
 816             /// # Examples
 817             ///
 818             /// Basic usage:
 819             ///
 820             /// ```
 821             /// #![feature(saturating_int_impl)]
 822             /// use std::num::Saturating;
 823             ///
 824             #[doc = concat!("assert_eq!(Saturating(10", stringify!($t), ").signum(), Saturating(1));")]
 825             #[doc = concat!("assert_eq!(Saturating(0", stringify!($t), ").signum(), Saturating(0));")]
 826             #[doc = concat!("assert_eq!(Saturating(-10", stringify!($t), ").signum(), Saturating(-1));")]
 827             /// ```
 828             #[inline]
 829             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 830             pub fn signum(self) -> Saturating<$t> {
 831                 Saturating(self.0.signum())
 832             }
 833
 834             /// Returns `true` if `self` is positive and `false` if the number is zero or
 835             /// negative.
 836             ///
 837             /// # Examples
 838             ///
 839             /// Basic usage:
 840             ///
 841             /// ```
 842             /// #![feature(saturating_int_impl)]
 843             /// use std::num::Saturating;
 844             ///
 845             #[doc = concat!("assert!(Saturating(10", stringify!($t), ").is_positive());")]
 846             #[doc = concat!("assert!(!Saturating(-10", stringify!($t), ").is_positive());")]
 847             /// ```
 848             #[inline]
 849             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 850             pub const fn is_positive(self) -> bool {
 851                 self.0.is_positive()
 852             }
 853
 854             /// Returns `true` if `self` is negative and `false` if the number is zero or
 855             /// positive.
 856             ///
 857             /// # Examples
 858             ///
 859             /// Basic usage:
 860             ///
 861             /// ```
 862             /// #![feature(saturating_int_impl)]
 863             /// use std::num::Saturating;
 864             ///
 865             #[doc = concat!("assert!(Saturating(-10", stringify!($t), ").is_negative());")]
 866             #[doc = concat!("assert!(!Saturating(10", stringify!($t), ").is_negative());")]
 867             /// ```
 868             #[inline]
 869             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 870             pub const fn is_negative(self) -> bool {
 871                 self.0.is_negative()
 872             }
 873         }
 874
 875         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 876         impl Neg for Saturating<$t> {
 877             type Output = Self;
 878             #[inline]
 879             fn neg(self) -> Self {
 880                 Saturating(self.0.saturating_neg())
 881             }
 882         }
 883         forward_ref_unop! { impl Neg, neg for Saturating<$t>,
 884                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 885     )*)
 886 }
 887
 888 saturating_int_impl_signed! { isize i8 i16 i32 i64 i128 }
 889
 890 macro_rules! saturating_int_impl_unsigned {
 891     ($($t:ty)*) => ($(
 892         impl Saturating<$t> {
 893             /// Returns the number of leading zeros in the binary representation of `self`.
 894             ///
 895             /// # Examples
 896             ///
 897             /// Basic usage:
 898             ///
 899             /// ```
 900             /// #![feature(saturating_int_impl)]
 901             /// use std::num::Saturating;
 902             ///
 903             #[doc = concat!("let n = Saturating(", stringify!($t), "::MAX >> 2);")]
 904             ///
 905             /// assert_eq!(n.leading_zeros(), 2);
 906             /// ```
 907             #[inline]
 908             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 909             pub const fn leading_zeros(self) -> u32 {
 910                 self.0.leading_zeros()
 911             }
 912
 913             /// Returns `true` if and only if `self == 2^k` for some `k`.
 914             ///
 915             /// # Examples
 916             ///
 917             /// Basic usage:
 918             ///
 919             /// ```
 920             /// #![feature(saturating_int_impl)]
 921             /// use std::num::Saturating;
 922             ///
 923             #[doc = concat!("assert!(Saturating(16", stringify!($t), ").is_power_of_two());")]
 924             #[doc = concat!("assert!(!Saturating(10", stringify!($t), ").is_power_of_two());")]
 925             /// ```
 926             #[inline]
 927             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 928             pub fn is_power_of_two(self) -> bool {
 929                 self.0.is_power_of_two()
 930             }
 931
 932         }
 933     )*)
 934 }
 935
 936 saturating_int_impl_unsigned! { usize u8 u16 u32 u64 u128 }
 937
 938 mod shift_max {
 939     #![allow(non_upper_case_globals)]
 940
 941     #[cfg(target_pointer_width = "16")]
 942     mod platform {
 943         pub const usize: u32 = super::u16;
 944         pub const isize: u32 = super::i16;
 945     }
 946
 947     #[cfg(target_pointer_width = "32")]
 948     mod platform {
 949         pub const usize: u32 = super::u32;
 950         pub const isize: u32 = super::i32;
 951     }
 952
 953     #[cfg(target_pointer_width = "64")]
 954     mod platform {
 955         pub const usize: u32 = super::u64;
 956         pub const isize: u32 = super::i64;
 957     }
 958
 959     pub const i8: u32 = (1 << 3) - 1;
 960     pub const i16: u32 = (1 << 4) - 1;
 961     pub const i32: u32 = (1 << 5) - 1;
 962     pub const i64: u32 = (1 << 6) - 1;
 963     pub const i128: u32 = (1 << 7) - 1;
 964     pub use self::platform::isize;
 965
 966     pub const u8: u32 = i8;
 967     pub const u16: u32 = i16;
 968     pub const u32: u32 = i32;
 969     pub const u64: u32 = i64;
 970     pub const u128: u32 = i128;
 971     pub use self::platform::usize;
 972 }