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 = "wrapping_int_assign_impl", since = "1.60.0")]
243 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
244 impl const AddAssign<$t> for Wrapping<$t> {
246 fn add_assign(&mut self, other: $t) {
247 *self = *self + Wrapping(other);
250 forward_ref_op_assign! { impl const AddAssign, add_assign for Wrapping<$t>, $t }
252 #[stable(feature = "rust1", since = "1.0.0")]
253 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
254 impl const Sub for Wrapping<$t> {
255 type Output = Wrapping<$t>;
258 fn sub(self, other: Wrapping<$t>) -> Wrapping<$t> {
259 Wrapping(self.0.wrapping_sub(other.0))
262 forward_ref_binop! { impl const Sub, sub for Wrapping<$t>, Wrapping<$t>,
263 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
265 #[stable(feature = "op_assign_traits", since = "1.8.0")]
266 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
267 impl const SubAssign for Wrapping<$t> {
269 fn sub_assign(&mut self, other: Wrapping<$t>) {
270 *self = *self - other;
273 forward_ref_op_assign! { impl const SubAssign, sub_assign for Wrapping<$t>, Wrapping<$t> }
275 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
276 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
277 impl const SubAssign<$t> for Wrapping<$t> {
279 fn sub_assign(&mut self, other: $t) {
280 *self = *self - Wrapping(other);
283 forward_ref_op_assign! { impl const SubAssign, sub_assign for Wrapping<$t>, $t }
285 #[stable(feature = "rust1", since = "1.0.0")]
286 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
287 impl const Mul for Wrapping<$t> {
288 type Output = Wrapping<$t>;
291 fn mul(self, other: Wrapping<$t>) -> Wrapping<$t> {
292 Wrapping(self.0.wrapping_mul(other.0))
295 forward_ref_binop! { impl Mul, mul for Wrapping<$t>, Wrapping<$t>,
296 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
298 #[stable(feature = "op_assign_traits", since = "1.8.0")]
299 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
300 impl const MulAssign for Wrapping<$t> {
302 fn mul_assign(&mut self, other: Wrapping<$t>) {
303 *self = *self * other;
306 forward_ref_op_assign! { impl const MulAssign, mul_assign for Wrapping<$t>, Wrapping<$t> }
308 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
309 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
310 impl const MulAssign<$t> for Wrapping<$t> {
312 fn mul_assign(&mut self, other: $t) {
313 *self = *self * Wrapping(other);
316 forward_ref_op_assign! { impl const MulAssign, mul_assign for Wrapping<$t>, $t }
318 #[stable(feature = "wrapping_div", since = "1.3.0")]
319 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
320 impl const Div for Wrapping<$t> {
321 type Output = Wrapping<$t>;
324 fn div(self, other: Wrapping<$t>) -> Wrapping<$t> {
325 Wrapping(self.0.wrapping_div(other.0))
328 forward_ref_binop! { impl const Div, div for Wrapping<$t>, Wrapping<$t>,
329 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
331 #[stable(feature = "op_assign_traits", since = "1.8.0")]
332 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
333 impl const DivAssign for Wrapping<$t> {
335 fn div_assign(&mut self, other: Wrapping<$t>) {
336 *self = *self / other;
339 forward_ref_op_assign! { impl const DivAssign, div_assign for Wrapping<$t>, Wrapping<$t> }
341 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
342 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
343 impl const DivAssign<$t> for Wrapping<$t> {
345 fn div_assign(&mut self, other: $t) {
346 *self = *self / Wrapping(other);
349 forward_ref_op_assign! { impl const DivAssign, div_assign for Wrapping<$t>, $t }
351 #[stable(feature = "wrapping_impls", since = "1.7.0")]
352 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
353 impl const Rem for Wrapping<$t> {
354 type Output = Wrapping<$t>;
357 fn rem(self, other: Wrapping<$t>) -> Wrapping<$t> {
358 Wrapping(self.0.wrapping_rem(other.0))
361 forward_ref_binop! { impl const Rem, rem for Wrapping<$t>, Wrapping<$t>,
362 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
364 #[stable(feature = "op_assign_traits", since = "1.8.0")]
365 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
366 impl const RemAssign for Wrapping<$t> {
368 fn rem_assign(&mut self, other: Wrapping<$t>) {
369 *self = *self % other;
372 forward_ref_op_assign! { impl const RemAssign, rem_assign for Wrapping<$t>, Wrapping<$t> }
374 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
375 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
376 impl const RemAssign<$t> for Wrapping<$t> {
378 fn rem_assign(&mut self, other: $t) {
379 *self = *self % Wrapping(other);
382 forward_ref_op_assign! { impl const RemAssign, rem_assign for Wrapping<$t>, $t }
384 #[stable(feature = "rust1", since = "1.0.0")]
385 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
386 impl const Not for Wrapping<$t> {
387 type Output = Wrapping<$t>;
390 fn not(self) -> Wrapping<$t> {
394 forward_ref_unop! { impl const Not, not for Wrapping<$t>,
395 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
397 #[stable(feature = "rust1", since = "1.0.0")]
398 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
399 impl const BitXor for Wrapping<$t> {
400 type Output = Wrapping<$t>;
403 fn bitxor(self, other: Wrapping<$t>) -> Wrapping<$t> {
404 Wrapping(self.0 ^ other.0)
407 forward_ref_binop! { impl const BitXor, bitxor for Wrapping<$t>, Wrapping<$t>,
408 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
410 #[stable(feature = "op_assign_traits", since = "1.8.0")]
411 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
412 impl const BitXorAssign for Wrapping<$t> {
414 fn bitxor_assign(&mut self, other: Wrapping<$t>) {
415 *self = *self ^ other;
418 forward_ref_op_assign! { impl const BitXorAssign, bitxor_assign for Wrapping<$t>, Wrapping<$t> }
420 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
421 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
422 impl const BitXorAssign<$t> for Wrapping<$t> {
424 fn bitxor_assign(&mut self, other: $t) {
425 *self = *self ^ Wrapping(other);
428 forward_ref_op_assign! { impl const BitXorAssign, bitxor_assign for Wrapping<$t>, $t }
430 #[stable(feature = "rust1", since = "1.0.0")]
431 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
432 impl const BitOr for Wrapping<$t> {
433 type Output = Wrapping<$t>;
436 fn bitor(self, other: Wrapping<$t>) -> Wrapping<$t> {
437 Wrapping(self.0 | other.0)
440 forward_ref_binop! { impl const BitOr, bitor for Wrapping<$t>, Wrapping<$t>,
441 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
443 #[stable(feature = "op_assign_traits", since = "1.8.0")]
444 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
445 impl const BitOrAssign for Wrapping<$t> {
447 fn bitor_assign(&mut self, other: Wrapping<$t>) {
448 *self = *self | other;
451 forward_ref_op_assign! { impl const BitOrAssign, bitor_assign for Wrapping<$t>, Wrapping<$t> }
453 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
454 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
455 impl const BitOrAssign<$t> for Wrapping<$t> {
457 fn bitor_assign(&mut self, other: $t) {
458 *self = *self | Wrapping(other);
461 forward_ref_op_assign! { impl const BitOrAssign, bitor_assign for Wrapping<$t>, $t }
463 #[stable(feature = "rust1", since = "1.0.0")]
464 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
465 impl const BitAnd for Wrapping<$t> {
466 type Output = Wrapping<$t>;
469 fn bitand(self, other: Wrapping<$t>) -> Wrapping<$t> {
470 Wrapping(self.0 & other.0)
473 forward_ref_binop! { impl const BitAnd, bitand for Wrapping<$t>, Wrapping<$t>,
474 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
476 #[stable(feature = "op_assign_traits", since = "1.8.0")]
477 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
478 impl const BitAndAssign for Wrapping<$t> {
480 fn bitand_assign(&mut self, other: Wrapping<$t>) {
481 *self = *self & other;
484 forward_ref_op_assign! { impl const BitAndAssign, bitand_assign for Wrapping<$t>, Wrapping<$t> }
486 #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")]
487 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
488 impl const BitAndAssign<$t> for Wrapping<$t> {
490 fn bitand_assign(&mut self, other: $t) {
491 *self = *self & Wrapping(other);
494 forward_ref_op_assign! { impl const BitAndAssign, bitand_assign for Wrapping<$t>, $t }
496 #[stable(feature = "wrapping_neg", since = "1.10.0")]
497 #[rustc_const_unstable(feature = "const_ops", issue = "90080")]
498 impl const Neg for Wrapping<$t> {
501 fn neg(self) -> Self {
505 forward_ref_unop! { impl const Neg, neg for Wrapping<$t>,
506 #[stable(feature = "wrapping_ref", since = "1.14.0")] }
511 wrapping_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
513 macro_rules! wrapping_int_impl {
516 /// Returns the smallest value that can be represented by this integer type.
523 /// #![feature(wrapping_int_impl)]
524 /// use std::num::Wrapping;
526 #[doc = concat!("assert_eq!(<Wrapping<", stringify!($t), ">>::MIN, Wrapping(", stringify!($t), "::MIN));")]
528 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
529 pub const MIN: Self = Self(<$t>::MIN);
531 /// Returns the largest value that can be represented by this integer type.
538 /// #![feature(wrapping_int_impl)]
539 /// use std::num::Wrapping;
541 #[doc = concat!("assert_eq!(<Wrapping<", stringify!($t), ">>::MAX, Wrapping(", stringify!($t), "::MAX));")]
543 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
544 pub const MAX: Self = Self(<$t>::MAX);
546 /// Returns the size of this integer type in bits.
553 /// #![feature(wrapping_int_impl)]
554 /// use std::num::Wrapping;
556 #[doc = concat!("assert_eq!(<Wrapping<", stringify!($t), ">>::BITS, ", stringify!($t), "::BITS);")]
558 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
559 pub const BITS: u32 = <$t>::BITS;
561 /// Returns the number of ones in the binary representation of `self`.
568 /// #![feature(wrapping_int_impl)]
569 /// use std::num::Wrapping;
571 #[doc = concat!("let n = Wrapping(0b01001100", stringify!($t), ");")]
573 /// assert_eq!(n.count_ones(), 3);
576 #[doc(alias = "popcount")]
577 #[doc(alias = "popcnt")]
578 #[must_use = "this returns the result of the operation, \
579 without modifying the original"]
580 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
581 pub const fn count_ones(self) -> u32 {
585 /// Returns the number of zeros in the binary representation of `self`.
592 /// #![feature(wrapping_int_impl)]
593 /// use std::num::Wrapping;
595 #[doc = concat!("assert_eq!(Wrapping(!0", stringify!($t), ").count_zeros(), 0);")]
598 #[must_use = "this returns the result of the operation, \
599 without modifying the original"]
600 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
601 pub const fn count_zeros(self) -> u32 {
605 /// Returns the number of trailing zeros in the binary representation of `self`.
612 /// #![feature(wrapping_int_impl)]
613 /// use std::num::Wrapping;
615 #[doc = concat!("let n = Wrapping(0b0101000", stringify!($t), ");")]
617 /// assert_eq!(n.trailing_zeros(), 3);
620 #[must_use = "this returns the result of the operation, \
621 without modifying the original"]
622 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
623 pub const fn trailing_zeros(self) -> u32 {
624 self.0.trailing_zeros()
627 /// Shifts the bits to the left by a specified amount, `n`,
628 /// wrapping the truncated bits to the end of the resulting
631 /// Please note this isn't the same operation as the `<<` shifting
639 /// #![feature(wrapping_int_impl)]
640 /// use std::num::Wrapping;
642 /// let n: Wrapping<i64> = Wrapping(0x0123456789ABCDEF);
643 /// let m: Wrapping<i64> = Wrapping(-0x76543210FEDCBA99);
645 /// assert_eq!(n.rotate_left(32), m);
648 #[must_use = "this returns the result of the operation, \
649 without modifying the original"]
650 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
651 pub const fn rotate_left(self, n: u32) -> Self {
652 Wrapping(self.0.rotate_left(n))
655 /// Shifts the bits to the right by a specified amount, `n`,
656 /// wrapping the truncated bits to the beginning of the resulting
659 /// Please note this isn't the same operation as the `>>` shifting
667 /// #![feature(wrapping_int_impl)]
668 /// use std::num::Wrapping;
670 /// let n: Wrapping<i64> = Wrapping(0x0123456789ABCDEF);
671 /// let m: Wrapping<i64> = Wrapping(-0xFEDCBA987654322);
673 /// assert_eq!(n.rotate_right(4), m);
676 #[must_use = "this returns the result of the operation, \
677 without modifying the original"]
678 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
679 pub const fn rotate_right(self, n: u32) -> Self {
680 Wrapping(self.0.rotate_right(n))
683 /// Reverses the byte order of the integer.
690 /// #![feature(wrapping_int_impl)]
691 /// use std::num::Wrapping;
693 /// let n: Wrapping<i16> = Wrapping(0b0000000_01010101);
694 /// assert_eq!(n, Wrapping(85));
696 /// let m = n.swap_bytes();
698 /// assert_eq!(m, Wrapping(0b01010101_00000000));
699 /// assert_eq!(m, Wrapping(21760));
702 #[must_use = "this returns the result of the operation, \
703 without modifying the original"]
704 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
705 pub const fn swap_bytes(self) -> Self {
706 Wrapping(self.0.swap_bytes())
709 /// Reverses the bit pattern of the integer.
713 /// Please note that this example is shared between integer types.
714 /// Which explains why `i16` is used here.
719 /// use std::num::Wrapping;
721 /// let n = Wrapping(0b0000000_01010101i16);
722 /// assert_eq!(n, Wrapping(85));
724 /// let m = n.reverse_bits();
726 /// assert_eq!(m.0 as u16, 0b10101010_00000000);
727 /// assert_eq!(m, Wrapping(-22016));
729 #[stable(feature = "reverse_bits", since = "1.37.0")]
730 #[rustc_const_stable(feature = "const_reverse_bits", since = "1.37.0")]
731 #[must_use = "this returns the result of the operation, \
732 without modifying the original"]
734 pub const fn reverse_bits(self) -> Self {
735 Wrapping(self.0.reverse_bits())
738 /// Converts an integer from big endian to the target's endianness.
740 /// On big endian this is a no-op. On little endian the bytes are
748 /// #![feature(wrapping_int_impl)]
749 /// use std::num::Wrapping;
751 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
753 /// if cfg!(target_endian = "big") {
754 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_be(n), n)")]
756 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_be(n), n.swap_bytes())")]
761 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
762 pub const fn from_be(x: Self) -> Self {
763 Wrapping(<$t>::from_be(x.0))
766 /// Converts an integer from little endian to the target's endianness.
768 /// On little endian this is a no-op. On big endian the bytes are
776 /// #![feature(wrapping_int_impl)]
777 /// use std::num::Wrapping;
779 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
781 /// if cfg!(target_endian = "little") {
782 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_le(n), n)")]
784 #[doc = concat!(" assert_eq!(<Wrapping<", stringify!($t), ">>::from_le(n), n.swap_bytes())")]
789 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
790 pub const fn from_le(x: Self) -> Self {
791 Wrapping(<$t>::from_le(x.0))
794 /// Converts `self` to big endian from the target's endianness.
796 /// On big endian this is a no-op. On little endian the bytes are
804 /// #![feature(wrapping_int_impl)]
805 /// use std::num::Wrapping;
807 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
809 /// if cfg!(target_endian = "big") {
810 /// assert_eq!(n.to_be(), n)
812 /// assert_eq!(n.to_be(), n.swap_bytes())
816 #[must_use = "this returns the result of the operation, \
817 without modifying the original"]
818 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
819 pub const fn to_be(self) -> Self {
820 Wrapping(self.0.to_be())
823 /// Converts `self` to little endian from the target's endianness.
825 /// On little endian this is a no-op. On big endian the bytes are
833 /// #![feature(wrapping_int_impl)]
834 /// use std::num::Wrapping;
836 #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")]
838 /// if cfg!(target_endian = "little") {
839 /// assert_eq!(n.to_le(), n)
841 /// assert_eq!(n.to_le(), n.swap_bytes())
845 #[must_use = "this returns the result of the operation, \
846 without modifying the original"]
847 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
848 pub const fn to_le(self) -> Self {
849 Wrapping(self.0.to_le())
852 /// Raises self to the power of `exp`, using exponentiation by squaring.
859 /// #![feature(wrapping_int_impl)]
860 /// use std::num::Wrapping;
862 #[doc = concat!("assert_eq!(Wrapping(3", stringify!($t), ").pow(4), Wrapping(81));")]
865 /// Results that are too large are wrapped:
868 /// #![feature(wrapping_int_impl)]
869 /// use std::num::Wrapping;
871 /// assert_eq!(Wrapping(3i8).pow(5), Wrapping(-13));
872 /// assert_eq!(Wrapping(3i8).pow(6), Wrapping(-39));
875 #[must_use = "this returns the result of the operation, \
876 without modifying the original"]
877 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
878 pub fn pow(self, exp: u32) -> Self {
879 Wrapping(self.0.wrapping_pow(exp))
885 wrapping_int_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
887 macro_rules! wrapping_int_impl_signed {
890 /// Returns the number of leading zeros in the binary representation of `self`.
897 /// #![feature(wrapping_int_impl)]
898 /// use std::num::Wrapping;
900 #[doc = concat!("let n = Wrapping(", stringify!($t), "::MAX) >> 2;")]
902 /// assert_eq!(n.leading_zeros(), 3);
905 #[must_use = "this returns the result of the operation, \
906 without modifying the original"]
907 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
908 pub const fn leading_zeros(self) -> u32 {
909 self.0.leading_zeros()
912 /// Computes the absolute value of `self`, wrapping around at
913 /// the boundary of the type.
915 /// The only case where such wrapping can occur is when one takes the absolute value of the negative
916 /// minimal value for the type this is a positive value that is too large to represent in the type. In
917 /// such a case, this function returns `MIN` itself.
924 /// #![feature(wrapping_int_impl)]
925 /// use std::num::Wrapping;
927 #[doc = concat!("assert_eq!(Wrapping(100", stringify!($t), ").abs(), Wrapping(100));")]
928 #[doc = concat!("assert_eq!(Wrapping(-100", stringify!($t), ").abs(), Wrapping(100));")]
929 #[doc = concat!("assert_eq!(Wrapping(", stringify!($t), "::MIN).abs(), Wrapping(", stringify!($t), "::MIN));")]
930 /// assert_eq!(Wrapping(-128i8).abs().0 as u8, 128u8);
933 #[must_use = "this returns the result of the operation, \
934 without modifying the original"]
935 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
936 pub fn abs(self) -> Wrapping<$t> {
937 Wrapping(self.0.wrapping_abs())
940 /// Returns a number representing sign of `self`.
942 /// - `0` if the number is zero
943 /// - `1` if the number is positive
944 /// - `-1` if the number is negative
951 /// #![feature(wrapping_int_impl)]
952 /// use std::num::Wrapping;
954 #[doc = concat!("assert_eq!(Wrapping(10", stringify!($t), ").signum(), Wrapping(1));")]
955 #[doc = concat!("assert_eq!(Wrapping(0", stringify!($t), ").signum(), Wrapping(0));")]
956 #[doc = concat!("assert_eq!(Wrapping(-10", stringify!($t), ").signum(), Wrapping(-1));")]
959 #[must_use = "this returns the result of the operation, \
960 without modifying the original"]
961 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
962 pub fn signum(self) -> Wrapping<$t> {
963 Wrapping(self.0.signum())
966 /// Returns `true` if `self` is positive and `false` if the number is zero or
974 /// #![feature(wrapping_int_impl)]
975 /// use std::num::Wrapping;
977 #[doc = concat!("assert!(Wrapping(10", stringify!($t), ").is_positive());")]
978 #[doc = concat!("assert!(!Wrapping(-10", stringify!($t), ").is_positive());")]
982 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
983 pub const fn is_positive(self) -> bool {
987 /// Returns `true` if `self` is negative and `false` if the number is zero or
995 /// #![feature(wrapping_int_impl)]
996 /// use std::num::Wrapping;
998 #[doc = concat!("assert!(Wrapping(-10", stringify!($t), ").is_negative());")]
999 #[doc = concat!("assert!(!Wrapping(10", stringify!($t), ").is_negative());")]
1003 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
1004 pub const fn is_negative(self) -> bool {
1005 self.0.is_negative()
1011 wrapping_int_impl_signed! { isize i8 i16 i32 i64 i128 }
1013 macro_rules! wrapping_int_impl_unsigned {
1016 /// Returns the number of leading zeros in the binary representation of `self`.
1023 /// #![feature(wrapping_int_impl)]
1024 /// use std::num::Wrapping;
1026 #[doc = concat!("let n = Wrapping(", stringify!($t), "::MAX) >> 2;")]
1028 /// assert_eq!(n.leading_zeros(), 2);
1031 #[must_use = "this returns the result of the operation, \
1032 without modifying the original"]
1033 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
1034 pub const fn leading_zeros(self) -> u32 {
1035 self.0.leading_zeros()
1038 /// Returns `true` if and only if `self == 2^k` for some `k`.
1045 /// #![feature(wrapping_int_impl)]
1046 /// use std::num::Wrapping;
1048 #[doc = concat!("assert!(Wrapping(16", stringify!($t), ").is_power_of_two());")]
1049 #[doc = concat!("assert!(!Wrapping(10", stringify!($t), ").is_power_of_two());")]
1053 #[unstable(feature = "wrapping_int_impl", issue = "32463")]
1054 pub fn is_power_of_two(self) -> bool {
1055 self.0.is_power_of_two()
1058 /// Returns the smallest power of two greater than or equal to `self`.
1060 /// When return value overflows (i.e., `self > (1 << (N-1))` for type
1061 /// `uN`), overflows to `2^N = 0`.
1068 /// #![feature(wrapping_next_power_of_two)]
1069 /// use std::num::Wrapping;
1071 #[doc = concat!("assert_eq!(Wrapping(2", stringify!($t), ").next_power_of_two(), Wrapping(2));")]
1072 #[doc = concat!("assert_eq!(Wrapping(3", stringify!($t), ").next_power_of_two(), Wrapping(4));")]
1073 #[doc = concat!("assert_eq!(Wrapping(200_u8).next_power_of_two(), Wrapping(0));")]
1076 #[must_use = "this returns the result of the operation, \
1077 without modifying the original"]
1078 #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
1079 reason = "needs decision on wrapping behaviour")]
1080 pub fn next_power_of_two(self) -> Self {
1081 Wrapping(self.0.wrapping_next_power_of_two())
1087 wrapping_int_impl_unsigned! { usize u8 u16 u32 u64 u128 }
1090 #![allow(non_upper_case_globals)]
1092 #[cfg(target_pointer_width = "16")]
1094 pub const usize: u32 = super::u16;
1095 pub const isize: u32 = super::i16;
1098 #[cfg(target_pointer_width = "32")]
1100 pub const usize: u32 = super::u32;
1101 pub const isize: u32 = super::i32;
1104 #[cfg(target_pointer_width = "64")]
1106 pub const usize: u32 = super::u64;
1107 pub const isize: u32 = super::i64;
1110 pub const i8: u32 = (1 << 3) - 1;
1111 pub const i16: u32 = (1 << 4) - 1;
1112 pub const i32: u32 = (1 << 5) - 1;
1113 pub const i64: u32 = (1 << 6) - 1;
1114 pub const i128: u32 = (1 << 7) - 1;
1115 pub use self::platform::isize;
1117 pub const u8: u32 = i8;
1118 pub const u16: u32 = i16;
1119 pub const u32: u32 = i32;
1120 pub const u64: u32 = i64;
1121 pub const u128: u32 = i128;
1122 pub use self::platform::usize;