Struct mycelium_bitfield::pack::Pack8
source · pub struct Pack8<T = u8, F = ()> { /* private fields */ }
Expand description
A spec for packing values into selected bit ranges of u8
values.
See the module-level documentation for details on using packing specs.
Implementations§
source§impl Pack8<u8>
impl Pack8<u8>
sourcepub const fn pack_in(value: u8) -> Packing8
pub const fn pack_in(value: u8) -> Packing8
Wrap a u8
to add methods for packing bit ranges using Pack8
.
This is equivalent to calling Packing8::new
, but only requires importing the packer type.
sourcepub const fn least_significant(n: u32) -> Self
pub const fn least_significant(n: u32) -> Self
Returns a packer for packing a value into the first bits
bits.
sourcepub const fn from_mask(mask: u8) -> Self
pub const fn from_mask(mask: u8) -> Self
Returns a packer that will pack a value into the provided mask.
sourcepub const fn from_const_range(range: Range<u32>) -> Self
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::Range
s, and not with
core::ops::RangeInclusive
, core::ops::RangeTo
,
core::ops::RangeFrom
, core::ops::RangeToInclusive
. :(
sourcepub fn from_range(range: impl RangeBounds<u32>) -> Self
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> Pack8<T, F>
impl<T, F> Pack8<T, F>
sourcepub const fn max_value(&self) -> u8
pub const fn max_value(&self) -> u8
Returns the maximum value of this packing spec (i.e. a value with all the bits set)
sourcepub const fn first_bit(&self) -> u8
pub const fn first_bit(&self) -> u8
Returns a value with the first bit in this packing spec set.
sourcepub const fn raw_mask(&self) -> u8
pub const fn raw_mask(&self) -> u8
Returns a raw, shifted mask for unpacking this packing spec.
sourcepub const fn pack_truncating(&self, value: u8, base: u8) -> u8
pub const fn pack_truncating(&self, value: u8, base: u8) -> u8
Pack the self.bits()
least-significant bits from value
into base
.
Any bits more significant than the self.bits()
-th bit are ignored.
sourcepub fn pack_into_truncating<'base>(
&self,
value: u8,
base: &'base mut u8
) -> &'base mut u8
pub fn pack_into_truncating<'base>( &self, value: u8, base: &'base mut u8 ) -> &'base mut u8
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.
sourcepub const fn then<T2>(&self) -> Pack8<T2, F>
pub const fn then<T2>(&self) -> Pack8<T2, F>
Returns a new packer for packing a T2
-typed value in the
next T2::BITS
bits after self
.
sourcepub const fn next(&self, n: u32) -> Pack8<u8, F>
pub const fn next(&self, n: u32) -> Pack8<u8, F>
Returns a packer for packing a value into the next more-significant
n
from self
.
sourcepub const fn remaining(&self) -> Pack8<u8, F>
pub const fn remaining(&self) -> Pack8<u8, F>
Returns a packer for packing a value into all the remaining
more-significant bits after self
.
sourcepub const fn set_all(&self, base: u8) -> u8
pub const fn set_all(&self, base: u8) -> u8
Set all bits packed by this packer to 1.
This is a convenience function for
self.pack(self.max_value(), base)
sourcepub fn set_all_in<'base>(&self, base: &'base mut u8) -> &'base mut u8
pub fn set_all_in<'base>(&self, base: &'base mut u8) -> &'base mut u8
Set all bits packed by this packer to 1 in base
.
This is a convenience function for
self.pack_into(self.max_value(), base)
sourcepub fn unset_all_in<'base>(&self, base: &'base mut u8) -> &'base mut u8
pub fn unset_all_in<'base>(&self, base: &'base mut u8) -> &'base mut u8
Set all bits packed by this packer to 0.
This is a convenience function for
self.pack_into(0, base)
sourcepub const fn unpack_bits(&self, src: u8) -> u8
pub const fn unpack_bits(&self, src: u8) -> u8
Unpack this packer’s bits from source
.
sourcepub const fn contained_in_any(&self, bits: u8) -> bool
pub const fn contained_in_any(&self, bits: u8) -> bool
Returns true
if any bits specified by this packing spec
are set in src
.
sourcepub const fn contained_in_all(&self, bits: u8) -> bool
pub const fn contained_in_all(&self, bits: u8) -> bool
Returns true
if all bits specified by this packing spec
are set in src
.
sourcepub fn assert_valid(&self)
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 const
s, this method can be called in
a unit test to ensure that the spec is valid.
sourcepub fn assert_all_valid(specs: &[(&str, Self)])
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 &str
s providing a name for each packing spec. This name
is used to refer to that packing spec in panic messages.
sourcepub const fn least_significant_index(&self) -> u32
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).
sourcepub const fn most_significant_index(&self) -> u32
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> Pack8<T, F>
impl<T, F> Pack8<T, F>
sourcepub const fn first() -> Self
pub const fn first() -> Self
Returns a packing spec for packing a T
-typed value in the
first T::BITS
least-significant bits.
sourcepub const fn starting_at(bit: u32, n: u32) -> Self
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 bit
th bit.
sourcepub const fn pair_at(&self, at: u32) -> Pair8<T>
pub const fn pair_at(&self, at: u32) -> Pair8<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.
sourcepub const fn pair_after(&self, after: Self) -> Pair8<T>
pub const fn pair_after(&self, after: Self) -> Pair8<T>
Returns a pair type for packing bits from the range
specified by self
after the specified packing spec.
sourcepub const fn pair_with<F2>(&self, dst: Pack8<T, F2>) -> Pair8<T>
pub const fn pair_with<F2>(&self, dst: Pack8<T, F2>) -> Pair8<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.
sourcepub fn pack(&self, value: T, base: u8) -> u8
pub fn pack(&self, value: T, base: u8) -> u8
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
.
sourcepub fn pack_into<'base>(&self, value: T, base: &'base mut u8) -> &'base mut u8
pub fn pack_into<'base>(&self, value: T, base: &'base mut u8) -> &'base mut u8
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
.
sourcepub fn try_unpack(&self, src: u8) -> Result<T, T::Error>
pub fn try_unpack(&self, src: u8) -> Result<T, T::Error>
Attempts to unpack a T
-typed value from src
.
Returns
Ok(T)
if aT
-typed value could be constructed from the bits insrc
Err(T::Error)
ifsrc
does not contain a valid bit pattern for aT
-typed value, as determined byT
’sFromBits::try_from_bits
implementation.