Trait bitvec::fields::BitField

source · [−]
pub trait BitField {
    fn load_le<U>(&self) -> U
    where
        U: BitStore;

    fn load_be<U>(&self) -> U
    where
        U: BitStore;

    fn store_le<U>(&mut self, value: U)
    where
        U: BitStore;

    fn store_be<U>(&mut self, value: U)
    where
        U: BitStore;

    fn load<U>(&self) -> U
    where
        U: BitStore,
    { ... }

    fn store<U>(&mut self, value: U)
    where
        U: BitStore,
    { ... }
}
Expand description

Permit a specific BitSlice to be used for C-style bitfield access.

Orders that permit batched access to regions of memory are enabled to load data from a BitSlice and store data to a BitSlice with faster behavior than the default bit-by-bit traversal.

This trait transfers data between a BitSlice and an element. The trait functions always place the live bit region against the least significant bit edge of the transfer element (return value for load, argument for store).

Implementations are encouraged to preserve in-memory bit ordering, so that call sites can provide a value pattern that the user can clearly see matches what they expect for memory ordering. These methods merely move data from a fixed location in an element to a variable location in the slice.

Methods should be called as bits[start .. end].load_or_store(), where the range subslice selects up to but no more than the U::BITS element width.

Required methods

Load from self, using little-endian element ordering.

This function interprets a multi-element slice as having its least significant chunk in the low memory address, and its most significant chunk in the high memory address. Each element T is still interpreted from individual bytes according to the local CPU ordering.

Parameters
  • &self: A read reference to some bits in memory. This slice must be trimmed to have a width no more than the U::BITS width of the type being loaded. This can be accomplished with range indexing on a larger slice.
Returns

A U value whose least self.len() significant bits are filled with the bits of self. If self spans multiple T elements, then the lowest-address T is interpreted as containing the least significant bits of the U return value, and the highest-address T is interpreted as containing its most significant bits.

Panics

If self is empty, or wider than a single U element, this panics.

Load from self, using big-endian element ordering.

This function interprets a multi-element slice as having its most significant chunk in the low memory address, and its least significant chunk in the high memory address. Each element T is still interpreted from individual bytes according to the local CPU ordering.

Parameters
  • &self: A read reference to some bits in memory. This slice must be trimmed to have a width no more than the U::BITS width of the type being loaded. This can be accomplished with range indexing on a larger slice.
Returns

A U value whose least self.len() significant bits are filled with the bits of self. If self spans multiple T elements, then the lowest-address T is interpreted as containing the most significant bits of the U return value, and the highest-address T is interpreted as containing its least significant bits.

Store into self, using little-endian element ordering.

This function interprets a multi-element slice as having its least significant chunk in the low memory address, and its most significant chunk in the high memory address. Each element T is still interpreted from individual bytes according to the local CPU ordering.

Parameters
  • &mut self: A write reference to some bits in memory. This slice must be trimmed to have a width no more than the U::BITS width of the type being stored. This can be accomplished with range indexing on a larger slice.
  • value: A value, whose self.len() least significant bits will be stored into self.
Behavior

The self.len() least significant bits of value are written into the domain of self. If self spans multiple T elements, then the lowest-address T is interpreted as containing the least significant bits of the U return value, and the highest-address T is interpreted as containing its most significant bits.

Panics

If self is empty, or wider than a single U element, this panics.

Store into self, using big-endian element ordering.

This function interprets a multi-element slice as having its most significant chunk in the low memory address, and its least significant chunk in the high memory address. Each element T is still interpreted from individual bytes according to the local CPU ordering.

Parameters
  • &mut self: A write reference to some bits in memory. This slice must be trimmed to have a width no more than the U::BITS width of the type being stored. This can be accomplished with range indexing on a larger slice.
  • value: A value, whose self.len() least significant bits will be stored into self.
Behavior

The self.len() least significant bits of value are written into the domain of self. If self spans multiple T elements, then the lowest-address T is interpreted as containing the most significant bits of the U return value, and the highest-address T is interpreted as containing its least significant bits.

Panics

If self is empty, or wider than a single U element, this panics.

Provided methods

Load the sequence of bits from self into the least-significant bits of an element.

This can load any fundamental type which implements BitStore. Other Rust fundamental types which do not implement it must be recast appropriately by the user.

The default implementation of this function calls load_le on little-endian byte-ordered CPUs, and load_be on big-endian byte-ordered CPUs.

Parameters
  • &self: A read reference to some bits in memory. This slice must be trimmed to have a width no more than the U::BITS width of the type being loaded. This can be accomplished with range indexing on a larger slice.
Returns

A U value whose least self.len() significant bits are filled with the bits of self.

Panics

If self is empty, or wider than a single U element, this panics.

Stores a sequence of bits from the user into the domain of self.

This can store any fundamental type which implements BitStore. Other Rust fundamental types which do not implement it must be recast appropriately by the user.

The default implementation of this function calls store_le on little-endian byte-ordered CPUs, and store_be on big-endian byte-ordered CPUs.

Parameters
  • &mut self: A write reference to some bits in memory. This slice must be trimmed to have a width no more than the U::BITS width of the type being stored. This can be accomplished with range indexing on a larger slice.
  • value: A value, whose self.len() least significant bits will be stored into self.
Behavior

The self.len() least significant bits of value are written into the domain of self.

Panics

If self is empty, or wider than a single U element, this panics.

Implementors