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;