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