pub struct PackUsize<T = usize, F = ()> { /* private fields */ }
Expand description

A spec for packing values into selected bit ranges of usize values.

See the module-level documentation for details on using packing specs.

Implementations§

source§

impl PackUsize<usize>

source

pub const fn pack_in(value: usize) -> PackingUsize

Wrap a usize to add methods for packing bit ranges using PackUsize.

This is equivalent to calling PackingUsize::new, but only requires importing the packer type.

source

pub const fn least_significant(n: u32) -> Self

Returns a packer for packing a value into the first bits bits.

source

pub const fn from_mask(mask: usize) -> Self

Returns a packer that will pack a value into the provided mask.

source

pub const fn from_const_range(range: Range<u32>) -> Self

This is a const fn-compatible equivalent of Self::from_range. Note that it can only be used with core::ops::Ranges, and not with core::ops::RangeInclusive, core::ops::RangeTo, core::ops::RangeFrom, core::ops::RangeToInclusive. :(

source

pub fn from_range(range: impl RangeBounds<u32>) -> Self

Construct a bit packing spec from a range of bits.

Panics
  • If the range does not fit within the integer type packed by this packing spec.
  • If the range’s start > the range’s end (although most range types should prevent this).
source§

impl<T, F> PackUsize<T, F>

source

pub const fn bits(&self) -> u32

Returns the number of bits needed to pack this value.

source

pub const fn max_value(&self) -> usize

Returns the maximum value of this packing spec (i.e. a value with all the bits set)

source

pub const fn first_bit(&self) -> usize

Returns a value with the first bit in this packing spec set.

source

pub const fn raw_mask(&self) -> usize

Returns a raw, shifted mask for unpacking this packing spec.

source

pub const fn pack_truncating(&self, value: usize, base: usize) -> usize

Pack the self.bits() least-significant bits from value into base.

Any bits more significant than the self.bits()-th bit are ignored.

source

pub fn pack_into_truncating<'base>( &self, value: usize, base: &'base mut usize ) -> &'base mut usize

Pack the self.bits() least-significant bits from value into base, mutating base.

Any bits more significant than the self.bits()-th bit are ignored.

source

pub const fn then<T2>(&self) -> PackUsize<T2, F>
where T2: FromBits<usize>,

Returns a new packer for packing a T2-typed value in the next T2::BITS bits after self.

source

pub const fn next(&self, n: u32) -> PackUsize<usize, F>

Returns a packer for packing a value into the next more-significant n from self.

source

pub const fn remaining(&self) -> PackUsize<usize, F>

Returns a packer for packing a value into all the remaining more-significant bits after self.

source

pub const fn set_all(&self, base: usize) -> usize

Set all bits packed by this packer to 1.

This is a convenience function for

self.pack(self.max_value(), base)
source

pub const fn unset_all(&self, base: usize) -> usize

Set all bits packed by this packer to 0.

This is a convenience function for

self.pack(0, base)
source

pub fn set_all_in<'base>(&self, base: &'base mut usize) -> &'base mut usize

Set all bits packed by this packer to 1 in base.

This is a convenience function for

self.pack_into(self.max_value(), base)
source

pub fn unset_all_in<'base>(&self, base: &'base mut usize) -> &'base mut usize

Set all bits packed by this packer to 0.

This is a convenience function for

self.pack_into(0, base)
source

pub const fn unpack_bits(&self, src: usize) -> usize

Unpack this packer’s bits from source.

source

pub const fn contained_in_any(&self, bits: usize) -> bool

Returns true if any bits specified by this packing spec are set in src.

source

pub const fn contained_in_all(&self, bits: usize) -> bool

Returns true if all bits specified by this packing spec are set in src.

source

pub fn assert_valid(&self)

Asserts that this packing spec is valid.

Because assertions cannot be made in const fn, this performs validating assertions that would ideally be made when constructing a new instance of this type. When packing specs are declared as consts, this method can be called in a unit test to ensure that the spec is valid.

source

pub fn assert_all_valid(specs: &[(&str, Self)])

Assert all of a set of packing specs are valid for packing and unpacking values into the same bitfield.

This asserts that each individual packing spec is valid (by calling assert_valid on that spec), and asserts that no two packing specs in specs overlap (indicating that they can safely represent a single bitfield’s subranges).

This function takes a slice of (&str, Self) tuples, with the &strs providing a name for each packing spec. This name is used to refer to that packing spec in panic messages.

source

pub const fn least_significant_index(&self) -> u32

Returns the index of the least-significant bit of this packing spec (i.e. the bit position of the start of the packed range).

source

pub const fn most_significant_index(&self) -> u32

Returns the index of the most-significant bit of this packing spec (i.e. the bit position of the end of the packed range).

This will always be greater than the value returned by least_significant_index.

source§

impl<T, F> PackUsize<T, F>
where T: FromBits<usize>,

source

pub const fn first() -> Self

Returns a packing spec for packing a T-typed value in the first T::BITS least-significant bits.

source

pub const fn starting_at(bit: u32, n: u32) -> Self

Returns a packer for packing a value into the next n more-significant after the bitth bit.

source

pub const fn pair_at(&self, at: u32) -> PairUsize<T>

Returns a pair type for packing bits from the range specified by self at the specified offset at, which may differ from self’s offset.

The packing pair can be used to pack bits from one location into another location, and vice versa.

source

pub const fn pair_after(&self, after: Self) -> PairUsize<T>

Returns a pair type for packing bits from the range specified by self after the specified packing spec.

source

pub const fn pair_with<F2>(&self, dst: PackUsize<T, F2>) -> PairUsize<T>

Returns a pair type for packing bits from the range specified by self into the range specified by with.

Note

The two ranges must be the same size. This can be asserted by the assert_valid method on the returned pair type.

source

pub fn pack(&self, value: T, base: usize) -> usize

Pack the self.bits() least-significant bits from value into base.

Panics

Panics if any other bits outside of self.bits() are set in value.

source

pub fn pack_into<'base>( &self, value: T, base: &'base mut usize ) -> &'base mut usize

Pack the self.bits() least-significant bits from value into base, mutating base.

Panics

Panics if any other bits outside of self.bits() are set in value.

source

pub fn try_unpack(&self, src: usize) -> Result<T, T::Error>

Attempts to unpack a T-typed value from src.

Returns
  • Ok(T) if a T-typed value could be constructed from the bits in src
  • Err(T::Error) if src does not contain a valid bit pattern for a T-typed value, as determined by T’s FromBits::try_from_bits implementation.
source

pub fn unpack(&self, src: usize) -> T
where T: FromBits<usize>,

Unpacks a T-typed value from src.

Panics

This method panics if src does not contain a valid bit pattern for a T-typed value, as determined by T’s FromBits::try_from_bits implementation.

Trait Implementations§

source§

impl<T, F> Binary for PackUsize<T, F>

source§

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

Formats the value using the given formatter.
source§

impl<T, F> Clone for PackUsize<T, F>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl<T, F> Debug for PackUsize<T, F>

source§

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

Formats the value using the given formatter. Read more
source§

impl<R: RangeBounds<u32>> From<R> for PackUsize

source§

fn from(range: R) -> Self

Converts to this type from the input type.
source§

impl<T, F> LowerHex for PackUsize<T, F>

source§

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

Formats the value using the given formatter.
source§

impl<A, B, F> PartialEq<&PackUsize<B, F>> for PackUsize<A, F>

source§

fn eq(&self, other: &&PackUsize<B, F>) -> bool

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

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.
source§

impl<A, B, F> PartialEq<PackUsize<B, F>> for &PackUsize<A, F>

source§

fn eq(&self, other: &PackUsize<B, F>) -> bool

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

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.
source§

impl<A, B, F> PartialEq<PackUsize<B, F>> for PackUsize<A, F>

source§

fn eq(&self, other: &PackUsize<B, F>) -> bool

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

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.
source§

impl<T, F> UpperHex for PackUsize<T, F>

source§

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

Formats the value using the given formatter.
source§

impl<T, F> Copy for PackUsize<T, F>

source§

impl<T, F> Eq for PackUsize<T, F>

Auto Trait Implementations§

§

impl<T, F> RefUnwindSafe for PackUsize<T, F>

§

impl<T, F> Send for PackUsize<T, F>

§

impl<T, F> Sync for PackUsize<T, F>

§

impl<T, F> Unpin for PackUsize<T, F>

§

impl<T, F> UnwindSafe for PackUsize<T, F>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.