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};
   7 use crate::ops::{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
  82 // FIXME(30524): impl Op<T> for Saturating<T>, impl OpAssign<T> for Saturating<T>
  83 macro_rules! saturating_impl {
  84     ($($t:ty)*) => ($(
  85         #[unstable(feature = "saturating_int_impl", issue = "87920")]
  86         impl Add for Saturating<$t> {
  87             type Output = Saturating<$t>;
  88
  89             #[inline]
  90             fn add(self, other: Saturating<$t>) -> Saturating<$t> {
  91                 Saturating(self.0.saturating_add(other.0))
  92             }
  93         }
  94         forward_ref_binop! { impl Add, add for Saturating<$t>, Saturating<$t>,
  95                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
  96
  97         #[unstable(feature = "saturating_int_impl", issue = "87920")]
  98         impl AddAssign for Saturating<$t> {
  99             #[inline]
 100             fn add_assign(&mut self, other: Saturating<$t>) {
 101                 *self = *self + other;
 102             }
 103         }
 104         forward_ref_op_assign! { impl AddAssign, add_assign for Saturating<$t>, Saturating<$t> }
 105
 106         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 107         impl Sub for Saturating<$t> {
 108             type Output = Saturating<$t>;
 109
 110             #[inline]
 111             fn sub(self, other: Saturating<$t>) -> Saturating<$t> {
 112                 Saturating(self.0.saturating_sub(other.0))
 113             }
 114         }
 115         forward_ref_binop! { impl Sub, sub for Saturating<$t>, Saturating<$t>,
 116                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 117
 118         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 119         impl SubAssign for Saturating<$t> {
 120             #[inline]
 121             fn sub_assign(&mut self, other: Saturating<$t>) {
 122                 *self = *self - other;
 123             }
 124         }
 125         forward_ref_op_assign! { impl SubAssign, sub_assign for Saturating<$t>, Saturating<$t> }
 126
 127         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 128         impl Mul for Saturating<$t> {
 129             type Output = Saturating<$t>;
 130
 131             #[inline]
 132             fn mul(self, other: Saturating<$t>) -> Saturating<$t> {
 133                 Saturating(self.0.saturating_mul(other.0))
 134             }
 135         }
 136         forward_ref_binop! { impl Mul, mul for Saturating<$t>, Saturating<$t>,
 137                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 138
 139         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 140         impl MulAssign for Saturating<$t> {
 141             #[inline]
 142             fn mul_assign(&mut self, other: Saturating<$t>) {
 143                 *self = *self * other;
 144             }
 145         }
 146         forward_ref_op_assign! { impl MulAssign, mul_assign for Saturating<$t>, Saturating<$t> }
 147
 148         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 149         impl Div for Saturating<$t> {
 150             type Output = Saturating<$t>;
 151
 152             #[inline]
 153             fn div(self, other: Saturating<$t>) -> Saturating<$t> {
 154                 // saturating div is the default behavior?
 155                 Saturating(self.0.div(other.0))
 156             }
 157         }
 158         forward_ref_binop! { impl Div, div for Saturating<$t>, Saturating<$t>,
 159                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 160
 161         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 162         impl DivAssign for Saturating<$t> {
 163             #[inline]
 164             fn div_assign(&mut self, other: Saturating<$t>) {
 165                 *self = *self / other;
 166             }
 167         }
 168         forward_ref_op_assign! { impl DivAssign, div_assign for Saturating<$t>, Saturating<$t> }
 169
 170         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 171         impl Not for Saturating<$t> {
 172             type Output = Saturating<$t>;
 173
 174             #[inline]
 175             fn not(self) -> Saturating<$t> {
 176                 Saturating(!self.0)
 177             }
 178         }
 179         forward_ref_unop! { impl Not, not for Saturating<$t>,
 180                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 181
 182         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 183         impl BitXor for Saturating<$t> {
 184             type Output = Saturating<$t>;
 185
 186             #[inline]
 187             fn bitxor(self, other: Saturating<$t>) -> Saturating<$t> {
 188                 Saturating(self.0 ^ other.0)
 189             }
 190         }
 191         forward_ref_binop! { impl BitXor, bitxor for Saturating<$t>, Saturating<$t>,
 192                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 193
 194         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 195         impl BitXorAssign for Saturating<$t> {
 196             #[inline]
 197             fn bitxor_assign(&mut self, other: Saturating<$t>) {
 198                 *self = *self ^ other;
 199             }
 200         }
 201         forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for Saturating<$t>, Saturating<$t> }
 202
 203         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 204         impl BitOr for Saturating<$t> {
 205             type Output = Saturating<$t>;
 206
 207             #[inline]
 208             fn bitor(self, other: Saturating<$t>) -> Saturating<$t> {
 209                 Saturating(self.0 | other.0)
 210             }
 211         }
 212         forward_ref_binop! { impl BitOr, bitor for Saturating<$t>, Saturating<$t>,
 213                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 214
 215         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 216         impl BitOrAssign for Saturating<$t> {
 217             #[inline]
 218             fn bitor_assign(&mut self, other: Saturating<$t>) {
 219                 *self = *self | other;
 220             }
 221         }
 222         forward_ref_op_assign! { impl BitOrAssign, bitor_assign for Saturating<$t>, Saturating<$t> }
 223
 224         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 225         impl BitAnd for Saturating<$t> {
 226             type Output = Saturating<$t>;
 227
 228             #[inline]
 229             fn bitand(self, other: Saturating<$t>) -> Saturating<$t> {
 230                 Saturating(self.0 & other.0)
 231             }
 232         }
 233         forward_ref_binop! { impl BitAnd, bitand for Saturating<$t>, Saturating<$t>,
 234                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 235
 236         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 237         impl BitAndAssign for Saturating<$t> {
 238             #[inline]
 239             fn bitand_assign(&mut self, other: Saturating<$t>) {
 240                 *self = *self & other;
 241             }
 242         }
 243         forward_ref_op_assign! { impl BitAndAssign, bitand_assign for Saturating<$t>, Saturating<$t> }
 244
 245         #[unstable(feature = "saturating_int_impl", issue = "87920")]
 246         impl Neg for Saturating<$t> {
 247             type Output = Self;
 248             #[inline]
 249             fn neg(self) -> Self {
 250                 Saturating(0) - self
 251             }
 252         }
 253         forward_ref_unop! { impl Neg, neg for Saturating<$t>,
 254                 #[unstable(feature = "saturating_int_impl", issue = "87920")] }
 255
 256     )*)
 257 }
 258
 259 saturating_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 260
 261 macro_rules! saturating_int_impl {
 262     ($($t:ty)*) => ($(
 263         impl Saturating<$t> {
 264             /// Returns the smallest value that can be represented by this integer type.
 265             ///
 266             /// # Examples
 267             ///
 268             /// Basic usage:
 269             ///
 270             /// ```
 271             /// #![feature(saturating_int_impl)]
 272             /// use std::num::Saturating;
 273             ///
 274             #[doc = concat!("assert_eq!(<Saturating<", stringify!($t), ">>::MIN, Saturating(", stringify!($t), "::MIN));")]
 275             /// ```
 276             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 277             pub const MIN: Self = Self(<$t>::MIN);
 278
 279             /// Returns the largest value that can be represented by this integer type.
 280             ///
 281             /// # Examples
 282             ///
 283             /// Basic usage:
 284             ///
 285             /// ```
 286             /// #![feature(saturating_int_impl)]
 287             /// use std::num::Saturating;
 288             ///
 289             #[doc = concat!("assert_eq!(<Saturating<", stringify!($t), ">>::MAX, Saturating(", stringify!($t), "::MAX));")]
 290             /// ```
 291             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 292             pub const MAX: Self = Self(<$t>::MAX);
 293
 294             /// Returns the size of this integer type in bits.
 295             ///
 296             /// # Examples
 297             ///
 298             /// Basic usage:
 299             ///
 300             /// ```
 301             /// #![feature(saturating_int_impl)]
 302             /// use std::num::Saturating;
 303             ///
 304             #[doc = concat!("assert_eq!(<Saturating<", stringify!($t), ">>::BITS, ", stringify!($t), "::BITS);")]
 305             /// ```
 306             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 307             pub const BITS: u32 = <$t>::BITS;
 308
 309             /// Returns the number of ones in the binary representation of `self`.
 310             ///
 311             /// # Examples
 312             ///
 313             /// Basic usage:
 314             ///
 315             /// ```
 316             /// #![feature(saturating_int_impl)]
 317             /// use std::num::Saturating;
 318             ///
 319             #[doc = concat!("let n = Saturating(0b01001100", stringify!($t), ");")]
 320             ///
 321             /// assert_eq!(n.count_ones(), 3);
 322             /// ```
 323             #[inline]
 324             #[doc(alias = "popcount")]
 325             #[doc(alias = "popcnt")]
 326             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 327             pub const fn count_ones(self) -> u32 {
 328                 self.0.count_ones()
 329             }
 330
 331             /// Returns the number of zeros in the binary representation of `self`.
 332             ///
 333             /// # Examples
 334             ///
 335             /// Basic usage:
 336             ///
 337             /// ```
 338             /// #![feature(saturating_int_impl)]
 339             /// use std::num::Saturating;
 340             ///
 341             #[doc = concat!("assert_eq!(Saturating(!0", stringify!($t), ").count_zeros(), 0);")]
 342             /// ```
 343             #[inline]
 344             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 345             pub const fn count_zeros(self) -> u32 {
 346                 self.0.count_zeros()
 347             }
 348
 349             /// Returns the number of trailing zeros in the binary representation of `self`.
 350             ///
 351             /// # Examples
 352             ///
 353             /// Basic usage:
 354             ///
 355             /// ```
 356             /// #![feature(saturating_int_impl)]
 357             /// use std::num::Saturating;
 358             ///
 359             #[doc = concat!("let n = Saturating(0b0101000", stringify!($t), ");")]
 360             ///
 361             /// assert_eq!(n.trailing_zeros(), 3);
 362             /// ```
 363             #[inline]
 364             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 365             pub const fn trailing_zeros(self) -> u32 {
 366                 self.0.trailing_zeros()
 367             }
 368
 369             /// Shifts the bits to the left by a specified amount, `n`,
 370             /// saturating the truncated bits to the end of the resulting
 371             /// integer.
 372             ///
 373             /// Please note this isn't the same operation as the `<<` shifting
 374             /// operator!
 375             ///
 376             /// # Examples
 377             ///
 378             /// Basic usage:
 379             ///
 380             /// ```
 381             /// #![feature(saturating_int_impl)]
 382             /// use std::num::Saturating;
 383             ///
 384             /// let n: Saturating<i64> = Saturating(0x0123456789ABCDEF);
 385             /// let m: Saturating<i64> = Saturating(-0x76543210FEDCBA99);
 386             ///
 387             /// assert_eq!(n.rotate_left(32), m);
 388             /// ```
 389             #[inline]
 390             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 391             pub const fn rotate_left(self, n: u32) -> Self {
 392                 Saturating(self.0.rotate_left(n))
 393             }
 394
 395             /// Shifts the bits to the right by a specified amount, `n`,
 396             /// saturating the truncated bits to the beginning of the resulting
 397             /// integer.
 398             ///
 399             /// Please note this isn't the same operation as the `>>` shifting
 400             /// operator!
 401             ///
 402             /// # Examples
 403             ///
 404             /// Basic usage:
 405             ///
 406             /// ```
 407             /// #![feature(saturating_int_impl)]
 408             /// use std::num::Saturating;
 409             ///
 410             /// let n: Saturating<i64> = Saturating(0x0123456789ABCDEF);
 411             /// let m: Saturating<i64> = Saturating(-0xFEDCBA987654322);
 412             ///
 413             /// assert_eq!(n.rotate_right(4), m);
 414             /// ```
 415             #[inline]
 416             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 417             pub const fn rotate_right(self, n: u32) -> Self {
 418                 Saturating(self.0.rotate_right(n))
 419             }
 420
 421             /// Reverses the byte order of the integer.
 422             ///
 423             /// # Examples
 424             ///
 425             /// Basic usage:
 426             ///
 427             /// ```
 428             /// #![feature(saturating_int_impl)]
 429             /// use std::num::Saturating;
 430             ///
 431             /// let n: Saturating<i16> = Saturating(0b0000000_01010101);
 432             /// assert_eq!(n, Saturating(85));
 433             ///
 434             /// let m = n.swap_bytes();
 435             ///
 436             /// assert_eq!(m, Saturating(0b01010101_00000000));
 437             /// assert_eq!(m, Saturating(21760));
 438             /// ```
 439             #[inline]
 440             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 441             pub const fn swap_bytes(self) -> Self {
 442                 Saturating(self.0.swap_bytes())
 443             }
 444
 445             /// Reverses the bit pattern of the integer.
 446             ///
 447             /// # Examples
 448             ///
 449             /// Please note that this example is shared between integer types.
 450             /// Which explains why `i16` is used here.
 451             ///
 452             /// Basic usage:
 453             ///
 454             /// ```
 455             /// #![feature(saturating_int_impl)]
 456             /// use std::num::Saturating;
 457             ///
 458             /// let n = Saturating(0b0000000_01010101i16);
 459             /// assert_eq!(n, Saturating(85));
 460             ///
 461             /// let m = n.reverse_bits();
 462             ///
 463             /// assert_eq!(m.0 as u16, 0b10101010_00000000);
 464             /// assert_eq!(m, Saturating(-22016));
 465             /// ```
 466             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 467             #[rustc_const_stable(feature = "const_reverse_bits", since = "1.37.0")]
 468             #[inline]
 469             #[must_use]
 470             pub const fn reverse_bits(self) -> Self {
 471                 Saturating(self.0.reverse_bits())
 472             }
 473
 474             /// Converts an integer from big endian to the target's endianness.
 475             ///
 476             /// On big endian this is a no-op. On little endian the bytes are
 477             /// swapped.
 478             ///
 479             /// # Examples
 480             ///
 481             /// Basic usage:
 482             ///
 483             /// ```
 484             /// #![feature(saturating_int_impl)]
 485             /// use std::num::Saturating;
 486             ///
 487             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 488             ///
 489             /// if cfg!(target_endian = "big") {
 490             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_be(n), n)")]
 491             /// } else {
 492             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_be(n), n.swap_bytes())")]
 493             /// }
 494             /// ```
 495             #[inline]
 496             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 497             pub const fn from_be(x: Self) -> Self {
 498                 Saturating(<$t>::from_be(x.0))
 499             }
 500
 501             /// Converts an integer from little endian to the target's endianness.
 502             ///
 503             /// On little endian this is a no-op. On big endian the bytes are
 504             /// swapped.
 505             ///
 506             /// # Examples
 507             ///
 508             /// Basic usage:
 509             ///
 510             /// ```
 511             /// #![feature(saturating_int_impl)]
 512             /// use std::num::Saturating;
 513             ///
 514             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 515             ///
 516             /// if cfg!(target_endian = "little") {
 517             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_le(n), n)")]
 518             /// } else {
 519             #[doc = concat!("    assert_eq!(<Saturating<", stringify!($t), ">>::from_le(n), n.swap_bytes())")]
 520             /// }
 521             /// ```
 522             #[inline]
 523             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 524             pub const fn from_le(x: Self) -> Self {
 525                 Saturating(<$t>::from_le(x.0))
 526             }
 527
 528             /// Converts `self` to big endian from the target's endianness.
 529             ///
 530             /// On big endian this is a no-op. On little endian the bytes are
 531             /// swapped.
 532             ///
 533             /// # Examples
 534             ///
 535             /// Basic usage:
 536             ///
 537             /// ```
 538             /// #![feature(saturating_int_impl)]
 539             /// use std::num::Saturating;
 540             ///
 541             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 542             ///
 543             /// if cfg!(target_endian = "big") {
 544             ///     assert_eq!(n.to_be(), n)
 545             /// } else {
 546             ///     assert_eq!(n.to_be(), n.swap_bytes())
 547             /// }
 548             /// ```
 549             #[inline]
 550             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 551             pub const fn to_be(self) -> Self {
 552                 Saturating(self.0.to_be())
 553             }
 554
 555             /// Converts `self` to little endian from the target's endianness.
 556             ///
 557             /// On little endian this is a no-op. On big endian the bytes are
 558             /// swapped.
 559             ///
 560             /// # Examples
 561             ///
 562             /// Basic usage:
 563             ///
 564             /// ```
 565             /// #![feature(saturating_int_impl)]
 566             /// use std::num::Saturating;
 567             ///
 568             #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")]
 569             ///
 570             /// if cfg!(target_endian = "little") {
 571             ///     assert_eq!(n.to_le(), n)
 572             /// } else {
 573             ///     assert_eq!(n.to_le(), n.swap_bytes())
 574             /// }
 575             /// ```
 576             #[inline]
 577             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 578             pub const fn to_le(self) -> Self {
 579                 Saturating(self.0.to_le())
 580             }
 581
 582             /// Raises self to the power of `exp`, using exponentiation by squaring.
 583             ///
 584             /// # Examples
 585             ///
 586             /// Basic usage:
 587             ///
 588             /// ```
 589             /// #![feature(saturating_int_impl)]
 590             /// use std::num::Saturating;
 591             ///
 592             #[doc = concat!("assert_eq!(Saturating(3", stringify!($t), ").pow(4), Saturating(81));")]
 593             /// ```
 594             ///
 595             /// Results that are too large are wrapped:
 596             ///
 597             /// ```
 598             /// #![feature(saturating_int_impl)]
 599             /// use std::num::Saturating;
 600             ///
 601             /// assert_eq!(Saturating(3i8).pow(5), Saturating(127));
 602             /// assert_eq!(Saturating(3i8).pow(6), Saturating(127));
 603             /// ```
 604             #[inline]
 605             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 606             pub fn pow(self, exp: u32) -> Self {
 607                 Saturating(self.0.saturating_pow(exp))
 608             }
 609         }
 610     )*)
 611 }
 612
 613 saturating_int_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 614
 615 macro_rules! saturating_int_impl_signed {
 616     ($($t:ty)*) => ($(
 617         impl Saturating<$t> {
 618             /// Returns the number of leading zeros in the binary representation of `self`.
 619             ///
 620             /// # Examples
 621             ///
 622             /// Basic usage:
 623             ///
 624             /// ```
 625             /// #![feature(saturating_int_impl)]
 626             /// use std::num::Saturating;
 627             ///
 628             #[doc = concat!("let n = Saturating(", stringify!($t), "::MAX >> 2);")]
 629             ///
 630             /// assert_eq!(n.leading_zeros(), 3);
 631             /// ```
 632             #[inline]
 633             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 634             pub const fn leading_zeros(self) -> u32 {
 635                 self.0.leading_zeros()
 636             }
 637
 638             /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self == MIN`
 639             /// instead of overflowing.
 640             ///
 641             /// # Examples
 642             ///
 643             /// Basic usage:
 644             ///
 645             /// ```
 646             /// #![feature(saturating_int_impl)]
 647             /// use std::num::Saturating;
 648             ///
 649             #[doc = concat!("assert_eq!(Saturating(100", stringify!($t), ").abs(), Saturating(100));")]
 650             #[doc = concat!("assert_eq!(Saturating(-100", stringify!($t), ").abs(), Saturating(100));")]
 651             #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating((", stringify!($t), "::MIN + 1).abs()));")]
 652             #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating(", stringify!($t), "::MIN.saturating_abs()));")]
 653             /// assert_eq!(Saturating(-128i8).abs().0 as u8, i8::MAX as u8);
 654             /// ```
 655             #[inline]
 656             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 657             pub fn abs(self) -> Saturating<$t> {
 658                 Saturating(self.0.saturating_abs())
 659             }
 660
 661             /// Returns a number representing sign of `self`.
 662             ///
 663             ///  - `0` if the number is zero
 664             ///  - `1` if the number is positive
 665             ///  - `-1` if the number is negative
 666             ///
 667             /// # Examples
 668             ///
 669             /// Basic usage:
 670             ///
 671             /// ```
 672             /// #![feature(saturating_int_impl)]
 673             /// use std::num::Saturating;
 674             ///
 675             #[doc = concat!("assert_eq!(Saturating(10", stringify!($t), ").signum(), Saturating(1));")]
 676             #[doc = concat!("assert_eq!(Saturating(0", stringify!($t), ").signum(), Saturating(0));")]
 677             #[doc = concat!("assert_eq!(Saturating(-10", stringify!($t), ").signum(), Saturating(-1));")]
 678             /// ```
 679             #[inline]
 680             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 681             pub fn signum(self) -> Saturating<$t> {
 682                 Saturating(self.0.signum())
 683             }
 684
 685             /// Returns `true` if `self` is positive and `false` if the number is zero or
 686             /// negative.
 687             ///
 688             /// # Examples
 689             ///
 690             /// Basic usage:
 691             ///
 692             /// ```
 693             /// #![feature(saturating_int_impl)]
 694             /// use std::num::Saturating;
 695             ///
 696             #[doc = concat!("assert!(Saturating(10", stringify!($t), ").is_positive());")]
 697             #[doc = concat!("assert!(!Saturating(-10", stringify!($t), ").is_positive());")]
 698             /// ```
 699             #[inline]
 700             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 701             pub const fn is_positive(self) -> bool {
 702                 self.0.is_positive()
 703             }
 704
 705             /// Returns `true` if `self` is negative and `false` if the number is zero or
 706             /// positive.
 707             ///
 708             /// # Examples
 709             ///
 710             /// Basic usage:
 711             ///
 712             /// ```
 713             /// #![feature(saturating_int_impl)]
 714             /// use std::num::Saturating;
 715             ///
 716             #[doc = concat!("assert!(Saturating(-10", stringify!($t), ").is_negative());")]
 717             #[doc = concat!("assert!(!Saturating(10", stringify!($t), ").is_negative());")]
 718             /// ```
 719             #[inline]
 720             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 721             pub const fn is_negative(self) -> bool {
 722                 self.0.is_negative()
 723             }
 724         }
 725     )*)
 726 }
 727
 728 saturating_int_impl_signed! { isize i8 i16 i32 i64 i128 }
 729
 730 macro_rules! saturating_int_impl_unsigned {
 731     ($($t:ty)*) => ($(
 732         impl Saturating<$t> {
 733             /// Returns the number of leading zeros in the binary representation of `self`.
 734             ///
 735             /// # Examples
 736             ///
 737             /// Basic usage:
 738             ///
 739             /// ```
 740             /// #![feature(saturating_int_impl)]
 741             /// use std::num::Saturating;
 742             ///
 743             #[doc = concat!("let n = Saturating(", stringify!($t), "::MAX >> 2);")]
 744             ///
 745             /// assert_eq!(n.leading_zeros(), 2);
 746             /// ```
 747             #[inline]
 748             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 749             pub const fn leading_zeros(self) -> u32 {
 750                 self.0.leading_zeros()
 751             }
 752
 753             /// Returns `true` if and only if `self == 2^k` for some `k`.
 754             ///
 755             /// # Examples
 756             ///
 757             /// Basic usage:
 758             ///
 759             /// ```
 760             /// #![feature(saturating_int_impl)]
 761             /// use std::num::Saturating;
 762             ///
 763             #[doc = concat!("assert!(Saturating(16", stringify!($t), ").is_power_of_two());")]
 764             #[doc = concat!("assert!(!Saturating(10", stringify!($t), ").is_power_of_two());")]
 765             /// ```
 766             #[inline]
 767             #[unstable(feature = "saturating_int_impl", issue = "87920")]
 768             pub fn is_power_of_two(self) -> bool {
 769                 self.0.is_power_of_two()
 770             }
 771
 772         }
 773     )*)
 774 }
 775
 776 saturating_int_impl_unsigned! { usize u8 u16 u32 u64 u128 }