library/core/src/num/wrapping.rs

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