Trait bitvec::access::BitAccess

source · [−]
pub trait BitAccess: Radium where
    <Self as Radium>::Item: BitRegister, {
    fn clear_bits(&self, mask: BitMask<Self::Item>) -> Self::Item { ... }
    fn set_bits(&self, mask: BitMask<Self::Item>) -> Self::Item { ... }
    fn invert_bits(&self, mask: BitMask<Self::Item>) -> Self::Item { ... }
    fn write_bit<O>(&self, index: BitIdx<Self::Item>, value: bool) -> bool
    where
        O: BitOrder,
    { ... }
    fn get_writers(
        value: bool
    ) -> for<'a> fn(_: &'a Self, _: BitMask<Self::Item>) -> Self::Item { ... }
}
Expand description

Bit-Level Access Instructions

This trait extends Radium in order to manipulate specific bits in an element according to the crate’s logic. It drives all memory access instructions and is responsible for translating the bit-selection logic of the index module into real effects.

This is blanket-implemented on all types that permit shared-mutable memory access via the radium crate. Its use is constrained in the store module. It is required to be a publicly accessible symbol, as it is exported in other traits, but it is a crate-internal item and is not part of the public API. Its blanket implementation for <R: Radium> prevents any other implementations from being written.

Implementation and Safety Notes

This trait is automatically implemented for all types that implement Radium, and relies exclusively on Radium’s API and implementations for its work. In particular, Radium has no functions which operate on pointers: it exclusively operates on memory through references. Since references must always refer to initialized memory, BitAccess and, by extension, all APIs in bitvec that touch memory, cannot be used to operate on uninitialized memory in any way.

While you may create a bitvec pointer object that targets uninitialized memory, you may not dereference it until the targeted memory has been wholly initialized with integer values.

This restriction cannot be loosened without stable access to pointer-based atomic intrinsics in the Rust standard library and corresponding updates to the Radium trait.

Do not attempt to access uninitialized memory through bitvec. Doing so will cause bitvec to produce references to uninitialized memory, which is undefined behavior.

Provided Methods

Clears bits within a memory element to 0.

The mask provided to this method must be constructed from indices that are valid in the caller’s context. As the mask is already computed by the caller, this does not take an ordering type parameter.

Parameters
  • mask: A mask of any number of bits. This is a selection mask: all bits in the mask that are set to 1 will set the corresponding bit in *self to 0.
Returns

The prior value of the memory element.

Effects

All bits in *self corresponding to 1 bits in the mask are cleared to 0; all others retain their original value.

Do not invert the mask prior to calling this function. BitMask is a selection type, not a bitwise-operation argument.

Sets bits within a memory element to 1.

The mask provided to this method must be constructed from indices that are valid in the caller’s context. As the mask is already computed by the caller, this does not take an ordering type parameter.

Parameters
  • mask: A mask of any number of bits. This is a selection mask: all bits in the mask that are set to 1 will set the corresponding bit in *self to 1.
Returns

The prior value of the memory element.

Effects

All bits in *self corresponding to 1 bits in the mask are set to 1; all others retain their original value.

Inverts bits within a memory element.

The mask provided to this method must be constructed from indices that are valid in the caller’s context. As the mask is already computed by the caller, this does not take an ordering type parameter.

Parameters
  • mask: A mask of any number of bits. This is a selection mask: all bits in the mask that are set to 1 will invert the corresponding bit in *self.
Returns

The prior value of the memory element.

Effects

All bits in *self corresponding to 1 bits in the mask are inverted; all others retain their original value.

Writes a value to one bit in a memory element, returning the previous value.

Type Parameters
  • O: An ordering of bits in a memory element that translates the index into a real position.
Parameters
  • index: The semantic index of the bit in *self to modify.
  • value: The new bit value to write into *self at the index.
Returns

The bit previously stored in *self at index. These operations are required to load the *self value from memory in order to operate, and so always have the prior value available for use. This can reduce spurious loads throughout the crate.

Effects

*self is updated with the bit at index set to value; all other bits remain unchanged.

Gets the function that will write value into all bits under a mask.

This is useful for preparing bulk operations that all write the same data into memory, and only need to provide the shape of memory to write.

Parameters
  • value: The bit that will be written by the returned function.
Returns

A function which writes value into memory at a given address and under a given mask. If value is false, then this produces clear_bits; if it is true, then this produces set_bits.

Implementors