Notes/notes-service/vendor/bitvec/doc/ptr/BitPtr.md

Single-Bit Pointer

This structure defines a pointer to exactly one bit in a memory element. It is a structure, rather than an encoding of a *Bit raw pointer, because it contains more information than can be packed into such a pointer. Furthermore, it can uphold the same requirements and guarantees that the rest of the crate demands, whereäs a raw pointer cannot.

Original

*bool and NonNull<bool>

API Differences

Since raw pointers are not sufficient in space or guarantees, and are limited by not being marked #[fundamental], this is an ordinary struct. Because it cannot use the *const/*mut distinction that raw pointers and references can, this encodes mutability in a type parameter instead.

In order to be consistent with the rest of the crate, particularly the *BitSlice encoding, this enforces that all T element addresses are well-aligned to T and non-null. While this type is used in the API as an analogue of raw pointers, it is restricted in value to only contain the values of valid references to memory, not arbitrary pointers.

ABI Differences

This is aligned to 1, rather than the processor word, in order to enable some crate-internal space optimizations.

Type Parameters

• M: Marks whether the pointer has mutability permissions to the referent memory. Only Mut pointers can be used to create &mut references.
• T: A memory type used to select both the register width and the bus behavior when performing memory accesses.
• O: The ordering of bits within a memory element.

Usage

This structure is used as the bitvec equivalent to *bool. It is used in all raw-pointer APIs and provides behavior to emulate raw pointers. It cannot be directly dereferenced, as it is not a pointer; it can only be transformed back into higher referential types, or used in functions that accept it.

These pointers can never be null or misaligned.

Safety

Rust and LLVM do not have a concept of bit-level initialization yet. Furthermore, the underlying foundational code that this type uses to manipulate individual bits in memory relies on construction of shared references to memory, which means that unlike standard pointers, the T element to which BitPtr values point must always be already initialized in your program context.

bitvec is not able to detect or enforce this requirement, and is currently not able to avoid it. See BitAccess for more information.