Type Alias Int 

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

Signed 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 Int<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> Int<N, B, OM>

(Signed 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_unsigned(self, rhs: Uint<N, B, OM>) -> Option<Self>

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

Examples

Basic usage:

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

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

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

Examples

Basic usage:

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

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

Checked absolute value. Computes the absolute value of self, returning None if self is equal to Self::MIN.

Examples

Basic usage:

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

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

(Signed integers only.) Mathematical methods.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

(Signed integers only.) Unchecked arithmetic methods which act on self: self.unchecked_.... Each method results in undefined behavior if overflow occurs (i.e. when the checked equivalent would return None). These methods should therefore only be used when it can be guaranteed that overflow will not occur. If you want to avoid panicking in arithmetic in debug mode, use the wrapping equivalents instead.

pub const unsafe fn unchecked_neg(self) -> Self

Unchecked integer negation. Computes -self without checking for overflow, resulting in undefined behavior if overflow occurs.

a.unchecked_neg() is equivalent to a.checked_neg().unwrap_unchecked().

Safety

This results in undefined behaviour if overflow occurs, i.e. when checked_neg would return None. This can only occur if self is Self::MIN.

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

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

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

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

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

pub const fn neg(self) -> Self

Trait Implementations

impl<const N: usize, const B: usize, const OM: u8> Neg for &Int<N, B, OM>

type Output = Integer<true, N, B, OM>

The resulting type after applying the - operator.

fn neg(self) -> Int<N, B, OM>

Performs the unary - operation.

impl<const N: usize, const B: usize, const OM: u8> Neg for Int<N, B, OM>

type Output = Integer<true, N, B, OM>

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl<const N: usize, const B: usize, const OM: u8> Signed for Int<N, B, OM>

Available on crate feature numtraits only.

fn abs(&self) -> Self

Computes the absolute value.

fn abs_sub(&self, other: &Self) -> Self

The positive difference of two numbers.

fn signum(&self) -> Self

Returns the sign of the number.

fn is_positive(&self) -> bool

Returns true if the number is positive and false if the number is zero or negative.

fn is_negative(&self) -> bool

Returns true if the number is negative and false if the number is zero or positive.

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

type Error = TryFromIntError

The type returned in the event of a conversion error.

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

Performs the conversion.