pub struct ApInt { /* fields omitted */ }
An arbitrary precision integer with modulo arithmetics similar to machine integers.
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
.
Creates a new ApInt
from a given i8
value with a bit-width of 8.
Creates a new ApInt
from a given u8
value with a bit-width of 8.
Creates a new ApInt
from a given i16
value with a bit-width of 16.
Creates a new ApInt
from a given u16
value with a bit-width of 16.
Creates a new ApInt
from a given i32
value with a bit-width of 32.
Creates a new ApInt
from a given u32
value with a bit-width of 32.
Creates a new ApInt
from a given i64
value with a bit-width of 64.
Creates a new ApInt
from a given u64
value with a bit-width of 64.
Creates a new ApInt
from a given i128
value with a bit-width of 128.
Creates a new ApInt
from a given u128
value with a bit-width of 128.
Creates a new ApInt
with the given bit width that represents zero.
Creates a new ApInt
with the given bit width that represents one.
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
.
Creates a new ApInt
with the given bit width that has all bits set.
Returns the smallest unsigned ApInt
that can be represented by the given BitWidth
.
Returns the largest unsigned ApInt
that can be represented by the given BitWidth
.
Returns the smallest signed ApInt
that can be represented by the given BitWidth
.
Returns the largest signed ApInt
that can be represented by the given BitWidth
.
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.
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.
- If
rhs
and self
have unmatching bit widths.
Tries to truncate this ApInt
inplace to the given target_width
and returns the result.
- This is useful for method chaining.
- For more details look into
truncate
.
- If the
target_width
is greater than the current width.
Tries to truncate this ApInt
inplace to the given target_width
.
- 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.
- If the
target_width
is greater than the current width.
Tries to zero-extend this ApInt
inplace to the given target_width
and returns the result.
- This is useful for method chaining.
- For more details look into
zero_extend
.
- If the
target_width
is less than the current width.
Tries to zero-extend this ApInt
inplace to the given target_width
.
- 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.
- If the
target_width
is less than the current width.
Tries to sign-extend this ApInt
inplace to the given target_width
and returns the result.
- This is useful for method chaining.
- For more details look into
sign_extend
.
- If the
target_width
is less than the current width.
Tries to sign-extend this ApInt
inplace to the given target_width
.
- 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.
- If the
target_width
is less than the current width.
Zero-resizes this ApInt
to the given target_width
and returns the result.
- This is useful for method chaining.
- For more details look into
zero_resize
.
Sign-resizes this ApInt
to the given target_width
and returns the result.
- This is useful for method chaining.
- For more details look into
sign_resize
.
Zero-resizes the given ApInt
inplace.
This operation will forward to
truncate
if target_width
is less than or equal to the width of
the given ApInt
zero_extend
otherwise
Sign-resizes the given ApInt
inplace.
This operation will forward to
truncate
if target_width
is less than or equal to the width of
the given ApInt
sign_extend
otherwise
Returns true
if this ApInt
represents the value zero (0
).
- Zero (
0
) is also called the additive neutral element.
- This operation is more efficient than comparing two instances
of
ApInt
for the same reason.
Returns true
if this ApInt
represents the value one (1
).
- One (
1
) is also called the multiplicative neutral element.
- This operation is more efficient than comparing two instances
of
ApInt
for the same reason.
Returns true
if this ApInt
represents an even number.
Returns true
if this ApInt
represents an odd number.
Flips all bits of self
and returns the result.
Flip all bits of this ApInt
inplace.
Tries to bit-and assign this ApInt
inplace to rhs
and returns the result.
Note: This forwards to
checked_bitand
.
If self
and rhs
have unmatching bit widths.
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.
If self
and rhs
have unmatching bit widths.
Tries to bit-and assign this ApInt
inplace to rhs
and returns the result.
Note: This forwards to
checked_bitor
.
If self
and rhs
have unmatching bit widths.
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.
If self
and rhs
have unmatching bit widths.
Tries to bit-xor assign this ApInt
inplace to rhs
and returns the result.
Note: This forwards to
checked_bitxor
.
If self
and rhs
have unmatching bit widths.
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.
If self
and rhs
have unmatching bit widths.
Returns the bit at the given bit position pos
.
This returns
Bit::Set
if the bit at pos
is 1
Bit::Unset
otherwise
- If
pos
is not a valid bit position for the width of this ApInt
.
Sets the bit at the given bit position pos
to one (1
).
- If
pos
is not a valid bit position for the width of this ApInt
.
Sets the bit at the given bit position pos
to zero (0
).
- If
pos
is not a valid bit position for the width of this ApInt
.
Flips the bit at the given bit position pos
.
- If the bit at the given position was
0
it will be 1
after this operation and vice versa.
- If
pos
is not a valid bit position for the width of this ApInt
.
Sets all bits of this ApInt
to one (1
).
Returns``trueif all bits in the
ApInt` are set.
Sets all bits of this ApInt
to zero (0
).
Returns true
if all bits in the ApInt
are unset.
Flips all bits of this ApInt
.
Returns the sign bit of this ApInt
.
Note: This is equal to the most significant bit of this ApInt
.
Sets the sign bit of this ApInt
to one (1
).
Sets the sign bit of this ApInt
to zero (0
).
Flips the sign bit of this ApInt
.
- 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.
Returns the number of ones in the binary representation of this ApInt
.
Returns the number of zeros in the binary representation of this ApInt
.
Returns the number of leading zeros in the binary representation of this ApInt
.
Returns the number of trailing zeros in the binary representation of this ApInt
.
Unsigned less-than (ult
) comparison between self
and rhs
.
- Returns
Ok(true)
if self < rhs
.
- Interprets both
ApInt
instances as unsigned values.
- If
self
and rhs
have unmatching bit widths.
Unsigned less-equals (ule
) comparison between self
and rhs
.
- Returns
Ok(true)
if self <= rhs
.
- Interprets both
ApInt
instances as unsigned values.
- If
self
and rhs
have unmatching bit widths.
Unsigned greater-than (ugt
) comparison between self
and rhs
.
- Returns
Ok(true)
if self > rhs
.
- Interprets both
ApInt
instances as unsigned values.
- If
self
and rhs
have unmatching bit widths.
Unsigned greater-equals (uge
) comparison between self
and rhs
.
- Returns
Ok(true)
if self >= rhs
.
- Interprets both
ApInt
instances as unsigned values.
- If
self
and rhs
have unmatching bit widths.
Signed less-than (slt
) comparison between self
and rhs
.
- Returns
Ok(true)
if self < rhs
.
- Interprets both
ApInt
instances as signed values.
- If
self
and rhs
have unmatching bit widths.
Signed less-equals (sle
) comparison between self
and rhs
.
- Returns
Ok(true)
if self <= rhs
.
- Interprets both
ApInt
instances as signed values.
- If
self
and rhs
have unmatching bit widths.
Signed greater-than (sgt
) comparison between self
and rhs
.
- Returns
Ok(true)
if self > rhs
.
- Interprets both
ApInt
instances as signed values.
- If
self
and rhs
have unmatching bit widths.
Signed greater-equals (sge
) comparison between self
and rhs
.
- Returns
Ok(true)
if self >= rhs
.
- Interprets both
ApInt
instances as signed values.
- If
self
and rhs
have unmatching bit widths.
Negates this ApInt
inplace and returns the result.
Note: This will not allocate memory.
Negates this ApInt
inplace.
Note: This will not allocate memory.
Adds rhs
to self
and returns the result.
Note: This will not allocate memory.
- If
self
and rhs
have unmatching bit widths.
Add-assigns rhs
to self
inplace.
Note: This will not allocate memory.
- If
self
and rhs
have unmatching bit widths.
Subtracts rhs
from self
and returns the result.
In the low-level bit-wise representation there is no difference between signed
and unsigned subtraction of fixed bit-width integers. (Cite: LLVM)
- If
self
and rhs
have unmatching bit widths.
Subtract-assigns rhs
from self
inplace.
In the low-level bit-wise representation there is no difference between signed
and unsigned subtraction of fixed bit-width integers. (Cite: LLVM)
- If
self
and rhs
have unmatching bit widths.
Multiplies rhs
with self
and returns the result.
In the low-level bit-wise representation there is no difference between signed
and unsigned multiplication of fixed bit-width integers. (Cite: LLVM)
- If
self
and rhs
have unmatching bit widths.
Multiply-assigns rhs
to self
inplace.
In the low-level bit-wise representation there is no difference between signed
and unsigned multiplication of fixed bit-width integers. (Cite: LLVM)
- If
self
and rhs
have unmatching bit widths.
Divides self
by rhs
using unsigned interpretation and returns the result.
- 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.
- If
self
and rhs
have unmatching bit widths.
Assignes self
to the division of self
by rhs
using unsigned
interpretation of the values.
- 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.
- If
self
and rhs
have unmatching bit widths.
Divides self
by rhs
using signed interpretation and returns the result.
- 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.
- If
self
and rhs
have unmatching bit widths.
Assignes self
to the division of self
by rhs
using signed
interpretation of the values.
- 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.
- If
self
and rhs
have unmatching bit widths.
Calculates the unsigned remainder of self
by rhs
and returns the result.
- 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.
- If
self
and rhs
have unmatching bit widths.
Assignes self
to the unsigned remainder of self
by rhs
.
- 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.
- If
self
and rhs
have unmatching bit widths.
Calculates the signed remainder of self
by rhs
and returns the result.
- 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.
- If
self
and rhs
have unmatching bit widths.
Assignes self
to the signed remainder of self
by rhs
.
- 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.
- If
self
and rhs
have unmatching bit widths.
Shift this ApInt
left by the given shift_amount
bits.
This operation is inplace and will not allocate memory.
- If the given
shift_amount
is invalid for the bit width of this ApInt
.
Shift this ApInt
left by the given shift_amount
bits and returns the result.
This operation is inplace and will not allocate memory.
- If the given
shift_amount
is invalid for the bit width of this ApInt
.
Logically right-shifts this ApInt
by the given shift_amount
bits.
This operation is inplace and will not allocate memory.
- If the given
shift_amount
is invalid for the bit width of this ApInt
.
Logically right-shifts this ApInt
by the given shift_amount
bits
and returns the result.
This operation is inplace and will not allocate memory.
- If the given
shift_amount
is invalid for the bit width of this ApInt
.
Arithmetically right-shifts this ApInt
by the given shift_amount
bits.
This operation is inplace and will not allocate memory.
Arithmetic shifting copies the sign bit instead of filling up with zeros.
- If the given
shift_amount
is invalid for the bit width of this ApInt
.
Arithmetically right-shifts this ApInt
by the given shift_amount
bits
and returns the result.
This operation is inplace and will not allocate memory.
Arithmetic shifting copies the sign bit instead of filling up with zeros.
- If the given
shift_amount
is invalid for the bit width of this ApInt
.
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.
- 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
.
let a = ApInt::from_str_radix(10, "42");
let b = ApInt::from_str_radix( 2, "1011011");
let c = ApInt::from_str_radix(16, "ffcc00");
let c = ApInt::from_str_radix(10, "256");
let d = ApInt::from_str_radix( 2, "01020");
let e = ApInt::from_str_radix(16, "hello");
Serialization
=======================================================================
Returns a String
representation of the binary encoded ApInt
for the given Radix
.
Resizes this ApInt
to a bool
primitive type.
Bits in this ApInt
that are not within the bounds
of the bool
are being ignored.
- Basically this returns
true
if the least significant
bit of this ApInt
is 1
and false
otherwise.
Resizes this ApInt
to a i8
primitive type.
- 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.
Resizes this ApInt
to a u8
primitive type.
- All bits but the least significant
8
bits are
being ignored by this operation to construct the
result.
Resizes this ApInt
to a i16
primitive type.
- 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.
Resizes this ApInt
to a u16
primitive type.
- All bits but the least significant
16
bits are
being ignored by this operation to construct the
result.
Resizes this ApInt
to a i32
primitive type.
- 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.
Resizes this ApInt
to a u32
primitive type.
- All bits but the least significant
32
bits are
being ignored by this operation to construct the
result.
Resizes this ApInt
to a i64
primitive type.
- 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.
Resizes this ApInt
to a u64
primitive type.
- All bits but the least significant
64
bits are
being ignored by this operation to construct the
result.
Resizes this ApInt
to a i128
primitive type.
- 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.
Resizes this ApInt
to a u128
primitive type.
- All bits but the least significant
128
bits are
being ignored by this operation to construct the
result.
Tries to represent the value of this ApInt
as a bool
.
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.
- If the value represented by this
ApInt
can not be
represented by a bool
.
Tries to represent the value of this ApInt
as a i8
.
- 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
.
- If the value represented by this
ApInt
can not be
represented by a i8
.
Tries to represent the value of this ApInt
as a u8
.
- This conversion is possible as long as the value represented
by this
ApInt
does not exceed the maximum value of u8
.
- If the value represented by this
ApInt
can not be
represented by a u8
.
Tries to represent the value of this ApInt
as a i16
.
- 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
.
- If the value represented by this
ApInt
can not be
represented by a i16
.
Tries to represent the value of this ApInt
as a u16
.
- This conversion is possible as long as the value represented
by this
ApInt
does not exceed the maximum value of u16
.
- If the value represented by this
ApInt
can not be
represented by a u16
.
Tries to represent the value of this ApInt
as a i32
.
- 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
.
- If the value represented by this
ApInt
can not be
represented by a i32
.
Tries to represent the value of this ApInt
as a u32
.
- This conversion is possible as long as the value represented
by this
ApInt
does not exceed the maximum value of u32
.
- If the value represented by this
ApInt
can not be
represented by a u32
.
Tries to represent the value of this ApInt
as a i64
.
- 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
.
- If the value represented by this
ApInt
can not be
represented by a i64
.
Tries to represent the value of this ApInt
as a u64
.
- This conversion is possible as long as the value represented
by this
ApInt
does not exceed the maximum value of u64
.
- If the value represented by this
ApInt
can not be
represented by a u64
.
Tries to represent the value of this ApInt
as a i128
.
- 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
.
- If the value represented by this
ApInt
can not be
represented by a i128
.
Tries to represent the value of this ApInt
as a u128
.
- This conversion is possible as long as the value represented
by this
ApInt
does not exceed the maximum value of u128
.
- 𝒪(n) where n is the number of digits of this
ApInt
.
- If the value represented by this
ApInt
can not be
represented by a u128
.
Creates a new ApInt
with the given BitWidth
and random Digit
s.
Creates a new ApInt
with the given BitWidth
and random Digit
s
using the given random number generator.
Note: This is useful for cryptographic or testing purposes.
Randomizes the digits of this ApInt
inplace.
This won't change its BitWidth
.
Randomizes the digits of this ApInt
inplace using the given
random number generator.
This won't change its BitWidth
.
Executes the destructor for this type. Read more
Performs copy-assignment from source
. Read more
Formats the value using the given formatter. Read more
Feeds this value into the given [Hasher
]. Read more
Feeds a slice of this type into the given [Hasher
]. Read more
Returns the BitWidth
of this ApInt
.
The resulting type after applying the !
operator.
Performs the unary !
operation.
The resulting type after applying the &
operator.
Performs the &
operation.
The resulting type after applying the &
operator.
Performs the &
operation.
The resulting type after applying the &
operator.
Performs the &
operation.
The resulting type after applying the |
operator.
Performs the |
operation.
The resulting type after applying the |
operator.
Performs the |
operation.
The resulting type after applying the |
operator.
Performs the |
operation.
The resulting type after applying the ^
operator.
Performs the ^
operation.
The resulting type after applying the ^
operator.
Performs the ^
operation.
The resulting type after applying the ^
operator.
Performs the ^
operation.
Performs the &=
operation.
Performs the |=
operation.
Performs the ^=
operation.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
The resulting type after applying the -
operator.
Performs the unary -
operation.
The resulting type after applying the -
operator.
Performs the unary -
operation.
The resulting type after applying the -
operator.
Performs the unary -
operation.
The resulting type after applying the +
operator.
Performs the +
operation.
The resulting type after applying the +
operator.
Performs the +
operation.
Performs the +=
operation.
The resulting type after applying the -
operator.
Performs the -
operation.
The resulting type after applying the -
operator.
Performs the -
operation.
Performs the -=
operation.
The resulting type after applying the *
operator.
Performs the *
operation.
The resulting type after applying the *
operator.
Performs the *
operation.
Performs the *=
operation.
Formats the value using the given formatter.
Formats the value using the given formatter.
Formats the value using the given formatter.
Formats the value using the given formatter.
Serialize this value into the given Serde serializer. Read more
Deserialize this value from the given Serde deserializer. Read more
ApInt
is safe to send between threads since it does not own
aliasing memory and has no reference counting mechanism like Rc
.
ApInt
is safe to share between threads since it does not own
aliasing memory and has no mutable internal state like Cell
or RefCell
.