In-Element Bit Ordering

This trait manages the translation of semantic bit indices into electrical positions within storage elements of a memory region.

Usage

bitvec APIs operate on semantic index counters that exist in an abstract memory space independently of the real memory that underlies them. In order to affect real memory, bitvec must translate these indices into real values. The at function maps abstract index values into their corresponding real positions that can then be used to access memory.

You will likely never call any of the trait functions yourself. They are used by bitvec internals to operate on memory regions; all you need to do is provide an implementation of this trait as a type parameter to bitvec data structures.

Safety

BitOrder is unsafe to implement because its translation of index to position cannot be forcibly checked by bitvec itself, and an improper implementation will lead to memory unsafety errors and unexpected collisions. The trait has strict requirements for each function. If these are not upheld, then the implementation is considered undefined at the library level and its use may produce incorrect or undefined behavior during compilation.

You are responsible for running verify_for_type or verify in your test suite if you implement BitOrder.

Implementation Rules

Values of this type are never constructed or passed to bitvec functions. Your implementation does not need to be zero-sized, but it will never have access to an instance to view its state. It may refer to other global state, but per the rules of at, that state may not change while any bitvec data structures are alive.

The only function you need to provide is at. Its requirements are listed in its trait documentation.

You may also choose to provide implementations of select and mask. These have a default implementation that is correct, but may be unoptimized for your implementation. As such, you may replace them with a better version, but your implementation of these functions must be exactly equal to the default implementation for all possible inputs.

This requirement is checked by the verify_for_type function.

Verification

The verify_for_type function verifies that a BitOrder implementation is correct for a single BitStore implementor, and the verify function runs verify_for_type on all unsigned integers that implement BitStore on a target. If you run these functions in your test suite, they will provide detailed information if your implementation is incorrect.

Examples

Implementations are not required to remain contiguous over a register, and may have any mapping they wish as long as it is total and bijective. This example swizzles the high and low halves of each byte.

use bitvec::{
  order::BitOrder,
  index::{BitIdx, BitPos},
  mem::BitRegister,
};

pub struct HiLo;

unsafe impl BitOrder for HiLo {
  fn at<R>(index: BitIdx<R>) -> BitPos<R>
  where R: BitRegister {
    unsafe { BitPos::new_unchecked(index.into_inner() ^ 4) }
  }
}

#[test]
#[cfg(test)]
fn prove_hilo() {
  bitvec::order::verify::<HiLo>();
}

Once a BitOrder implementation passes the test suite, it can be freely used as a type parameter in bitvec data structures. The translation takes place automatically, and you never need to look at this trait again.

3.4 KiB Raw Permalink Blame History