Struct BitIdx

pub struct BitIdx<R = usize>
where
    R: BitRegister,
{ /* private fields */ }

Semantic Bit Index

This type is a counter in the ring 0 .. R::BITS and serves to mark a semantic index within some register element. It is a virtual index, and is the stored value used in pointer encodings to track region start information.

It is translated to a real index through the BitOrder trait. This virtual index is the only counter that can be used for address computation, and once lowered to an electrical index through BitOrder::at, the electrical address can only be used for setting up machine instructions.

Type Parameters

• R: The register element that this index governs.

Validity

Values of this type are required to be in the range 0 .. R::BITS. Any value not less than R::BITS makes the program invalid, and will likely cause either a crash or incorrect memory access.

Construction

This type can never be constructed outside of the bitvec crate. It is passed in to BitOrder implementations, which may use it to construct electrical position values from it. All values of this type constructed by bitvec are known to be correct in their region; no other construction site can be trusted.

Implementations

impl<R> BitIdx<R>

where R: BitRegister,

pub const MAX: Self

The inclusive maximum index within an R element.

pub const MIN: Self

The inclusive minimum index within an R element.

pub fn new(idx: u8) -> Result<Self, BitIdxError<R>>

Wraps a counter value as a known-good index into an R register.

Parameters

• idx: The counter value to mark as an index. This must be in the range 0 .. R::BITS.

Returns

This returns idx, either marked as a valid BitIdx or an invalid BitIdxError by whether it is within the valid range 0 .. R::BITS.

pub unsafe fn new_unchecked(idx: u8) -> Self

Wraps a counter value as an assumed-good index into an R register.

Parameters

• idx: The counter value to mark as an index. This must be in the range 0 .. R::BITS.

Returns

This unconditionally marks idx as a valid bit-index.

Safety

If the idx value is outside the valid range, then the program is incorrect. Debug builds will panic; release builds do not inspect the value or specify a behavior.

pub fn into_inner(self) -> u8

Removes the index wrapper, leaving the internal counter.

pub fn next(self) -> (Self, bool)

Increments an index counter, wrapping at the back edge of the register.

Parameters

• self: The index to increment.

Returns

• .0: The next index after self.
• .1: Indicates whether the new index is in the next memory address.

pub fn prev(self) -> (Self, bool)

Decrements an index counter, wrapping at the front edge of the register.

Parameters

• self: The index to decrement.

Returns

• .0: The previous index before self.
• .1: Indicates whether the new index is in the previous memory address.

pub fn position<O>(self) -> BitPos<R>

where O: BitOrder,

Computes the bit position corresponding to self under some ordering.

This forwards to O::at::<R>, which is the only public, safe, constructor for a position counter.

pub fn select<O>(self) -> BitSel<R>

where O: BitOrder,

Computes the bit selector corresponding to self under an ordering.

This forwards to O::select::<R>, which is the only public, safe, constructor for a bit selector.

pub fn mask<O>(self) -> BitMask<R>

where O: BitOrder,

Computes the bit selector for self as an accessor mask.

This is a type-cast over Self::select.

pub fn range( self, upto: BitEnd<R>, ) -> impl Iterator<Item = Self> + DoubleEndedIterator + ExactSizeIterator + FusedIterator

Iterates over all indices between an inclusive start and exclusive end point.

Because implementation details of the range type family, including the RangeBounds trait, are not yet stable, and heterogeneous ranges are not supported, this must be an opaque iterator rather than a direct Range<BitIdx<R>>.

Parameters

• from: The inclusive low bound of the range. This will be the first index produced by the iterator.
• upto: The exclusive high bound of the range. The iterator will halt before yielding an index of this value.

Returns

An opaque iterator that is equivalent to the range from .. upto.

Requirements

from must be no greater than upto.

pub fn range_all() -> impl Iterator<Item = Self> + DoubleEndedIterator + ExactSizeIterator + FusedIterator

Iterates over all possible index values.

Trait Implementations

impl<R> Binary for BitIdx<R>

where R: BitRegister,

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

Formats the value using the given formatter.

impl<R> Clone for BitIdx<R>

where R: BitRegister + Clone,

fn clone(&self) -> BitIdx<R>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<R> Debug for BitIdx<R>

where R: BitRegister,

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

Formats the value using the given formatter.

impl<R> Default for BitIdx<R>

where R: BitRegister + Default,

fn default() -> BitIdx<R>

Returns the “default value” for a type.

impl<R> Display for BitIdx<R>

where R: BitRegister,

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

Formats the value using the given formatter.

impl<R> Hash for BitIdx<R>

where R: BitRegister + Hash,

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<R> Ord for BitIdx<R>

where R: BitRegister + Ord,

fn cmp(&self, other: &BitIdx<R>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<R> PartialEq for BitIdx<R>

where R: BitRegister + PartialEq,

fn eq(&self, other: &BitIdx<R>) -> 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<R> PartialOrd for BitIdx<R>

where R: BitRegister + PartialOrd,

fn partial_cmp(&self, other: &BitIdx<R>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<R> Copy for BitIdx<R>

where R: BitRegister + Copy,

impl<R> Eq for BitIdx<R>

where R: BitRegister + Eq,

impl<R> StructuralPartialEq for BitIdx<R>

where R: BitRegister,