Struct mycelium_bitfield::pack::Pack128

pub struct Pack128<T = u128, F = ()> { /* private fields */ }

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

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

Implementations

impl Pack128<u128>

pub const fn pack_in(value: u128) -> Packing128

Wrap a u128 to add methods for packing bit ranges using Pack128.

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

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

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

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

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

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. :(

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).

impl<T, F> Pack128<T, F>

pub const fn bits(&self) -> u32

Returns the number of bits needed to pack this value.

pub const fn max_value(&self) -> u128

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

pub const fn first_bit(&self) -> u128

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

pub const fn raw_mask(&self) -> u128

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

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

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

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

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

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.

pub const fn then<T2>(&self) -> Pack128<T2, F>

where T2: FromBits<u128>,

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

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

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

pub const fn remaining(&self) -> Pack128<u128, F>

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

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

Set all bits packed by this packer to 1.

This is a convenience function for

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

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

Set all bits packed by this packer to 0.

This is a convenience function for

self.pack(0, base)

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

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

This is a convenience function for

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

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

Set all bits packed by this packer to 0.

This is a convenience function for

self.pack_into(0, base)

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

Unpack this packer’s bits from source.

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

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

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

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

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.

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.

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).

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.

impl<T, F> Pack128<T, F>

where T: FromBits<u128>,

pub const fn first() -> Self

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

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.

pub const fn pair_at(&self, at: u32) -> Pair128<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.

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

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

pub const fn pair_with<F2>(&self, dst: Pack128<T, F2>) -> Pair128<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.

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

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.

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

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.

pub fn try_unpack(&self, src: u128) -> 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.

pub fn unpack(&self, src: u128) -> T

where T: FromBits<u128>,

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

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

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

Formats the value using the given formatter.

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

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn from(range: R) -> Self

Converts to this type from the input type.

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

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

Formats the value using the given formatter.

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

fn eq(&self, other: &&Pack128<B, F>) -> 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<A, B, F> PartialEq<Pack128<B, F>> for &Pack128<A, F>

fn eq(&self, other: &Pack128<B, F>) -> 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<A, B, F> PartialEq<Pack128<B, F>> for Pack128<A, F>

fn eq(&self, other: &Pack128<B, F>) -> 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<T, F> UpperHex for Pack128<T, F>

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

Formats the value using the given formatter.

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

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