Struct awint::ExtAwi

#[repr(C)]
pub struct ExtAwi { /* private fields */ }

An arbitrary width integer with manually controlled bitwidth. Most arithmetic is wrapping like Rust’s integers. All reallocations are explicit.

This struct implements Deref<Target = Bits>, see the main documentation of Bits for more. There are also some functions that InlAwi and Bits do not implement, namely some higher level string serialization functions that require allocation. Also note that ExtAwi and Awi cannot take advantage of the constness of Bits operations, see InlAwi.

See the crate level documentation of awint_macros for more macros and information.

use awint::awi::*;

fn example(x0: &mut Bits, x1: &Bits) {
    // when dealing with `Bits` with different bitwidths, use the
    // `*_resize_` functions or the concatenations of components
    // macros with unbounded fillers from `awint_macros`
    x0.sign_resize_(x1);
    // multiply in place by 2 for an example
    x0.digit_cin_mul_(0, 2);
}

// using `bw` function for quick `NonZeroUsize` construction from a literal
let mut x = ExtAwi::zero(bw(100));
assert!(x.is_zero());
// constructing an `ExtAwi` from an `InlAwi`
let y = ExtAwi::from(inlawi!(-123i16));
example(&mut x, &y);
assert_eq!(x.as_ref(), inlawi!(-246i100).as_ref());
// you can freely mix references originating from both `ExtAwi` and `InlAwi`
example(&mut x, &inlawi!(0x10u16));
assert_eq!(x, extawi!(0x20u100));

Implementations

impl<'a> ExtAwi

pub fn nzbw(&self) -> NonZero<usize>

Returns the bitwidth of this ExtAwi as a NonZeroUsize

pub fn bw(&self) -> usize

Returns the bitwidth of this ExtAwi as a usize

pub fn from_bits(bits: &Bits) -> ExtAwi

Creates an ExtAwi from copying a Bits reference. The same functionality is provided by an From<&Bits> implementation for ExtAwi.

pub fn zero(w: NonZero<usize>) -> ExtAwi

Zero-value construction with bitwidth w

pub fn umax(w: NonZero<usize>) -> ExtAwi

Unsigned-maximum-value construction with bitwidth w

pub fn imax(w: NonZero<usize>) -> ExtAwi

Signed-maximum-value construction with bitwidth w

pub fn imin(w: NonZero<usize>) -> ExtAwi

Signed-minimum-value construction with bitwidth w

pub fn uone(w: NonZero<usize>) -> ExtAwi

Unsigned-one-value construction with bitwidth w

impl ExtAwi

pub fn from_u8(x: u8) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_u16(x: u16) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_u32(x: u32) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_u64(x: u64) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_u128(x: u128) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_usize(x: usize) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_i8(x: i8) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_i16(x: i16) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_i32(x: i32) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_i64(x: i64) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_i128(x: i128) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_isize(x: isize) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

pub fn from_bool(x: bool) -> ExtAwi

Creates an ExtAwi with one bit set to this bool

pub fn from_digit(x: usize) -> ExtAwi

Creates an ExtAwi with the same bitwidth and bits as the integer

impl ExtAwi

non-const string representation conversion

pub fn bits_to_vec_radix( bits: &Bits, signed: bool, radix: u8, upper: bool, min_chars: usize ) -> Result<Vec<u8>, SerdeError>

Creates a Vec<u8> representing bits (sign indicators, prefixes, and postfixes not included). This function performs allocation. This is a wrapper around awint_core::Bits::to_bytes_radix that truncates leading zeros. An additional min_chars specifies the minimum number of characters that should exist. min_chars specifies the minimum number of chars in the integer part, inserting leading ’0’s if there are not enough chars, just like Rust’s built in {:0d} formatting. Note that an empty vector will be returned if min_chars == 0 && bits.is_zero().

Errors

This can only return an error if radix is not in the range 2..=36 or if resource exhaustion occurs.

pub fn bits_to_string_radix( bits: &Bits, signed: bool, radix: u8, upper: bool, min_chars: usize ) -> Result<String, SerdeError>

Creates a string representing bits. This function performs allocation. This does the same thing as ExtAwi::bits_to_vec_radix but with a String.

pub fn from_bytes_radix( sign: Option<bool>, src: &[u8], radix: u8, bw: NonZero<usize> ) -> Result<ExtAwi, SerdeError>

Creates an ExtAwi representing the given arguments. This function performs allocation. This is a wrapper around awint_core::Bits::bytes_radix_ that zero or sign resizes the result to match bw.

Errors

See the error conditions of Bits::bytes_radix_. Note that - is an invalid character even though to_vec_radix can return -. This is because we need to handle both unsigned and signed integer inputs, specified only by sign. If the input is a negative signed integer representation with - appended to the front, the subslice src[1..] can be taken and sign can be set to Some(true).

pub fn from_str_radix( sign: Option<bool>, str: &str, radix: u8, bw: NonZero<usize> ) -> Result<ExtAwi, SerdeError>

Creates an ExtAwi representing the given arguments. This does the same thing as ExtAwi::from_bytes_radix but with an &str.

pub fn from_bytes_general( sign: Option<bool>, integer: &[u8], fraction: &[u8], exp: isize, radix: u8, bw: NonZero<usize>, fp: isize ) -> Result<ExtAwi, SerdeError>

Creates an ExtAwi representing the given arguments. This function performs allocation. In addition to the arguments and semantics from ExtAwi::from_bytes_radix, this function includes the ability to deal with general fixed point integer deserialization. src is now split into separate integer and fraction parts. An exponent exp further multiplies the numerical value by radix^exp. fp is the location of the fixed point in the output representation of the numerical value (e.x. for a plain integer fp == 0). fp can be negative or greater than the bitwidth.

This function uses a single rigorous round-to-even that occurs after the exponent and fixed point multiplier are applied and before any numerical information is lost.

See crate::FP::to_vec_general for the inverse of this function.

Errors

See the error conditions of ExtAwi::from_bytes_radix. The precision can now be arbitrarily large (any overflow in the low numerical significance direction will be rounded), but overflow can still happen in the more significant direction. Empty strings are interpreted as a zero value.

pub fn from_str_general( sign: Option<bool>, integer: &str, fraction: &str, exp: isize, radix: u8, bw: NonZero<usize>, fp: isize ) -> Result<ExtAwi, SerdeError>

Creates an ExtAwi representing the given arguments. This does the same thing as ExtAwi::from_bytes_general but with &strs.

Methods from Deref<Target = Bits>

pub fn nzbw(&self) -> NonZero<usize>

Returns the bitwidth as a NonZeroUsize

pub fn bw(&self) -> usize

Returns the bitwidth as a usize

pub fn u8_slice_(&'a mut self, buf: &[u8])

Assigns the bits of buf to self. If (buf.len() * 8) > self.bw() then the corresponding bits in buf beyond self.bw() are ignored. If (buf.len() * 8) < self.bw() then the rest of the bits in self are zeroed. This function is portable across target architecture pointer sizes and endianness.

pub fn to_u8_slice(&'a self, buf: &mut [u8])

Assigns the bits of self to buf. If (buf.len() * 8) > self.bw() then the corresponding bits in buf beyond self.bw() are zeroed. If (buf.len() * 8) < self.bw() then the bits of self beyond the buffer do nothing. This function is portable across target architecture pointer sizes and endianness.

pub fn zero_(&mut self)

Zero-assigns. Same as the Unsigned-minimum-value. All bits are set to 0.

pub fn umax_(&mut self)

Unsigned-maximum-value-assigns. All bits are set to 1.

pub fn imax_(&mut self)

Signed-maximum-value-assigns. All bits are set to 1, except for the most significant bit.

pub fn imin_(&mut self)

Signed-minimum-value-assigns. Only the most significant bit is set.

pub fn uone_(&mut self)

Unsigned-one-assigns. Only the least significant bit is set. The unsigned distinction is important, because a positive one value does not exist for signed integers with a bitwidth of 1.

pub fn not_(&mut self)

Not-assigns self

pub fn copy_(&mut self, rhs: &Bits) -> Option<()>

Copy-assigns the bits of rhs to self

pub fn or_(&mut self, rhs: &Bits) -> Option<()>

Or-assigns rhs to self

pub fn and_(&mut self, rhs: &Bits) -> Option<()>

And-assigns rhs to self

pub fn xor_(&mut self, rhs: &Bits) -> Option<()>

Xor-assigns rhs to self

pub fn range_or_(&mut self, range: Range<usize>) -> Option<()>

Or-assigns a range of ones to self. An empty or reversed range does nothing to self. None is returned if range.start > self.bw() or range.end > self.bw().

pub fn range_and_(&mut self, range: Range<usize>) -> Option<()>

And-assigns a range of ones to self. Useful for masking. An empty or reversed range zeroes self. None is returned if range.start > self.bw() or range.end > self.bw().

pub fn range_xor_(&mut self, range: Range<usize>) -> Option<()>

Xor-assigns a range of ones to self. An empty or reversed range does nothing to self. None is returned if range.start > self.bw() or range.end > self.bw().

pub fn digit_or_(&mut self, rhs: usize, shl: usize)

Or-assigns rhs to self at a position shl. Set bits of rhs that are shifted beyond the bitwidth of self are truncated.

pub fn resize_(&mut self, rhs: &Bits, extension: bool)

Resize-copy-assigns rhs to self. If self.bw() >= rhs.bw(), the copied value of rhs will be extended with bits set to extension. If self.bw() < rhs.bw(), the copied value of rhs will be truncated.

pub fn zero_resize_(&mut self, rhs: &Bits) -> bool

Zero-resize-copy-assigns rhs to self and returns overflow. This is the same as lhs.resize_(rhs, false), but returns true if the unsigned meaning of the integer is changed.

pub fn sign_resize_(&mut self, rhs: &Bits) -> bool

Sign-resize-copy-assigns rhs to self and returns overflow. This is the same as lhs.resize_(rhs, rhs.msb()), but returns true if the signed meaning of the integer is changed.

pub fn is_zero(&self) -> bool

If self is zero

pub fn is_umax(&self) -> bool

If self is unsigned-maximum

pub fn is_imax(&self) -> bool

If self is signed-maximum

pub fn is_imin(&self) -> bool

If self is signed-minimum

pub fn is_uone(&self) -> bool

If self is unsigned-one

pub fn const_eq(&self, rhs: &Bits) -> Option<bool>

Equality comparison, self == rhs

pub fn const_ne(&self, rhs: &Bits) -> Option<bool>

Not-equal comparison, self != rhs

pub fn ult(&self, rhs: &Bits) -> Option<bool>

Unsigned-less-than comparison, self < rhs

pub fn ule(&self, rhs: &Bits) -> Option<bool>

Unsigned-less-than-or-equal comparison, self <= rhs

pub fn ugt(&self, rhs: &Bits) -> Option<bool>

Unsigned-greater-than comparison, self > rhs

pub fn uge(&self, rhs: &Bits) -> Option<bool>

Unsigned-greater-than-or-equal comparison, self >= rhs

pub fn ilt(&self, rhs: &Bits) -> Option<bool>

Signed-less-than comparison, self < rhs

pub fn ile(&self, rhs: &Bits) -> Option<bool>

Signed-less-than-or-equal comparison, self <= rhs

pub fn igt(&self, rhs: &Bits) -> Option<bool>

Signed-greater-than comparison, self > rhs

pub fn ige(&self, rhs: &Bits) -> Option<bool>

Signed-greater-than-or-equal comparison, self >= rhs

pub fn total_cmp(&self, rhs: &Bits) -> Ordering

Total ordering over bitstrings, including differentiation between differing bitwidths of self and rhs. This orders first on bitwidth and then on unsigned value.

pub fn bytes_radix_( &mut self, sign: Option<bool>, src: &[u8], radix: u8, pad0: &mut Bits, pad1: &mut Bits ) -> Result<(), SerdeError>

Assigns to self the integer value represented by src in the given radix. If src should be interpreted as unsigned, sign should be None, otherwise it should be set to the sign. In order for this function to be const, two scratchpads pad0 and pad1 with the same bitwidth as self must be supplied, which can be mutated by the function in arbitrary ways.

Errors

self is not mutated if an error occurs. See crate::SerdeError for error conditions. The characters 0..=9, a..=z, and A..=Z are allowed depending on the radix. The char _ is ignored, and all other chars result in an error. src cannot be empty. The value of the string must be representable in the bitwidth of self with the specified sign, otherwise an overflow error is returned.

pub fn to_bytes_radix( &self, signed: bool, dst: &mut [u8], radix: u8, upper: bool, pad: &mut Bits ) -> Result<(), SerdeError>

Assigns the [u8] representation of self to dst (sign indicators, prefixes, and postfixes not included). signed specifies if self should be interpreted as signed. radix specifies the radix, and upper specifies if letters should be uppercase. In order for this function to be const, a scratchpad pad with the same bitwidth as self must be supplied. Note that if dst.len() is more than what is needed to store the representation, the leading bytes will all be set to b’0’.

Errors

Note: If an error is returned, dst may be set to anything

This function can fail from NonEqualWidths, InvalidRadix, and Overflow (if dst cannot represent the value of self). See crate::SerdeError.

pub fn digit_udivide_inplace_(&mut self, div: usize) -> Option<usize>

Unsigned-divides self by div, sets self to the quotient, and returns the remainder. Returns None if div == 0.

pub fn digit_udivide_(&mut self, duo: &Bits, div: usize) -> Option<usize>

pub fn lsb(&self) -> bool

Returns the least significant bit

pub fn msb(&self) -> bool

Returns the most significant bit

pub fn get(&self, inx: usize) -> Option<bool>

Gets the bit at inx bits from the least significant bit, returning None if inx >= self.bw()

pub fn set(&mut self, inx: usize, bit: bool) -> Option<()>

Sets the bit at inx bits from the least significant bit, returning None if inx >= self.bw()

pub fn lz(&self) -> usize

Returns the number of leading zero bits

pub fn tz(&self) -> usize

Returns the number of trailing zero bits

pub fn sig(&self) -> usize

Returns the number of significant bits, self.bw() - self.lz()

pub fn count_ones(&self) -> usize

Returns the number of set ones

pub fn field( &mut self, to: usize, rhs: &Bits, from: usize, width: usize ) -> Option<()>

“Fielding” bitfields with targeted copy assigns. The bitwidths of self and rhs do not have to be equal, but the inputs must collectively obey width <= self.bw() && width <= rhs.bw() && to <= (self.bw() - width) && from <= (rhs.bw() - width) or else None is returned. width can be zero, in which case this function just checks the input correctness and does not mutate self.

This function works by copying a width sized bitfield from rhs at bitposition from and overwriting width bits at bitposition to in self. Only the width bits in self are mutated, any bits before and after the bitfield are left unchanged.

use awint::{inlawi, Bits, InlAwi};
// As an example, two hexadecimal digits will be overwritten
// starting with the 12th digit in `y` using a bitfield with
// value 0x42u8 extracted from `x`.
let x = inlawi!(0x11142111u50);
// the underscores are just for emphasis
let mut y = inlawi!(0xfd_ec_ba9876543210u100);
// from `x` digit place 3, we copy 2 digits to `y` digit place 12.
y.field(12 * 4, &x, 3 * 4, 2 * 4);
assert_eq!(y, inlawi!(0xfd_42_ba9876543210u100));

pub fn field_to(&mut self, to: usize, rhs: &Bits, width: usize) -> Option<()>

A specialization of Bits::field with from set to 0.

pub fn field_from( &mut self, rhs: &Bits, from: usize, width: usize ) -> Option<()>

A specialization of Bits::field with to set to 0.

pub fn field_width(&mut self, rhs: &Bits, width: usize) -> Option<()>

A specialization of Bits::field with to and from set to 0.

pub fn field_bit(&mut self, to: usize, rhs: &Bits, from: usize) -> Option<()>

A specialization of Bits::field with width set to 1.

pub fn lut_(&mut self, lut: &Bits, inx: &Bits) -> Option<()>

Copy entry from lookup table. Copies a self.bw() sized bitfield from lut at bit position inx.to_usize() * self.bw(). If lut.bw() != (self.bw() * (2^inx.bw())), None will be returned.

use awint::{inlawi, Bits, InlAwi};
let mut out = inlawi!(0u10);
// lookup table consisting of 4 10-bit entries
let lut = inlawi!(4u10, 3u10, 2u10, 1u10);
// the indexer has to have a bitwidth of 2 to index 2^2 = 4 entries
let mut inx = inlawi!(0u2);

// get the third entry (this is using zero indexing)
inx.usize_(2);
out.lut_(&lut, &inx).unwrap();
assert_eq!(out, inlawi!(3u10));

pub fn lut_set(&mut self, entry: &Bits, inx: &Bits) -> Option<()>

Set entry in lookup table. The inverse of Bits::lut_, this uses entry as a bitfield to overwrite part of self at bit position inx.to_usize() * entry.bw(). If self.bw() != (entry.bw() * (2^inx.bw())), None will be returned.

pub fn mux_(&mut self, rhs: &Bits, b: bool) -> Option<()>

Multiplex by conditionally copy-assigning rhs to self if b

pub fn repeat_(&mut self, rhs: &Bits)

Repeat-assigns self by rhs. This is logically equivalent to concatenating an infinite number of rhs bit strings together, then resize-assigning to self.

pub fn digit_cin_mul_(&mut self, cin: usize, rhs: usize) -> usize

Assigns cin + (self * rhs) to self and returns the overflow

pub fn digit_mul_add_(&mut self, lhs: &Bits, rhs: usize) -> Option<bool>

Add-assigns lhs * rhs to self and returns if overflow happened

pub fn mul_add_(&mut self, lhs: &Bits, rhs: &Bits) -> Option<()>

Multiplies lhs by rhs and add-assigns the product to self. Three operands eliminates the need for an allocating temporary.

pub fn mul_(&mut self, rhs: &Bits, pad: &mut Bits) -> Option<()>

Multiply-assigns self by rhs. pad is a scratchpad that will be mutated arbitrarily.

pub fn arb_umul_add_(&mut self, lhs: &Bits, rhs: &Bits)

Arbitrarily-unsigned-multiplies lhs by rhs and add-assigns the product to self. This function is equivalent to:

use awint::awi::*;

fn arb_umul_(add: &mut Bits, lhs: &Bits, rhs: &Bits) {
    let mut resized_lhs = Awi::zero(add.nzbw());
    // Note that this function is specified as unsigned,
    // because we use `zero_resize_`
    resized_lhs.zero_resize_(lhs);
    let mut resized_rhs = Awi::zero(add.nzbw());
    resized_rhs.zero_resize_(rhs);
    add.mul_add_(&resized_lhs, &resized_rhs).unwrap();
}

except that it avoids allocation and is more efficient overall

pub fn arb_imul_add_(&mut self, lhs: &mut Bits, rhs: &mut Bits)

Arbitrarily-signed-multiplies lhs by rhs and add-assigns the product to self. Has the same behavior as Bits::arb_umul_add_ except that is interprets the arguments as signed. lhs and rhs are marked mutable but their values are not changed by this function.

pub fn shl_(&mut self, s: usize) -> Option<()>

Left-shifts-assigns by s bits. If s >= self.bw(), then None is returned and the Bits are left unchanged.

Left shifts can act as a very fast multiplication by a power of two for both the signed and unsigned interpretation of Bits.

pub fn lshr_(&mut self, s: usize) -> Option<()>

Logically-right-shift-assigns by s bits. If s >= self.bw(), then None is returned and the Bits are left unchanged.

Logical right shifts do not copy the sign bit, and thus can act as a very fast floored division by a power of two for the unsigned interpretation of Bits.

pub fn ashr_(&mut self, s: usize) -> Option<()>

Arithmetically-right-shift-assigns by s bits. If s >= self.bw(), then None is returned and the Bits are left unchanged.

Arithmetic right shifts copy the sign bit, and thus can act as a very fast floored division by a power of two for the signed interpretation of Bits.

pub fn rotl_(&mut self, s: usize) -> Option<()>

Left-rotate-assigns by s bits. If s >= self.bw(), then None is returned and the Bits are left unchanged.

This function is equivalent to the following:

use awint::awi::*;
let mut input = inlawi!(0x4321u16);
let mut output = inlawi!(0u16);
// rotate left by 4 bits or one hexadecimal digit
let shift = 4;

// temporary clone of the input
let mut tmp = Awi::from(input);
cc!(input; output).unwrap();
if shift != 0 {
    if shift >= input.bw() {
        // the actual function would return `None`
        panic!();
    }
    output.shl_(shift).unwrap();
    tmp.lshr_(input.bw() - shift).unwrap();
    output.or_(&tmp);
};

assert_eq!(output, inlawi!(0x3214u16));
let mut using_rotate = Awi::from(input);
using_rotate.rotl_(shift).unwrap();
assert_eq!(using_rotate, awi!(0x3214u16));

// Note that slices are typed in a little-endian order opposite of
// how integers are typed, but they still visually rotate in the
// same way. This means `Rust`s built in slice rotation is in the
// opposite direction to integers and `Bits`
let mut array = [4, 3, 2, 1];
array.rotate_left(1);
assert_eq!(array, [3, 2, 1, 4]);
assert_eq!(0x4321u16.rotate_left(4), 0x3214);
let mut x = inlawi!(0x4321u16);
x.rotl_(4).unwrap();
// `Bits` has the preferred endianness
assert_eq!(x, inlawi!(0x3214u16));

Unlike the example above which needs cloning, this function avoids any allocation and has many optimized branches for different input sizes and shifts.

pub fn rotr_(&mut self, s: usize) -> Option<()>

Right-rotate-assigns by s bits. If s >= self.bw(), then None is returned and the Bits are left unchanged.

See Bits::rotl_ for more details.

pub fn rev_(&mut self)

Reverse-bit-order-assigns self. The least significant bit becomes the most significant bit, the second least significant bit becomes the second most significant bit, etc.

pub fn funnel_(&mut self, rhs: &Bits, s: &Bits) -> Option<()>

Funnel shift with power-of-two bitwidths. Returns None if 2*self.bw() != rhs.bw() || 2^s.bw() != self.bw(). A self.bw() sized field is assigned to self from rhs starting from the bit position s. The shift cannot overflow because of the restriction on the bitwidth of s.

use awint::awi::*;
let mut lhs = inlawi!(0xffff_ffffu32);
let mut rhs = inlawi!(0xfedc_ba98_7654_3210u64);
// `lhs.bw()` must be a power of two, `s.bw()` here is
// `log_2(32) == 5`. The value of `s` is set to what bit
// of `rhs` should be the starting bit for `lhs`.
let mut s = inlawi!(12u5);
lhs.funnel_(&rhs, &s).unwrap();
assert_eq!(lhs, inlawi!(0xa9876543_u32))

pub fn u8_(&mut self, x: u8)

pub fn i8_(&mut self, x: i8)

pub fn u16_(&mut self, x: u16)

pub fn i16_(&mut self, x: i16)

pub fn u32_(&mut self, x: u32)

pub fn i32_(&mut self, x: i32)

pub fn u64_(&mut self, x: u64)

pub fn i64_(&mut self, x: i64)

pub fn u128_(&mut self, x: u128)

pub fn i128_(&mut self, x: i128)

pub fn usize_(&mut self, x: usize)

pub fn isize_(&mut self, x: isize)

pub fn bool_(&mut self, x: bool)

pub fn digit_(&mut self, x: usize)

pub fn to_u8(&self) -> u8

pub fn to_i8(&self) -> i8

pub fn to_u16(&self) -> u16

pub fn to_i16(&self) -> i16

pub fn to_u32(&self) -> u32

pub fn to_i32(&self) -> i32

pub fn to_u64(&self) -> u64

pub fn to_i64(&self) -> i64

pub fn to_u128(&self) -> u128

pub fn to_i128(&self) -> i128

pub fn to_usize(&self) -> usize

pub fn to_isize(&self) -> isize

pub fn to_bool(&self) -> bool

pub fn to_digit(&self) -> usize

pub fn inc_(&mut self, cin: bool) -> bool

Increment-assigns self with a carry-in cin and returns the carry-out bit. If cin == true then one is added to self, otherwise nothing happens. false is always returned unless self.is_umax().

pub fn dec_(&mut self, cin: bool) -> bool

Decrement-assigns self with a carry-in cin and returns the carry-out bit. If cin == false then one is subtracted from self, otherwise nothing happens. true is always returned unless self.is_zero().

pub fn neg_(&mut self, neg: bool)

Negate-assigns self if neg is true. Note that signed minimum values will overflow.

pub fn abs_(&mut self)

Absolute-value-assigns self. Note that signed minimum values will overflow, unless self is interpreted as unsigned after a call to this function.

pub fn add_(&mut self, rhs: &Bits) -> Option<()>

Add-assigns by rhs

pub fn sub_(&mut self, rhs: &Bits) -> Option<()>

Subtract-assigns by rhs

pub fn rsb_(&mut self, rhs: &Bits) -> Option<()>

Reverse-subtract-assigns by rhs. Sets self to (-self) + rhs.

pub fn neg_add_(&mut self, neg: bool, rhs: &Bits) -> Option<()>

Negate-add-assigns by rhs. Negates conditionally on neg.

pub fn cin_sum_( &mut self, cin: bool, lhs: &Bits, rhs: &Bits ) -> Option<(bool, bool)>

A general summation with carry-in cin and two inputs lhs and rhs. self is set to the sum. The unsigned overflow (equivalent to the carry-out bit) and the signed overflow is returned as a tuple. None is returned if any bitwidths do not match. If subtraction is desired, one of the operands can be negated.

Trait Implementations

impl AsMut<Bits> for ExtAwi

fn as_mut(&mut self) -> &mut Bits

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<Bits> for ExtAwi

fn as_ref(&self) -> &Bits

Converts this type into a shared reference of the (usually inferred) input type.

impl Binary for ExtAwi

Forwards to the corresponding impl for Bits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Borrow<Bits> for ExtAwi

fn borrow(&self) -> &Bits

Immutably borrows from an owned value.

impl BorrowMut<Bits> for ExtAwi

fn borrow_mut(&mut self) -> &mut Bits

Mutably borrows from an owned value.

impl Clone for ExtAwi

fn clone(&self) -> ExtAwi

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ExtAwi

Forwards to the corresponding impl for Bits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for ExtAwi

type Target = Bits

The resulting type after dereferencing.

fn deref(&self) -> &<ExtAwi as Deref>::Target

Dereferences the value.

impl DerefMut for ExtAwi

fn deref_mut(&mut self) -> &mut Bits

Mutably dereferences the value.

impl Display for ExtAwi

Forwards to the corresponding impl for Bits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drop for ExtAwi

fn drop(&mut self)

Executes the destructor for this type.

impl From<&Bits> for ExtAwi

Creates an ExtAwi from copying a Bits reference

fn from(bits: &Bits) -> ExtAwi

Converts to this type from the input type.

impl<const BW: usize, const LEN: usize> From<InlAwi<BW, LEN>> for ExtAwi

Creates an ExtAwi from copying an InlAwi

fn from(awi: InlAwi<BW, LEN>) -> ExtAwi

Converts to this type from the input type.

impl From<bool> for ExtAwi

fn from(x: bool) -> ExtAwi

Converts to this type from the input type.

impl From<i128> for ExtAwi

fn from(x: i128) -> ExtAwi

Converts to this type from the input type.

impl From<i16> for ExtAwi

fn from(x: i16) -> ExtAwi

Converts to this type from the input type.

impl From<i32> for ExtAwi

fn from(x: i32) -> ExtAwi

Converts to this type from the input type.

impl From<i64> for ExtAwi

fn from(x: i64) -> ExtAwi

Converts to this type from the input type.

impl From<i8> for ExtAwi

fn from(x: i8) -> ExtAwi

Converts to this type from the input type.

impl From<isize> for ExtAwi

fn from(x: isize) -> ExtAwi

Converts to this type from the input type.

impl From<u128> for ExtAwi

fn from(x: u128) -> ExtAwi

Converts to this type from the input type.

impl From<u16> for ExtAwi

fn from(x: u16) -> ExtAwi

Converts to this type from the input type.

impl From<u32> for ExtAwi

fn from(x: u32) -> ExtAwi

Converts to this type from the input type.

impl From<u64> for ExtAwi

fn from(x: u64) -> ExtAwi

Converts to this type from the input type.

impl From<u8> for ExtAwi

fn from(x: u8) -> ExtAwi

Converts to this type from the input type.

impl From<usize> for ExtAwi

fn from(x: usize) -> ExtAwi

Converts to this type from the input type.

impl FromStr for ExtAwi

fn from_str(s: &str) -> Result<ExtAwi, <ExtAwi as FromStr>::Err>

Creates an ExtAwi described by s. There are three modes of operation which invoke ExtAwi::from_str_radix or ExtAwi::from_str_general differently.

Note: there is currently a bug in Rust that causes certain fixed point literals to fail to parse when attempting to use them in the concatenation macros. In case of getting “literal is not supported” errors, use ExtAwi::from_str directly.

Additionally, note that it is easy to cause resource exhaustion with large bitwidths, exponents, or fixed points that can approach usize::MAX. In a future version of awint we should have a guarded function for helping with entering literals through things like UIs.

All valid inputs must begin with ‘0’-‘9’ or a ‘-’ followed by ‘0’-‘9’.

If only ’ _ ’, ‘0’, and ‘1’ chars are present, this function uses binary mode. It will interpret the input as a binary string, the number of ’0’s and ’1’s of which is the bitwidth (including leading ’0’s and excluding ’ _ ’s). For example: 42 in binary is 101010. If “101010” is entered into this function, it will return an ExtAwi with bitwidth 6 and unsigned value 42. “0000101010” results in bitwidth 10 and unsigned value 42. “1111_1111” results in bitwidth 8 and signed value -128 or equivalently unsigned value 255.

In integer mode, a decimal bitwidth must be specified after a ‘u’ (unsigned) or ‘i’ (signed) suffix. A prefix of “0b” specifies a binary radix, “0o” specifies an octal radix, “0x” specifies hexadecimal, otherwise a decimal radix is used. For example: “42u10” entered into this function creates an ExtAwi with bitwidth 10 and unsigned value 42. “-42i10” results in bitwidth 10 and signed value of -42. “0xffff_ffffu32” results in bitwidth 32 and an unsigned value of 0xffffffff (also 4294967295 in decimal and u32::MAX). “0x1_0000_0000u32” results in an error with SerdeError::Overflow, because it exceeds the maximum unsigned value for a 32 bit integer. “123” results in SerdeError::EmptyBitwidth, because it is not in binary mode and no bitwidth suffix has been supplied.

If, after the bitwidth, an ‘f’ char is present, fixed point mode is activated. A decimal fixed point position must be specified after the ‘f’ that tells where the fixed point will be in the resulting bits (see crate::FP for more). If the most significant numerical bit would be cut off, SerdeError::Overflow is returned.

Additionally, an exponent char ‘e’ (for non-hexadecimal radixes only) or ‘p’ can be included after the integer or fraction parts but before the bitwidth suffix. The exponent as typed uses the radix of the integer part, and it is raised to the same radix when modifying the numerical value. The exponent can only be negative for fixed point mode. For example: “123e5u32” has numerical value 12300000. “123e-5u32” returns an error since it is trying to use a negative exponent in integer mode. “-0x1234.5678p-3i32f16” has a numerical value of -0x1234.5678 * 0x10^-0x3 and uses ExtAwi::from_bytes_general to round-to-even to a 32 bit fixed point number with fixed point position 16. You probably want to use underscores to make it clearer where different parts are, e.x. “-0x1234.5678_p-3_i32_f16”.

For all parts including the integer, fraction, exponent, bitwidth, and fixed point parts, if their prefix char exists but there is not at least one ‘0’ for them, some kind of empty error is returned. For example: “0xu8” should be “0x0u8”. “.i8f0” should be “0.0i8f0”. “1u32f” should be “1u32f0”.

type Err = SerdeError

The associated error which can be returned from parsing.

impl Hash for ExtAwi

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

where H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<RangeFull> for ExtAwi

type Output = Bits

The returned type after indexing.

fn index(&self, _i: RangeFull) -> &Bits

Performs the indexing (container[index]) operation.

impl IndexMut<RangeFull> for ExtAwi

fn index_mut(&mut self, _i: RangeFull) -> &mut Bits

Performs the mutable indexing (container[index]) operation.

impl LowerHex for ExtAwi

Forwards to the corresponding impl for Bits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Octal for ExtAwi

Forwards to the corresponding impl for Bits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for ExtAwi

If self and other have unmatching bit widths, false will be returned.

fn eq(&self, rhs: &ExtAwi) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl UpperHex for ExtAwi

Forwards to the corresponding impl for Bits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for ExtAwi

If self and other have unmatching bit widths, false will be returned.

impl Send for ExtAwi

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

impl Sync for ExtAwi

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