Struct mycelium_bitfield::pack::PackUsize

source ·

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.