src/libcore/num/wrapping.rs

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