library/core/src/num/int_macros.rs

   1 macro_rules! int_impl {
   2     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, $Feature:expr,
   3      $EndFeature:expr, $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
   4      $reversed:expr, $le_bytes:expr, $be_bytes:expr,
   5      $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
   6         doc_comment! {
   7             concat!("The smallest value that can be represented by this integer type.
   8
   9 # Examples
  10
  11 Basic usage:
  12
  13 ```
  14 ", $Feature, "assert_eq!(", stringify!($SelfT), "::MIN, ", stringify!($Min), ");",
  15 $EndFeature, "
  16 ```"),
  17             #[stable(feature = "assoc_int_consts", since = "1.43.0")]
  18             pub const MIN: Self = !0 ^ ((!0 as $UnsignedT) >> 1) as Self;
  19         }
  20
  21         doc_comment! {
  22             concat!("The largest value that can be represented by this integer type.
  23
  24 # Examples
  25
  26 Basic usage:
  27
  28 ```
  29 ", $Feature, "assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($Max), ");",
  30 $EndFeature, "
  31 ```"),
  32             #[stable(feature = "assoc_int_consts", since = "1.43.0")]
  33             pub const MAX: Self = !Self::MIN;
  34         }
  35
  36         doc_comment! {
  37             concat!("The size of this integer type in bits.
  38
  39 # Examples
  40
  41 ```
  42 ", $Feature, "#![feature(int_bits_const)]
  43 assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");",
  44 $EndFeature, "
  45 ```"),
  46             #[unstable(feature = "int_bits_const", issue = "76904")]
  47             pub const BITS: u32 = $BITS;
  48         }
  49
  50         doc_comment! {
  51             concat!("Converts a string slice in a given base to an integer.
  52
  53 The string is expected to be an optional `+` or `-` sign followed by digits.
  54 Leading and trailing whitespace represent an error. Digits are a subset of these characters,
  55 depending on `radix`:
  56
  57  * `0-9`
  58  * `a-z`
  59  * `A-Z`
  60
  61 # Panics
  62
  63 This function panics if `radix` is not in the range from 2 to 36.
  64
  65 # Examples
  66
  67 Basic usage:
  68
  69 ```
  70 ", $Feature, "assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));",
  71 $EndFeature, "
  72 ```"),
  73             #[stable(feature = "rust1", since = "1.0.0")]
  74             pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
  75                 from_str_radix(src, radix)
  76             }
  77         }
  78
  79         doc_comment! {
  80             concat!("Returns the number of ones in the binary representation of `self`.
  81
  82 # Examples
  83
  84 Basic usage:
  85
  86 ```
  87 ", $Feature, "let n = 0b100_0000", stringify!($SelfT), ";
  88
  89 assert_eq!(n.count_ones(), 1);",
  90 $EndFeature, "
  91 ```
  92 "),
  93             #[stable(feature = "rust1", since = "1.0.0")]
  94             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
  95             #[inline]
  96             pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
  97         }
  98
  99         doc_comment! {
 100             concat!("Returns the number of zeros in the binary representation of `self`.
 101
 102 # Examples
 103
 104 Basic usage:
 105
 106 ```
 107 ", $Feature, "assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 1);", $EndFeature, "
 108 ```"),
 109             #[stable(feature = "rust1", since = "1.0.0")]
 110             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 111             #[inline]
 112             pub const fn count_zeros(self) -> u32 {
 113                 (!self).count_ones()
 114             }
 115         }
 116
 117         doc_comment! {
 118             concat!("Returns the number of leading zeros in the binary representation of `self`.
 119
 120 # Examples
 121
 122 Basic usage:
 123
 124 ```
 125 ", $Feature, "let n = -1", stringify!($SelfT), ";
 126
 127 assert_eq!(n.leading_zeros(), 0);",
 128 $EndFeature, "
 129 ```"),
 130             #[stable(feature = "rust1", since = "1.0.0")]
 131             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 132             #[inline]
 133             pub const fn leading_zeros(self) -> u32 {
 134                 (self as $UnsignedT).leading_zeros()
 135             }
 136         }
 137
 138         doc_comment! {
 139             concat!("Returns the number of trailing zeros in the binary representation of `self`.
 140
 141 # Examples
 142
 143 Basic usage:
 144
 145 ```
 146 ", $Feature, "let n = -4", stringify!($SelfT), ";
 147
 148 assert_eq!(n.trailing_zeros(), 2);",
 149 $EndFeature, "
 150 ```"),
 151             #[stable(feature = "rust1", since = "1.0.0")]
 152             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 153             #[inline]
 154             pub const fn trailing_zeros(self) -> u32 {
 155                 (self as $UnsignedT).trailing_zeros()
 156             }
 157         }
 158
 159         doc_comment! {
 160             concat!("Returns the number of leading ones in the binary representation of `self`.
 161
 162 # Examples
 163
 164 Basic usage:
 165
 166 ```
 167 ", $Feature, "let n = -1", stringify!($SelfT), ";
 168
 169 assert_eq!(n.leading_ones(), ", stringify!($BITS), ");",
 170 $EndFeature, "
 171 ```"),
 172             #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
 173             #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
 174             #[inline]
 175             pub const fn leading_ones(self) -> u32 {
 176                 (self as $UnsignedT).leading_ones()
 177             }
 178         }
 179
 180         doc_comment! {
 181             concat!("Returns the number of trailing ones in the binary representation of `self`.
 182
 183 # Examples
 184
 185 Basic usage:
 186
 187 ```
 188 ", $Feature, "let n = 3", stringify!($SelfT), ";
 189
 190 assert_eq!(n.trailing_ones(), 2);",
 191 $EndFeature, "
 192 ```"),
 193             #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
 194             #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
 195             #[inline]
 196             pub const fn trailing_ones(self) -> u32 {
 197                 (self as $UnsignedT).trailing_ones()
 198             }
 199         }
 200
 201         doc_comment! {
 202             concat!("Shifts the bits to the left by a specified amount, `n`,
 203 wrapping the truncated bits to the end of the resulting integer.
 204
 205 Please note this isn't the same operation as the `<<` shifting operator!
 206
 207 # Examples
 208
 209 Basic usage:
 210
 211 ```
 212 let n = ", $rot_op, stringify!($SelfT), ";
 213 let m = ", $rot_result, ";
 214
 215 assert_eq!(n.rotate_left(", $rot, "), m);
 216 ```"),
 217             #[stable(feature = "rust1", since = "1.0.0")]
 218             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 219             #[must_use = "this returns the result of the operation, \
 220                           without modifying the original"]
 221             #[inline]
 222             pub const fn rotate_left(self, n: u32) -> Self {
 223                 (self as $UnsignedT).rotate_left(n) as Self
 224             }
 225         }
 226
 227         doc_comment! {
 228             concat!("Shifts the bits to the right by a specified amount, `n`,
 229 wrapping the truncated bits to the beginning of the resulting
 230 integer.
 231
 232 Please note this isn't the same operation as the `>>` shifting operator!
 233
 234 # Examples
 235
 236 Basic usage:
 237
 238 ```
 239 let n = ", $rot_result, stringify!($SelfT), ";
 240 let m = ", $rot_op, ";
 241
 242 assert_eq!(n.rotate_right(", $rot, "), m);
 243 ```"),
 244             #[stable(feature = "rust1", since = "1.0.0")]
 245             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 246             #[must_use = "this returns the result of the operation, \
 247                           without modifying the original"]
 248             #[inline]
 249             pub const fn rotate_right(self, n: u32) -> Self {
 250                 (self as $UnsignedT).rotate_right(n) as Self
 251             }
 252         }
 253
 254         doc_comment! {
 255             concat!("Reverses the byte order of the integer.
 256
 257 # Examples
 258
 259 Basic usage:
 260
 261 ```
 262 let n = ", $swap_op, stringify!($SelfT), ";
 263
 264 let m = n.swap_bytes();
 265
 266 assert_eq!(m, ", $swapped, ");
 267 ```"),
 268             #[stable(feature = "rust1", since = "1.0.0")]
 269             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 270             #[inline]
 271             pub const fn swap_bytes(self) -> Self {
 272                 (self as $UnsignedT).swap_bytes() as Self
 273             }
 274         }
 275
 276         doc_comment! {
 277             concat!("Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,
 278                 second least-significant bit becomes second most-significant bit, etc.
 279
 280 # Examples
 281
 282 Basic usage:
 283
 284 ```
 285 let n = ", $swap_op, stringify!($SelfT), ";
 286 let m = n.reverse_bits();
 287
 288 assert_eq!(m, ", $reversed, ");
 289 assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());
 290 ```"),
 291             #[stable(feature = "reverse_bits", since = "1.37.0")]
 292             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 293             #[inline]
 294             #[must_use]
 295             pub const fn reverse_bits(self) -> Self {
 296                 (self as $UnsignedT).reverse_bits() as Self
 297             }
 298         }
 299
 300         doc_comment! {
 301             concat!("Converts an integer from big endian to the target's endianness.
 302
 303 On big endian this is a no-op. On little endian the bytes are swapped.
 304
 305 # Examples
 306
 307 Basic usage:
 308
 309 ```
 310 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 311
 312 if cfg!(target_endian = \"big\") {
 313     assert_eq!(", stringify!($SelfT), "::from_be(n), n)
 314 } else {
 315     assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())
 316 }",
 317 $EndFeature, "
 318 ```"),
 319             #[stable(feature = "rust1", since = "1.0.0")]
 320             #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 321             #[inline]
 322             pub const fn from_be(x: Self) -> Self {
 323                 #[cfg(target_endian = "big")]
 324                 {
 325                     x
 326                 }
 327                 #[cfg(not(target_endian = "big"))]
 328                 {
 329                     x.swap_bytes()
 330                 }
 331             }
 332         }
 333
 334         doc_comment! {
 335             concat!("Converts an integer from little endian to the target's endianness.
 336
 337 On little endian this is a no-op. On big endian the bytes are swapped.
 338
 339 # Examples
 340
 341 Basic usage:
 342
 343 ```
 344 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 345
 346 if cfg!(target_endian = \"little\") {
 347     assert_eq!(", stringify!($SelfT), "::from_le(n), n)
 348 } else {
 349     assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())
 350 }",
 351 $EndFeature, "
 352 ```"),
 353             #[stable(feature = "rust1", since = "1.0.0")]
 354             #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 355             #[inline]
 356             pub const fn from_le(x: Self) -> Self {
 357                 #[cfg(target_endian = "little")]
 358                 {
 359                     x
 360                 }
 361                 #[cfg(not(target_endian = "little"))]
 362                 {
 363                     x.swap_bytes()
 364                 }
 365             }
 366         }
 367
 368         doc_comment! {
 369             concat!("Converts `self` to big endian from the target's endianness.
 370
 371 On big endian this is a no-op. On little endian the bytes are swapped.
 372
 373 # Examples
 374
 375 Basic usage:
 376
 377 ```
 378 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 379
 380 if cfg!(target_endian = \"big\") {
 381     assert_eq!(n.to_be(), n)
 382 } else {
 383     assert_eq!(n.to_be(), n.swap_bytes())
 384 }",
 385 $EndFeature, "
 386 ```"),
 387             #[stable(feature = "rust1", since = "1.0.0")]
 388             #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 389             #[inline]
 390             pub const fn to_be(self) -> Self { // or not to be?
 391                 #[cfg(target_endian = "big")]
 392                 {
 393                     self
 394                 }
 395                 #[cfg(not(target_endian = "big"))]
 396                 {
 397                     self.swap_bytes()
 398                 }
 399             }
 400         }
 401
 402         doc_comment! {
 403             concat!("Converts `self` to little endian from the target's endianness.
 404
 405 On little endian this is a no-op. On big endian the bytes are swapped.
 406
 407 # Examples
 408
 409 Basic usage:
 410
 411 ```
 412 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 413
 414 if cfg!(target_endian = \"little\") {
 415     assert_eq!(n.to_le(), n)
 416 } else {
 417     assert_eq!(n.to_le(), n.swap_bytes())
 418 }",
 419 $EndFeature, "
 420 ```"),
 421             #[stable(feature = "rust1", since = "1.0.0")]
 422             #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 423             #[inline]
 424             pub const fn to_le(self) -> Self {
 425                 #[cfg(target_endian = "little")]
 426                 {
 427                     self
 428                 }
 429                 #[cfg(not(target_endian = "little"))]
 430                 {
 431                     self.swap_bytes()
 432                 }
 433             }
 434         }
 435
 436         doc_comment! {
 437             concat!("Checked integer addition. Computes `self + rhs`, returning `None`
 438 if overflow occurred.
 439
 440 # Examples
 441
 442 Basic usage:
 443
 444 ```
 445 ", $Feature, "assert_eq!((", stringify!($SelfT),
 446 "::MAX - 2).checked_add(1), Some(", stringify!($SelfT), "::MAX - 1));
 447 assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);",
 448 $EndFeature, "
 449 ```"),
 450             #[stable(feature = "rust1", since = "1.0.0")]
 451             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 452             #[must_use = "this returns the result of the operation, \
 453                           without modifying the original"]
 454             #[inline]
 455             pub const fn checked_add(self, rhs: Self) -> Option<Self> {
 456                 let (a, b) = self.overflowing_add(rhs);
 457                 if unlikely!(b) {None} else {Some(a)}
 458             }
 459         }
 460
 461         doc_comment! {
 462             concat!("Unchecked integer addition. Computes `self + rhs`, assuming overflow
 463 cannot occur. This results in undefined behavior when `self + rhs > ", stringify!($SelfT),
 464 "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`."),
 465             #[unstable(
 466                 feature = "unchecked_math",
 467                 reason = "niche optimization path",
 468                 issue = "none",
 469             )]
 470             #[must_use = "this returns the result of the operation, \
 471                           without modifying the original"]
 472             #[inline]
 473             pub unsafe fn unchecked_add(self, rhs: Self) -> Self {
 474                 // SAFETY: the caller must uphold the safety contract for
 475                 // `unchecked_add`.
 476                 unsafe { intrinsics::unchecked_add(self, rhs) }
 477             }
 478         }
 479
 480         doc_comment! {
 481             concat!("Checked integer subtraction. Computes `self - rhs`, returning `None` if
 482 overflow occurred.
 483
 484 # Examples
 485
 486 Basic usage:
 487
 488 ```
 489 ", $Feature, "assert_eq!((", stringify!($SelfT),
 490 "::MIN + 2).checked_sub(1), Some(", stringify!($SelfT), "::MIN + 1));
 491 assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(3), None);",
 492 $EndFeature, "
 493 ```"),
 494             #[stable(feature = "rust1", since = "1.0.0")]
 495             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 496             #[must_use = "this returns the result of the operation, \
 497                           without modifying the original"]
 498             #[inline]
 499             pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
 500                 let (a, b) = self.overflowing_sub(rhs);
 501                 if unlikely!(b) {None} else {Some(a)}
 502             }
 503         }
 504
 505         doc_comment! {
 506             concat!("Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
 507 cannot occur. This results in undefined behavior when `self - rhs > ", stringify!($SelfT),
 508 "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`."),
 509             #[unstable(
 510                 feature = "unchecked_math",
 511                 reason = "niche optimization path",
 512                 issue = "none",
 513             )]
 514             #[must_use = "this returns the result of the operation, \
 515                           without modifying the original"]
 516             #[inline]
 517             pub unsafe fn unchecked_sub(self, rhs: Self) -> Self {
 518                 // SAFETY: the caller must uphold the safety contract for
 519                 // `unchecked_sub`.
 520                 unsafe { intrinsics::unchecked_sub(self, rhs) }
 521             }
 522         }
 523
 524         doc_comment! {
 525             concat!("Checked integer multiplication. Computes `self * rhs`, returning `None` if
 526 overflow occurred.
 527
 528 # Examples
 529
 530 Basic usage:
 531
 532 ```
 533 ", $Feature, "assert_eq!(", stringify!($SelfT),
 534 "::MAX.checked_mul(1), Some(", stringify!($SelfT), "::MAX));
 535 assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);",
 536 $EndFeature, "
 537 ```"),
 538             #[stable(feature = "rust1", since = "1.0.0")]
 539             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 540             #[must_use = "this returns the result of the operation, \
 541                           without modifying the original"]
 542             #[inline]
 543             pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
 544                 let (a, b) = self.overflowing_mul(rhs);
 545                 if unlikely!(b) {None} else {Some(a)}
 546             }
 547         }
 548
 549         doc_comment! {
 550             concat!("Unchecked integer multiplication. Computes `self * rhs`, assuming overflow
 551 cannot occur. This results in undefined behavior when `self * rhs > ", stringify!($SelfT),
 552 "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`."),
 553             #[unstable(
 554                 feature = "unchecked_math",
 555                 reason = "niche optimization path",
 556                 issue = "none",
 557             )]
 558             #[must_use = "this returns the result of the operation, \
 559                           without modifying the original"]
 560             #[inline]
 561             pub unsafe fn unchecked_mul(self, rhs: Self) -> Self {
 562                 // SAFETY: the caller must uphold the safety contract for
 563                 // `unchecked_mul`.
 564                 unsafe { intrinsics::unchecked_mul(self, rhs) }
 565             }
 566         }
 567
 568         doc_comment! {
 569             concat!("Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0`
 570 or the division results in overflow.
 571
 572 # Examples
 573
 574 Basic usage:
 575
 576 ```
 577 ", $Feature, "assert_eq!((", stringify!($SelfT),
 578 "::MIN + 1).checked_div(-1), Some(", stringify!($Max), "));
 579 assert_eq!(", stringify!($SelfT), "::MIN.checked_div(-1), None);
 580 assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);",
 581 $EndFeature, "
 582 ```"),
 583             #[stable(feature = "rust1", since = "1.0.0")]
 584             #[rustc_const_unstable(feature = "const_checked_int_methods", issue = "53718")]
 585             #[must_use = "this returns the result of the operation, \
 586                           without modifying the original"]
 587             #[inline]
 588             pub const fn checked_div(self, rhs: Self) -> Option<Self> {
 589                 if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) {
 590                     None
 591                 } else {
 592                     // SAFETY: div by zero and by INT_MIN have been checked above
 593                     Some(unsafe { intrinsics::unchecked_div(self, rhs) })
 594                 }
 595             }
 596         }
 597
 598         doc_comment! {
 599             concat!("Checked Euclidean division. Computes `self.div_euclid(rhs)`,
 600 returning `None` if `rhs == 0` or the division results in overflow.
 601
 602 # Examples
 603
 604 Basic usage:
 605
 606 ```
 607 assert_eq!((", stringify!($SelfT),
 608 "::MIN + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));
 609 assert_eq!(", stringify!($SelfT), "::MIN.checked_div_euclid(-1), None);
 610 assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);
 611 ```"),
 612             #[stable(feature = "euclidean_division", since = "1.38.0")]
 613             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
 614             #[must_use = "this returns the result of the operation, \
 615                           without modifying the original"]
 616             #[inline]
 617             pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
 618                 if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) {
 619                     None
 620                 } else {
 621                     Some(self.div_euclid(rhs))
 622                 }
 623             }
 624         }
 625
 626         doc_comment! {
 627             concat!("Checked integer remainder. Computes `self % rhs`, returning `None` if
 628 `rhs == 0` or the division results in overflow.
 629
 630 # Examples
 631
 632 Basic usage:
 633
 634 ```
 635 ", $Feature, "
 636 assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));
 637 assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);
 638 assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);",
 639 $EndFeature, "
 640 ```"),
 641             #[stable(feature = "wrapping", since = "1.7.0")]
 642             #[rustc_const_unstable(feature = "const_checked_int_methods", issue = "53718")]
 643             #[must_use = "this returns the result of the operation, \
 644                           without modifying the original"]
 645             #[inline]
 646             pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
 647                 if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) {
 648                     None
 649                 } else {
 650                     // SAFETY: div by zero and by INT_MIN have been checked above
 651                     Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
 652                 }
 653             }
 654         }
 655
 656         doc_comment! {
 657             concat!("Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None`
 658 if `rhs == 0` or the division results in overflow.
 659
 660 # Examples
 661
 662 Basic usage:
 663
 664 ```
 665 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));
 666 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);
 667 assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);
 668 ```"),
 669             #[stable(feature = "euclidean_division", since = "1.38.0")]
 670             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
 671             #[must_use = "this returns the result of the operation, \
 672                           without modifying the original"]
 673             #[inline]
 674             pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
 675                 if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) {
 676                     None
 677                 } else {
 678                     Some(self.rem_euclid(rhs))
 679                 }
 680             }
 681         }
 682
 683         doc_comment! {
 684             concat!("Checked negation. Computes `-self`, returning `None` if `self == MIN`.
 685
 686 # Examples
 687
 688 Basic usage:
 689
 690 ```
 691 ", $Feature, "
 692 assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));
 693 assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);",
 694 $EndFeature, "
 695 ```"),
 696             #[stable(feature = "wrapping", since = "1.7.0")]
 697             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 698             #[inline]
 699             pub const fn checked_neg(self) -> Option<Self> {
 700                 let (a, b) = self.overflowing_neg();
 701                 if unlikely!(b) {None} else {Some(a)}
 702             }
 703         }
 704
 705         doc_comment! {
 706             concat!("Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger
 707 than or equal to the number of bits in `self`.
 708
 709 # Examples
 710
 711 Basic usage:
 712
 713 ```
 714 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));
 715 assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);",
 716 $EndFeature, "
 717 ```"),
 718             #[stable(feature = "wrapping", since = "1.7.0")]
 719             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 720             #[must_use = "this returns the result of the operation, \
 721                           without modifying the original"]
 722             #[inline]
 723             pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
 724                 let (a, b) = self.overflowing_shl(rhs);
 725                 if unlikely!(b) {None} else {Some(a)}
 726             }
 727         }
 728
 729         doc_comment! {
 730             concat!("Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
 731 larger than or equal to the number of bits in `self`.
 732
 733 # Examples
 734
 735 Basic usage:
 736
 737 ```
 738 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));
 739 assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);",
 740 $EndFeature, "
 741 ```"),
 742             #[stable(feature = "wrapping", since = "1.7.0")]
 743             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 744             #[must_use = "this returns the result of the operation, \
 745                           without modifying the original"]
 746             #[inline]
 747             pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
 748                 let (a, b) = self.overflowing_shr(rhs);
 749                 if unlikely!(b) {None} else {Some(a)}
 750             }
 751         }
 752
 753         doc_comment! {
 754             concat!("Checked absolute value. Computes `self.abs()`, returning `None` if
 755 `self == MIN`.
 756
 757 # Examples
 758
 759 Basic usage:
 760
 761 ```
 762 ", $Feature, "
 763 assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));
 764 assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);",
 765 $EndFeature, "
 766 ```"),
 767             #[stable(feature = "no_panic_abs", since = "1.13.0")]
 768             #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 769             #[inline]
 770             pub const fn checked_abs(self) -> Option<Self> {
 771                 if self.is_negative() {
 772                     self.checked_neg()
 773                 } else {
 774                     Some(self)
 775                 }
 776             }
 777         }
 778
 779         doc_comment! {
 780             concat!("Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
 781 overflow occurred.
 782
 783 # Examples
 784
 785 Basic usage:
 786
 787 ```
 788 ", $Feature, "assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));
 789 assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);",
 790 $EndFeature, "
 791 ```"),
 792
 793             #[stable(feature = "no_panic_pow", since = "1.34.0")]
 794             #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
 795             #[must_use = "this returns the result of the operation, \
 796                           without modifying the original"]
 797             #[inline]
 798             pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
 799                 if exp == 0 {
 800                     return Some(1);
 801                 }
 802                 let mut base = self;
 803                 let mut acc: Self = 1;
 804
 805                 while exp > 1 {
 806                     if (exp & 1) == 1 {
 807                         acc = try_opt!(acc.checked_mul(base));
 808                     }
 809                     exp /= 2;
 810                     base = try_opt!(base.checked_mul(base));
 811                 }
 812                 // since exp!=0, finally the exp must be 1.
 813                 // Deal with the final bit of the exponent separately, since
 814                 // squaring the base afterwards is not necessary and may cause a
 815                 // needless overflow.
 816                 Some(try_opt!(acc.checked_mul(base)))
 817             }
 818         }
 819
 820         doc_comment! {
 821             concat!("Saturating integer addition. Computes `self + rhs`, saturating at the numeric
 822 bounds instead of overflowing.
 823
 824 # Examples
 825
 826 Basic usage:
 827
 828 ```
 829 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);
 830 assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(100), ", stringify!($SelfT),
 831 "::MAX);
 832 assert_eq!(", stringify!($SelfT), "::MIN.saturating_add(-1), ", stringify!($SelfT),
 833 "::MIN);",
 834 $EndFeature, "
 835 ```"),
 836
 837             #[stable(feature = "rust1", since = "1.0.0")]
 838             #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 839             #[must_use = "this returns the result of the operation, \
 840                           without modifying the original"]
 841             #[inline]
 842             pub const fn saturating_add(self, rhs: Self) -> Self {
 843                 intrinsics::saturating_add(self, rhs)
 844             }
 845         }
 846
 847         doc_comment! {
 848             concat!("Saturating integer subtraction. Computes `self - rhs`, saturating at the
 849 numeric bounds instead of overflowing.
 850
 851 # Examples
 852
 853 Basic usage:
 854
 855 ```
 856 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);
 857 assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub(100), ", stringify!($SelfT),
 858 "::MIN);
 859 assert_eq!(", stringify!($SelfT), "::MAX.saturating_sub(-1), ", stringify!($SelfT),
 860 "::MAX);",
 861 $EndFeature, "
 862 ```"),
 863             #[stable(feature = "rust1", since = "1.0.0")]
 864             #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 865             #[must_use = "this returns the result of the operation, \
 866                           without modifying the original"]
 867             #[inline]
 868             pub const fn saturating_sub(self, rhs: Self) -> Self {
 869                 intrinsics::saturating_sub(self, rhs)
 870             }
 871         }
 872
 873         doc_comment! {
 874             concat!("Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN`
 875 instead of overflowing.
 876
 877 # Examples
 878
 879 Basic usage:
 880
 881 ```
 882 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);
 883 assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);
 884 assert_eq!(", stringify!($SelfT), "::MIN.saturating_neg(), ", stringify!($SelfT),
 885 "::MAX);
 886 assert_eq!(", stringify!($SelfT), "::MAX.saturating_neg(), ", stringify!($SelfT),
 887 "::MIN + 1);",
 888 $EndFeature, "
 889 ```"),
 890
 891             #[stable(feature = "saturating_neg", since = "1.45.0")]
 892             #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 893             #[inline]
 894             pub const fn saturating_neg(self) -> Self {
 895                 intrinsics::saturating_sub(0, self)
 896             }
 897         }
 898
 899         doc_comment! {
 900             concat!("Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self ==
 901 MIN` instead of overflowing.
 902
 903 # Examples
 904
 905 Basic usage:
 906
 907 ```
 908 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);
 909 assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);
 910 assert_eq!(", stringify!($SelfT), "::MIN.saturating_abs(), ", stringify!($SelfT),
 911 "::MAX);
 912 assert_eq!((", stringify!($SelfT), "::MIN + 1).saturating_abs(), ", stringify!($SelfT),
 913 "::MAX);",
 914 $EndFeature, "
 915 ```"),
 916
 917             #[stable(feature = "saturating_neg", since = "1.45.0")]
 918             #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 919             #[inline]
 920             pub const fn saturating_abs(self) -> Self {
 921                 if self.is_negative() {
 922                     self.saturating_neg()
 923                 } else {
 924                     self
 925                 }
 926             }
 927         }
 928
 929         doc_comment! {
 930             concat!("Saturating integer multiplication. Computes `self * rhs`, saturating at the
 931 numeric bounds instead of overflowing.
 932
 933 # Examples
 934
 935 Basic usage:
 936
 937 ```
 938 ", $Feature, "
 939 assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);
 940 assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);
 941 assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);",
 942 $EndFeature, "
 943 ```"),
 944             #[stable(feature = "wrapping", since = "1.7.0")]
 945             #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 946             #[must_use = "this returns the result of the operation, \
 947                           without modifying the original"]
 948             #[inline]
 949             pub const fn saturating_mul(self, rhs: Self) -> Self {
 950                 match self.checked_mul(rhs) {
 951                     Some(x) => x,
 952                     None => if (self < 0) == (rhs < 0) {
 953                         Self::MAX
 954                     } else {
 955                         Self::MIN
 956                     }
 957                 }
 958             }
 959         }
 960
 961         doc_comment! {
 962             concat!("Saturating integer exponentiation. Computes `self.pow(exp)`,
 963 saturating at the numeric bounds instead of overflowing.
 964
 965 # Examples
 966
 967 Basic usage:
 968
 969 ```
 970 ", $Feature, "
 971 assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);
 972 assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);
 973 assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);",
 974 $EndFeature, "
 975 ```"),
 976             #[stable(feature = "no_panic_pow", since = "1.34.0")]
 977             #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
 978             #[must_use = "this returns the result of the operation, \
 979                           without modifying the original"]
 980             #[inline]
 981             pub const fn saturating_pow(self, exp: u32) -> Self {
 982                 match self.checked_pow(exp) {
 983                     Some(x) => x,
 984                     None if self < 0 && exp % 2 == 1 => Self::MIN,
 985                     None => Self::MAX,
 986                 }
 987             }
 988         }
 989
 990         doc_comment! {
 991             concat!("Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
 992 boundary of the type.
 993
 994 # Examples
 995
 996 Basic usage:
 997
 998 ```
 999 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);
1000 assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT),
1001 "::MIN + 1);",
1002 $EndFeature, "
1003 ```"),
1004             #[stable(feature = "rust1", since = "1.0.0")]
1005             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1006             #[must_use = "this returns the result of the operation, \
1007                           without modifying the original"]
1008             #[inline]
1009             pub const fn wrapping_add(self, rhs: Self) -> Self {
1010                 intrinsics::wrapping_add(self, rhs)
1011             }
1012         }
1013
1014         doc_comment! {
1015             concat!("Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
1016 boundary of the type.
1017
1018 # Examples
1019
1020 Basic usage:
1021
1022 ```
1023 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);
1024 assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ",
1025 stringify!($SelfT), "::MAX);",
1026 $EndFeature, "
1027 ```"),
1028             #[stable(feature = "rust1", since = "1.0.0")]
1029             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1030             #[must_use = "this returns the result of the operation, \
1031                           without modifying the original"]
1032             #[inline]
1033             pub const fn wrapping_sub(self, rhs: Self) -> Self {
1034                 intrinsics::wrapping_sub(self, rhs)
1035             }
1036         }
1037
1038         doc_comment! {
1039             concat!("Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
1040 the boundary of the type.
1041
1042 # Examples
1043
1044 Basic usage:
1045
1046 ```
1047 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);
1048 assert_eq!(11i8.wrapping_mul(12), -124);",
1049 $EndFeature, "
1050 ```"),
1051             #[stable(feature = "rust1", since = "1.0.0")]
1052             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1053             #[must_use = "this returns the result of the operation, \
1054                           without modifying the original"]
1055             #[inline]
1056             pub const fn wrapping_mul(self, rhs: Self) -> Self {
1057                 intrinsics::wrapping_mul(self, rhs)
1058             }
1059         }
1060
1061         doc_comment! {
1062             concat!("Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
1063 boundary of the type.
1064
1065 The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
1066 `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
1067 that is too large to represent in the type. In such a case, this function returns `MIN` itself.
1068
1069 # Panics
1070
1071 This function will panic if `rhs` is 0.
1072
1073 # Examples
1074
1075 Basic usage:
1076
1077 ```
1078 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);
1079 assert_eq!((-128i8).wrapping_div(-1), -128);",
1080 $EndFeature, "
1081 ```"),
1082             #[stable(feature = "num_wrapping", since = "1.2.0")]
1083             #[rustc_const_unstable(feature = "const_wrapping_int_methods", issue = "53718")]
1084             #[must_use = "this returns the result of the operation, \
1085                           without modifying the original"]
1086             #[inline]
1087             pub const fn wrapping_div(self, rhs: Self) -> Self {
1088                 self.overflowing_div(rhs).0
1089             }
1090         }
1091
1092         doc_comment! {
1093             concat!("Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
1094 wrapping around at the boundary of the type.
1095
1096 Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
1097 for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
1098 type. In this case, this method returns `MIN` itself.
1099
1100 # Panics
1101
1102 This function will panic if `rhs` is 0.
1103
1104 # Examples
1105
1106 Basic usage:
1107
1108 ```
1109 assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);
1110 assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
1111 ```"),
1112             #[stable(feature = "euclidean_division", since = "1.38.0")]
1113             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
1114             #[must_use = "this returns the result of the operation, \
1115                           without modifying the original"]
1116             #[inline]
1117             pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
1118                 self.overflowing_div_euclid(rhs).0
1119             }
1120         }
1121
1122         doc_comment! {
1123             concat!("Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
1124 boundary of the type.
1125
1126 Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
1127 invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
1128 this function returns `0`.
1129
1130 # Panics
1131
1132 This function will panic if `rhs` is 0.
1133
1134 # Examples
1135
1136 Basic usage:
1137
1138 ```
1139 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);
1140 assert_eq!((-128i8).wrapping_rem(-1), 0);",
1141 $EndFeature, "
1142 ```"),
1143             #[stable(feature = "num_wrapping", since = "1.2.0")]
1144             #[rustc_const_unstable(feature = "const_wrapping_int_methods", issue = "53718")]
1145             #[must_use = "this returns the result of the operation, \
1146                           without modifying the original"]
1147             #[inline]
1148             pub const fn wrapping_rem(self, rhs: Self) -> Self {
1149                 self.overflowing_rem(rhs).0
1150             }
1151         }
1152
1153         doc_comment! {
1154             concat!("Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
1155 at the boundary of the type.
1156
1157 Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
1158 for the type). In this case, this method returns 0.
1159
1160 # Panics
1161
1162 This function will panic if `rhs` is 0.
1163
1164 # Examples
1165
1166 Basic usage:
1167
1168 ```
1169 assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);
1170 assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
1171 ```"),
1172             #[stable(feature = "euclidean_division", since = "1.38.0")]
1173             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
1174             #[must_use = "this returns the result of the operation, \
1175                           without modifying the original"]
1176             #[inline]
1177             pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1178                 self.overflowing_rem_euclid(rhs).0
1179             }
1180         }
1181
1182         doc_comment! {
1183             concat!("Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
1184 of the type.
1185
1186 The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
1187 is the negative minimal value for the type); this is a positive value that is too large to represent
1188 in the type. In such a case, this function returns `MIN` itself.
1189
1190 # Examples
1191
1192 Basic usage:
1193
1194 ```
1195 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);
1196 assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT),
1197 "::MIN);",
1198 $EndFeature, "
1199 ```"),
1200             #[stable(feature = "num_wrapping", since = "1.2.0")]
1201             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1202             #[inline]
1203             pub const fn wrapping_neg(self) -> Self {
1204                 self.overflowing_neg().0
1205             }
1206         }
1207
1208         doc_comment! {
1209             concat!("Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
1210 any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1211
1212 Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
1213 the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
1214 The primitive integer types all implement a `[`rotate_left`](#method.rotate_left) function,
1215 which may be what you want instead.
1216
1217 # Examples
1218
1219 Basic usage:
1220
1221 ```
1222 ", $Feature, "assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);
1223 assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);",
1224 $EndFeature, "
1225 ```"),
1226             #[stable(feature = "num_wrapping", since = "1.2.0")]
1227             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1228             #[must_use = "this returns the result of the operation, \
1229                           without modifying the original"]
1230             #[inline]
1231             pub const fn wrapping_shl(self, rhs: u32) -> Self {
1232                 // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1233                 // out of bounds
1234                 unsafe {
1235                     intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1236                 }
1237             }
1238         }
1239
1240         doc_comment! {
1241             concat!("Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
1242 removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1243
1244 Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
1245 to the range of the type, rather than the bits shifted out of the LHS being returned to the other
1246 end. The primitive integer types all implement a [`rotate_right`](#method.rotate_right) function,
1247 which may be what you want instead.
1248
1249 # Examples
1250
1251 Basic usage:
1252
1253 ```
1254 ", $Feature, "assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);
1255 assert_eq!((-128i16).wrapping_shr(64), -128);",
1256 $EndFeature, "
1257 ```"),
1258             #[stable(feature = "num_wrapping", since = "1.2.0")]
1259             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1260             #[must_use = "this returns the result of the operation, \
1261                           without modifying the original"]
1262             #[inline]
1263             pub const fn wrapping_shr(self, rhs: u32) -> Self {
1264                 // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1265                 // out of bounds
1266                 unsafe {
1267                     intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1268                 }
1269             }
1270         }
1271
1272         doc_comment! {
1273             concat!("Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
1274 the boundary of the type.
1275
1276 The only case where such wrapping can occur is when one takes the absolute value of the negative
1277 minimal value for the type; this is a positive value that is too large to represent in the type. In
1278 such a case, this function returns `MIN` itself.
1279
1280 # Examples
1281
1282 Basic usage:
1283
1284 ```
1285 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);
1286 assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);
1287 assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT),
1288 "::MIN);
1289 assert_eq!((-128i8).wrapping_abs() as u8, 128);",
1290 $EndFeature, "
1291 ```"),
1292             #[stable(feature = "no_panic_abs", since = "1.13.0")]
1293             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1294             #[allow(unused_attributes)]
1295             #[inline]
1296             pub const fn wrapping_abs(self) -> Self {
1297                  if self.is_negative() {
1298                      self.wrapping_neg()
1299                  } else {
1300                      self
1301                  }
1302             }
1303         }
1304
1305         doc_comment! {
1306             concat!("Computes the absolute value of `self` without any wrapping
1307 or panicking.
1308
1309
1310 # Examples
1311
1312 Basic usage:
1313
1314 ```
1315 ", $Feature, "#![feature(unsigned_abs)]
1316 assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");
1317 assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");
1318 assert_eq!((-128i8).unsigned_abs(), 128u8);",
1319 $EndFeature, "
1320 ```"),
1321             #[unstable(feature = "unsigned_abs", issue = "74913")]
1322             #[inline]
1323             pub const fn unsigned_abs(self) -> $UnsignedT {
1324                  self.wrapping_abs() as $UnsignedT
1325             }
1326         }
1327
1328         doc_comment! {
1329             concat!("Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1330 wrapping around at the boundary of the type.
1331
1332 # Examples
1333
1334 Basic usage:
1335
1336 ```
1337 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);
1338 assert_eq!(3i8.wrapping_pow(5), -13);
1339 assert_eq!(3i8.wrapping_pow(6), -39);",
1340 $EndFeature, "
1341 ```"),
1342             #[stable(feature = "no_panic_pow", since = "1.34.0")]
1343             #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1344             #[must_use = "this returns the result of the operation, \
1345                           without modifying the original"]
1346             #[inline]
1347             pub const fn wrapping_pow(self, mut exp: u32) -> Self {
1348                 if exp == 0 {
1349                     return 1;
1350                 }
1351                 let mut base = self;
1352                 let mut acc: Self = 1;
1353
1354                 while exp > 1 {
1355                     if (exp & 1) == 1 {
1356                         acc = acc.wrapping_mul(base);
1357                     }
1358                     exp /= 2;
1359                     base = base.wrapping_mul(base);
1360                 }
1361
1362                 // since exp!=0, finally the exp must be 1.
1363                 // Deal with the final bit of the exponent separately, since
1364                 // squaring the base afterwards is not necessary and may cause a
1365                 // needless overflow.
1366                 acc.wrapping_mul(base)
1367             }
1368         }
1369
1370         doc_comment! {
1371             concat!("Calculates `self` + `rhs`
1372
1373 Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would
1374 occur. If an overflow would have occurred then the wrapped value is returned.
1375
1376 # Examples
1377
1378 Basic usage:
1379
1380 ```
1381 ", $Feature, "
1382 assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));
1383 assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT),
1384 "::MIN, true));", $EndFeature, "
1385 ```"),
1386             #[stable(feature = "wrapping", since = "1.7.0")]
1387             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1388             #[must_use = "this returns the result of the operation, \
1389                           without modifying the original"]
1390             #[inline]
1391             pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1392                 let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1393                 (a as Self, b)
1394             }
1395         }
1396
1397         doc_comment! {
1398             concat!("Calculates `self` - `rhs`
1399
1400 Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
1401 would occur. If an overflow would have occurred then the wrapped value is returned.
1402
1403 # Examples
1404
1405 Basic usage:
1406
1407 ```
1408 ", $Feature, "
1409 assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));
1410 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT),
1411 "::MAX, true));", $EndFeature, "
1412 ```"),
1413             #[stable(feature = "wrapping", since = "1.7.0")]
1414             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1415             #[must_use = "this returns the result of the operation, \
1416                           without modifying the original"]
1417             #[inline]
1418             pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1419                 let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
1420                 (a as Self, b)
1421             }
1422         }
1423
1424         doc_comment! {
1425             concat!("Calculates the multiplication of `self` and `rhs`.
1426
1427 Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
1428 would occur. If an overflow would have occurred then the wrapped value is returned.
1429
1430 # Examples
1431
1432 Basic usage:
1433
1434 ```
1435 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));
1436 assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));",
1437 $EndFeature, "
1438 ```"),
1439             #[stable(feature = "wrapping", since = "1.7.0")]
1440             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1441             #[must_use = "this returns the result of the operation, \
1442                           without modifying the original"]
1443             #[inline]
1444             pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
1445                 let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
1446                 (a as Self, b)
1447             }
1448         }
1449
1450         doc_comment! {
1451             concat!("Calculates the divisor when `self` is divided by `rhs`.
1452
1453 Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1454 occur. If an overflow would occur then self is returned.
1455
1456 # Panics
1457
1458 This function will panic if `rhs` is 0.
1459
1460 # Examples
1461
1462 Basic usage:
1463
1464 ```
1465 ", $Feature, "
1466 assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));
1467 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT),
1468 "::MIN, true));",
1469 $EndFeature, "
1470 ```"),
1471             #[inline]
1472             #[stable(feature = "wrapping", since = "1.7.0")]
1473             #[rustc_const_unstable(feature = "const_overflowing_int_methods", issue = "53718")]
1474             #[must_use = "this returns the result of the operation, \
1475                           without modifying the original"]
1476             pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
1477                 if unlikely!(self == Self::MIN && rhs == -1) {
1478                     (self, true)
1479                 } else {
1480                     (self / rhs, false)
1481                 }
1482             }
1483         }
1484
1485         doc_comment! {
1486             concat!("Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
1487
1488 Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1489 occur. If an overflow would occur then `self` is returned.
1490
1491 # Panics
1492
1493 This function will panic if `rhs` is 0.
1494
1495 # Examples
1496
1497 Basic usage:
1498
1499 ```
1500 assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));
1501 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT),
1502 "::MIN, true));
1503 ```"),
1504             #[inline]
1505             #[stable(feature = "euclidean_division", since = "1.38.0")]
1506             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
1507             #[must_use = "this returns the result of the operation, \
1508                           without modifying the original"]
1509             pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
1510                 if unlikely!(self == Self::MIN && rhs == -1) {
1511                     (self, true)
1512                 } else {
1513                     (self.div_euclid(rhs), false)
1514                 }
1515             }
1516         }
1517
1518         doc_comment! {
1519             concat!("Calculates the remainder when `self` is divided by `rhs`.
1520
1521 Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1522 arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1523
1524 # Panics
1525
1526 This function will panic if `rhs` is 0.
1527
1528 # Examples
1529
1530 Basic usage:
1531
1532 ```
1533 ", $Feature, "
1534 assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));
1535 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));",
1536 $EndFeature, "
1537 ```"),
1538             #[inline]
1539             #[stable(feature = "wrapping", since = "1.7.0")]
1540             #[rustc_const_unstable(feature = "const_overflowing_int_methods", issue = "53718")]
1541             #[must_use = "this returns the result of the operation, \
1542                           without modifying the original"]
1543             pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
1544                 if unlikely!(self == Self::MIN && rhs == -1) {
1545                     (0, true)
1546                 } else {
1547                     (self % rhs, false)
1548                 }
1549             }
1550         }
1551
1552
1553         doc_comment! {
1554             concat!("Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
1555
1556 Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1557 arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1558
1559 # Panics
1560
1561 This function will panic if `rhs` is 0.
1562
1563 # Examples
1564
1565 Basic usage:
1566
1567 ```
1568 assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));
1569 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));
1570 ```"),
1571             #[stable(feature = "euclidean_division", since = "1.38.0")]
1572             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
1573             #[must_use = "this returns the result of the operation, \
1574                           without modifying the original"]
1575             #[inline]
1576             pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
1577                 if unlikely!(self == Self::MIN && rhs == -1) {
1578                     (0, true)
1579                 } else {
1580                     (self.rem_euclid(rhs), false)
1581                 }
1582             }
1583         }
1584
1585
1586         doc_comment! {
1587             concat!("Negates self, overflowing if this is equal to the minimum value.
1588
1589 Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
1590 happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
1591 minimum value will be returned again and `true` will be returned for an overflow happening.
1592
1593 # Examples
1594
1595 Basic usage:
1596
1597 ```
1598 assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));
1599 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT),
1600 "::MIN, true));", $EndFeature, "
1601 ```"),
1602             #[inline]
1603             #[stable(feature = "wrapping", since = "1.7.0")]
1604             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1605             #[allow(unused_attributes)]
1606             pub const fn overflowing_neg(self) -> (Self, bool) {
1607                 if unlikely!(self == Self::MIN) {
1608                     (Self::MIN, true)
1609                 } else {
1610                     (-self, false)
1611                 }
1612             }
1613         }
1614
1615         doc_comment! {
1616             concat!("Shifts self left by `rhs` bits.
1617
1618 Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1619 value was larger than or equal to the number of bits. If the shift value is too large, then value is
1620 masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1621
1622 # Examples
1623
1624 Basic usage:
1625
1626 ```
1627 ", $Feature, "assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));
1628 assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));",
1629 $EndFeature, "
1630 ```"),
1631             #[stable(feature = "wrapping", since = "1.7.0")]
1632             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1633             #[must_use = "this returns the result of the operation, \
1634                           without modifying the original"]
1635             #[inline]
1636             pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1637                 (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1638             }
1639         }
1640
1641         doc_comment! {
1642             concat!("Shifts self right by `rhs` bits.
1643
1644 Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1645 value was larger than or equal to the number of bits. If the shift value is too large, then value is
1646 masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1647
1648 # Examples
1649
1650 Basic usage:
1651
1652 ```
1653 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));
1654 assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));",
1655 $EndFeature, "
1656 ```"),
1657             #[stable(feature = "wrapping", since = "1.7.0")]
1658             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1659             #[must_use = "this returns the result of the operation, \
1660                           without modifying the original"]
1661             #[inline]
1662             pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1663                 (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1664             }
1665         }
1666
1667         doc_comment! {
1668             concat!("Computes the absolute value of `self`.
1669
1670 Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
1671 happened. If self is the minimum value (e.g., ", stringify!($SelfT), "::MIN for values of type
1672  ", stringify!($SelfT), "), then the minimum value will be returned again and true will be returned
1673 for an overflow happening.
1674
1675 # Examples
1676
1677 Basic usage:
1678
1679 ```
1680 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));
1681 assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));
1682 assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT),
1683 "::MIN, true));",
1684 $EndFeature, "
1685 ```"),
1686             #[stable(feature = "no_panic_abs", since = "1.13.0")]
1687             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1688             #[inline]
1689             pub const fn overflowing_abs(self) -> (Self, bool) {
1690                 (self.wrapping_abs(), self == Self::MIN)
1691             }
1692         }
1693
1694         doc_comment! {
1695             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
1696
1697 Returns a tuple of the exponentiation along with a bool indicating
1698 whether an overflow happened.
1699
1700 # Examples
1701
1702 Basic usage:
1703
1704 ```
1705 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));
1706 assert_eq!(3i8.overflowing_pow(5), (-13, true));",
1707 $EndFeature, "
1708 ```"),
1709             #[stable(feature = "no_panic_pow", since = "1.34.0")]
1710             #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1711             #[must_use = "this returns the result of the operation, \
1712                           without modifying the original"]
1713             #[inline]
1714             pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
1715                 if exp == 0 {
1716                     return (1,false);
1717                 }
1718                 let mut base = self;
1719                 let mut acc: Self = 1;
1720                 let mut overflown = false;
1721                 // Scratch space for storing results of overflowing_mul.
1722                 let mut r;
1723
1724                 while exp > 1 {
1725                     if (exp & 1) == 1 {
1726                         r = acc.overflowing_mul(base);
1727                         acc = r.0;
1728                         overflown |= r.1;
1729                     }
1730                     exp /= 2;
1731                     r = base.overflowing_mul(base);
1732                     base = r.0;
1733                     overflown |= r.1;
1734                 }
1735
1736                 // since exp!=0, finally the exp must be 1.
1737                 // Deal with the final bit of the exponent separately, since
1738                 // squaring the base afterwards is not necessary and may cause a
1739                 // needless overflow.
1740                 r = acc.overflowing_mul(base);
1741                 r.1 |= overflown;
1742                 r
1743             }
1744         }
1745
1746         doc_comment! {
1747             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
1748
1749 # Examples
1750
1751 Basic usage:
1752
1753 ```
1754 ", $Feature, "let x: ", stringify!($SelfT), " = 2; // or any other integer type
1755
1756 assert_eq!(x.pow(5), 32);",
1757 $EndFeature, "
1758 ```"),
1759             #[stable(feature = "rust1", since = "1.0.0")]
1760             #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1761             #[must_use = "this returns the result of the operation, \
1762                           without modifying the original"]
1763             #[inline]
1764             #[rustc_inherit_overflow_checks]
1765             pub const fn pow(self, mut exp: u32) -> Self {
1766                 if exp == 0 {
1767                     return 1;
1768                 }
1769                 let mut base = self;
1770                 let mut acc = 1;
1771
1772                 while exp > 1 {
1773                     if (exp & 1) == 1 {
1774                         acc = acc * base;
1775                     }
1776                     exp /= 2;
1777                     base = base * base;
1778                 }
1779
1780                 // since exp!=0, finally the exp must be 1.
1781                 // Deal with the final bit of the exponent separately, since
1782                 // squaring the base afterwards is not necessary and may cause a
1783                 // needless overflow.
1784                 acc * base
1785             }
1786         }
1787
1788         doc_comment! {
1789             concat!("Calculates the quotient of Euclidean division of `self` by `rhs`.
1790
1791 This computes the integer `n` such that `self = n * rhs + self.rem_euclid(rhs)`,
1792 with `0 <= self.rem_euclid(rhs) < rhs`.
1793
1794 In other words, the result is `self / rhs` rounded to the integer `n`
1795 such that `self >= n * rhs`.
1796 If `self > 0`, this is equal to round towards zero (the default in Rust);
1797 if `self < 0`, this is equal to round towards +/- infinity.
1798
1799 # Panics
1800
1801 This function will panic if `rhs` is 0 or the division results in overflow.
1802
1803 # Examples
1804
1805 Basic usage:
1806
1807 ```
1808 let a: ", stringify!($SelfT), " = 7; // or any other integer type
1809 let b = 4;
1810
1811 assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
1812 assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
1813 assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
1814 assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
1815 ```"),
1816             #[stable(feature = "euclidean_division", since = "1.38.0")]
1817             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
1818             #[must_use = "this returns the result of the operation, \
1819                           without modifying the original"]
1820             #[inline]
1821             #[rustc_inherit_overflow_checks]
1822             pub const fn div_euclid(self, rhs: Self) -> Self {
1823                 let q = self / rhs;
1824                 if self % rhs < 0 {
1825                     return if rhs > 0 { q - 1 } else { q + 1 }
1826                 }
1827                 q
1828             }
1829         }
1830
1831
1832         doc_comment! {
1833             concat!("Calculates the least nonnegative remainder of `self (mod rhs)`.
1834
1835 This is done as if by the Euclidean division algorithm -- given
1836 `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and
1837 `0 <= r < abs(rhs)`.
1838
1839 # Panics
1840
1841 This function will panic if `rhs` is 0 or the division results in overflow.
1842
1843 # Examples
1844
1845 Basic usage:
1846
1847 ```
1848 let a: ", stringify!($SelfT), " = 7; // or any other integer type
1849 let b = 4;
1850
1851 assert_eq!(a.rem_euclid(b), 3);
1852 assert_eq!((-a).rem_euclid(b), 1);
1853 assert_eq!(a.rem_euclid(-b), 3);
1854 assert_eq!((-a).rem_euclid(-b), 1);
1855 ```"),
1856             #[stable(feature = "euclidean_division", since = "1.38.0")]
1857             #[rustc_const_unstable(feature = "const_euclidean_int_methods", issue = "53718")]
1858             #[must_use = "this returns the result of the operation, \
1859                           without modifying the original"]
1860             #[inline]
1861             #[rustc_inherit_overflow_checks]
1862             pub const fn rem_euclid(self, rhs: Self) -> Self {
1863                 let r = self % rhs;
1864                 if r < 0 {
1865                     if rhs < 0 {
1866                         r - rhs
1867                     } else {
1868                         r + rhs
1869                     }
1870                 } else {
1871                     r
1872                 }
1873             }
1874         }
1875
1876         doc_comment! {
1877             concat!("Computes the absolute value of `self`.
1878
1879 # Overflow behavior
1880
1881 The absolute value of `", stringify!($SelfT), "::MIN` cannot be represented as an
1882 `", stringify!($SelfT), "`, and attempting to calculate it will cause an overflow. This means that
1883 code in debug mode will trigger a panic on this case and optimized code will return `",
1884 stringify!($SelfT), "::MIN` without a panic.
1885
1886 # Examples
1887
1888 Basic usage:
1889
1890 ```
1891 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".abs(), 10);
1892 assert_eq!((-10", stringify!($SelfT), ").abs(), 10);",
1893 $EndFeature, "
1894 ```"),
1895             #[stable(feature = "rust1", since = "1.0.0")]
1896             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1897             #[allow(unused_attributes)]
1898             #[inline]
1899             #[rustc_inherit_overflow_checks]
1900             pub const fn abs(self) -> Self {
1901                 // Note that the #[inline] above means that the overflow
1902                 // semantics of the subtraction depend on the crate we're being
1903                 // inlined into.
1904                 if self.is_negative() {
1905                     -self
1906                 } else {
1907                     self
1908                 }
1909             }
1910         }
1911
1912         doc_comment! {
1913             concat!("Returns a number representing sign of `self`.
1914
1915  - `0` if the number is zero
1916  - `1` if the number is positive
1917  - `-1` if the number is negative
1918
1919 # Examples
1920
1921 Basic usage:
1922
1923 ```
1924 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".signum(), 1);
1925 assert_eq!(0", stringify!($SelfT), ".signum(), 0);
1926 assert_eq!((-10", stringify!($SelfT), ").signum(), -1);",
1927 $EndFeature, "
1928 ```"),
1929             #[stable(feature = "rust1", since = "1.0.0")]
1930             #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")]
1931             #[inline]
1932             pub const fn signum(self) -> Self {
1933                 match self {
1934                     n if n > 0 =>  1,
1935                     0          =>  0,
1936                     _          => -1,
1937                 }
1938             }
1939         }
1940
1941         doc_comment! {
1942             concat!("Returns `true` if `self` is positive and `false` if the number is zero or
1943 negative.
1944
1945 # Examples
1946
1947 Basic usage:
1948
1949 ```
1950 ", $Feature, "assert!(10", stringify!($SelfT), ".is_positive());
1951 assert!(!(-10", stringify!($SelfT), ").is_positive());",
1952 $EndFeature, "
1953 ```"),
1954             #[stable(feature = "rust1", since = "1.0.0")]
1955             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1956             #[inline]
1957             pub const fn is_positive(self) -> bool { self > 0 }
1958         }
1959
1960         doc_comment! {
1961             concat!("Returns `true` if `self` is negative and `false` if the number is zero or
1962 positive.
1963
1964 # Examples
1965
1966 Basic usage:
1967
1968 ```
1969 ", $Feature, "assert!((-10", stringify!($SelfT), ").is_negative());
1970 assert!(!10", stringify!($SelfT), ".is_negative());",
1971 $EndFeature, "
1972 ```"),
1973             #[stable(feature = "rust1", since = "1.0.0")]
1974             #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1975             #[inline]
1976             pub const fn is_negative(self) -> bool { self < 0 }
1977         }
1978
1979         doc_comment! {
1980             concat!("Return the memory representation of this integer as a byte array in
1981 big-endian (network) byte order.
1982 ",
1983 $to_xe_bytes_doc,
1984 "
1985 # Examples
1986
1987 ```
1988 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
1989 assert_eq!(bytes, ", $be_bytes, ");
1990 ```"),
1991             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
1992             #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
1993             #[inline]
1994             pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
1995                 self.to_be().to_ne_bytes()
1996             }
1997         }
1998
1999 doc_comment! {
2000             concat!("Return the memory representation of this integer as a byte array in
2001 little-endian byte order.
2002 ",
2003 $to_xe_bytes_doc,
2004 "
2005 # Examples
2006
2007 ```
2008 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
2009 assert_eq!(bytes, ", $le_bytes, ");
2010 ```"),
2011             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2012             #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2013             #[inline]
2014             pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2015                 self.to_le().to_ne_bytes()
2016             }
2017         }
2018
2019         doc_comment! {
2020             concat!("
2021 Return the memory representation of this integer as a byte array in
2022 native byte order.
2023
2024 As the target platform's native endianness is used, portable code
2025 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2026 instead.
2027 ",
2028 $to_xe_bytes_doc,
2029 "
2030 [`to_be_bytes`]: #method.to_be_bytes
2031 [`to_le_bytes`]: #method.to_le_bytes
2032
2033 # Examples
2034
2035 ```
2036 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
2037 assert_eq!(
2038     bytes,
2039     if cfg!(target_endian = \"big\") {
2040         ", $be_bytes, "
2041     } else {
2042         ", $le_bytes, "
2043     }
2044 );
2045 ```"),
2046             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2047             #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2048             // SAFETY: const sound because integers are plain old datatypes so we can always
2049             // transmute them to arrays of bytes
2050             #[rustc_allow_const_fn_unstable(const_fn_transmute)]
2051             #[inline]
2052             pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2053                 // SAFETY: integers are plain old datatypes so we can always transmute them to
2054                 // arrays of bytes
2055                 unsafe { mem::transmute(self) }
2056             }
2057         }
2058
2059         doc_comment! {
2060             concat!("
2061 Return the memory representation of this integer as a byte array in
2062 native byte order.
2063
2064 [`to_ne_bytes`] should be preferred over this whenever possible.
2065
2066 [`to_ne_bytes`]: #method.to_ne_bytes
2067 ",
2068
2069 "
2070 # Examples
2071
2072 ```
2073 #![feature(num_as_ne_bytes)]
2074 let num = ", $swap_op, stringify!($SelfT), ";
2075 let bytes = num.as_ne_bytes();
2076 assert_eq!(
2077     bytes,
2078     if cfg!(target_endian = \"big\") {
2079         &", $be_bytes, "
2080     } else {
2081         &", $le_bytes, "
2082     }
2083 );
2084 ```"),
2085             #[unstable(feature = "num_as_ne_bytes", issue = "76976")]
2086             #[inline]
2087             pub fn as_ne_bytes(&self) -> &[u8; mem::size_of::<Self>()] {
2088                 // SAFETY: integers are plain old datatypes so we can always transmute them to
2089                 // arrays of bytes
2090                 unsafe { &*(self as *const Self as *const _) }
2091             }
2092         }
2093
2094 doc_comment! {
2095             concat!("Create an integer value from its representation as a byte array in
2096 big endian.
2097 ",
2098 $from_xe_bytes_doc,
2099 "
2100 # Examples
2101
2102 ```
2103 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
2104 assert_eq!(value, ", $swap_op, ");
2105 ```
2106
2107 When starting from a slice rather than an array, fallible conversion APIs can be used:
2108
2109 ```
2110 use std::convert::TryInto;
2111
2112 fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2113     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2114     *input = rest;
2115     ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())
2116 }
2117 ```"),
2118             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2119             #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2120             #[inline]
2121             pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2122                 Self::from_be(Self::from_ne_bytes(bytes))
2123             }
2124         }
2125
2126 doc_comment! {
2127             concat!("
2128 Create an integer value from its representation as a byte array in
2129 little endian.
2130 ",
2131 $from_xe_bytes_doc,
2132 "
2133 # Examples
2134
2135 ```
2136 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
2137 assert_eq!(value, ", $swap_op, ");
2138 ```
2139
2140 When starting from a slice rather than an array, fallible conversion APIs can be used:
2141
2142 ```
2143 use std::convert::TryInto;
2144
2145 fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2146     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2147     *input = rest;
2148     ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())
2149 }
2150 ```"),
2151             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2152             #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2153             #[inline]
2154             pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2155                 Self::from_le(Self::from_ne_bytes(bytes))
2156             }
2157         }
2158
2159         doc_comment! {
2160             concat!("Create an integer value from its memory representation as a byte
2161 array in native endianness.
2162
2163 As the target platform's native endianness is used, portable code
2164 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2165 appropriate instead.
2166
2167 [`from_be_bytes`]: #method.from_be_bytes
2168 [`from_le_bytes`]: #method.from_le_bytes
2169 ",
2170 $from_xe_bytes_doc,
2171 "
2172 # Examples
2173
2174 ```
2175 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
2176     ", $be_bytes, "
2177 } else {
2178     ", $le_bytes, "
2179 });
2180 assert_eq!(value, ", $swap_op, ");
2181 ```
2182
2183 When starting from a slice rather than an array, fallible conversion APIs can be used:
2184
2185 ```
2186 use std::convert::TryInto;
2187
2188 fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2189     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2190     *input = rest;
2191     ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())
2192 }
2193 ```"),
2194             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2195             #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2196             // SAFETY: const sound because integers are plain old datatypes so we can always
2197             // transmute to them
2198             #[rustc_allow_const_fn_unstable(const_fn_transmute)]
2199             #[inline]
2200             pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2201                 // SAFETY: integers are plain old datatypes so we can always transmute to them
2202                 unsafe { mem::transmute(bytes) }
2203             }
2204         }
2205
2206         doc_comment! {
2207             concat!("**This method is soft-deprecated.**
2208
2209 Although using it won’t cause a compilation warning,
2210 new code should use [`", stringify!($SelfT), "::MIN", "`](#associatedconstant.MIN) instead.
2211
2212 Returns the smallest value that can be represented by this integer type."),
2213             #[stable(feature = "rust1", since = "1.0.0")]
2214             #[inline(always)]
2215             #[rustc_promotable]
2216             #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")]
2217             pub const fn min_value() -> Self {
2218                 Self::MIN
2219             }
2220         }
2221
2222         doc_comment! {
2223             concat!("**This method is soft-deprecated.**
2224
2225 Although using it won’t cause a compilation warning,
2226 new code should use [`", stringify!($SelfT), "::MAX", "`](#associatedconstant.MAX) instead.
2227
2228 Returns the largest value that can be represented by this integer type."),
2229             #[stable(feature = "rust1", since = "1.0.0")]
2230             #[inline(always)]
2231             #[rustc_promotable]
2232             #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2233             pub const fn max_value() -> Self {
2234                 Self::MAX
2235             }
2236         }
2237     }
2238 }