Struct bitvec::index::BitIdx

#[repr(transparent)]
pub struct BitIdx<R> where
    R: BitRegister,  { /* fields omitted */ }

A semantic index counter within a register element R.

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 an electrical 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 instruction selection.

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, selection, or mask 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 LAST: Self

The inclusive maximum index within an element R.

pub const ZERO: Self

The inclusive minimum index within an element R.

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

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

Parameters

• value: The counter value to mark as an index. This must be not less than Self::ZERO and not more than Self::LAST.

Returns

This returns value, marked as either a valid or invalid index by whether or not it is within the valid range 0 .. R::BITS.

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

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

Parameters

• value: The counter value to mark as an index. This must be not less than Self::ZERO and not more than Self::LAST.

Returns

This returns value, marked as a valid index.

Safety

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

pub fn cast<S>(self) -> Result<BitIdx<S>, BitIdxError<S>> where
    S: BitRegister, 

Casts to a new index type.

This will always succeed if self.value() is a valid index in the S register; it will return an error if the self index is too wide for S.

pub fn value(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 that the new index is in the next register.

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 that the new index is in the previous register.

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: BitTail<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 heterogenous 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.

pub fn offset(self, by: isize) -> (isize, Self)

Computes the jump distance for some number of bits away from a starting index.

This computes the number of elements by which to adjust a base pointer, and then the bit index of the destination bit in the new referent register element.

Parameters

• self: An index within some element, from which the offset is computed.
• by: The distance by which to jump. Negative values move lower in the index and element-pointer space; positive values move higher.

Returns

• .0: The number of elements R by which to adjust a base pointer. This value can be passed directly into ptr::offset.
• .1: The index of the destination bit within the destination element.

pub fn span(self, len: usize) -> (usize, BitTail<R>)

Computes the span information for a region beginning at self for len bits.

The span information is the number of elements in the region that hold live bits, and the position of the tail marker after the live bits.

This forwards to BitTail::span, as the computation is identical for the two types. Beginning a span at any Idx is equivalent to beginning it at the tail of a previous span.

Parameters

• self: The start bit of the span.
• len: The number of bits in the span.

Returns

• .0: The number of elements, starting in the element that contains self, that contain live bits of the span.
• .1: The tail counter of the span’s end point.

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> Clone for BitIdx<R> where
    R: BitRegister, 

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

Returns a copy of the value.

pub 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> Default for BitIdx<R> where
    R: BitRegister, 

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> Hash for BitIdx<R> where
    R: BitRegister, 

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<R: Ord> Ord for BitIdx<R> where
    R: BitRegister, 

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

This method returns an Ordering between self and other.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

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

Restrict a value to a certain interval.

impl<R: PartialEq> PartialEq<BitIdx<R>> for BitIdx<R> where
    R: BitRegister, 

fn eq(&self, other: &BitIdx<R>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &BitIdx<R>) -> bool

This method tests for !=.

impl<R: PartialOrd> PartialOrd<BitIdx<R>> for BitIdx<R> where
    R: BitRegister, 

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

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

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

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

impl<R> TryFrom<u8> for BitIdx<R> where
    R: BitRegister, 

type Error = BitIdxError<R>

The type returned in the event of a conversion error.

fn try_from(value: u8) -> Result<Self, Self::Error>

Performs the conversion.

impl<R: Copy> Copy for BitIdx<R> where
    R: BitRegister, 

impl<R: Eq> Eq for BitIdx<R> where
    R: BitRegister, 

impl<R> StructuralEq for BitIdx<R> where
    R: BitRegister, 

impl<R> StructuralPartialEq for BitIdx<R> where
    R: BitRegister,