Struct Integer

Source

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

Expand description

A fixed-size integer type, generic over signedness, bit width, and overflow behaviour.

Integer has four const-generic parameters:

S: determines whether the integer behaves as an unsigned integer (S = false), or a signed integer (S = true);
N: specifies how many bytes should be used to store the integer. The bytes are stored in little endian order (least significant byte first).
B: specifies the bit width of the integer. If B = 0 (the default value), then the bit width of the integer is taken to be N * 8. Otherwise, the bit width is taken to be B, and in this case it is required that N - 8 < B*8 <= N (i.e. N = B.div_ceil(8)).
OM: specifies the behaviour of the type when arithmetic overflow occurs. There are three valid overflow modes, each corresponding to a variant of the OverflowMode enum:
- 0 (Wrap): arithmetic operations wrap around on overflow.
- 1 (Panic): arithmetic operations panic on overflow.
- 2 (Saturate): arithmetic operations saturate on overflow.
  By default, OM is set to 0 if the overflow-checks flag is disabled, and 1 if overflow-checks is enabled.

Integer closely follows the API and behaviour of Rust’s primitive integer types: u8, i8, u16, i16, u32, i32, u64, i64, u128, i128, usize and isize. The only differences are:

The primitive integers are stored in native-endian byte order. Integers are always stored in little-endian byte order.
Primitive integers are serialised in serde as decimal strings. Integers are serialised using derive(Serialize), i.e. as a struct.
In no-alloc environments, primitive integers are formatted as decimal strings by the Debug trait, whereas Integers are formatted as padded hexadecimal strings.
The primitive integers panic on arithmetic overflow if overflow-checks is enabled, and wrap around on overflow if overflow-checks is disabled. The overflow behaviour of Integer is determined by Self::OVERFLOW_MODE:
- Wrap: arithmetic operations wrap around on overflow, so the behaviour is the same as the Wrapping(T) type in the standard library (i.e. the same as the primitive integer type behaviour when overflow-checks is disabled).
- Panic: arithmetic operations panic on overflow, so the behaviour is the same as the primitive integer type behaviour when overflow-checks is enabled.
- Saturate: arithmetic operations saturate on overflow, so the behaviour is the same as the Saturating(T) type in the standard library.
- OverflowMode::DEFAULT: the overflow behaviour is the same as the primitive integer type overflow behaviour.

Implementations§

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Associated constants.

Source

pub const OVERFLOW_MODE: OverflowMode

The overflow mode used for this type, determined by the const-generic parameter OM:

If OM is 0, the overflow mode is OverflowMode::Wrap.
If OM is 1, the overflow mode is OverflowMode::Panic.
If OM is 2, the overflow mode is OverflowMode::Saturate.

§Examples

use bnum::prelude::*;
use bnum::OverflowMode;
 
type U264w = t!(U264w);
type I155p = t!(I155p);
type I512s = t!(I512s);
 
assert_eq!(U264w::OVERFLOW_MODE, OverflowMode::Wrap);
assert_eq!(I155p::OVERFLOW_MODE, OverflowMode::Panic);
assert_eq!(I512s::OVERFLOW_MODE, OverflowMode::Saturate);

Source

pub const BITS: u32

The bit width of the type.

§Examples

use bnum::types::{U512, I1024};
 
assert_eq!(U512::BITS, 512);
assert_eq!(I1024::BITS, 1024);

Source

pub const BYTES: u32

The total number of bytes that this type contains.

§Examples

use bnum::types::{U256, I512};

assert_eq!(U256::BYTES, 32); // 256 / 8 = 32
assert_eq!(I512::BYTES, 64); // 512 / 8 = 64

Source

pub const MIN: Self

The minimum value that this type can represent. For unsigned integers, this is 0. For signed integers, this is -2^(Self::BITS - 1).

§Examples

use bnum::prelude::*;
use bnum::types::{U512, I512};
 
assert_eq!(U512::MIN, n!(0));
assert_eq!(I512::MIN.trailing_zeros(), 511); // memory representation is 100...0

Source

pub const MAX: Self

The maximum value that this type can represent. For unsigned integers, this is 2^Self::BITS - 1. For signed integers, this is 2^(Self::BITS - 1) - 1.

§Examples

use bnum::types::{U256, I256};
 
assert_eq!(U256::MAX.not(), U256::MIN); // memory representation of `Self::MAX` is 111...1
assert_eq!(I256::MAX.not(), I256::MIN); // memory representation of `Self::MAX` is 011...1

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Bigint helper methods: common functions used to implement big integer arithmetic.

Source

pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool)

Computes self + rhs + carry, and returns a tuple of the low (wrapping) bits and the high (carry) bit of the result, in that order.

If carry is false, then this method is equivalent to overflowing_add.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U1024, I1024};

assert_eq!(n!(1U1024).carrying_add(n!(1), true), (n!(3), false));
assert_eq!(U1024::MAX.carrying_add(n!(1), false), (n!(0), true));
assert_eq!(U1024::MAX.carrying_add(U1024::MAX, true), (U1024::MAX, true));

assert_eq!(n!(1I1024).carrying_add(n!(1), true), (n!(3), false));
assert_eq!(I1024::MAX.carrying_add(n!(0), true), (I1024::MIN, true));
assert_eq!(I1024::MAX.carrying_add(I1024::MAX, true), (n!(-1), true));
assert_eq!(I1024::MIN.carrying_add(I1024::MIN, true), (n!(1), true));

Source

pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool)

Computes self - rhs - borrow, and returns a tuple of the low (wrapping) bits of the result and a boolean indicating whether an arithmetic borrow (overflow) occurred.

If borrow is false, then this method is equivalent to overflowing_sub.

§Examples

Basic usage:

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

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

assert_eq!(n!(1I512).borrowing_sub(n!(1I512), true), (n!(-1I512), false));
assert_eq!(I512::MIN.borrowing_sub(n!(1), false), (I512::MAX, true));
assert_eq!(n!(0).borrowing_sub(I512::MIN, true), (I512::MAX, false));

Source

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

Computes self * rhs, and returns a tuple of the low (wrapping) bits and high (overflow) bits of the result, in that order.

§Examples

Basic usage:

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

assert_eq!(n!(7U256).widening_mul(n!(3)), (n!(21), n!(0)));
assert_eq!(n!(2U256).pow(255).widening_mul(n!(2U256).pow(100)), (n!(0), n!(2U256).pow(99)));

assert_eq!(n!(-5I256).widening_mul(n!(8)), (n!(-40).cast_unsigned(), n!(-1)));
assert_eq!(I256::MIN.widening_mul(n!(2)), (n!(0), n!(-1)));

Source

pub const fn carrying_mul( self, rhs: Self, carry: Self, ) -> (Uint<N, B, OM>, Self)

Computes self * rhs + carry, and returns a tuple of the low (wrapping) bits and high (overflow) bits of the result, in that order.

§Examples

Basic usage:

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

assert_eq!(n!(7U2048).carrying_mul(n!(3), n!(5)), (n!(26), n!(0)));
assert_eq!(U2048::MAX.carrying_mul(U2048::MAX, U2048::MAX), (n!(0), U2048::MAX));

assert_eq!(n!(-5I2048).carrying_mul(n!(8), n!(-6)), (n!(-46).cast_unsigned(), n!(-1)));
assert_eq!(I2048::MIN.carrying_mul(n!(2), n!(3)), (n!(3), n!(-1)));

Source

pub const fn carrying_mul_add( self, rhs: Self, carry: Self, add: Self, ) -> (Uint<N, B, OM>, Self)

Computes self * rhs + carry + add, and returns a tuple of the low (wrapping) bits and high (overflow) bits of the result, in that order.

§Examples

Basic usage:

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

assert_eq!(n!(7U2048).carrying_mul_add(n!(3), n!(5), n!(12)), (n!(38), n!(0)));
assert_eq!(U2048::MAX.carrying_mul_add(U2048::MAX, U2048::MAX, U2048::MAX), (U2048::MAX, U2048::MAX));

assert_eq!(n!(-5I2048).carrying_mul_add(n!(8), n!(-6), n!(-11)), (n!(-57).cast_unsigned(), n!(-1)));
assert_eq!(I2048::MIN.carrying_mul_add(n!(2), n!(3), n!(-2)), (n!(1), n!(-1)));

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

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

assert_eq!(n!(1U2048).unbounded_shl(1), n!(2));
assert_eq!(U2048::MAX.unbounded_shl(2048), n!(0));
assert_eq!(U2048::MAX.unbounded_shl(2049), n!(0));

assert_eq!(n!(1).unbounded_shl(2047), I2048::MIN);
assert_eq!(I2048::MAX.unbounded_shl(2048), n!(0));
assert_eq!(I2048::MIN.unbounded_shl(2049), n!(0));

Source

pub const fn unbounded_shr(self, rhs: u32) -> Self

Right-shifts self by rhs bits. If rhs is larger than or equal to Self::BITS, then the entire value is shifted out, and:

for unsigned integers, 0 is returned.
for signed integers, -1 is returned if self is negative, and 0 is returned if self is non-negative.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U1024, I1024};

assert_eq!(n!(2U1024).unbounded_shr(1), n!(1));
assert_eq!(U1024::MAX.unbounded_shr(1024), n!(0));
assert_eq!(U1024::MAX.unbounded_shr(1030), n!(0));

assert_eq!(I1024::MIN.unbounded_shr(1023), n!(-1));
assert_eq!(n!(-1I1024).unbounded_shr(1024), n!(-1));
assert_eq!(I1024::MAX.unbounded_shr(1025), n!(0));

Source

pub const fn reverse_bits(self) -> Self

Reverses the order of the bits of self.

§Examples

Basic usage:

use bnum::prelude::*;

type U24 = Uint<3>;
type I24 = Int<3>;

let a: U24 = 0b10110011_11001010_00011101.as_();
assert_eq!(a.reverse_bits(), 0b10111000_01010011_11001101.as_());

let b: I24 = 0b01101001_00111100_11100011.as_();
assert_eq!(b.reverse_bits(), 0b11000111_00111100_10010110.as_());

Source

pub const fn bit(&self, index: u32) -> bool

Returns a boolean representing the bit in the given position (true if the bit is 1). The least significant bit is at index 0, the most significant bit is at index Self::BITS - 1.

§Examples

Basic usage:

use bnum::prelude::*;

let a = n!(0b1101001101U24);
for i in [0, 2, 3, 6, 8, 9] {
    assert!(a.bit(i));
}

let b = n!(0b0010110010I24);
for i in [1, 4, 5, 7] {
    assert!(b.bit(i));
}

Source

pub const fn set_bit(&mut self, index: u32, value: bool)

Sets/unsets the bit in the given position (i.e. to 1 if value is true). The least significant bit is at index 0, the most significant bit is at index Self::BITS - 1.

§Examples

Basic usage:

use bnum::prelude::*;

let mut a = n!(0b1001011001001U24);
a.set_bit(2, true);
assert_eq!(a, n!(0b1001011001101));
a.set_bit(1, false); // no change
assert_eq!(a, n!(0b1001011001101));

let mut b = n!(0b010010110110100I24);
b.set_bit(4, false);
assert_eq!(b, n!(0b010010110100100));
b.set_bit(0, false); // no change
assert_eq!(b, n!(0b010010110100100));

Source §

impl<const S: bool, const N: usize, const OM: u8> Integer<S, N, 0, OM>

Methods for reading and manipulating the underlying bits of the integer.

Source

pub const fn swap_bytes(self) -> Self

Reverses the order of the bytes of self.

§Examples

Basic usage:

use bnum::prelude::*;

type U24 = Uint<3>;
type I24 = Int<3>;

let a: U24 = n!(0x7C283D);
assert_eq!(a.swap_bytes(), n!(0x3D287C));

let b: I24 = n!(0x1DC87B);
assert_eq!(b.swap_bytes(), n!(0x7BC81D));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, N, B, OM>

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

Source

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);

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Methods that convert integers to and from byte arrays and slices.

Source

pub const fn to_bytes(self) -> [u8; N]

Returns the underlying bytes of self as an array.

This method is equivalent to to_le_bytes.

§Examples

Basic usage:

use bnum::prelude::*;
 
let a = n!(0xE3BD89U24);
assert_eq!(a.to_bytes(), [0x89, 0xBD, 0xE3]);
 
let b = n!(0x0A412FI24);
assert_eq!(b.to_bytes(), [0x2F, 0x41, 0x0A]);

Source

pub const fn as_bytes(&self) -> &[u8; N]

Returns a reference to underlying bytes of self.

§Examples

Basic usage:

use bnum::prelude::*;
 
let a = n!(0xD1FB70U24);
assert_eq!(a.as_bytes(), &[0x70, 0xFB, 0xD1]);
 
let b = n!(0x3F23A1I24);
assert_eq!(b.as_bytes(), &[0xA1, 0x23, 0x3F]);

Source

pub const fn as_bytes_mut(&mut self) -> &mut [u8; N]

Returns a mutable reference to underlying bytes of self.

§Examples

Basic usage:

use bnum::prelude::*;
 
let mut a = n!(0xD1FB70U24);
let bytes = a.as_bytes_mut();
bytes[0] = 0x3D;
bytes[2] = 0xA5;
assert_eq!(a, n!(0xA5FB3D));
 
let mut b = n!(0x1D3C4EI24);
let bytes = b.as_bytes_mut();
bytes[1] = 0xFF;
assert_eq!(b, n!(0x1DFF4E));

Source

pub const fn from_bytes(digits: [u8; N]) -> Self

Creates a new integer from the given array of bytes. The first byte in the array is interpreted as the least significant byte, the last byte in the array is interpreted as the most significant byte.

If Self::BITS is not a multiple of 8, then the high-order bits are ignored.

This method is equivalent to from_le_bytes.

§Examples

Basic usage:

use bnum::prelude::*;
 
type U24 = Uint<3>;
type I24 = Int<3>;
type U15 = t!(U15);
 
let bytes = [0x56, 0x34, 0x12];
assert_eq!(U24::from_bytes(bytes), n!(0x123456));
 
let bytes = [0xFE, 0xDC, 0x7B];
assert_eq!(I24::from_bytes(bytes), n!(0x7BDCFE));
 
assert_eq!(U15::from_bytes([0xFF, 0xFF]), U15::MAX); // = 0x7FFF. the high-order bit is ignored

Source

pub const fn from_be_slice(slice: &[u8]) -> Option<Self>

Converts the slice of big endian bytes to an integer. An empty slice is interpreted as zero. If the value represented by the bytes is too large to be stored in Self, then None is returned.

§Examples

use bnum::prelude::*;
 
type U24 = Uint<3>;
type I24 = Int<3>;
 
let a: U24 = n!(0x005CF1);
 
let b = U24::from_be_slice(&[0x00, 0x5C, 0xF1]);
assert_eq!(b, Some(a));
 
let c = U24::from_be_slice(&[0x00, 0x00, 0x5C, 0xF1]);
assert_eq!(c, Some(a));

let d = U24::from_be_slice(&[0x00, 0x00, 0x00, 0x5C, 0xF1]);
assert_eq!(d, Some(a));
 
let e = U24::from_be_slice(&[0x01, 0x00, 0x5C, 0xF1]);
assert_eq!(e, None);
 
let a: I24 = n!(0xFF8A06).cast_signed();
assert!(a.is_negative());
 
let b = I24::from_be_slice(&[0xFF, 0x8A, 0x06]);
assert_eq!(b, Some(a));
 
let c = I24::from_be_slice(&[0xFF, 0xFF, 0x8A, 0x06]);
assert_eq!(c, Some(a));
 
let d = I24::from_be_slice(&[0xFF, 0xFF, 0xFF, 0x8A, 0x06]);
assert_eq!(d, Some(a));
 
let e = I24::from_be_slice(&[0xFE, 0xFF, 0x8A, 0x06]);
assert_eq!(e, None);

Source

pub const fn from_le_slice(slice: &[u8]) -> Option<Self>

Converts the slice of little endian bytes to an integer. An empty slice is interpreted as zero. If the value represented by the bytes is too large to be stored in Self, then None is returned.

§Examples

use bnum::prelude::*;
 
type U24 = Uint<3>;
type I24 = Int<3>;
 
let a: U24 = n!(0x005CF1);
let b = U24::from_le_slice(&[0xF1, 0x5C, 0x00]);
assert_eq!(b, Some(a));
 
let c = U24::from_le_slice(&[0xF1, 0x5C]);
assert_eq!(c, Some(a));

let d = U24::from_le_slice(&[0xF1, 0x5C, 0x00, 0x00, 0x00]);
assert_eq!(d, Some(a));

let e = U24::from_le_slice(&[0xF1, 0x5C, 0x00, 0x01]);
assert_eq!(e, None);
 
let a: I24 = n!(0xFF8A06).cast_signed();
assert!(a.is_negative());
 
let b = I24::from_le_slice(&[0x06, 0x8A, 0xFF]);
assert_eq!(b, Some(a));
 
let c = I24::from_le_slice(&[0x06, 0x8A]); // 0x8A has a leading one, so the slice represents a negative number
assert_eq!(c, Some(a));

let d = I24::from_le_slice(&[0x06, 0x8A, 0xFF, 0xFF, 0xFF]);
assert_eq!(d, Some(a));

let e = I24::from_le_slice(&[0x06, 0x8A, 0xFF, 0xFE]);
assert_eq!(e, None);

Basic usage:

use bnum::prelude::*;
 
type U24 = Uint<3>;
type I24 = Int<3>;
 
let bytes = [0xD7, 0xAB, 0x6F];
assert_eq!(U24::from_le_bytes(bytes), n!(0x6FABD7));
 
let bytes = [0xFF, 0x75, 0x6F];
assert_eq!(I24::from_le_bytes(bytes), n!(0x6F75FF));

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

use bnum::prelude::*;
use bnum::types::{U256, I256};
 
assert_eq!(n!(5U256).checked_div(n!(2)), Some(n!(2)));
assert_eq!(n!(1U256).checked_div(n!(0)), None);
 
assert_eq!(n!(-13I256).checked_div(n!(5)), Some(n!(-2)));
assert_eq!(I256::MIN.checked_div(n!(-1)), None);

Source

pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self>

Checked Euclidean division. Computes self.div_euclid(rhs), returning None if rhs is zero or if the division would overflow (this is only possible for signed integers).

For unsigned integers, this is equivalent to self.checked_div(rhs).

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U2048, I2048};
 
assert_eq!(n!(13U2048).checked_div_euclid(n!(5)), Some(n!(2)));
assert_eq!(U2048::MAX.checked_div_euclid(n!(0)), None);
 
assert_eq!(n!(-13I2048).checked_div_euclid(n!(5)), Some(n!(-3)));
assert_eq!(I2048::MIN.checked_div_euclid(n!(-1)), None);

Source

pub const fn checked_rem(self, rhs: Self) -> Option<Self>

Checked integer remainder. Computes self % rhs, returning None if rhs is zero or if computing the remainder would result in overflow (this is only possible for signed integers).

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U1024, I1024};
 
assert_eq!(n!(5U1024).checked_rem(n!(2)), Some(n!(1)));
assert_eq!(n!(1U1024).checked_rem(n!(0)), None);
 
assert_eq!(n!(-13I1024).checked_rem(n!(5)), Some(n!(-3)));
assert_eq!(I1024::MIN.checked_rem(n!(-1)), None);

Source

pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self>

Checked Euclidean remainder. Computes self.rem_euclid(rhs), returning None if rhs is zero or if computing the remainder would result in overflow (this is only possible for signed integers).

For unsigned integers, this is equivalent to self.checked_rem(rhs).

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U512, I512};
 
assert_eq!(n!(13U512).checked_rem_euclid(n!(5)), Some(n!(3)));
assert_eq!(U512::MAX.checked_rem_euclid(n!(0)), None);
 
assert_eq!(n!(-13I512).checked_rem_euclid(n!(5)), Some(n!(2)));
assert_eq!(I512::MIN.checked_rem_euclid(n!(-1)), None);

Source

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

Checked negation. Computes -self, returning None if overflow occurred.

For unsigned integers, overflow occurs if self is non-zero. For signed integers, overflow occurs if self is equal to Self::MIN.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U256, I256};
 
assert_eq!(n!(1U256).checked_neg(), None);
assert_eq!(n!(0U256).checked_neg(), Some(n!(0)));
 
assert_eq!(n!(1I256).checked_neg(), Some(n!(-1)));
assert_eq!(I256::MIN.checked_neg(), None);

Source

pub const fn checked_shl(self, rhs: u32) -> Option<Self>

Checked left shift. Computes self << rhs, returning None if rhs is greater than or equal to Self::BITS.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U2048, I2048};
 
assert_eq!(n!(1U2048).checked_shl(1), Some(n!(2)));
assert_eq!(n!(1U2048).checked_shl(2048), None);
assert_eq!(n!(2U2048).checked_shl(2047), Some(n!(0)));
 
assert_eq!(n!(-1I2048).checked_shl(2), Some(n!(-4)));
assert_eq!(n!(-1I2048).checked_shl(2048), None);
assert_eq!(n!(-1).checked_shl(2047), Some(I2048::MIN));

Source

pub const fn checked_shr(self, rhs: u32) -> Option<Self>

Checked right shift. Computes self >> rhs, returning None if rhs is greater than or equal to Self::BITS.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U1024, I1024};

assert_eq!(n!(1U1024).checked_shr(1), Some(n!(0)));
assert_eq!(U1024::MAX.checked_shr(1024), None);
assert_eq!(U1024::MAX.checked_shr(1023), Some(n!(1)));
 
assert_eq!(n!(-1I1024).checked_shr(1), Some(n!(-1)));
assert_eq!(I1024::MIN.checked_shr(1024), None);
assert_eq!(I1024::MIN.checked_shr(I1024::BITS - 1), Some(n!(-1)));

Source

pub const fn checked_pow(self, exp: u32) -> Option<Self>

Checked exponentiation. Computes self.pow(exp), returning None if overflow occurred.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U512, I512};
 
assert_eq!(n!(2U512).checked_pow(10), Some(n!(1024)));
assert_eq!(n!(2U512).checked_pow(512), None);
 
assert_eq!(n!(-2I512).checked_pow(3), Some(n!(-8)));
assert_eq!(n!(-2).checked_pow(511), Some(I512::MIN));
assert_eq!(n!(2I512).checked_pow(512), None);

Source

pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self>

If rhs is positive, computes the smallest integer multiple of rhs that is greater than or equal to self. If rhs is negative, computes the largest integer multiple of rhs that is less than or equal to self.

Returns None if rhs is zero, or if the result is too large or too small to be represented by Self.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U256, I256};
 
assert_eq!(n!(4U256).checked_next_multiple_of(n!(2)), Some(n!(4)));
assert_eq!(n!(17U256).checked_next_multiple_of(n!(7)), Some(n!(21)));
assert_eq!(n!(1U256).checked_next_multiple_of(n!(0)), None);
assert_eq!(U256::MAX.checked_next_multiple_of(n!(2)), None);
assert_eq!(U256::MAX.checked_next_multiple_of(n!(1)), Some(U256::MAX));
 
assert_eq!(n!(-9I256).checked_next_multiple_of(n!(-3)), Some(n!(-9)));
assert_eq!(n!(-10I256).checked_next_multiple_of(n!(4)), Some(n!(-8)));
assert_eq!(n!(-17I256).checked_next_multiple_of(n!(-4)), Some(n!(-20)));
assert_eq!(n!(83I256).checked_next_multiple_of(n!(-6)), Some(n!(78)));
assert_eq!(I256::MIN.checked_next_multiple_of(n!(2)), Some(I256::MIN));
assert_eq!(n!(0I256).checked_next_multiple_of(n!(3)), Some(n!(0)));

Source

pub const fn checked_ilog2(self) -> Option<u32>

Computes base-2 logarithm of self, rounded down, i.e. the largest integer n such that 2^n <= self.

Returns None if self is less than or equal to zero.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U2048, I2048};
 
assert_eq!(n!(1U2048).checked_ilog2(), Some(0));
assert_eq!(U2048::MAX.checked_ilog2(), Some(2047));
assert_eq!(n!(0U2048).checked_ilog2(), None);
 
assert_eq!(I2048::MAX.checked_ilog2(), Some(2046));
assert_eq!(n!(-1I2048).checked_ilog2(), None);

Source

pub const fn checked_ilog10(self) -> Option<u32>

Computes base-10 logarithm of self, rounded down, i.e. the largest integer n such that 10^n <= self.

Returns None if self is less than or equal to zero.

§Examples

Basic usage:

use bnum::prelude::*;
 
assert_eq!(n!(1U1024).checked_ilog10(), Some(0));
assert_eq!(n!(1000U1024).checked_ilog10(), Some(3));
assert_eq!(n!(0U1024).checked_ilog10(), None);
 
assert_eq!(n!(100I1024).checked_ilog10(), Some(2));
assert_eq!(n!(-1I1024).checked_ilog10(), None);

Source

pub const fn checked_ilog(self, base: Self) -> Option<u32>

Computes logarithm of self to the given base, rounded down, i.e. the largest integer n such that base^n <= self.

Returns None if self is less than or equal to zero, or if base is less than 2.

Note that you should use checked_ilog2 or checked_ilog10 for base-2 or base-10 logarithms, respectively, as they are more efficient.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U512, I512};
 
assert_eq!(n!(9U512).checked_ilog(n!(3)), Some(2));
assert_eq!(n!(1U512).checked_ilog(n!(1)), None);
assert_eq!(n!(0U512).checked_ilog(n!(0)), None);
 
assert_eq!(n!(65I512).checked_ilog(n!(4)), Some(3));
assert_eq!(n!(2I512).checked_ilog(n!(-1)), None);
assert_eq!(I512::MIN.checked_ilog(n!(2)), None);

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, N, B, OM>

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);

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<true, N, B, OM>

use bnum::prelude::*;
use bnum::types::I2048;
 
assert_eq!(n!(-123I2048).checked_abs(), Some(n!(123)));
assert_eq!(n!(456I2048).checked_abs(), Some(n!(456)));
assert_eq!(I2048::MIN.checked_abs(), None);

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Mathematical methods.

Source

pub const fn pow(self, exp: u32) -> Self

Returns self raised to the power of exp.

§Overflow behaviour

If Self::OVERFLOW_MODE is Wrap, this method is equivalent to wrapping_pow.
If Self::OVERFLOW_MODE is Panic, this method is equivalent to strict_pow.
If Self::OVERFLOW_MODE is Saturate, this method is equivalent to saturating_pow.

§Examples

Basic usage:

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

assert_eq!(n!(3U256).pow(5), n!(243));
assert_eq!(n!(-7I256).pow(3), n!(-343));

Source

pub const fn div_euclid(self, rhs: Self) -> Self

Returns the Euclidean quotient of self by rhs.

§Overflow behaviour

If Self::OVERFLOW_MODE is Wrap, this method is equivalent to wrapping_div_euclid.
If Self::OVERFLOW_MODE is Panic, this method is equivalent to strict_div_euclid.
If Self::OVERFLOW_MODE is Saturate, this method is equivalent to saturating_div_euclid.

§Examples

use bnum::prelude::*;

assert_eq!(n!(37U512).div_euclid(n!(8)), n!(4));
assert_eq!(n!(-37I512).div_euclid(n!(8)), n!(-5));

Source

pub const fn rem_euclid(self, rhs: Self) -> Self

Returns the Euclidean remainder of self by rhs. This is always equivalent to self.strict_rem_euclid(rhs), regardless of Self::OVERFLOW_MODE.

§Examples

use bnum::prelude::*;

assert_eq!(n!(37U1024).rem_euclid(n!(8)), n!(5));
assert_eq!(n!(-37I1024).rem_euclid(n!(-8)), n!(3));

Source

pub const fn is_power_of_two(self) -> bool

Returns true if and only if self == 2^k for some integer k.

§Examples

use bnum::prelude::*;

assert!(n!(16U2048).is_power_of_two());
assert!(!n!(-8I2048).is_power_of_two());

Source

pub const fn midpoint(self, rhs: Self) -> Self

Computes the arithmetic mean of self and rhs, rounded towards zero (i.e. (self + rhs) / 2), without the possibility of overflow.

§Examples

use bnum::prelude::*;

assert_eq!(n!(10U256).midpoint(n!(22)), n!(16));
assert_eq!(n!(12U256).midpoint(n!(21)), n!(16));
assert_eq!(n!(-10I256).midpoint(n!(2)), n!(-4));
assert_eq!(n!(-13I256).midpoint(n!(0)), n!(-6));

Source

pub const fn ilog2(self) -> u32

Computes the base-2 logarithm of self, rounded down, i.e. the largest integer n such that 2^n <= self.

§Panics

This function will panic if self is less than or equal to zero.

§Examples

use bnum::prelude::*;

assert_eq!(n!(16U512).ilog2(), 4);
assert_eq!(n!(20I512).ilog2(), 4);

Source

pub const fn ilog10(self) -> u32

Computes the base-10 logarithm of self, rounded down, i.e. the largest integer n such that 10^n <= self.

§Panics

This function will panic if self is less than or equal to zero.

§Examples

use bnum::prelude::*;

assert_eq!(n!(1000U512).ilog10(), 3);
assert_eq!(n!(9999I512).ilog10(), 3);

Source

pub const fn ilog(self, base: Self) -> u32

Computes logarithm of self to the given base, rounded down, i.e. the largest integer n such that base^n <= self.

Note that you should use ilog2 or ilog10 for base-2 or base-10 logarithms respectively, as these are more efficient.

§Panics

This function will panic if self is less than or equal to zero, or if base is less than 2.

§Examples

use bnum::prelude::*;

assert_eq!(n!(243U1024).ilog(n!(3)), 5);
assert_eq!(n!(124I1024).ilog(n!(5)), 2);

Source

pub const fn abs_diff(self, other: Self) -> Uint<N, B, OM>

Computes the absolute difference between self and other, i.e. |self - other|, without the possibility of overflow.

§Examples

use bnum::prelude::*;

assert_eq!(n!(12U2048).abs_diff(n!(30)), n!(18));
assert_eq!(n!(-12I2048).abs_diff(n!(5)), n!(17));

Source

pub const fn next_multiple_of(self, rhs: Self) -> Self

If rhs is positive, computes the smallest integer multiple of rhs that is greater than or equal to self. If rhs is negative, computes the largest integer multiple of rhs that is less than or equal to self.

§Panics

This function will panic if rhs is zero.

This function will also panic if overflow occurs and Self::OVERFLOW_MODE is Panic.

§Examples

use bnum::prelude::*;

assert_eq!(n!(20U256).next_multiple_of(n!(6)), n!(24));
assert_eq!(n!(0U256).next_multiple_of(n!(5)), n!(0));

assert_eq!(n!(18I256).next_multiple_of(n!(-4)), n!(16));
assert_eq!(n!(-17I256).next_multiple_of(n!(-11)), n!(-22));

Source

pub const fn div_floor(self, rhs: Self) -> Self

Computes the quotient of self by rhs, rounding the result towards negative infinity.

§Panics

This function will panic if rhs is zero. For signed integers, it will also panic if self is Self::MIN and rhs is -1, since this would overflow. This behaviour is not affected by Self::OVERFLOW_MODE.

§Examples

use bnum::prelude::*;

assert_eq!(n!(37U512).div_floor(n!(8)), n!(4));
assert_eq!(n!(-37I512).div_floor(n!(8)), n!(-5));

Source

pub const fn div_ceil(self, rhs: Self) -> Self

Computes the quotient of self by rhs, rounding the result towards positive infinity.

§Panics

This function will panic if rhs is zero. For signed integers, it will also panic if self is Self::MIN and rhs is -1, since this would overflow. This behaviour is not affected by Self::OVERFLOW_MODE.

§Examples

use bnum::prelude::*;

assert_eq!(n!(37U512).div_ceil(n!(8)), n!(5));
assert_eq!(n!(-37I512).div_ceil(n!(8)), n!(-4));

Source

pub const fn is_zero(&self) -> bool

Returns whether or not self equals zero.

§Examples

use bnum::prelude::*;

assert!(n!(0U1024).is_zero());
assert!(n!(0I1024).is_zero());

assert!(!n!(1U1024).is_zero());
assert!(!n!(-1I1024).is_zero());

Source

pub const fn is_one(&self) -> bool

Returns whether or not self equals one.

§Examples

use bnum::prelude::*;

assert!(n!(1U2048).is_one());
assert!(n!(1I2048).is_one());

assert!(!n!(0U2048).is_one());
assert!(!n!(-1I2048).is_one());

Source

pub const fn isqrt(self) -> Self

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, N, B, OM>

(Unsigned integers only.) Mathematical methods.

Source

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));

Source

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));

Source

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);

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<true, N, B, OM>

(Signed integers only.) Mathematical methods.

Source

pub const fn cast_unsigned(self) -> Uint<N, B, OM>

Casts self to an unsigned 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 Uint<N, B, OM>.

§Examples

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

assert_eq!(n!(-1).cast_unsigned(), U512::MAX);
assert_eq!(n!(0I512).cast_unsigned(), n!(0U512));

Source

pub const fn unsigned_abs(self) -> Uint<N, B, OM>

Returns the absolute value of self as an unsigned integer.

§Examples

use bnum::prelude::*;
use bnum::types::I1024;

assert_eq!(n!(-20I1024).unsigned_abs(), n!(20));
assert_eq!(n!(15I1024).unsigned_abs(), n!(15));
assert_eq!(I1024::MIN.unsigned_abs(), I1024::MIN.cast_unsigned());

Source

pub const fn abs(self) -> Self

Returns the absolute value of self.

§Overflow behaviour

If Self::OVERFLOW_MODE is Wrap, this function will return Self::MIN on overflow (i.e. when self is Self::MIN).
If Self::OVERFLOW_MODE is Panic, this function will panic on overflow.
If Self::OVERFLOW_MODE is Saturate, this function will return Self::MAX on overflow.

§Examples

use bnum::prelude::*;

assert_eq!(n!(-20I2048).abs(), n!(20));
assert_eq!(n!(15I2048).abs(), n!(15));

Source

pub const fn signum(self) -> Self

Returns the sign of self as a signed integer, i.e. 1 if self is positive, -1 if self is negative, and 0 if self is zero.

§Examples

use bnum::prelude::*;

assert_eq!(n!(42I256).signum(), n!(1));
assert_eq!(n!(-7I256).signum(), n!(-1));
assert_eq!(n!(0I256).signum(), n!(0));

Source

pub const fn is_positive(self) -> bool

Returns whether or not self is (strictly) positive.

§Examples

use bnum::prelude::*;

assert!(n!(314I512).is_positive());
assert!(!n!(-159I512).is_positive());
assert!(!n!(0I512).is_positive());

Source

pub const fn is_negative(self) -> bool

Returns whether or not self is (strictly) negative.

§Examples

use bnum::prelude::*;

assert!(n!(-271I512).is_negative());
assert!(!n!(828I512).is_negative());
assert!(!n!(0I512).is_negative());

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Basic usage:

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

assert_eq!(n!(13U512).overflowing_rem_euclid(n!(5)), (n!(3), false));
assert_eq!(n!(-23I512).overflowing_rem_euclid(n!(4)), (n!(1), false));
assert_eq!(I512::MIN.overflowing_rem_euclid(n!(-1)), (n!(0), true));

Source

pub const fn overflowing_neg(self) -> (Self, bool)

Returns a tuple of !self + 1 along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

Note that the second item of the tuple will be true if self is not zero.

§Examples

Basic usage:

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

assert_eq!(n!(1U256).overflowing_neg(), (U256::MAX, true));
assert_eq!(n!(0U256).overflowing_neg(), (n!(0), false));

assert_eq!(n!(1I256).overflowing_neg(), (n!(-1), false));
assert_eq!(I256::MIN.overflowing_neg(), (I256::MIN, true));

Source

pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool)

Returns a tuple of the left shift along with a boolean indicating whether rhs is greater than or equal to Self::BITS. If rhs >= Self::BITS then the returned value is self left-shifted by rhs % Self::BITS.

§Examples

Basic usage:

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

assert_eq!(n!(1U2048).overflowing_shl(1), (n!(2), false));
assert_eq!(n!(1U2048).overflowing_shl(2049), (n!(2), true));
assert_eq!(n!(1U2048).overflowing_shl(2048), (n!(1), true));

assert_eq!(n!(-2I2048).overflowing_shl(3), (n!(-16), false));
assert_eq!(n!(-2I2048).overflowing_shl(2051), (n!(-16), true));
assert_eq!(n!(-2I2048).overflowing_shl(2048), (n!(-2), true));

Source

pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool)

Returns a tuple of the right shift along with a boolean indicating whether rhs is greater than or equal to Self::BITS. If rhs >= Self::BITS then the returned value is self right-shifted by rhs % Self::BITS.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U1024, I1024};

assert_eq!(n!(1U1024).overflowing_shr(1), (n!(0), false));
assert_eq!(n!(2U1024).overflowing_shr(1025), (n!(1), true));
assert_eq!(U1024::MAX.overflowing_shr(1024), (U1024::MAX, true));
assert_eq!(U1024::MAX.overflowing_shr(1023), (n!(1), false));

assert_eq!(n!(-4I1024).overflowing_shr(2), (n!(-1), false));
assert_eq!(I1024::MIN.overflowing_shr(1023), (n!(-1), false));
assert_eq!(I1024::MIN.overflowing_shr(1024), (I1024::MIN, true));

Source

pub const fn overflowing_pow(self, exp: u32) -> (Self, bool)

Returns a tuple of the exponentiation 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!(2U512).overflowing_pow(10), (n!(1024), false));
assert_eq!(n!(2U512).overflowing_pow(512), (n!(0), true));

assert_eq!(n!(-7I512).overflowing_pow(3), (n!(-343), false));
assert_eq!(n!(-2I512).overflowing_pow(511), (I512::MIN, false));
assert_eq!(n!(2I512).overflowing_pow(511), (I512::MIN, true));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, 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.

Source

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));

Source

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));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<true, N, B, OM>

(Signed 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.

Source

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

Returns a tuple of the subtraction (with an unsigned 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::{U256, I256};

assert_eq!(n!(-1I256).overflowing_add_unsigned(n!(1)), (n!(0), false));
assert_eq!(I256::MAX.overflowing_add_unsigned(n!(1)), (I256::MIN, true));
assert_eq!(I256::MIN.overflowing_add_unsigned(U256::MAX), (I256::MAX, false));

Source

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

Returns a tuple of the subtraction (with an unsigned 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

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

assert_eq!(n!(1I512).overflowing_sub_unsigned(n!(1)), (n!(0), false));
assert_eq!(I512::MIN.overflowing_sub_unsigned(n!(1)), (I512::MAX, true));
assert_eq!(I512::MAX.overflowing_sub_unsigned(U512::MAX), (I512::MIN, false));

Source

pub const fn overflowing_abs(self) -> (Self, bool)

Returns a tuple of the absolute value of self along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned (this can only happen when self equals Self::MIN, in which case Self::MIN is returned).

§Examples

use bnum::prelude::*;
use bnum::types::I1024;

assert_eq!(n!(-123I1024).overflowing_abs(), (n!(123), false));
assert_eq!(n!(456I1024).overflowing_abs(), (n!(456), false));
assert_eq!(I1024::MIN.overflowing_abs(), (I1024::MIN, true));

Converts a string slice in a given base to an integer.

The string is expected to be an optional + (or - if the integer is signed) sign followed by digits. Leading and trailing whitespace represent an error. Underscores (which are accepted in Rust literals) also represent an error.

Digits are a subset of these characters, depending on radix:

0-9
a-z
A-Z

§Panics

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

§Examples

Basic usage:

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

assert_eq!(U512::from_str_radix("A", 16), Ok(n!(10)));
assert_eq!(I512::from_str_radix("-B", 16), Ok(n!(-11)));

Source

pub const fn from_ascii(src: &[u8]) -> Result<Self, ParseIntError>

Parses an integer from an ASCII-byte slice with decimal digits.

The characters are expected to be an optional + (or - if the integer is signed) sign followed by only digits. Leading and trailing non-digit characters (including whitespace) represent an error. Underscores (which are accepted in Rust literals) also represent an error.

§Examples

Basic usage:

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

assert_eq!(U512::from_ascii(b"+10"), Ok(n!(10U512)));
assert_eq!(I512::from_ascii(b"-1234"), Ok(n!(-1234I512)));

Source

pub const fn from_ascii_radix( src: &[u8], radix: u32, ) -> Result<Self, ParseIntError>

Parses an integer from an ASCII-byte slice with digits in a given base.

The characters are expected to be an optional + sign followed by only digits. Leading and trailing non-digit characters (including whitespace) represent an error. Underscores (which are accepted in Rust literals) also represent an error.

Digits are a subset of these characters, depending on radix:

0-9
a-z
A-Z

§Panics

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

§Examples

Basic usage:

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

assert_eq!(U512::from_ascii_radix(b"A", 16), Ok(n!(10)));
assert_eq!(I512::from_ascii_radix(b"-C", 16), Ok(n!(-12)));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, N, B, OM>

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

Source

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);

Source

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);

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Source

pub fn to_str_radix(&self, radix: u32) -> String

Available on crate feature alloc only.

Returns the integer as a string in the given radix.

§Panics

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

§Examples

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

let src = "abcdefghijklmnopqrstuvwxyz";
let n = U512::from_str_radix(src, 36).unwrap();
assert_eq!(n.to_str_radix(36), src);
 
let a: I512 = n!(-0o123456701234567);
assert_eq!(a.to_str_radix(8), "-123456701234567");

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::I512;
 
assert_eq!(n!(5U512).saturating_div(n!(2)), n!(2));
assert_eq!(I512::MIN.saturating_div(n!(-1)), I512::MAX);

Source

pub const fn saturating_div_euclid(self, rhs: Self) -> Self

Saturating Euclidean integer division. The only time the result can saturate is if the integer is signed, and self is Self::MIN and rhs is -1, in which case the result is Self::MAX.

§Panics

This function will panic if rhs is zero.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::I512;
 
assert_eq!(n!(19U512).saturating_div_euclid(n!(5)), n!(3));
assert_eq!(I512::MIN.saturating_div_euclid(n!(-1)), I512::MAX);

Source

pub const fn saturating_pow(self, exp: u32) -> Self

Saturating exponentiation. Computes self.pow(exp), returning Self::MAX if the result is too large to be represented by Self, or Self::MIN if the result is too small to be represented by Self.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U256, I256};
 
assert_eq!(n!(2U256).saturating_pow(8), n!(256));
assert_eq!(n!(2U256).saturating_pow(256), U256::MAX);
 
assert_eq!(n!(-2I256).saturating_pow(257), I256::MIN);
assert_eq!(n!(-2I256).saturating_pow(256), I256::MAX);

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, 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.

Source

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));

Source

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));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<true, N, B, OM>

(Signed 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.

Source

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

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

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{I512, U512};
 
assert_eq!(n!(-1I512).saturating_add_unsigned(n!(1)), n!(0));
assert_eq!(n!(0I512).saturating_add_unsigned(U512::MAX), I512::MAX);

Source

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

Saturating subtraction with an unsigned integer of the same bit width. Computes self + rhs, returning Self::MIN if the result is too small to be represented by Self.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::I1024;
 
assert_eq!(n!(1I1024).saturating_sub_unsigned(n!(1)), n!(0));
assert_eq!(I1024::MIN.saturating_sub_unsigned(n!(1)), I1024::MIN);

Source

pub const fn saturating_abs(self) -> Self

Computes the absolute value of self, returning Self::MAX if the result is too large to be represented by Self. The only time this can happen is if self is Self::MIN.

§Examples

use bnum::prelude::*;
use bnum::types::I2048;
 
assert_eq!(n!(-7I2048).saturating_abs(), n!(7));
assert_eq!(n!(22I2048).saturating_abs(), n!(22));
assert_eq!(I2048::MIN.saturating_abs(), I2048::MAX);

Source

pub const fn saturating_neg(self) -> Self

Saturating negation. Computes -self, returning Self::MAX if the result is too large to be represented by Self. The only time this can happen is if self is Self::MIN.

§Examples

use bnum::prelude::*;
use bnum::types::I256;
 
assert_eq!(n!(7I256).saturating_neg(), n!(-7));
assert_eq!(n!(-22I256).saturating_neg(), n!(22));
assert_eq!(I256::MIN.saturating_neg(), I256::MAX);

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

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.

Source

pub const fn strict_add(self, rhs: Self) -> Self

Strict integer addition. 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!(2U24).strict_add(n!(3U24)), n!(5U24));
assert_eq!(n!(-2I24).strict_add(n!(-3I24)), n!(-5I24));

The following examples will panic due to overflow:

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

Source

pub const fn strict_sub(self, rhs: Self) -> Self

Strict integer addition. 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(n!(2U24)), n!(3U24));
assert_eq!(n!(-5I24).strict_sub(n!(-2I24)), n!(-3I24));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::I512;
 
let _ = I512::MIN.strict_sub(n!(1));

Source

pub const fn strict_mul(self, rhs: Self) -> Self

Strict integer addition. 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!(2U24).strict_mul(n!(3U24)), n!(6U24));
assert_eq!(n!(-2I24).strict_mul(n!(3I24)), n!(-6I24));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::U1024;
 
let _ = U1024::MAX.strict_mul(n!(2));

Source

pub const fn strict_div(self, rhs: Self) -> Self

Strict integer addition. Computes self + rhs, panicking if overflow occurs.

§Panics

This function will panic if rhs is 0 or if overflow occurs, regardless of Self::OVERFLOW_MODE.

Overflow can only occur if the integers are signed, and self is Self::MIN and rhs is -1.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(9U24).strict_div(n!(4)), n!(2));
assert_eq!(n!(-9I24).strict_div(n!(4)), n!(-2));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::I2048;
 
let _ = I2048::MIN.strict_div(n!(-1));

The following example will panic due to division by zero:

use bnum::prelude::*;
 
let _ = n!(10U2048).strict_div(n!(0));

Source

pub const fn strict_div_euclid(self, rhs: Self) -> Self

Strict integer addition. Computes self + rhs, panicking if overflow occurs.

§Panics

This function will panic if rhs is 0 or if overflow occurs, regardless of Self::OVERFLOW_MODE.

Overflow can only occur if the integers are signed, and self is Self::MIN and rhs is -1.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(9U24).strict_div_euclid(n!(4)), n!(2));
assert_eq!(n!(-9I24).strict_div_euclid(n!(4)), n!(-3));

The following example will panic due to overflow:

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

The following example will panic due to division by zero:

use bnum::prelude::*;
 
let _ = n!(10U256).strict_div_euclid(n!(0));

Source

pub const fn strict_rem(self, rhs: Self) -> Self

Strict integer remainder. Computes self % rhs, panicking if the division results in overflow.

§Panics

This function will panic if rhs is 0 or if overflow occurs in the division, regardless of Self::OVERFLOW_MODE.

Overflow can only occur if the integers are signed, and self is Self::MIN and rhs is -1.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(9U24).strict_rem(n!(4)), n!(1));
assert_eq!(n!(-9I24).strict_rem(n!(4)), n!(-1));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::I512;
 
let _ = I512::MIN.strict_rem(n!(-1));

The following example will panic due to division by zero:

use bnum::prelude::*;
 
let _ = n!(10U512).strict_rem(n!(0));

Source

pub const fn strict_rem_euclid(self, rhs: Self) -> Self

Strict integer remainder. Computes self % rhs, panicking if the division results in overflow.

§Panics

This function will panic if rhs is 0 or if overflow occurs in the division, regardless of Self::OVERFLOW_MODE.

Overflow can only occur if the integers are signed, and self is Self::MIN and rhs is -1.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(9U24).strict_rem_euclid(n!(4)), n!(1));
assert_eq!(n!(-9I24).strict_rem_euclid(n!(4)), n!(3));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::I1024;
 
let _ = I1024::MIN.strict_rem_euclid(n!(-1));

The following example will panic due to division by zero:

use bnum::prelude::*;
 
let _ = n!(10U1024).strict_rem_euclid(n!(0));

Source

pub const fn strict_neg(self) -> Self

Strict negation. Computes -self, panicking if overflow occurs.

§Panics

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

For unsigned integers, overflow will occur unless self is 0. For signed integers, overflow will only occur if self is Self::MIN.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(0U24).strict_neg(), n!(0));
assert_eq!(n!(5I24).strict_neg(), n!(-5));

The following examples will panic due to overflow:

use bnum::prelude::*;
 
let _ = n!(1U256).strict_neg();

use bnum::types::I256;
 
let _ = I256::MIN.strict_neg();

Source

pub const fn strict_shl(self, rhs: u32) -> Self

Strict left shift. Computes self << rhs, panicking if rhs is greater than or equal to Self::BITS.

§Panics

This function will panic if rhs is greater than or equal to Self::BITS, regardless of Self::OVERFLOW_MODE.

§Examples

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

The following example will panic due to overflow:

use bnum::prelude::*;
 
let _ = n!(1U512).strict_shl(512);

Source

pub const fn strict_shr(self, rhs: u32) -> Self

Strict right shift. Computes self >> rhs, panicking if rhs is greater than or equal to Self::BITS.

§Panics

This function will panic if rhs is greater than or equal to Self::BITS, regardless of Self::OVERFLOW_MODE.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(17U24).strict_shr(2), n!(4U24));
assert_eq!(n!(-23I24).strict_shr(2), n!(-6I24));

The following example will panic due to overflow:

use bnum::types::I1024;
 
let _ = I1024::MAX.strict_shr(1024);

Source

pub const fn strict_pow(self, exp: u32) -> Self

Strict exponentiation. Computes self.pow(exp), panicking if overflow occurs.

§Panics

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

§Examples

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

The following example will panic due to overflow:

use bnum::prelude::*;
 
let _ = n!(2U2048).strict_pow(2048);

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, 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.

Source

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));

Source

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));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<true, N, B, OM>

(Signed 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.

Source

pub const fn strict_abs(self) -> Self

Strict absolute value. Computes self.abs(), panicking if overflow occurs.

§Panics

This function will panic if overflow occurs (i.e. if self is Self::MIN), regardless of Self::OVERFLOW_MODE.

§Examples

use bnum::prelude::*;
 
assert_eq!(n!(-5I24).strict_abs(), n!(5I24));

The following example will panic due to overflow:

use bnum::types::I512;
 
let _ = I512::MIN.strict_abs();

Source

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

Strict addition with an unsigned 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!(5I24).strict_add_unsigned(n!(2U24)), n!(7I24));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::I1024;
 
let _ = I1024::MAX.strict_add_unsigned(n!(1U1024));

Source

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

Strict subtraction by an unsigned 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!(5I24).strict_sub_unsigned(n!(7U24)), n!(-2I24));

The following example will panic due to overflow:

use bnum::prelude::*;
use bnum::types::I2048;
 
let _ = I2048::MIN.strict_sub_unsigned(n!(1U2048));

Source

pub const fn wrapping_add(self, rhs: Self) -> Self

Wrap integer addition. Computes self + rhs modulo Self::MAX + 1.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U1024, I1024};
 
assert_eq!(n!(1U1024).wrapping_add(n!(1)), n!(2));
assert_eq!(U1024::MAX.wrapping_add(n!(1)), n!(0));
 
assert_eq!(I1024::MIN.wrapping_add(n!(-1)), I1024::MAX);
assert_eq!(I1024::MAX.wrapping_add(n!(1)), I1024::MIN);

Source

pub const fn wrapping_sub(self, rhs: Self) -> Self

Wrap integer subtraction. Computes self - rhs modulo Self::MAX + 1.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U256, I256};
 
assert_eq!(n!(1U256).wrapping_sub(n!(1)), n!(0));
assert_eq!(n!(0U256).wrapping_sub(n!(1)), U256::MAX);
 
assert_eq!(I256::MIN.wrapping_sub(n!(1)), I256::MAX);
assert_eq!(I256::MAX.wrapping_sub(n!(-1)), I256::MIN);

Source

pub const fn wrapping_mul(self, rhs: Self) -> Self

Wrap integer multiplication. Computes self * rhs modulo Self::MAX + 1.

§Examples

Basic usage:

use bnum::prelude::*;
use bnum::types::{U512, I512};
 
assert_eq!(n!(1U512).wrapping_mul(n!(1)), n!(1));
assert_eq!(U512::power_of_two(511).wrapping_mul(n!(2)), n!(0));
 
assert_eq!(I512::MIN.wrapping_mul(n!(-1)), I512::MIN);
assert_eq!(I512::MIN.wrapping_mul(I512::MIN), n!(0));

Wrap integer remainder. This is equivalent to self.strict_rem(rhs).

§Panics

This function will panic if rhs is zero.

§Examples

use bnum::prelude::*;
 
use bnum::types::I256;
 
assert_eq!(n!(13U256).wrapping_rem(n!(5)), n!(3));
assert_eq!(I256::MIN.wrapping_rem(n!(-1)), n!(0));

Basic usage:

use bnum::prelude::*;
use bnum::types::I512;
 
assert_eq!(n!(2U512).wrapping_pow(10), n!(1024));
assert_eq!(n!(2U512).wrapping_pow(512), n!(0));
 
assert_eq!(n!(-2I512).wrapping_pow(512), n!(0));
assert_eq!(n!(2I512).wrapping_pow(511), I512::MIN);

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<false, N, B, OM>

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));

Source §

impl<const N: usize, const B: usize, const OM: u8> Integer<true, N, B, OM>

(Signed 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.

Source

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

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

§Examples

use bnum::prelude::*;
use bnum::types::{U512, I512};
 
assert_eq!(I512::MIN.wrapping_add_unsigned(U512::MAX), I512::MAX);
assert_eq!(n!(0I512).wrapping_add_unsigned(U512::MAX), n!(-1));

Source

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

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

§Examples

use bnum::prelude::*;
use bnum::types::{U1024, I1024};
 
assert_eq!(I1024::MAX.wrapping_sub_unsigned(U1024::MAX), I1024::MIN);
assert_eq!(n!(0I1024).wrapping_sub_unsigned(U1024::MAX), n!(1));

Source

pub const fn wrapping_abs(self) -> Self

Wrap absolute value. Computes self.abs() modulo Self::MAX + 1. Note that overflow can only occur when self is Self::MIN, in which case the function returns Self::MIN.

§Examples

use bnum::prelude::*;
use bnum::types::I2048;
 
assert_eq!(n!(-123I2048).wrapping_abs(), n!(123));
assert_eq!(I2048::MIN.wrapping_abs(), I2048::MIN);

Source §

impl<const S: bool, const N: usize, const B: usize, const OM: u8> Integer<S, N, B, OM>

Provides const function alternatives to methods of common traits, such as Add and BitOr. These functions will be removed once const traits are stabilized.