Struct SignedBits

pub struct SignedBits<const N: usize>(/* private fields */);

The SignedBits type is a fixed-size bit vector. It is meant to imitate the behavior of signed bit vectors in hardware. Due to the design of the SignedBits type, you can only create a signed bit vector of up to 128 bits in lnegth for now. However, you can easily express larger constructs in hardware using arrays, tuples and structs. The only real limitation of the SignedBits type being 128 bits is that you cannot perform arbitrary arithmetic on longer bit values in your hardware designs.

Signed arithmetic is performed using 2’s complement arithmetic. See https://en.wikipedia.org/wiki/Two%27s_complement for more information.

Note that unlike the Bits type, comparisons are performed using signed arithmetic. Note also that the right shift operator when applied to a signed value will sign extend the value. This is the same behavior as is seen in Rust (i.e., ((-4) >> 1) == -2).

If you want to right shift a signed value without sign extension, then you should convert it to a Bits type first.

Implementations

impl<const N: usize> SignedBits<N>

pub const MASK: Self

Return a SignedBits value with all bits set to 1.

pub const fn mask() -> Self

Return a SignedBits value with all bits set to 1.

let mask = SignedBits::<8>::mask();
assert_eq!(mask.as_unsigned(), 0xFF);

Note that for a SignedBits value, the mask is the same as a representation of -1.

pub fn sign_bit(&self) -> bool

Extract the sign bit from the SignedBits value. By convention for 2’s complement arithmetic, this is true if the value is negative.

let positive = SignedBits::<8>::from(1);
assert!(!positive.sign_bit());
let negative = SignedBits::<8>::from(-1);
assert!(negative.sign_bit());

pub fn max_value() -> i128

Return the largest positive value that can be represented by this sized SignedBits value.

assert_eq!(SignedBits::<8>::max_value(), i8::MAX as i128);

pub fn min_value() -> i128

Return the smallest negative value that can be represented by this sized SignedBits value.

assert_eq!(SignedBits::<8>::min_value(), i8::MIN as i128);

pub fn set_bit(&mut self, bit: usize, value: bool)

Set a specific bit of a SignedBits value to 1 or 0. Note that changing the MSB of a signed bit vector changes the sign of that vector.

let mut value = SignedBits::<8>::from(0);
value.set_bit(0, true);
assert_eq!(value, 1);
value.set_bit(7, true);
assert_eq!(value, -127);

pub fn get_bit(&self, bit: usize) -> bool

Get the value of a specific bit of a SignedBits value.

let mut value = SignedBits::<4>::from(5);
assert!(value.get_bit(0));
assert!(!value.get_bit(1));
assert!(value.get_bit(2));

pub fn is_negative(&self) -> bool

Test if the value is negative.

assert!(signed::<8>(-1).is_negative());
assert!(!signed::<8>(0).is_negative());
assert!(!signed::<8>(1).is_negative());

pub fn is_non_negative(&self) -> bool

Test if the value is positive or zero.

assert!(!signed::<8>(-1).is_non_negative());
assert!(signed::<8>(0).is_non_negative());
assert!(signed::<8>(1).is_non_negative());

pub fn slice<const M: usize>(&self, start: usize) -> Bits<M>

Extracts a range of bits from the SignedBits value. Because we cannot guarantee that the sliced bits include the proper 2’s complement representation for a signed value, they are simple a Bits vector.

let x = signed::<8>(-14); // In binary: 1111_0010
let y = x.slice::<4>(0);
assert_eq!(y, 0b0010);

pub fn as_unsigned(self) -> Bits<N>

Reinterpret the SignedBits value as an unsigned Bits value. This is useful for performing bit manipulations on the value that may or not preserve the 2’s complement nature of the value.

let x = signed::<8>(-14); // In binary: 1111_0010
let y : Bits<8> = x.as_unsigned();
assert_eq!(y, 0b1111_0010);

Trait Implementations

impl<const N: usize> Add<SignedBits<N>> for i128

type Output = SignedBits<N>

The resulting type after applying the + operator.

fn add(self, rhs: SignedBits<N>) -> Self::Output

Performs the + operation.

impl<const N: usize> Add<i128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the + operator.

fn add(self, rhs: i128) -> Self::Output

Performs the + operation.

impl<const N: usize> Add for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<const N: usize> AddAssign<i128> for SignedBits<N>

fn add_assign(&mut self, rhs: i128)

Performs the += operation.

impl<const N: usize> AddAssign for SignedBits<N>

fn add_assign(&mut self, rhs: SignedBits<N>)

Performs the += operation.

impl<const N: usize> Binary for SignedBits<N>

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

Formats the value using the given formatter.

impl<const N: usize> BitAnd<SignedBits<N>> for i128

type Output = SignedBits<N>

The resulting type after applying the & operator.

fn bitand(self, rhs: SignedBits<N>) -> Self::Output

Performs the & operation.

impl<const N: usize> BitAnd<i128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the & operator.

fn bitand(self, rhs: i128) -> Self::Output

Performs the & operation.

impl<const N: usize> BitAnd for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the & operator.

fn bitand(self, rhs: SignedBits<N>) -> SignedBits<N>

Performs the & operation.

impl<const N: usize> BitAndAssign<i128> for SignedBits<N>

fn bitand_assign(&mut self, rhs: i128)

Performs the &= operation.

impl<const N: usize> BitAndAssign for SignedBits<N>

fn bitand_assign(&mut self, rhs: SignedBits<N>)

Performs the &= operation.

impl<const N: usize> BitOr<SignedBits<N>> for i128

type Output = SignedBits<N>

The resulting type after applying the | operator.

fn bitor(self, rhs: SignedBits<N>) -> Self::Output

Performs the | operation.

impl<const N: usize> BitOr<i128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the | operator.

fn bitor(self, rhs: i128) -> Self::Output

Performs the | operation.

impl<const N: usize> BitOr for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the | operator.

fn bitor(self, rhs: SignedBits<N>) -> SignedBits<N>

Performs the | operation.

impl<const N: usize> BitOrAssign<i128> for SignedBits<N>

fn bitor_assign(&mut self, rhs: i128)

Performs the |= operation.

impl<const N: usize> BitOrAssign for SignedBits<N>

fn bitor_assign(&mut self, rhs: SignedBits<N>)

Performs the |= operation.

impl<const N: usize> BitXor<SignedBits<N>> for i128

type Output = SignedBits<N>

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: SignedBits<N>) -> Self::Output

Performs the ^ operation.

impl<const N: usize> BitXor<i128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: i128) -> Self::Output

Performs the ^ operation.

impl<const N: usize> BitXor for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: SignedBits<N>) -> SignedBits<N>

Performs the ^ operation.

impl<const N: usize> BitXorAssign<i128> for SignedBits<N>

fn bitxor_assign(&mut self, rhs: i128)

Performs the ^= operation.

impl<const N: usize> BitXorAssign for SignedBits<N>

fn bitxor_assign(&mut self, rhs: SignedBits<N>)

Performs the ^= operation.

impl<const N: usize> Clone for SignedBits<N>

fn clone(&self) -> SignedBits<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for SignedBits<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for SignedBits<N>

fn default() -> Self

Returns the “default value” for a type.

impl<const N: usize> Display for SignedBits<N>

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

Formats the value using the given formatter.

impl<const N: usize> From<i128> for SignedBits<N>

fn from(value: i128) -> Self

Converts to this type from the input type.

impl<const N: usize> Hash for SignedBits<N>

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const N: usize> LowerHex for SignedBits<N>

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

Formats the value using the given formatter.

impl<const N: usize> Neg for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<const N: usize> Not for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<const N: usize> Ord for SignedBits<N>

fn cmp(&self, other: &SignedBits<N>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<const N: usize> PartialEq<i128> for SignedBits<N>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const N: usize> PartialEq for SignedBits<N>

fn eq(&self, other: &SignedBits<N>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const N: usize> PartialOrd for SignedBits<N>

fn partial_cmp(&self, other: &SignedBits<N>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const M: usize, const N: usize> Shl<Bits<M>> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the << operator.

fn shl(self, rhs: Bits<M>) -> Self::Output

Performs the << operation.

impl<const N: usize> Shl<u128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the << operator.

fn shl(self, rhs: u128) -> Self::Output

Performs the << operation.

impl<const M: usize, const N: usize> ShlAssign<Bits<M>> for SignedBits<N>

fn shl_assign(&mut self, rhs: Bits<M>)

Performs the <<= operation.

impl<const N: usize> ShlAssign<u128> for SignedBits<N>

fn shl_assign(&mut self, rhs: u128)

Performs the <<= operation.

impl<const M: usize, const N: usize> Shr<Bits<M>> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the >> operator.

fn shr(self, rhs: Bits<M>) -> Self::Output

Performs the >> operation.

impl<const N: usize> Shr<u128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the >> operator.

fn shr(self, rhs: u128) -> Self::Output

Performs the >> operation.

impl<const M: usize, const N: usize> ShrAssign<Bits<M>> for SignedBits<N>

fn shr_assign(&mut self, rhs: Bits<M>)

Performs the >>= operation.

impl<const N: usize> ShrAssign<u128> for SignedBits<N>

fn shr_assign(&mut self, rhs: u128)

Performs the >>= operation.

impl<const N: usize> Sub<i128> for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the - operator.

fn sub(self, rhs: i128) -> Self::Output

Performs the - operation.

impl<const N: usize> Sub for SignedBits<N>

type Output = SignedBits<N>

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl<const N: usize> SubAssign<i128> for SignedBits<N>

fn sub_assign(&mut self, rhs: i128)

Performs the -= operation.

impl<const N: usize> SubAssign for SignedBits<N>

fn sub_assign(&mut self, rhs: SignedBits<N>)

Performs the -= operation.

impl<const N: usize> UpperHex for SignedBits<N>

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

Formats the value using the given formatter.

impl<const N: usize> Copy for SignedBits<N>

impl<const N: usize> Eq for SignedBits<N>

impl<const N: usize> StructuralPartialEq for SignedBits<N>