Type Alias Uint 

pub type Uint<const N: usize, const B: usize = 0, const OM: u8 = {OverflowMode::DEFAULT as u8}> = Integer<false, N, B, OM>;

Unsigned integer type with const-generic bit width and overflow behaviour.

By default, the overflow behaviour is the same as the primitive integer types (i.e. panicking when the overflow-checks flag is enabled, and wrapping when overflow-checks is disabled).

For more details on how the const-generic parameters are interpreted, see the documentation for Integer.

Aliased Type

pub struct Uint<const N: usize, const B: usize = 0, const OM: u8 = {OverflowMode::DEFAULT as u8}> { /* private fields */ }

Implementations

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Methods for reading and manipulating the underlying bits of the integer.

pub const fn bit_width(self) -> u32

Returns the smallest number of bits necessary to represent self.

This is equal to the size of the type in bits minus the leading zeros of self.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U256;

assert_eq!(U256::MAX.bit_width(), 256);
assert_eq!(n!(0U256).bit_width(), 0);

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Checked arithmetic methods which act on self: self.checked_.... Each method cannot panic and returns an Option<Self>. None is returned when overflow would have occurred or there was an attempt to divide by zero or calculate a remainder with a divisor of zero.

pub const fn checked_add_signed(self, rhs: Int<N, B, OM>) -> Option<Self>

Checked addition with a signed integer of the same bit width. Computes self + rhs, returning None if overflow occurred.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U512;
 
assert_eq!(n!(1U512).checked_add_signed(n!(1)), Some(n!(2)));
assert_eq!(U512::MAX.checked_add_signed(n!(1)), None);
assert_eq!(n!(1U512).checked_add_signed(n!(-2)), None);

pub const fn checked_sub_signed(self, rhs: Int<N, B, OM>) -> Option<Self>

Checked subtraction by a signed integer of the same bit width. Computes self - rhs, returning None if overflow occurred.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U2048;
 
assert_eq!(n!(1U2048).checked_sub_signed(n!(-1)), Some(n!(2)));
assert_eq!(U2048::MAX.checked_sub_signed(n!(-1)), None);
assert_eq!(n!(1U2048).checked_sub_signed(n!(2)), None);

pub const fn checked_signed_diff(self, rhs: Self) -> Option<Int<N, B, OM>>

Checked integer subtraction. Computes self - rhs, returning None if the result cannot be represented by an Int<N, B, OM>.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U1024;
 
assert_eq!(n!(1U1024).checked_signed_diff(n!(2)), Some(n!(-1)));
assert_eq!(U1024::MAX.checked_signed_diff(n!(1)), None);
assert_eq!(n!(2U1024).checked_signed_diff(n!(1)), Some(n!(1)));

pub const fn checked_next_power_of_two(self) -> Option<Self>

Computes the smallest power of two that is greater than or equal to self. Returns None if the result is too large to be represented by Self.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U256;
 
assert_eq!(n!(16U256).checked_next_power_of_two(), Some(n!(16)));
assert_eq!(n!(17U256).checked_next_power_of_two(), Some(n!(32)));
assert_eq!(U256::MAX.checked_next_power_of_two(), None);

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Mathematical methods.

pub const fn cast_signed(self) -> Int<N, B, OM>

Casts self to a signed integer type of the same bit width, leaving the memory representation unchanged.

This is function equivalent to using the As trait to cast self to Int<N, B, OM>.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U256, I256};

assert_eq!(U256::MAX.cast_signed(), n!(-1I256));
assert_eq!(n!(0U256).cast_signed(), n!(0I256));

pub const fn next_power_of_two(self) -> Self

Returns the smallest power of two greater than or equal to self.

Panics

This function will panic if Self::OVERFLOW_MODE is Panic and the result would be too large to be represented by Self.

Examples

use bnum::prelude::*;

assert_eq!(n!(20U256).next_power_of_two(), n!(32));
assert_eq!(n!(16U256).next_power_of_two(), n!(16));
assert_eq!(n!(0U256).next_power_of_two(), n!(1));

pub const fn power_of_two(power: u32) -> Self

Returns an integer whose value is 2.pow(power). This is faster than using a shift left on Self::ONE or using the pow function.

Panics

This function will panic if power is greater than or equal to Self::BITS.

Examples

use bnum::prelude::*;
use bnum::types::U256;

assert_eq!(U256::power_of_two(11), n!(1) << 11);

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Overflowing arithmetic methods which act on self: self.overflowing_.... Each method returns a tuple of type (Self, bool) where the first item of the tuple is the result of wrapping variant of the method (self.wrapping_...), and the second item is a boolean which indicates whether overflow would have occurred.

pub const fn overflowing_add_signed(self, rhs: Int<N, B, OM>) -> (Self, bool)

Returns a tuple of the addition (with a signed integer of the same bit width) along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U512, I512};

assert_eq!(n!(1U512).overflowing_add_signed(n!(1)), (n!(2), false));
assert_eq!(U512::MAX.overflowing_add_signed(n!(1)), (n!(0), true));
assert_eq!(n!(1U512).overflowing_add_signed(n!(-2)), (U512::MAX, true));

pub const fn overflowing_sub_signed(self, rhs: Int<N, B, OM>) -> (Self, bool)

Returns a tuple of the subtraction (with a signed integer of the same bit width) along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U2048, I2048};

assert_eq!(n!(1U2048).overflowing_sub_signed(n!(-1)), (n!(2), false));
assert_eq!(U2048::MAX.overflowing_sub_signed(n!(-1)), (n!(0), true));
assert_eq!(n!(1U2048).overflowing_sub_signed(n!(2)), (U2048::MAX, true));

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

Methods which convert to integers from strings and lists of digits in a given radix (base).

pub const fn from_radix_be(buf: &[u8], radix: u32) -> Option<Self>

Converts a slice of big-endian digits in the given radix to an integer. Each u8 of the slice is interpreted as one digit of base radix of the number, so this function will return None if any digit is greater than or equal to radix, or if the integer represented by the digits is too large to be represented by Self. Otherwise, the integer is wrapped in Some.

Panics

This function panics if radix is not in the range from 2 to 256 inclusive.

Examples

use bnum::prelude::*;
use bnum::types::U512;

let a = U512::from_radix_be(&[4, 3, 2, 1], 11).unwrap();
let b: U512 = n!(1)*n!(11).pow(0) + n!(2)*n!(11).pow(1) + n!(3)*n!(11).pow(2) + n!(4)*n!(11).pow(3);

assert_eq!(a, b); // 4*11^3 + 3*11^2 + 2*11^1 + 1*11^0

pub const fn from_radix_le(buf: &[u8], radix: u32) -> Option<Self>

Converts a slice of little-endian digits in the given radix to an integer. Each u8 of the slice is interpreted as one digit of base radix of the number, so this function will return None if any digit is greater than or equal to radix, or if the integer represented by the digits is too large to be represented by Self. Otherwise, the integer is wrapped in Some.

Panics

This function panics if radix is not in the range from 2 to 256 inclusive.

Examples

use bnum::prelude::*;
use bnum::types::U512;

let a = U512::from_radix_le(&[5, 6, 7, 8], 18).unwrap();
let b: U512 = n!(5)*n!(18).pow(0) + n!(6)*n!(18).pow(1) + n!(7)*n!(18).pow(2) + n!(8)*n!(18).pow(3);

assert_eq!(a, b); // 8*18^3 + 7*18^2 + 6*18^1 + 5*18^0

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Methods which convert integers to strings and lists of digits in a given radix (base).

pub fn to_radix_be(&self, radix: u32) -> Vec<u8>

Available on crate feature alloc only.

Returns the integer in the given base in big-endian digit order.

Panics

This function panics if radix is not in the range from 2 to 256 inclusive.

use bnum::types::U512;

let digits = &[3, 55, 60, 100, 5, 0, 5, 88];
let n = U512::from_radix_be(digits, 120).unwrap();
assert_eq!(n.to_radix_be(120), digits);

pub fn to_radix_le(&self, radix: u32) -> Vec<u8>

Available on crate feature alloc only.

Returns the integer in the given base in little-endian digit order.

Panics

This function panics if radix is not in the range from 2 to 256 inclusive.

use bnum::types::U512;

let digits = &[1, 67, 88, 200, 55, 68, 87, 120, 178];
let n = U512::from_radix_le(digits, 250).unwrap();
assert_eq!(n.to_radix_le(250), digits);

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Saturating arithmetic methods which act on self: self.saturating_.... For each method, if overflow occurs, the largest or smallest value that can be represented by Self is returned instead.

pub const fn saturating_add_signed(self, rhs: Int<N, B, OM>) -> Self

Saturating addition with a signed integer of the same bit width. Computes self + rhs, returning Self::MAX if the result is too large to be represented by Self, or Self::MIN if the result is negative.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U512;
 
assert_eq!(n!(1U512).saturating_add_signed(n!(-1)), n!(0));
assert_eq!(U512::MAX.saturating_add_signed(n!(1)), U512::MAX);
assert_eq!(n!(1U512).saturating_add_signed(n!(-2)), n!(0));

pub const fn saturating_sub_signed(self, rhs: Int<N, B, OM>) -> Self

Saturating subtraction with a signed integer of the same bit width. Computes self - rhs, returning Self::MIN if the result is negative, or Self::MAX if the result is too large to be represented by Self.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U2048;
 
assert_eq!(n!(1U2048).saturating_sub_signed(n!(-1)), n!(2));
assert_eq!(U2048::MAX.saturating_sub_signed(n!(-4)), U2048::MAX);
assert_eq!(n!(1U2048).saturating_sub_signed(n!(3)), n!(0));

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Strict arithmetic methods which act on self: self.strict_.... Each method will always panic if overflow or division by zero occurs (i.e. when the checked equivalent would return None), regardless of Self::OVERFLOW_MODE.

pub const fn strict_add_signed(self, rhs: Int<N, B, OM>) -> Self

Strict addition with a signed integer of the same bit width. Computes self + rhs, panicking if overflow occurs.

Panics

This function will panic if overflow occurs, regardless of Self::OVERFLOW_MODE.

Examples

use bnum::prelude::*;
 
assert_eq!(n!(5U24).strict_add_signed(n!(-2I24)), n!(3U24));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::U256;
 
let _ = U256::MIN.strict_add_signed(n!(-1I256));

pub const fn strict_sub_signed(self, rhs: Int<N, B, OM>) -> Self

Strict subtraction by a signed integer of the same bit width. Computes self - rhs, panicking if overflow occurs.

Panics

This function will panic if overflow occurs, regardless of Self::OVERFLOW_MODE.

Examples

use bnum::prelude::*;
 
assert_eq!(n!(5U24).strict_sub_signed(n!(-2I24)), n!(7U24));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::U256;
 
let _ = U256::MAX.strict_sub_signed(n!(-1I256));

impl<const N: usize, const B: usize, const OM: u8> Uint<N, B, OM>

(Unsigned integers only.) Wrap arithmetic methods which act on self: self.wrapping_.... Each method returns of the calculation truncated to the number of bits of self (i.e. modulo Self::MAX + 1), except for the wrapping_shl and wrapping_shr methods, which return the value shifted by rhs % Self::BITS.

pub const fn wrapping_add_signed(self, rhs: Int<N, B, OM>) -> Self

Wrap integer addition with a signed integer of the same bit width. Computes self + rhs modulo Self::MAX + 1.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U512;
 
assert_eq!(n!(1U512).wrapping_add_signed(n!(1)), n!(2));
assert_eq!(U512::MAX.wrapping_add_signed(n!(1)), n!(0));
assert_eq!(n!(1U512).wrapping_add_signed(n!(-2)), U512::MAX);

pub const fn wrapping_sub_signed(self, rhs: Int<N, B, OM>) -> Self

Wrap integer subtraction with a signed integer of the same bit width. Computes self - rhs modulo Self::MAX + 1.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U2048;
 
assert_eq!(n!(1U2048).wrapping_sub_signed(n!(-1)), n!(2));
assert_eq!(U2048::MAX.wrapping_sub_signed(n!(-1)), n!(0));
assert_eq!(n!(1U2048).wrapping_sub_signed(n!(2)), U2048::MAX);

pub const fn wrapping_next_power_of_two(self) -> Self

Returns the smallest power of two greater than or equal to self. If the next power of two is greater than Self::MAX, the return value is wrapped to zero.

Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::U256;
 
assert_eq!(n!(4U256).wrapping_next_power_of_two(), n!(4));
assert_eq!(n!(31U256).wrapping_next_power_of_two(), n!(32));
assert_eq!(U256::MAX.wrapping_next_power_of_two(), n!(0));

Trait Implementations

impl<const N: usize, const B: usize, const M: usize, const A: usize, const OM: u8> TryFrom<Integer<true, N, B, OM>> for Uint<M, A, OM>

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: Int<N, B, OM>) -> Result<Self, Self::Error>

Performs the conversion.

impl<const N: usize, const B: usize, const OM: u8> TryFrom<char> for Uint<N, B, OM>

type Error = TryFromCharError

The type returned in the event of a conversion error.

fn try_from(c: char) -> Result<Self, Self::Error>

Performs the conversion.

impl<const N: usize, const B: usize, const OM: u8> Unsigned for Uint<N, B, OM>

Available on crate feature numtraits only.