Skip to main content

Crate bitref

Crate bitref 

Source
Expand description

§RustCrypto: Bit-Level Reference Types

Crate Docs Build Status Apache 2.0/MIT Licensed MSRV Project Chat

Provides &BitSlice/&mut BitSlice, a fat pointer-sized reference type which can be initialized from &[u8]/&mut [u8] and can be used to implement any reference-based patterns that possible with byte slices, e.g. Borrow, Deref, Index/IndexMut, and ToOwned.

§About

The BitSlice type in this crate was inspired by a similar type in the bitvec. However, the implementation approach used in this crate minimizes use of unsafe code to just fat pointer encoding/decoding and simple repr(transparent) casts to construct reference newtypes.

Notably it performs no arithmetic on pointers whatsoever and works entirely within the domain of slices, largely ensuring any bugs should result in panics rather than memory safety errors, with a hypothetical caveat noted below.

(NOTE: in the future, we may experiment with more usage of unsafe if the performance gains can justify its use, but will ensure the resulting code is easily reasoned about)

§Soundness

This crate relies on operations which are not yet fully specified in the Rust memory model, and while sound in all existing supported versions of the Rust compiler, may result in undefined behavior in future versions.

Notably, while it passes Miri with -Zmiri-tree-borrows, it fails under Stacked Borrows. Ensuring this crate will be fully sound in future versions of Rust will require upstream resolution regarding the operational semantics and this discrepancy between SB/TB. For more information, see:

https://github.com/rust-lang/unsafe-code-guidelines/issues/134

§Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations.

§License

Licensed under either of:

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs§

BitSlice
Slice of bits: similar to &[u8], but with bit-level granularity.
IndexOutOfBounds
Index is out-of-bounds.
Iter
Iterator over the bits of a BitSlice.