Trait bitvec::field::BitField [−][src]
pub trait BitField {
fn load_le<M>(&self) -> M
where
M: BitMemory;
fn load_be<M>(&self) -> M
where
M: BitMemory;
fn store_le<M>(&mut self, value: M)
where
M: BitMemory;
fn store_be<M>(&mut self, value: M)
where
M: BitMemory;
fn load<M>(&self) -> M
where
M: BitMemory,
{ ... }
fn store<M>(&mut self, value: M)
where
M: BitMemory,
{ ... }
}
Expand description
Performs C-style bitfield access through a BitSlice
.
Bit orderings that permit batched access to regions of memory are enabled to
load data from, and store data to, a BitStore
with faster behavior than the
default bit-by-bit traversal.
This trait transfers data between a BitSlice
and a local element. The trait
functions always place the live bit region of the slice against the least
significant bit edge of the local element (return value of load
, argument of
store
).
Implementations are encouraged to preserve in-memory bit ordering within a memory element, so that call sites can provide a value pattern that the user can clearly see matches what they expect for memory ordering. These methods should only move data between locations, without modifying the data itself.
Methods should be called as bits[start .. end].load_or_store()
, where the
range subslice selects no mor than the M::BITS
element width being
transferred.
Required methods
Loads from self
, using little-endian element T
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 theM::BITS
width of the type being loaded. This can be accomplished with range indexing on a larger slice.
Returns
A value M
whose least self.len()
significant bits are filled with
the bits of self
. If self
spans multiple elements T
, then the
lowest-address T
is interpreted as containing the least significant
bits of the return value M
, and the highest-address T
is interpreted
as containing its most significant bits.
Panics
This method is encouraged to panic if self
is empty, or wider than a
single element M
.
Loads from self
, using big-endian element T
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 theM::BITS
width of the type being loaded. This can be accomplished with range indexing on a larger slice.
Returns
A value M
whose least self.len()
significant bits are filled with
the bits of self
. If self
spans multiple elements T
, then the
lowest-address T
is interpreted as containing the most significant
bits of the return value M
, and the highest-address T
is interpreted
as containing its least significant bits.
Panics
This method is encouraged to panic if self
is empty, or wider than a
single element M
.
Stores 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 theM::BITS
width of the type being stored. This can be accomplished with range indexing on a larger slice.value
: A value, whoseself.len()
least significant bits will be stored intoself
.
Behavior
The self.len()
least significant bits of value
are written into the
domain of self
. If self
spans multiple elements T
, then the
lowest-address T
is interpreted as containing the least significant
bits of the M
return value, and the highest-address T
is interpreted
as containing its most significant bits.
Panics
This method is encouraged to panic if self
is empty, or wider than a
single element M
.
Stores 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 theM::BITS
width of the type being stored. This can be accomplished with range indexing on a larger slice.value
: A value, whoseself.len()
least significant bits will be stored intoself
.
Behavior
The self.len()
least significant bits of value
are written into the
domain of self
. If self
spans multiple elements T
, then the
lowest-address T
is interpreted as containing the most significant
bits of the M
return value, and the highest-address T
is interpreted
as containing its least significant bits.
Panics
This method is encouraged to panic if self
is empty, or wider than a
single element M
.
Provided methods
Loads the bits in the self
region into a local value.
This can load into any of the unsigned integers which implement
BitMemory
. Any further transformation must be done 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 theM::BITS
width of the type being loaded. This can be accomplished with range indexing on a larger slice.
Returns
A value M
whose least self.len()
significant bits are filled with
the bits of self
.
Panics
This method is encouraged to panic if self
is empty, or wider than a
single element M
.
Stores a sequence of bits from the user into the domain of self
.
This can store any of the unsigned integers which implement
BitMemory
. Any other types must first be transformed 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 theM::BITS
width of the type being stored. This can be accomplished with range indexing on a larger slice.value
: A value, whoseself.len()
least significant bits will be stored intoself
.
Behavior
The self.len()
least significant bits of value
are written into the
domain of self
.
Panics
This method is encouraged to panic if self
is empty, or wider than a
single element M
.