1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
/*! # Addressable Bits
`bitvec` is a foundation library for memory compaction techniques that rely on
viewing memory as bit-addressed rather than byte-addressed.
The `bitvec` project is designed to provide a comprehensive set of tools for
users who need memory compaction, with as low a cost as possible.
# Usage
`bitvec` provides data structures that specialize the major sequence types in
the standard library:
- `[bool]` becomes [`BitSlice`]
- `[bool; N]` becomes [`BitArray`]
- `Box<[bool]>` becomes [`BitBox`]
- `Vec<bool>` becomes [`BitVec`]
You can start using the crate in an existing codebase by replacing types and
chasing compiler errors from there.
As an example,
```rust
# #[cfg(feature = "alloc")] {
let mut io_buf: Vec<u8> = Vec::new();
io_buf.extend(&[0x47, 0xA5]);
let mut stats: Vec<bool> = Vec::new();
stats.extend(&[true, false, true, true, false, false, true, false]);
# }
```
would become
```rust
# #[cfg(feature = "alloc")] {
use bitvec::prelude::*;
let mut io_buf = bitvec![Msb0, u8; 0; 16];
io_buf[.. 4].store(4u8);
io_buf[4 .. 8].store(7u8);
io_buf[8 .. 16].store(0xA5u8);
let mut stats: BitVec = BitVec::new();
stats.extend(&[true, false, true, true, false, false, true, false]);
# }
```
# Capabilities
`bitvec` stands out from other bit-vector libraries, both in Rust and in other
languages, in a few significant ways.
Unlike other Rust libraries, `bitvec` stores its information in pointers to
memory regions, rather than in the region directly. By using its own pointer
encoding scheme, it can use references `&BitSlice` and `&mut BitSlice` to manage
memory and fit seamlessly into the Rust language rules and API signatures.
Unlike *any* other bit-sequence system, `bitvec` enables users to specify the
register element type used to store data, and the ordering of bits within those
elements. This sidesteps the problems found in C [bitfields], C++
[`std::bitset`], Python [`bitstring`], Erlang [`bitstream`], and Rust libraries
such as [`bit-vec`].
By permitting the in-memory layout to be specified by the user, rather than
within the library, users are able to have the behavior characteristics they
want without effort or workarounds.
This works by suppling two type parameters: `O: BitOrder` specifies the ordering
of bits within a register element, and `T: BitStore` specifies which register
element is used to store bits. `T` is restricted to be only the unsigned
integers, and `Cell` or `Atomic` variants of them.
`bitvec` correctly handles memory aliasing by leveraging the type system to mark
regions that have become subject to concurrency and either force the use of
atomic memory accesses or forbid simultaneous multiprocessing. You will never
need to insert your own guards to prevent race conditions, and [`BitSlice`]
provides APIs to separate any slice into its aliased and unaliased sub-regions.
# Library Structure
You should generally import the library prelude, with
```rust
use bitvec::prelude::*;
```
The prelude contains all the symbols you will need to make use of the crate.
Almost all begin with the prefix `Bit`; only the orderings `Lsb0` and `Msb0` do
not. This will reduce the likelihood of name collisions. See the prelude module
documentation for more detail on which symbols are imported, and how you can
more precisely control this.
Each major component in the library is divided into its own module. This
includes each data structure and trait, as well as utility objects used for
implementation. The data structures that mirror the language distribution have
submodules for each part of their mirroring: `api` ports inherent methods,
`iter` contains iteration logic, `ops` operator overrides, and `traits` all
other trait implementations.The data structure’s own module only contains its
own definition and its inherent methods that are not ports of the standard
libraries.
# Usage
As a replacement for `bool` data structures, you should be able to replace old
type definition and value construction sites with their corresponding items from
this crate, and the rest of your project should just work with the new types.
To use `bitvec` for bitfields, use [`BitArray`] or [`BitVec`] to manage your data
buffers (compile-time static and run-time dynamic, respectively), and the
[`BitField`] trait to manage transferring values into and out of them.
The [`BitSlice`] type contains most of the methods and trait implementations used
to interact with the *contents* of a memory buffer. [`BitVec`] adds methods for
operating on allocations, and specializes [`BitSlice`] methods that can take
advantage of owned buffers.
The `domain` module, whose types are accessed by the `.{bit_,}domain{,_mut}`
methods on [`BitSlice`], allows users to split their views of memory on aliasing
boundaries, removing synchronization where provably safe.
There are many ways to construct a bit-level view of data. The [`BitArray`],
`BitBox`, and [`BitVec`] types are all owning types that contain a buffer of
memory and dereference to [`BitSlice`] in order to view it. In addition, you can
borrow any piece of ordinary Rust memory as a [`BitSlice`] view using its
borrowing constructor functions, and the [`BitView`] trait methods.
# Examples
See the `examples/` directory of the project repository for detailed examples,
or the type documentation for introductory samples.
[`BitArray`]: array/struct.BitArray.html
[`BitBox`]: boxed/struct.BitBox.html
[`BitField`]: field/trait.BitField.html
[`BitSlice`]: slice/struct.BitSlice.html
[`BitVec`]: vec/struct.BitVec.html
[`BitView`]: view/trait.BitView.html
[`bitstream`]: https://erlang.org/doc/programming_examples/bit_syntax.html
[`bitstring`]: https://pypi.org/project/bitstring/
[`bit-vec`]: https://crates.io/crates/bit-vec
[`std::bitset`]: https://en.cppreference.com/w/cpp/utility/bitset
[bitfields]: https://en.cppreference.com/w/c/language/bit_field
!*/
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(debug_assertions, warn(missing_docs))]
#![cfg_attr(not(debug_assertions), deny(missing_docs))]
#![deny(unconditional_recursion)]
#[cfg(feature = "alloc")]
extern crate alloc;
#[macro_use]
pub mod macros;
mod access;
pub mod array;
pub mod domain;
pub mod field;
pub mod index;
pub mod mem;
pub mod order;
mod pointer;
pub mod prelude;
pub mod slice;
pub mod store;
pub mod view;
#[cfg(feature = "alloc")]
pub mod boxed;
#[cfg(feature = "alloc")]
pub mod vec;
#[cfg(not(feature = "devel"))]
mod devel;
#[cfg(feature = "devel")]
pub mod devel;
#[cfg(feature = "serde")]
mod serdes;