bv/
lib.rs

1#![doc(html_root_url = "https://tov.github.io/bv-rs")]
2//! The main type exported by the library, [`BitVec`], is a packed,
3//! growable bit-vector. Its API mirrors that of `Vec` where reasonable.
4//!
5//! The library also defines slice operations that return
6//! [`BitSlice`] or [`BitSliceMut`], akin to Rust’s array slices but for
7//! bit-vectors. A common API to bit-vectors and bit-slices is provided by the [`Bits`],
8//! [`BitsMut`], and [`BitsPush`] traits. These traits also allow treating a variety
9//! of other types as bit vectors:
10//!
11//!  - all primitive unsigned integer types (*e.g.,* `u64`, `u32`),
12//!  - vectors and slices thereof (*e.g.*, `Vec<usize>`, `&[u8]`, `[u16; 4]`), and
13//!  - unpacked vectors and arrays of `bool` (*e.g.*, `[bool; 15]`).
14//!
15//! Additionally, the [`BitsExt`] trait provides adapter methods including
16//! bit-wise logic and concatenation. These adapters work for all types that implement
17//! [`Bits`].
18//!
19//! # Examples
20//!
21//! A first example with [`BitVec`]:
22//!
23//! ```
24//! use bv::BitVec;
25//!
26//! let mut bv1: BitVec = BitVec::new_fill(false, 50);
27//! let mut bv2: BitVec = BitVec::new_fill(false, 50);
28//!
29//! assert_eq!(bv1, bv2);
30//!
31//! bv1.set(49, true);
32//! assert_ne!(bv1, bv2);
33//!
34//! assert_eq!(bv1.pop(), Some(true));
35//! assert_eq!(bv2.pop(), Some(false));
36//! assert_eq!(bv1, bv2);
37//! ```
38//!
39//! Adapters, from [`BitsExt`] and [`adapter`]:
40//!
41//! ```
42//! use bv::*;
43//! use bv::adapter::BoolAdapter;
44//!
45//! // Here, we use an `&[u16]` as a bit vector, and we adapt a
46//! // `Vec<bool>` as well.
47//! let array = &[0b1100u16];
48//! let vec   = BoolAdapter::new(vec![false, true, false, true]);
49//!
50//! // `xor` is not a `BitVec`, but a lazy adapter, thus, we can index
51//! // it or efficiently compare it to another bit vector, without
52//! // allocating.
53//! let xor   = array.bit_xor(&vec);
54//! assert_eq!( xor, bit_vec![false, true, true, false] );
55//! ```
56//!
57//! This function performs a three-way *or*, returning a `BitVec` without
58//! allocating an intermediate result:
59//!
60//! ```
61//! use bv::{Bits, BitsExt, BitVec};
62//!
63//! fn three_way_or<T, U, V>(bv1: T, bv2: U, bv3: V) -> BitVec<T::Block>
64//!     where T: Bits,
65//!           U: Bits<Block = T::Block>,
66//!           V: Bits<Block = T::Block> {
67//!
68//!     bv1.into_bit_or(bv2).into_bit_or(bv3).to_bit_vec()
69//! }
70//! ```
71//!
72//! # Usage
73//!
74//! It’s [on crates.io](https://crates.io/crates/bv), so you can add
75//!
76//! ```toml
77//! [dependencies]
78//! bv = "0.11.1"
79//! ```
80//!
81//! to your `Cargo.toml` and
82//!
83//! ```rust
84//! extern crate bv;
85//! ```
86//!
87//! to your crate root.
88//!
89//! This crate supports Rust version 1.31 and newer.
90//!
91//! [`BitVec`]: struct.BitVec.html
92//! [`Bits`]: trait.Bits.html
93//! [`BitsMut`]: trait.BitsMut.html
94//! [`BitsPush`]: trait.BitsPush.html
95//! [`BitSlice`]: struct.BitSlice.html
96//! [`BitSliceMut`]: struct.BitSliceMut.html
97//! [`BitsExt`]: trait.BitsExt.html
98//! [`adapter`]: adapter/index.html
99
100#![warn(missing_docs)]
101
102#[cfg(feature = "serde")]
103#[macro_use]
104extern crate serde;
105
106#[cfg(test)]
107#[macro_use]
108extern crate quickcheck;
109
110mod range_compat;
111
112#[macro_use]
113mod macros;
114
115mod storage;
116pub use self::storage::BlockType;
117
118mod traits;
119pub use self::traits::{Bits, BitsExt, BitsMut, BitsMutExt, BitsPush,
120                       BitSliceable, BitSliceableMut};
121
122mod slice;
123pub use self::slice::{BitSlice, BitSliceMut};
124
125mod bit_vec;
126pub use self::bit_vec::BitVec;
127
128mod array_n_impls;
129mod iter;
130mod prims;
131
132pub mod adapter;
bv/lib.rs

bv/
lib.rs
