# 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.

[`Radium`]: radium::Radium
[`index`]: crate::index
[`radium`]: radium
[`store`]: crate::store