# Struct mycelium_bitfield::pack::Pack128

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

## Expand description

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

values.

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

## Implementations§

source§### impl Pack128<u128>

### impl Pack128<u128>

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

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

source#### pub 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.

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

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

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

source#### pub 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`

. :(

source#### pub 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> Pack128<T, F>

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

source#### pub const fn max_value(&self) -> u128

#### pub const fn max_value(&self) -> u128

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

source#### pub const fn first_bit(&self) -> u128

#### pub const fn first_bit(&self) -> u128

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

source#### pub const fn raw_mask(&self) -> u128

#### pub const fn raw_mask(&self) -> u128

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

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

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

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

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

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

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

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) -> Pack128<u128, F>

#### 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`

.

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

#### pub const fn remaining(&self) -> Pack128<u128, 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: u128) -> u128

#### 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)`

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

#### 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)`

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

#### 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)`

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

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

Unpack this packer’s bits from `source`

.

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

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

Returns `true`

if **any** bits specified by this packing spec
are set in `src`

.

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

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

Returns `true`

if **all** bits specified by this packing spec
are set in `src`

.

source#### pub 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.

source#### pub 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.

source#### pub 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).

source#### pub 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> Pack128<T, F>

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

source#### pub 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.

source#### pub 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.

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

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

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

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

source#### pub const fn pair_with<F2>(&self, dst: Pack128<T, F2>) -> Pair128<T>

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

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

#### 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`

.

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

#### 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`

.

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

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