Struct apint::ApInt

pub struct ApInt { /* fields omitted */ }

An arbitrary precision integer with modulo arithmetics similar to machine integers.

Methods

impl ApInt

Constructors =======================================================================

pub fn from_bit<B>(bit: B) -> ApInt where
    B: Into<Bit>, 

Creates a new ApInt from the given Bit value with a bit width of 1.

This function is generic over types that are convertible to Bit such as bool.

pub fn from_i8(val: i8) -> ApInt

Creates a new ApInt from a given i8 value with a bit-width of 8.

pub fn from_u8(val: u8) -> ApInt

Creates a new ApInt from a given u8 value with a bit-width of 8.

pub fn from_i16(val: i16) -> ApInt

Creates a new ApInt from a given i16 value with a bit-width of 16.

pub fn from_u16(val: u16) -> ApInt

Creates a new ApInt from a given u16 value with a bit-width of 16.

pub fn from_i32(val: i32) -> ApInt

Creates a new ApInt from a given i32 value with a bit-width of 32.

pub fn from_u32(val: u32) -> ApInt

Creates a new ApInt from a given u32 value with a bit-width of 32.

pub fn from_i64(val: i64) -> ApInt

Creates a new ApInt from a given i64 value with a bit-width of 64.

pub fn from_u64(val: u64) -> ApInt

Creates a new ApInt from a given u64 value with a bit-width of 64.

pub fn from_i128(val: i128) -> ApInt

Creates a new ApInt from a given i128 value with a bit-width of 64.

pub fn from_u128(val: u128) -> ApInt

Creates a new ApInt from a given u128 value with a bit-width of 64.

pub fn zero(width: BitWidth) -> ApInt

Creates a new ApInt with the given bit width that represents zero.

pub fn one(width: BitWidth) -> ApInt

Creates a new ApInt with the given bit width that represents one.

pub fn all_unset(width: BitWidth) -> ApInt

Creates a new ApInt with the given bit width that has all bits unset.

Note: This is equal to calling ApInt::zero with the given width.

pub fn all_set(width: BitWidth) -> ApInt

Creates a new ApInt with the given bit width that has all bits set.

pub fn unsigned_min_value(width: BitWidth) -> ApInt

Returns the smallest unsigned ApInt that can be represented by the given BitWidth.

pub fn unsigned_max_value(width: BitWidth) -> ApInt

Returns the largest unsigned ApInt that can be represented by the given BitWidth.

pub fn signed_min_value(width: BitWidth) -> ApInt

Returns the smallest signed ApInt that can be represented by the given BitWidth.

pub fn signed_max_value(width: BitWidth) -> ApInt

Returns the largest signed ApInt that can be represented by the given BitWidth.

impl ApInt

pub fn assign(&mut self, rhs: &ApInt)

Assigns rhs to this ApInt.

This mutates digits and may affect the bitwidth of self which might result in an expensive operations.

After this operation rhs and self are equal to each other.

pub fn strict_assign(&mut self, rhs: &ApInt) -> Result<()>

Strictly assigns rhs to this ApInt.

After this operation rhs and self are equal to each other.

Note: Strict assigns protect against mutating the bit width of self and thus return an error instead of executing a probably expensive assign operation.

Errors

• If rhs and self have unmatching bit widths.

impl ApInt

Casting: Truncation & Extension =======================================================================

pub fn into_truncate<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to truncate this ApInt inplace to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into truncate.

Errors

• If the target_width is greater than the current width.

pub fn into_strict_truncate<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to strictly truncate this ApInt inplace to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into strict_truncate.

Errors

• If target_width is equal to or greater than the bitwidth of the given ApInt.

pub fn truncate<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Tries to truncate this ApInt inplace to the given target_width.

Note

• This is a no-op if self.width() and target_width are equal.
• This operation is inplace as long as self.width() and target_width require the same amount of digits for their representation.

Errors

• If the target_width is greater than the current width.

pub fn strict_truncate<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Tries to strictly truncate this ApInt inplace to the given target_width.

Note

• Strict truncation means that the resulting ApInt is ensured to have a smaller BitWidth than before this operation.
• For more details look into truncate.

Errors

• If target_width is equal to or greater than the bitwidth of the given ApInt.

pub fn into_zero_extend<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to zero-extend this ApInt inplace to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into zero_extend.

Errors

• If the target_width is less than the current width.

pub fn into_strict_zero_extend<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to strictly zero-extend this ApInt inplace to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into strict_zero_extend.

Errors

• If target_width is equal to or greater than the bitwidth of the given ApInt.

pub fn zero_extend<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Tries to zero-extend this ApInt inplace to the given target_width.

Note

• This is a no-op if self.width() and target_width are equal.
• This operation is inplace as long as self.width() and target_width require the same amount of digits for their representation.

Errors

• If the target_width is less than the current width.

pub fn strict_zero_extend<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Tries to strictly zero-extends this ApInt inplace to the given target_width.

Note

• Strict zero-extension means that the resulting ApInt is ensured to have a larger BitWidth than before this operation.
• For more details look into zero_extend.

Errors

• If target_width is equal to or greater than the bitwidth of the given ApInt.

pub fn into_sign_extend<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to sign-extend this ApInt inplace to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into sign_extend.

Errors

• If the target_width is less than the current width.

pub fn into_strict_sign_extend<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to strictly sign-extend this ApInt inplace to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into strict_sign_extend.

Errors

• If target_width is equal to or greater than the bitwidth of the given ApInt.

pub fn sign_extend<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Tries to sign-extend this ApInt inplace to the given target_width.

Note

• This is a no-op if self.width() and target_width are equal.
• This operation is inplace as long as self.width() and target_width require the same amount of digits for their representation.

Errors

• If the target_width is less than the current width.

pub fn strict_sign_extend<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Tries to strictly sign-extends this ApInt inplace to the given target_width.

Note

• Strict sign-extension means that the resulting ApInt is ensured to have a larger BitWidth than before this operation.
• For more details look into sign_extend.

Errors

• If target_width is equal to or greater than the bitwidth of the given ApInt.

pub fn into_zero_resize<W>(self, target_width: W) -> ApInt where
    W: Into<BitWidth>, 

Zero-resizes this ApInt to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into zero_resize.

pub fn into_strict_zero_resize<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to strictly zero-resize this ApInt to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into strict_zero_resize.

Errors

• If target_width is equal to the bitwidth of the given ApInt.

pub fn into_sign_resize<W>(self, target_width: W) -> ApInt where
    W: Into<BitWidth>, 

Sign-resizes this ApInt to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into sign_resize.

pub fn into_strict_sign_resize<W>(self, target_width: W) -> Result<ApInt> where
    W: Into<BitWidth>, 

Tries to strictly sign-resize this ApInt to the given target_width and returns the result.

Note

• This is useful for method chaining.
• For more details look into strict_sign_resize.

Errors

• If target_width is equal to the bitwidth of the given ApInt.

pub fn zero_resize<W>(&mut self, target_width: W) where
    W: Into<BitWidth>, 

Zero-resizes the given ApInt inplace.

Note

This operation will forward to

• truncate if target_width is less than or equal to the width of the given ApInt
• zero_extend otherwise

pub fn strict_zero_resize<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Strictly zero-resizes the given ApInt inplace.

Note

This operation will forward to

• strict_truncate if target_width is less than or equal to the width of the given ApInt
• strict_zero_extend otherwise

Errors

• If target_width is equal to the bitwidth of the given ApInt.

pub fn sign_resize<W>(&mut self, target_width: W) where
    W: Into<BitWidth>, 

Sign-resizes the given ApInt inplace.

Note

This operation will forward to

• truncate if target_width is less than or equal to the width of the given ApInt
• sign_extend otherwise

pub fn strict_sign_resize<W>(&mut self, target_width: W) -> Result<()> where
    W: Into<BitWidth>, 

Strictly sign-resizes the given ApInt inplace.

Note

This operation will forward to

• strict_truncate if target_width is less than or equal to the width of the given ApInt
• strict_sign_extend otherwise

Errors

• If target_width is equal to the bitwidth of the given ApInt.

impl ApInt

Utility & Helper Methods ===========================================================================

pub fn is_zero(&self) -> bool

Returns true if this ApInt represents the value zero (0).

Note

• Zero (0) is also called the additive neutral element.
• This operation is more efficient than comparing two instances of ApInt for the same reason.

pub fn is_one(&self) -> bool

Returns true if this ApInt represents the value one (1).

Note

• One (1) is also called the multiplicative neutral element.
• This operation is more efficient than comparing two instances of ApInt for the same reason.

pub fn is_even(&self) -> bool

Returns true if this ApInt represents an even number.

pub fn is_odd(&self) -> bool

Returns true if this ApInt represents an odd number.

impl ApInt

Bitwise Operations ===========================================================================

pub fn bitnot(&mut self)

Flip all bits of this ApInt inplace.

pub fn into_checked_bitand(self, rhs: &ApInt) -> Result<ApInt>

Tries to bit-and assign this ApInt inplace to rhs and returns the result.

Note: This forwards to checked_bitand.

Errors

If self and rhs have unmatching bit widths.

pub fn checked_bitand_assign(&mut self, rhs: &ApInt) -> Result<()>

Bit-and assigns all bits of this ApInt with the bits of rhs.

Note: This operation is inplace of self and won't allocate memory.

Errors

If self and rhs have unmatching bit widths.

pub fn into_checked_bitor(self, rhs: &ApInt) -> Result<ApInt>

Tries to bit-and assign this ApInt inplace to rhs and returns the result.

Note: This forwards to checked_bitor.

Errors

If self and rhs have unmatching bit widths.

pub fn checked_bitor_assign(&mut self, rhs: &ApInt) -> Result<()>

Bit-or assigns all bits of this ApInt with the bits of rhs.

Note: This operation is inplace of self and won't allocate memory.

Errors

If self and rhs have unmatching bit widths.

pub fn into_checked_bitxor(self, rhs: &ApInt) -> Result<ApInt>

Tries to bit-xor assign this ApInt inplace to rhs and returns the result.

Note: This forwards to checked_bitxor.

Errors

If self and rhs have unmatching bit widths.

pub fn checked_bitxor_assign(&mut self, rhs: &ApInt) -> Result<()>

Bit-xor assigns all bits of this ApInt with the bits of rhs.

Note: This operation is inplace of self and won't allocate memory.

Errors

If self and rhs have unmatching bit widths.

impl ApInt

Bitwise Access ===========================================================================

pub fn get_bit_at<P>(&self, pos: P) -> Result<Bit> where
    P: Into<BitPos>, 

Returns the bit at the given bit position pos.

This returns

• Bit::Set if the bit at pos is 1
• Bit::Unset otherwise

Errors

• If pos is not a valid bit position for the width of this ApInt.

pub fn set_bit_at<P>(&mut self, pos: P) -> Result<()> where
    P: Into<BitPos>, 

Sets the bit at the given bit position pos to one (1).

Errors

• If pos is not a valid bit position for the width of this ApInt.

pub fn unset_bit_at<P>(&mut self, pos: P) -> Result<()> where
    P: Into<BitPos>, 

Sets the bit at the given bit position pos to zero (0).

Errors

• If pos is not a valid bit position for the width of this ApInt.

pub fn flip_bit_at<P>(&mut self, pos: P) -> Result<()> where
    P: Into<BitPos>, 

Flips the bit at the given bit position pos.

Note

• If the bit at the given position was 0 it will be 1 after this operation and vice versa.

Errors

• If pos is not a valid bit position for the width of this ApInt.

pub fn set_all(&mut self)

Sets all bits of this ApInt to one (1).

pub fn is_all_set(&self) -> bool

Returns``trueif all bits in theApInt` are set.

pub fn unset_all(&mut self)

Sets all bits of this ApInt to zero (0).

pub fn is_all_unset(&self) -> bool

Returns true if all bits in the ApInt are unset.

pub fn flip_all(&mut self)

Flips all bits of this ApInt.

pub fn sign_bit(&self) -> Bit

Returns the sign bit of this ApInt.

Note: This is equal to the most significant bit of this ApInt.

pub fn set_sign_bit(&mut self)

Sets the sign bit of this ApInt to one (1).

pub fn unset_sign_bit(&mut self)

Sets the sign bit of this ApInt to zero (0).

pub fn flip_sign_bit(&mut self)

Flips the sign bit of this ApInt.

Note

• If the sign bit was 0 it will be 1 after this operation and vice versa.
• Depending on the interpretation of the ApInt this operation changes its signedness.

impl ApInt

Bitwise utility methods. ===========================================================================

pub fn count_ones(&self) -> usize

Returns the number of ones in the binary representation of this ApInt.

pub fn count_zeros(&self) -> usize

Returns the number of zeros in the binary representation of this ApInt.

pub fn leading_zeros(&self) -> usize

Returns the number of leading zeros in the binary representation of this ApInt.

pub fn trailing_zeros(&self) -> usize

Returns the number of trailing zeros in the binary representation of this ApInt.

impl ApInt

Relational Operations =======================================================================

pub fn checked_ult(&self, rhs: &ApInt) -> Result<bool>

Unsigned less-than (ult) comparison between self and rhs.

Note

• Returns Ok(true) if self < rhs.
• Interprets both ApInt instances as unsigned values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_ule(&self, rhs: &ApInt) -> Result<bool>

Unsigned less-equals (ule) comparison between self and rhs.

Note

• Returns Ok(true) if self <= rhs.
• Interprets both ApInt instances as unsigned values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_ugt(&self, rhs: &ApInt) -> Result<bool>

Unsigned greater-than (ugt) comparison between self and rhs.

Note

• Returns Ok(true) if self > rhs.
• Interprets both ApInt instances as unsigned values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_uge(&self, rhs: &ApInt) -> Result<bool>

Unsigned greater-equals (uge) comparison between self and rhs.

Note

• Returns Ok(true) if self >= rhs.
• Interprets both ApInt instances as unsigned values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_slt(&self, rhs: &ApInt) -> Result<bool>

Signed less-than (slt) comparison between self and rhs.

Note

• Returns Ok(true) if self < rhs.
• Interprets both ApInt instances as signed values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_sle(&self, rhs: &ApInt) -> Result<bool>

Signed less-equals (sle) comparison between self and rhs.

Note

• Returns Ok(true) if self <= rhs.
• Interprets both ApInt instances as signed values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_sgt(&self, rhs: &ApInt) -> Result<bool>

Signed greater-than (sgt) comparison between self and rhs.

Note

• Returns Ok(true) if self > rhs.
• Interprets both ApInt instances as signed values.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_sge(&self, rhs: &ApInt) -> Result<bool>

Signed greater-equals (sge) comparison between self and rhs.

Note

• Returns Ok(true) if self >= rhs.
• Interprets both ApInt instances as signed values.

Errors

• If self and rhs have unmatching bit widths.

impl ApInt

Arithmetic Operations =======================================================================

pub fn into_negate(self) -> ApInt

Negates this ApInt inplace and returns the result.

Note: This will not allocate memory.

pub fn negate(&mut self)

Negates this ApInt inplace.

Note: This will not allocate memory.

pub fn into_checked_add(self, rhs: &ApInt) -> Result<ApInt>

Adds rhs to self and returns the result.

Note: This will not allocate memory.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_add_assign(&mut self, rhs: &ApInt) -> Result<()>

Add-assigns rhs to self inplace.

Note: This will not allocate memory.

Errors

• If self and rhs have unmatching bit widths.

pub fn into_checked_sub(self, rhs: &ApInt) -> Result<ApInt>

Subtracts rhs from self and returns the result.

Note

In the low-level bit-wise representation there is no difference between signed and unsigned subtraction of fixed bit-width integers. (Cite: LLVM)

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_sub_assign(&mut self, rhs: &ApInt) -> Result<()>

Subtract-assigns rhs from self inplace.

Note

In the low-level bit-wise representation there is no difference between signed and unsigned subtraction of fixed bit-width integers. (Cite: LLVM)

Errors

• If self and rhs have unmatching bit widths.

pub fn into_checked_mul(self, rhs: &ApInt) -> Result<ApInt>

Multiplies rhs with self and returns the result.

Note

In the low-level bit-wise representation there is no difference between signed and unsigned multiplication of fixed bit-width integers. (Cite: LLVM)

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_mul_assign(&mut self, rhs: &ApInt) -> Result<()>

Multiply-assigns rhs to self inplace.

Note

In the low-level bit-wise representation there is no difference between signed and unsigned multiplication of fixed bit-width integers. (Cite: LLVM)

Errors

• If self and rhs have unmatching bit widths.

pub fn into_checked_udiv(self, rhs: &ApInt) -> Result<ApInt>

Divides self by rhs using unsigned interpretation and returns the result.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_udiv_assign(&mut self, rhs: &ApInt) -> Result<()>

Assignes self to the division of self by rhs using unsigned interpretation of the values.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn into_checked_sdiv(self, rhs: &ApInt) -> Result<ApInt>

Divides self by rhs using signed interpretation and returns the result.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_sdiv_assign(&mut self, rhs: &ApInt) -> Result<()>

Assignes self to the division of self by rhs using signed interpretation of the values.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn into_checked_urem(self, rhs: &ApInt) -> Result<ApInt>

Calculates the unsigned remainder of self by rhs and returns the result.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_urem_assign(&mut self, rhs: &ApInt) -> Result<()>

Assignes self to the unsigned remainder of self by rhs.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn into_checked_srem(self, rhs: &ApInt) -> Result<ApInt>

Calculates the signed remainder of self by rhs and returns the result.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

pub fn checked_srem_assign(&mut self, rhs: &ApInt) -> Result<()>

Assignes self to the signed remainder of self by rhs.

Note

• This operation will not allocate memory and computes inplace of self.
• In the low-level machine abstraction signed division and unsigned division are two different operations.

Errors

• If self and rhs have unmatching bit widths.

impl ApInt

Shift Operations =======================================================================

pub fn checked_shl_assign<S>(&mut self, shift_amount: S) -> Result<()> where
    S: Into<ShiftAmount>, 

Shift this ApInt left by the given shift_amount bits.

This operation is inplace and will not allocate memory.

Errors

• If the given shift_amount is invalid for the bit width of this ApInt.

pub fn into_checked_shl<S>(self, shift_amount: S) -> Result<ApInt> where
    S: Into<ShiftAmount>, 

Shift this ApInt left by the given shift_amount bits and returns the result.

This operation is inplace and will not allocate memory.

Errors

• If the given shift_amount is invalid for the bit width of this ApInt.

pub fn checked_lshr_assign<S>(&mut self, shift_amount: S) -> Result<()> where
    S: Into<ShiftAmount>, 

Logically right-shifts this ApInt by the given shift_amount bits.

This operation is inplace and will not allocate memory.

Errors

• If the given shift_amount is invalid for the bit width of this ApInt.

pub fn into_checked_lshr<S>(self, shift_amount: S) -> Result<ApInt> where
    S: Into<ShiftAmount>, 

Logically right-shifts this ApInt by the given shift_amount bits and returns the result.

This operation is inplace and will not allocate memory.

Errors

• If the given shift_amount is invalid for the bit width of this ApInt.

pub fn checked_ashr_assign<S>(&mut self, shift_amount: S) -> Result<()> where
    S: Into<ShiftAmount>, 

Arithmetically right-shifts this ApInt by the given shift_amount bits.

This operation is inplace and will not allocate memory.

Note

Arithmetic shifting copies the sign bit instead of filling up with zeros.

Errors

• If the given shift_amount is invalid for the bit width of this ApInt.

pub fn into_checked_ashr<S>(self, shift_amount: S) -> Result<ApInt> where
    S: Into<ShiftAmount>, 

Arithmetically right-shifts this ApInt by the given shift_amount bits and returns the result.

This operation is inplace and will not allocate memory.

Note

Arithmetic shifting copies the sign bit instead of filling up with zeros.

Errors

• If the given shift_amount is invalid for the bit width of this ApInt.

impl ApInt

Deserialization =======================================================================

pub fn from_str_radix<R, S>(radix: R, input: S) -> Result<ApInt> where
    R: Into<Radix>,
    S: AsRef<str>, 

Parses the given input String with the given Radix and returns an ApInt with the given target_width BitWidth.

Note: The given input is parsed as big-endian value. This means, the most significant bit (MSB) is the leftst bit in the string representation provided by the user.

The string is assumed to contain no whitespace and contain only values within a subset of the range of 0..9 and a..z depending on the given radix.

The string is assumed to have no sign as ApInt does not handle signdness.

Errors

• If input is empty.
• If input is not a valid representation for an ApInt for the given radix.
• If input has trailing zero characters (0), e.g. "0042" instead of "42".
• If input represents an ApInt value that does not fit into the given target_bitwidth.

Examples

let a = ApInt::from_str_radix(10, "42");      // ok
let b = ApInt::from_str_radix( 2, "1011011"); // ok (dec. = 91)
let c = ApInt::from_str_radix(16, "ffcc00");  // ok (dec. = 16763904)
let c = ApInt::from_str_radix(10, "256");     // Error: 256 does not fit within 8 bits!
let d = ApInt::from_str_radix( 2, "01020");   // Error: Invalid digit '2' at position 3 for given radix.
let e = ApInt::from_str_radix(16, "hello");   // Error: "hello" is not a valid ApInt representation!

impl ApInt

Serialization =======================================================================

pub fn as_string_with_radix<R>(&self, radix: R) -> String where
    R: Into<Radix>, 

Returns a String representation of the binary encoded ApInt for the given Radix.

impl ApInt

Operations to lossful cast to primitive number types. =======================================================================

pub fn resize_to_bool(&self) -> bool

Resizes this ApInt to a bool primitive type.

Bits in this ApInt that are not within the bounds of the bool are being ignored.

Note

• Basically this returns true if the least significant bit of this ApInt is 1 and false otherwise.

pub fn resize_to_i8(&self) -> i8

Resizes this ApInt to a i8 primitive type.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 8 bits the value is sign extended to the target bit width.
• All bits but the least significant 8 bits are being ignored by this operation to construct the result.

pub fn resize_to_u8(&self) -> u8

Resizes this ApInt to a u8 primitive type.

Note

• All bits but the least significant 8 bits are being ignored by this operation to construct the result.

pub fn resize_to_i16(&self) -> i16

Resizes this ApInt to a i16 primitive type.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 16 bits the value is sign extended to the target bit width.
• All bits but the least significant 16 bits are being ignored by this operation to construct the result.

pub fn resize_to_u16(&self) -> u16

Resizes this ApInt to a u16 primitive type.

Note

• All bits but the least significant 16 bits are being ignored by this operation to construct the result.

pub fn resize_to_i32(&self) -> i32

Resizes this ApInt to a i32 primitive type.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 32 bits the value is sign extended to the target bit width.
• All bits but the least significant 32 bits are being ignored by this operation to construct the result.

pub fn resize_to_u32(&self) -> u32

Resizes this ApInt to a u32 primitive type.

Note

• All bits but the least significant 32 bits are being ignored by this operation to construct the result.

pub fn resize_to_i64(&self) -> i64

Resizes this ApInt to a i64 primitive type.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 64 bits the value is sign extended to the target bit width.
• All bits but the least significant 64 bits are being ignored by this operation to construct the result.

pub fn resize_to_u64(&self) -> u64

Resizes this ApInt to a u64 primitive type.

Note

• All bits but the least significant 64 bits are being ignored by this operation to construct the result.

pub fn resize_to_i128(&self) -> i128

Resizes this ApInt to a i128 primitive type.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 128 bits the value is sign extended to the target bit width.
• All bits but the least significant 128 bits are being ignored by this operation to construct the result.

pub fn resize_to_u128(&self) -> u128

Resizes this ApInt to a u128 primitive type.

Note

• All bits but the least significant 128 bits are being ignored by this operation to construct the result.

impl ApInt

Operations to lossless cast to primitive number types. =======================================================================

pub fn try_to_bool(&self) -> Result<bool>

Tries to represent the value of this ApInt as a bool.

Note

This returns true if the value represented by this ApInt is 1, returns false if the value represented by this ApInt is 0 and returns an error otherwise.

Errors

• If the value represented by this ApInt can not be represented by a bool.

pub fn try_to_i8(&self) -> Result<i8>

Tries to represent the value of this ApInt as a i8.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 8 bits the value is sign extended to the target bit width.
• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u8.

Errors

• If the value represented by this ApInt can not be represented by a i8.

pub fn try_to_u8(&self) -> Result<u8>

Tries to represent the value of this ApInt as a u8.

Note

• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u8.

Errors

• If the value represented by this ApInt can not be represented by a u8.

pub fn try_to_i16(&self) -> Result<i16>

Tries to represent the value of this ApInt as a i16.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 16 bits the value is sign extended to the target bit width.
• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u16.

Errors

• If the value represented by this ApInt can not be represented by a i16.

pub fn try_to_u16(&self) -> Result<u16>

Tries to represent the value of this ApInt as a u16.

Note

• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u16.

Errors

• If the value represented by this ApInt can not be represented by a u16.

pub fn try_to_i32(&self) -> Result<i32>

Tries to represent the value of this ApInt as a i32.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 32 bits the value is sign extended to the target bit width.
• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u32.

Errors

• If the value represented by this ApInt can not be represented by a i32.

pub fn try_to_u32(&self) -> Result<u32>

Tries to represent the value of this ApInt as a u32.

Note

• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u32.

Errors

• If the value represented by this ApInt can not be represented by a u32.

pub fn try_to_i64(&self) -> Result<i64>

Tries to represent the value of this ApInt as a i64.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 64 bits the value is sign extended to the target bit width.
• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u64.

Errors

• If the value represented by this ApInt can not be represented by a i64.

pub fn try_to_u64(&self) -> Result<u64>

Tries to represent the value of this ApInt as a u64.

Note

• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u64.

Errors

• If the value represented by this ApInt can not be represented by a u64.

pub fn try_to_i128(&self) -> Result<i128>

Tries to represent the value of this ApInt as a i128.

Note

• This operation will conserve the signedness of the value. This means that for ApInt instances with a BitWidth less than 128 bits the value is sign extended to the target bit width.
• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u128.

Errors

• If the value represented by this ApInt can not be represented by a i128.

pub fn try_to_u128(&self) -> Result<u128>

Tries to represent the value of this ApInt as a u128.

Note

• This conversion is possible as long as the value represented by this ApInt does not exceed the maximum value of u128.

Complexity

• 𝒪(n) where n is the number of digits of this ApInt.

Errors

• If the value represented by this ApInt can not be represented by a u128.

impl ApInt

Random Utilities using rand crate. =======================================================================

pub fn random_with_width(width: BitWidth) -> ApInt

Creates a new ApInt with the given BitWidth and random Digits.

pub fn random_with_width_using<R>(width: BitWidth, rng: &mut R) -> ApInt where
    R: Rng, 

Creates a new ApInt with the given BitWidth and random Digits using the given random number generator.

Note: This is useful for cryptographic or testing purposes.

pub fn randomize(&mut self)

Randomizes the digits of this ApInt inplace.

This won't change its BitWidth.

pub fn randomize_using<R>(&mut self, rng: &mut R) where
    R: Rng, 

Randomizes the digits of this ApInt inplace using the given random number generator.

This won't change its BitWidth.

Trait Implementations

impl Drop for ApInt

fn drop(&mut self)

Executes the destructor for this type.

impl<B> From<B> for ApInt where
    B: Into<Bit>, 

fn from(bit: B) -> ApInt

Performs the conversion.

impl From<u8> for ApInt

fn from(val: u8) -> ApInt

Performs the conversion.

impl From<i8> for ApInt

fn from(val: i8) -> ApInt

Performs the conversion.

impl From<u16> for ApInt

fn from(val: u16) -> ApInt

Performs the conversion.

impl From<i16> for ApInt

fn from(val: i16) -> ApInt

Performs the conversion.

impl From<u32> for ApInt

fn from(val: u32) -> ApInt

Performs the conversion.

impl From<i32> for ApInt

fn from(val: i32) -> ApInt

Performs the conversion.

impl From<u64> for ApInt

fn from(val: u64) -> ApInt

Performs the conversion.

impl From<i64> for ApInt

fn from(val: i64) -> ApInt

Performs the conversion.

impl From<u128> for ApInt

fn from(val: u128) -> ApInt

Performs the conversion.

impl From<i128> for ApInt

fn from(val: i128) -> ApInt

Performs the conversion.

impl From<[i64; 2]> for ApInt

fn from(val: [i64; 2]) -> ApInt

Performs the conversion.

impl From<[u64; 2]> for ApInt

fn from(val: [u64; 2]) -> ApInt

Performs the conversion.

impl From<[i64; 3]> for ApInt

fn from(val: [i64; 3]) -> ApInt

Performs the conversion.

impl From<[u64; 3]> for ApInt

fn from(val: [u64; 3]) -> ApInt

Performs the conversion.

impl From<[i64; 4]> for ApInt

fn from(val: [i64; 4]) -> ApInt

Performs the conversion.

impl From<[u64; 4]> for ApInt

fn from(val: [u64; 4]) -> ApInt

Performs the conversion.

impl From<[i64; 5]> for ApInt

fn from(val: [i64; 5]) -> ApInt

Performs the conversion.

impl From<[u64; 5]> for ApInt

fn from(val: [u64; 5]) -> ApInt

Performs the conversion.

impl From<[i64; 6]> for ApInt

fn from(val: [i64; 6]) -> ApInt

Performs the conversion.

impl From<[u64; 6]> for ApInt

fn from(val: [u64; 6]) -> ApInt

Performs the conversion.

impl From<[i64; 7]> for ApInt

fn from(val: [i64; 7]) -> ApInt

Performs the conversion.

impl From<[u64; 7]> for ApInt

fn from(val: [u64; 7]) -> ApInt

Performs the conversion.

impl From<[i64; 8]> for ApInt

fn from(val: [i64; 8]) -> ApInt

Performs the conversion.

impl From<[u64; 8]> for ApInt

fn from(val: [u64; 8]) -> ApInt

Performs the conversion.

impl From<[i64; 16]> for ApInt

fn from(val: [i64; 16]) -> ApInt

Performs the conversion.

impl From<[u64; 16]> for ApInt

fn from(val: [u64; 16]) -> ApInt

Performs the conversion.

impl From<[i64; 32]> for ApInt

fn from(val: [i64; 32]) -> ApInt

Performs the conversion.

impl From<[u64; 32]> for ApInt

fn from(val: [u64; 32]) -> ApInt

Performs the conversion.

impl Clone for ApInt

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ApInt

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for ApInt

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Width for ApInt

fn width(&self) -> BitWidth

Returns the BitWidth of this ApInt.

impl Not for ApInt

type Output = ApInt

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<'a> BitAnd<&'a ApInt> for ApInt

type Output = ApInt

The resulting type after applying the & operator.

fn bitand(self, rhs: &'a ApInt) -> Self::Output

Performs the & operation.

impl<'a, 'b> BitAnd<&'a ApInt> for &'b ApInt

type Output = ApInt

The resulting type after applying the & operator.

fn bitand(self, rhs: &'a ApInt) -> Self::Output

Performs the & operation.

impl<'a, 'b> BitAnd<&'a ApInt> for &'b mut ApInt

type Output = ApInt

The resulting type after applying the & operator.

fn bitand(self, rhs: &'a ApInt) -> Self::Output

Performs the & operation.

impl<'a> BitOr<&'a ApInt> for ApInt

type Output = ApInt

The resulting type after applying the | operator.

fn bitor(self, rhs: &'a ApInt) -> Self::Output

Performs the | operation.

impl<'a, 'b> BitOr<&'a ApInt> for &'b ApInt

type Output = ApInt

The resulting type after applying the | operator.

fn bitor(self, rhs: &'a ApInt) -> Self::Output

Performs the | operation.

impl<'a, 'b> BitOr<&'a ApInt> for &'b mut ApInt

type Output = ApInt

The resulting type after applying the | operator.

fn bitor(self, rhs: &'a ApInt) -> Self::Output

Performs the | operation.

impl<'a> BitXor<&'a ApInt> for ApInt

type Output = ApInt

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: &'a ApInt) -> Self::Output

Performs the ^ operation.

impl<'a, 'b> BitXor<&'a ApInt> for &'b ApInt

type Output = ApInt

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: &'a ApInt) -> Self::Output

Performs the ^ operation.

impl<'a, 'b> BitXor<&'a ApInt> for &'b mut ApInt

type Output = ApInt

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: &'a ApInt) -> Self::Output

Performs the ^ operation.

impl<'a> BitAndAssign<&'a ApInt> for ApInt

fn bitand_assign(&mut self, rhs: &'a ApInt)

Performs the &= operation.

impl<'a> BitOrAssign<&'a ApInt> for ApInt

fn bitor_assign(&mut self, rhs: &'a ApInt)

Performs the |= operation.

impl<'a> BitXorAssign<&'a ApInt> for ApInt

fn bitxor_assign(&mut self, rhs: &'a ApInt)

Performs the ^= operation.

impl PartialEq for ApInt

fn eq(&self, other: &ApInt) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Eq for ApInt

impl Neg for ApInt

type Output = ApInt

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<'a> Neg for &'a ApInt

type Output = ApInt

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<'a> Neg for &'a mut ApInt

type Output = &'a mut ApInt

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<'a> Add<&'a ApInt> for ApInt

type Output = ApInt

The resulting type after applying the + operator.

fn add(self, rhs: &'a ApInt) -> Self::Output

Performs the + operation.

impl<'a, 'b> Add<&'a ApInt> for &'b ApInt

type Output = ApInt

The resulting type after applying the + operator.

fn add(self, rhs: &'a ApInt) -> Self::Output

Performs the + operation.

impl<'a> AddAssign<&'a ApInt> for ApInt

fn add_assign(&mut self, rhs: &'a ApInt)

Performs the += operation.

impl<'a> Sub<&'a ApInt> for ApInt

type Output = ApInt

The resulting type after applying the - operator.

fn sub(self, rhs: &'a ApInt) -> Self::Output

Performs the - operation.

impl<'a, 'b> Sub<&'a ApInt> for &'b ApInt

type Output = ApInt

The resulting type after applying the - operator.

fn sub(self, rhs: &'a ApInt) -> Self::Output

Performs the - operation.

impl<'a> SubAssign<&'a ApInt> for ApInt

fn sub_assign(&mut self, rhs: &'a ApInt)

Performs the -= operation.

impl<'a> Mul<&'a ApInt> for ApInt

type Output = ApInt

The resulting type after applying the * operator.

fn mul(self, rhs: &'a ApInt) -> Self::Output

Performs the * operation.

impl<'a, 'b> Mul<&'a ApInt> for &'b ApInt

type Output = ApInt

The resulting type after applying the * operator.

fn mul(self, rhs: &'a ApInt) -> Self::Output

Performs the * operation.

impl<'a> MulAssign<&'a ApInt> for ApInt

fn mul_assign(&mut self, rhs: &'a ApInt)

Performs the *= operation.

impl Serialize for ApInt

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'de> Deserialize<'de> for ApInt

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Send for ApInt

ApInt is safe to send between threads since it does not own aliasing memory and has no reference counting mechanism like Rc.

impl Sync for ApInt

ApInt is safe to share between threads since it does not own aliasing memory and has no mutable internal state like Cell or RefCell.

impl From<ApInt> for UInt

fn from(value: ApInt) -> UInt

Performs the conversion.

impl From<ApInt> for Int

fn from(value: ApInt) -> Int

Performs the conversion.