1 //! Definitions of `Wrapping<T>`.
4 use crate::ops::{Add, AddAssign, BitAnd, BitAndAssign, BitOr, BitOrAssign};
5 use crate::ops::{BitXor, BitXorAssign, Div, DivAssign};
6 use crate::ops::{Mul, MulAssign, Neg, Not, Rem, RemAssign};
7 use crate::ops::{Shl, ShlAssign, Shr, ShrAssign, Sub, SubAssign};
9 /// Provides intentionally-wrapped arithmetic on `T`.
11 /// Operations like `+` on `u32` values are intended to never overflow,
12 /// and in some debug configurations overflow is detected and results
13 /// in a panic. While most arithmetic falls into this category, some
14 /// code explicitly expects and relies upon modular arithmetic (e.g.,
17 /// Wrapping arithmetic can be achieved either through methods like
18 /// `wrapping_add`, or through the `Wrapping<T>` type, which says that
19 /// all standard arithmetic operations on the underlying value are
20 /// intended to have wrapping semantics.
22 /// The underlying value can be retrieved through the `.0` index of the
28 /// use std::num::Wrapping;
30 /// let zero = Wrapping(0u32);
31 /// let one = Wrapping(1u32);
33 /// assert_eq!(u32::MAX, (zero - one).0);
38 /// `Wrapping<T>` is guaranteed to have the same layout and ABI as `T`.
39 #[stable(feature = "rust1", since = "1.0.0")]
40 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)]
42 pub struct Wrapping<T>(#[stable(feature = "rust1", since = "1.0.0")] pub T);
44 #[stable(feature = "rust1", since = "1.0.0")]
45 impl<T: fmt::Debug> fmt::Debug for Wrapping<T> {
46 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51 #[stable(feature = "wrapping_display", since = "1.10.0")]
52 impl<T: fmt::Display> fmt::Display for Wrapping<T> {
53 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
58 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
59 impl<T: fmt::Binary> fmt::Binary for Wrapping<T> {
60 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
65 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
66 impl<T: fmt::Octal> fmt::Octal for Wrapping<T> {
67 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
72 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
73 impl<T: fmt::LowerHex> fmt::LowerHex for Wrapping<T> {
74 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
79 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
80 impl<T: fmt::UpperHex> fmt::UpperHex for Wrapping<T> {
81 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86 #[allow(unused_macros)]
87 macro_rules! sh_impl_signed {
88 ($t:ident, $f:ident) => {
89 #[stable(feature = "rust1", since = "1.0.0")]
90 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
91 impl const Shl<$f> for Wrapping<$t> {
92 type Output = Wrapping<$t>;
95 fn shl(self, other: $f) -> Wrapping<$t> {
97 Wrapping(self.0.wrapping_shr((-other & self::shift_max::$t as $f) as u32))
99 Wrapping(self.0.wrapping_shl((other & self::shift_max::$t as $f) as u32))
103 forward_ref_binop! { impl const Shl, shl for Wrapping<$t>, $f,
104 #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] }
106 #[stable(feature = "op_assign_traits", since = "1.8.0")]
107 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
108 impl const ShlAssign<$f> for Wrapping<$t> {
110 fn shl_assign(&mut self, other: $f) {
111 *self = *self << other;
114 forward_ref_op_assign! { impl const ShlAssign, shl_assign for Wrapping<$t>, $f }
116 #[stable(feature = "rust1", since = "1.0.0")]
117 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
118 impl const Shr<$f> for Wrapping<$t> {
119 type Output = Wrapping<$t>;
122 fn shr(self, other: $f) -> Wrapping<$t> {
124 Wrapping(self.0.wrapping_shl((-other & self::shift_max::$t as $f) as u32))
126 Wrapping(self.0.wrapping_shr((other & self::shift_max::$t as $f) as u32))
130 forward_ref_binop! { impl const Shr, shr for Wrapping<$t>, $f,
131 #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] }
133 #[stable(feature = "op_assign_traits", since = "1.8.0")]
134 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
135 impl const ShrAssign<$f> for Wrapping<$t> {
137 fn shr_assign(&mut self, other: $f) {
138 *self = *self >> other;
141 forward_ref_op_assign! { impl const ShrAssign, shr_assign for Wrapping<$t>, $f }
145 macro_rules! sh_impl_unsigned {
146 ($t:ident, $f:ident) => {
147 #[stable(feature = "rust1", since = "1.0.0")]
148 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
149 impl const Shl<$f> for Wrapping<$t> {
150 type Output = Wrapping<$t>;
153 fn shl(self, other: $f) -> Wrapping<$t> {
154 Wrapping(self.0.wrapping_shl((other & self::shift_max::$t as $f) as u32))
157 forward_ref_binop! { impl const Shl, shl for Wrapping<$t>, $f,
158 #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] }
160 #[stable(feature = "op_assign_traits", since = "1.8.0")]
161 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
162 impl const ShlAssign<$f> for Wrapping<$t> {
164 fn shl_assign(&mut self, other: $f) {
165 *self = *self << other;
168 forward_ref_op_assign! { impl const ShlAssign, shl_assign for Wrapping<$t>, $f }
170 #[stable(feature = "rust1", since = "1.0.0")]
171 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
172 impl const Shr<$f> for Wrapping<$t> {
173 type Output = Wrapping<$t>;
176 fn shr(self, other: $f) -> Wrapping<$t> {
177 Wrapping(self.0.wrapping_shr((other & self::shift_max::$t as $f) as u32))
180 forward_ref_binop! { impl const Shr, shr for Wrapping<$t>, $f,
181 #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] }
183 #[stable(feature = "op_assign_traits", since = "1.8.0")]
184 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
185 impl const ShrAssign<$f> for Wrapping<$t> {
187 fn shr_assign(&mut self, other: $f) {
188 *self = *self >> other;
191 forward_ref_op_assign! { impl const ShrAssign, shr_assign for Wrapping<$t>, $f }
195 // FIXME (#23545): uncomment the remaining impls
196 macro_rules! sh_impl_all {
197 ($($t:ident)*) => ($(
198 //sh_impl_unsigned! { $t, u8 }
199 //sh_impl_unsigned! { $t, u16 }
200 //sh_impl_unsigned! { $t, u32 }
201 //sh_impl_unsigned! { $t, u64 }
202 //sh_impl_unsigned! { $t, u128 }
203 sh_impl_unsigned! { $t, usize }
205 //sh_impl_signed! { $t, i8 }
206 //sh_impl_signed! { $t, i16 }
207 //sh_impl_signed! { $t, i32 }
208 //sh_impl_signed! { $t, i64 }
209 //sh_impl_signed! { $t, i128 }
210 //sh_impl_signed! { $t, isize }
214 sh_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize }
216 // FIXME(30524): impl Op<T> for Wrapping<T>, impl OpAssign<T> for Wrapping<T>
217 macro_rules! wrapping_impl {
219 #[stable(feature = "rust1", since = "1.0.0")]
220 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
221 impl const Add for Wrapping<$t> {
222 type Output = Wrapping<$t>;
225 fn add(self, other: Wrapping<$t>) -> Wrapping<$t> {
226 Wrapping(self.0.wrapping_add(other.0))
229 forward_ref_binop! { impl const Add, add for Wrapping<$t>, Wrapping<$t>,
230 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
232 #[stable(feature = "op_assign_traits", since = "1.8.0")]
233 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
234 impl const AddAssign for Wrapping<$t> {
236 fn add_assign(&mut self, other: Wrapping<$t>) {
237 *self = *self + other;
240 forward_ref_op_assign! { impl const AddAssign, add_assign for Wrapping<$t>, Wrapping<$t> }
242 #[stable(feature = "rust1", since = "1.0.0")]
243 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
244 impl const Sub for Wrapping<$t> {
245 type Output = Wrapping<$t>;
248 fn sub(self, other: Wrapping<$t>) -> Wrapping<$t> {
249 Wrapping(self.0.wrapping_sub(other.0))
252 forward_ref_binop! { impl const Sub, sub for Wrapping<$t>, Wrapping<$t>,
253 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
255 #[stable(feature = "op_assign_traits", since = "1.8.0")]
256 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
257 impl const SubAssign for Wrapping<$t> {
259 fn sub_assign(&mut self, other: Wrapping<$t>) {
260 *self = *self - other;
263 forward_ref_op_assign! { impl const SubAssign, sub_assign for Wrapping<$t>, Wrapping<$t> }
265 #[stable(feature = "rust1", since = "1.0.0")]
266 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
267 impl const Mul for Wrapping<$t> {
268 type Output = Wrapping<$t>;
271 fn mul(self, other: Wrapping<$t>) -> Wrapping<$t> {
272 Wrapping(self.0.wrapping_mul(other.0))
275 forward_ref_binop! { impl Mul, mul for Wrapping<$t>, Wrapping<$t>,
276 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
278 #[stable(feature = "op_assign_traits", since = "1.8.0")]
279 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
280 impl const MulAssign for Wrapping<$t> {
282 fn mul_assign(&mut self, other: Wrapping<$t>) {
283 *self = *self * other;
286 forward_ref_op_assign! { impl const MulAssign, mul_assign for Wrapping<$t>, Wrapping<$t> }
288 #[stable(feature = "wrapping_div", since = "1.3.0")]
289 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
290 impl const Div for Wrapping<$t> {
291 type Output = Wrapping<$t>;
294 fn div(self, other: Wrapping<$t>) -> Wrapping<$t> {
295 Wrapping(self.0.wrapping_div(other.0))
298 forward_ref_binop! { impl const Div, div for Wrapping<$t>, Wrapping<$t>,
299 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
301 #[stable(feature = "op_assign_traits", since = "1.8.0")]
302 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
303 impl const DivAssign for Wrapping<$t> {
305 fn div_assign(&mut self, other: Wrapping<$t>) {
306 *self = *self / other;
309 forward_ref_op_assign! { impl const DivAssign, div_assign for Wrapping<$t>, Wrapping<$t> }
311 #[stable(feature = "wrapping_impls", since = "1.7.0")]
312 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
313 impl const Rem for Wrapping<$t> {
314 type Output = Wrapping<$t>;
317 fn rem(self, other: Wrapping<$t>) -> Wrapping<$t> {
318 Wrapping(self.0.wrapping_rem(other.0))
321 forward_ref_binop! { impl const Rem, rem for Wrapping<$t>, Wrapping<$t>,
322 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
324 #[stable(feature = "op_assign_traits", since = "1.8.0")]
325 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
326 impl const RemAssign for Wrapping<$t> {
328 fn rem_assign(&mut self, other: Wrapping<$t>) {
329 *self = *self % other;
332 forward_ref_op_assign! { impl const RemAssign, rem_assign for Wrapping<$t>, Wrapping<$t> }
334 #[stable(feature = "rust1", since = "1.0.0")]
335 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
336 impl const Not for Wrapping<$t> {
337 type Output = Wrapping<$t>;
340 fn not(self) -> Wrapping<$t> {
344 forward_ref_unop! { impl const Not, not for Wrapping<$t>,
345 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
347 #[stable(feature = "rust1", since = "1.0.0")]
348 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
349 impl const BitXor for Wrapping<$t> {
350 type Output = Wrapping<$t>;
353 fn bitxor(self, other: Wrapping<$t>) -> Wrapping<$t> {
354 Wrapping(self.0 ^ other.0)
357 forward_ref_binop! { impl const BitXor, bitxor for Wrapping<$t>, Wrapping<$t>,
358 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
360 #[stable(feature = "op_assign_traits", since = "1.8.0")]
361 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
362 impl const BitXorAssign for Wrapping<$t> {
364 fn bitxor_assign(&mut self, other: Wrapping<$t>) {
365 *self = *self ^ other;
368 forward_ref_op_assign! { impl const BitXorAssign, bitxor_assign for Wrapping<$t>, Wrapping<$t> }
370 #[stable(feature = "rust1", since = "1.0.0")]
371 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
372 impl const BitOr for Wrapping<$t> {
373 type Output = Wrapping<$t>;
376 fn bitor(self, other: Wrapping<$t>) -> Wrapping<$t> {
377 Wrapping(self.0 | other.0)
380 forward_ref_binop! { impl const BitOr, bitor for Wrapping<$t>, Wrapping<$t>,
381 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
383 #[stable(feature = "op_assign_traits", since = "1.8.0")]
384 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
385 impl const BitOrAssign for Wrapping<$t> {
387 fn bitor_assign(&mut self, other: Wrapping<$t>) {
388 *self = *self | other;
391 forward_ref_op_assign! { impl const BitOrAssign, bitor_assign for Wrapping<$t>, Wrapping<$t> }
393 #[stable(feature = "rust1", since = "1.0.0")]
394 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
395 impl const BitAnd for Wrapping<$t> {
396 type Output = Wrapping<$t>;
399 fn bitand(self, other: Wrapping<$t>) -> Wrapping<$t> {
400 Wrapping(self.0 & other.0)
403 forward_ref_binop! { impl const BitAnd, bitand for Wrapping<$t>, Wrapping<$t>,
404 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
406 #[stable(feature = "op_assign_traits", since = "1.8.0")]
407 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
408 impl const BitAndAssign for Wrapping<$t> {
410 fn bitand_assign(&mut self, other: Wrapping<$t>) {
411 *self = *self & other;
414 forward_ref_op_assign! { impl const BitAndAssign, bitand_assign for Wrapping<$t>, Wrapping<$t> }
416 #[stable(feature = "wrapping_neg", since = "1.10.0")]
417 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
418 impl const Neg for Wrapping<$t> {
421 fn neg(self) -> Self {
425 forward_ref_unop! { impl const Neg, neg for Wrapping<$t>,
426 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
431 wrapping_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
433 macro_rules! wrapping_int_impl {
436 /// Returns the smallest value that can be represented by this integer type.
443 /// #![feature(wrapping_int_impl)]
444 /// use std::num::Wrapping;
446 #[doc = concat!("assert_eq!(<Wrapping<", stringify!($t), ">>::MIN, Wrapping(", stringify!($t), "::MIN));")]
448 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
449 pub const MIN: Self = Self(<$t>::MIN);
451 /// Returns the largest value that can be represented by this integer type.
458 /// #![feature(wrapping_int_impl)]
459 /// use std::num::Wrapping;
461 #[doc = concat!("assert_eq!(<Wrapping<", stringify!($t), ">>::MAX, Wrapping(", stringify!($t), "::MAX));")]
463 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
464 pub const MAX: Self = Self(<$t>::MAX);
466 /// Returns the size of this integer type in bits.
473 /// #![feature(wrapping_int_impl)]
474 /// use std::num::Wrapping;
476 #[doc = concat!("assert_eq!(<Wrapping<", stringify!($t), ">>::BITS, ", stringify!($t), "::BITS);")]
478 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
479 pub const BITS: u32 = <$t>::BITS;
481 /// Returns the number of ones in the binary representation of `self`.
488 /// #![feature(wrapping_int_impl)]
489 /// use std::num::Wrapping;
491 #[doc = concat!("let n = Wrapping(0b01001100", stringify!($t), ");")]
493 /// assert_eq!(n.count_ones(), 3);
496 #[doc(alias = "popcount")]
497 #[doc(alias = "popcnt")]
498 #[must_use = "this returns the result of the operation, \
499 without modifying the original"]
500 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
501 pub const fn count_ones(self) -> u32 {
505 /// Returns the number of zeros in the binary representation of `self`.
512 /// #![feature(wrapping_int_impl)]
513 /// use std::num::Wrapping;
515 #[doc = concat!("assert_eq!(Wrapping(!0", stringify!($t), ").count_zeros(), 0);")]
518 #[must_use = "this returns the result of the operation, \
519 without modifying the original"]
520 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
521 pub const fn count_zeros(self) -> u32 {
525 /// Returns the number of trailing zeros in the binary representation of `self`.
532 /// #![feature(wrapping_int_impl)]
533 /// use std::num::Wrapping;
535 #[doc = concat!("let n = Wrapping(0b0101000", stringify!($t), ");")]
537 /// assert_eq!(n.trailing_zeros(), 3);
540 #[must_use = "this returns the result of the operation, \
541 without modifying the original"]
542 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
543 pub const fn trailing_zeros(self) -> u32 {
544 self.0.trailing_zeros()
547 /// Shifts the bits to the left by a specified amount, `n`,
548 /// wrapping the truncated bits to the end of the resulting
551 /// Please note this isn't the same operation as the `<<` shifting
559 /// #![feature(wrapping_int_impl)]
560 /// use std::num::Wrapping;
562 /// let n: Wrapping<i64> = Wrapping(0x0123456789ABCDEF);
563 /// let m: Wrapping<i64> = Wrapping(-0x76543210FEDCBA99);
565 /// assert_eq!(n.rotate_left(32), m);
568 #[must_use = "this returns the result of the operation, \
569 without modifying the original"]
570 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
571 pub const fn rotate_left(self, n: u32) -> Self {
572 Wrapping(self.0.rotate_left(n))
575 /// Shifts the bits to the right by a specified amount, `n`,
576 /// wrapping the truncated bits to the beginning of the resulting
579 /// Please note this isn't the same operation as the `>>` shifting
587 /// #![feature(wrapping_int_impl)]
588 /// use std::num::Wrapping;
590 /// let n: Wrapping<i64> = Wrapping(0x0123456789ABCDEF);
591 /// let m: Wrapping<i64> = Wrapping(-0xFEDCBA987654322);
593 /// assert_eq!(n.rotate_right(4), m);
596 #[must_use = "this returns the result of the operation, \
597 without modifying the original"]
598 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
599 pub const fn rotate_right(self, n: u32) -> Self {
600 Wrapping(self.0.rotate_right(n))
603 /// Reverses the byte order of the integer.
610 /// #![feature(wrapping_int_impl)]
611 /// use std::num::Wrapping;
613 /// let n: Wrapping<i16> = Wrapping(0b0000000_01010101);
614 /// assert_eq!(n, Wrapping(85));
616 /// let m = n.swap_bytes();
618 /// assert_eq!(m, Wrapping(0b01010101_00000000));
619 /// assert_eq!(m, Wrapping(21760));
622 #[must_use = "this returns the result of the operation, \
623 without modifying the original"]
624 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
625 pub const fn swap_bytes(self) -> Self {
626 Wrapping(self.0.swap_bytes())
629 /// Reverses the bit pattern of the integer.
633 /// Please note that this example is shared between integer types.
634 /// Which explains why `i16` is used here.
639 /// use std::num::Wrapping;
641 /// let n = Wrapping(0b0000000_01010101i16);
642 /// assert_eq!(n, Wrapping(85));
644 /// let m = n.reverse_bits();
646 /// assert_eq!(m.0 as u16, 0b10101010_00000000);
647 /// assert_eq!(m, Wrapping(-22016));
649 #[stable(feature = "reverse_bits", since = "1.37.0")]
650 #[rustc_const_stable(feature = "const_reverse_bits", since = "1.37.0")]
651 #[must_use = "this returns the result of the operation, \
652 without modifying the original"]
654 pub const fn reverse_bits(self) -> Self {
655 Wrapping(self.0.reverse_bits())
658 /// Converts an integer from big endian to the target's endianness.
660 /// On big endian this is a no-op. On little endian the bytes are
668 /// #![feature(wrapping_int_impl)]
669 /// use std::num::Wrapping;
671 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
673 /// if cfg!(target_endian = "big") {
674 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_be(n), n)")]
676 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_be(n), n.swap_bytes())")]
681 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
682 pub const fn from_be(x: Self) -> Self {
683 Wrapping(<$t>::from_be(x.0))
686 /// Converts an integer from little endian to the target's endianness.
688 /// On little endian this is a no-op. On big endian the bytes are
696 /// #![feature(wrapping_int_impl)]
697 /// use std::num::Wrapping;
699 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
701 /// if cfg!(target_endian = "little") {
702 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_le(n), n)")]
704 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_le(n), n.swap_bytes())")]
709 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
710 pub const fn from_le(x: Self) -> Self {
711 Wrapping(<$t>::from_le(x.0))
714 /// Converts `self` to big endian from the target's endianness.
716 /// On big endian this is a no-op. On little endian the bytes are
724 /// #![feature(wrapping_int_impl)]
725 /// use std::num::Wrapping;
727 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
729 /// if cfg!(target_endian = "big") {
730 /// assert_eq!(n.to_be(), n)
732 /// assert_eq!(n.to_be(), n.swap_bytes())
736 #[must_use = "this returns the result of the operation, \
737 without modifying the original"]
738 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
739 pub const fn to_be(self) -> Self {
740 Wrapping(self.0.to_be())
743 /// Converts `self` to little endian from the target's endianness.
745 /// On little endian this is a no-op. On big endian the bytes are
753 /// #![feature(wrapping_int_impl)]
754 /// use std::num::Wrapping;
756 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
758 /// if cfg!(target_endian = "little") {
759 /// assert_eq!(n.to_le(), n)
761 /// assert_eq!(n.to_le(), n.swap_bytes())
765 #[must_use = "this returns the result of the operation, \
766 without modifying the original"]
767 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
768 pub const fn to_le(self) -> Self {
769 Wrapping(self.0.to_le())
772 /// Raises self to the power of `exp`, using exponentiation by squaring.
779 /// #![feature(wrapping_int_impl)]
780 /// use std::num::Wrapping;
782 #[doc = concat!("assert_eq!(Wrapping(3", stringify!($t), ").pow(4), Wrapping(81));")]
785 /// Results that are too large are wrapped:
788 /// #![feature(wrapping_int_impl)]
789 /// use std::num::Wrapping;
791 /// assert_eq!(Wrapping(3i8).pow(5), Wrapping(-13));
792 /// assert_eq!(Wrapping(3i8).pow(6), Wrapping(-39));
795 #[must_use = "this returns the result of the operation, \
796 without modifying the original"]
797 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
798 pub fn pow(self, exp: u32) -> Self {
799 Wrapping(self.0.wrapping_pow(exp))
805 wrapping_int_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
807 macro_rules! wrapping_int_impl_signed {
810 /// Returns the number of leading zeros in the binary representation of `self`.
817 /// #![feature(wrapping_int_impl)]
818 /// use std::num::Wrapping;
820 #[doc = concat!("let n = Wrapping(", stringify!($t), "::MAX) >> 2;")]
822 /// assert_eq!(n.leading_zeros(), 3);
825 #[must_use = "this returns the result of the operation, \
826 without modifying the original"]
827 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
828 pub const fn leading_zeros(self) -> u32 {
829 self.0.leading_zeros()
832 /// Computes the absolute value of `self`, wrapping around at
833 /// the boundary of the type.
835 /// The only case where such wrapping can occur is when one takes the absolute value of the negative
836 /// minimal value for the type this is a positive value that is too large to represent in the type. In
837 /// such a case, this function returns `MIN` itself.
844 /// #![feature(wrapping_int_impl)]
845 /// use std::num::Wrapping;
847 #[doc = concat!("assert_eq!(Wrapping(100", stringify!($t), ").abs(), Wrapping(100));")]
848 #[doc = concat!("assert_eq!(Wrapping(-100", stringify!($t), ").abs(), Wrapping(100));")]
849 #[doc = concat!("assert_eq!(Wrapping(", stringify!($t), "::MIN).abs(), Wrapping(", stringify!($t), "::MIN));")]
850 /// assert_eq!(Wrapping(-128i8).abs().0 as u8, 128u8);
853 #[must_use = "this returns the result of the operation, \
854 without modifying the original"]
855 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
856 pub fn abs(self) -> Wrapping<$t> {
857 Wrapping(self.0.wrapping_abs())
860 /// Returns a number representing sign of `self`.
862 /// - `0` if the number is zero
863 /// - `1` if the number is positive
864 /// - `-1` if the number is negative
871 /// #![feature(wrapping_int_impl)]
872 /// use std::num::Wrapping;
874 #[doc = concat!("assert_eq!(Wrapping(10", stringify!($t), ").signum(), Wrapping(1));")]
875 #[doc = concat!("assert_eq!(Wrapping(0", stringify!($t), ").signum(), Wrapping(0));")]
876 #[doc = concat!("assert_eq!(Wrapping(-10", stringify!($t), ").signum(), Wrapping(-1));")]
879 #[must_use = "this returns the result of the operation, \
880 without modifying the original"]
881 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
882 pub fn signum(self) -> Wrapping<$t> {
883 Wrapping(self.0.signum())
886 /// Returns `true` if `self` is positive and `false` if the number is zero or
894 /// #![feature(wrapping_int_impl)]
895 /// use std::num::Wrapping;
897 #[doc = concat!("assert!(Wrapping(10", stringify!($t), ").is_positive());")]
898 #[doc = concat!("assert!(!Wrapping(-10", stringify!($t), ").is_positive());")]
902 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
903 pub const fn is_positive(self) -> bool {
907 /// Returns `true` if `self` is negative and `false` if the number is zero or
915 /// #![feature(wrapping_int_impl)]
916 /// use std::num::Wrapping;
918 #[doc = concat!("assert!(Wrapping(-10", stringify!($t), ").is_negative());")]
919 #[doc = concat!("assert!(!Wrapping(10", stringify!($t), ").is_negative());")]
923 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
924 pub const fn is_negative(self) -> bool {
931 wrapping_int_impl_signed! { isize i8 i16 i32 i64 i128 }
933 macro_rules! wrapping_int_impl_unsigned {
936 /// Returns the number of leading zeros in the binary representation of `self`.
943 /// #![feature(wrapping_int_impl)]
944 /// use std::num::Wrapping;
946 #[doc = concat!("let n = Wrapping(", stringify!($t), "::MAX) >> 2;")]
948 /// assert_eq!(n.leading_zeros(), 2);
951 #[must_use = "this returns the result of the operation, \
952 without modifying the original"]
953 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
954 pub const fn leading_zeros(self) -> u32 {
955 self.0.leading_zeros()
958 /// Returns `true` if and only if `self == 2^k` for some `k`.
965 /// #![feature(wrapping_int_impl)]
966 /// use std::num::Wrapping;
968 #[doc = concat!("assert!(Wrapping(16", stringify!($t), ").is_power_of_two());")]
969 #[doc = concat!("assert!(!Wrapping(10", stringify!($t), ").is_power_of_two());")]
973 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
974 pub fn is_power_of_two(self) -> bool {
975 self.0.is_power_of_two()
978 /// Returns the smallest power of two greater than or equal to `self`.
980 /// When return value overflows (i.e., `self > (1 << (N-1))` for type
981 /// `uN`), overflows to `2^N = 0`.
988 /// #![feature(wrapping_next_power_of_two)]
989 /// use std::num::Wrapping;
991 #[doc = concat!("assert_eq!(Wrapping(2", stringify!($t), ").next_power_of_two(), Wrapping(2));")]
992 #[doc = concat!("assert_eq!(Wrapping(3", stringify!($t), ").next_power_of_two(), Wrapping(4));")]
993 #[doc = concat!("assert_eq!(Wrapping(200_u8).next_power_of_two(), Wrapping(0));")]
996 #[must_use = "this returns the result of the operation, \
997 without modifying the original"]
998 #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
999 reason = "needs decision on wrapping behaviour")]
1000 pub fn next_power_of_two(self) -> Self {
1001 Wrapping(self.0.wrapping_next_power_of_two())
1007 wrapping_int_impl_unsigned! { usize u8 u16 u32 u64 u128 }
1010 #![allow(non_upper_case_globals)]
1012 #[cfg(target_pointer_width = "16")]
1014 pub const usize: u32 = super::u16;
1015 pub const isize: u32 = super::i16;
1018 #[cfg(target_pointer_width = "32")]
1020 pub const usize: u32 = super::u32;
1021 pub const isize: u32 = super::i32;
1024 #[cfg(target_pointer_width = "64")]
1026 pub const usize: u32 = super::u64;
1027 pub const isize: u32 = super::i64;
1030 pub const i8: u32 = (1 << 3) - 1;
1031 pub const i16: u32 = (1 << 4) - 1;
1032 pub const i32: u32 = (1 << 5) - 1;
1033 pub const i64: u32 = (1 << 6) - 1;
1034 pub const i128: u32 = (1 << 7) - 1;
1035 pub use self::platform::isize;
1037 pub const u8: u32 = i8;
1038 pub const u16: u32 = i16;
1039 pub const u32: u32 = i32;
1040 pub const u64: u32 = i64;
1041 pub const u128: u32 = i128;
1042 pub use self::platform::usize;