Crate bv

The main type exported by the library, BitVec, is a packed, growable bit-vector. Its API mirrors that of Vec where reasonable.

The library also defines slice operations that return BitSlice or BitSliceMut, akin to Rust’s array slices but for bit-vectors. A common API to bit-vectors and bit-slices is provided by the Bits, BitsMut, and BitsPush traits. These traits also allow treating a variety of other types as bit vectors:

• all primitive unsigned integer types (e.g., u64, u32),
• vectors and slices thereof (e.g., Vec<usize>, &[u8], [u16; 4]), and
• unpacked vectors and arrays of bool (e.g., [bool; 15]).

Additionally, the BitsExt trait provides adapter methods including bit-wise logic and concatenation. These adapters work for all types that implement Bits.

Examples

A first example with BitVec:

use bv::BitVec;

let mut bv1: BitVec = BitVec::new_fill(false, 50);
let mut bv2: BitVec = BitVec::new_fill(false, 50);

assert_eq!(bv1, bv2);

bv1.set(49, true);
assert_ne!(bv1, bv2);

assert_eq!(bv1.pop(), Some(true));
assert_eq!(bv2.pop(), Some(false));
assert_eq!(bv1, bv2);

Adapters, from BitsExt and adapter:

use bv::*;
use bv::adapter::BoolAdapter;

// Here, we use an `&[u16]` as a bit vector, and we adapt a
// `Vec<bool>` as well.
let array = &[0b1100u16];
let vec   = BoolAdapter::new(vec![false, true, false, true]);

// `xor` is not a `BitVec`, but a lazy adapter, thus, we can index
// it or efficiently compare it to another bit vector, without
// allocating.
let xor   = array.bit_xor(&vec);
assert_eq!( xor, bit_vec![false, true, true, false] );

This function performs a three-way or, returning a BitVec without allocating an intermediate result:

use bv::{Bits, BitsExt, BitVec};

fn three_way_or<T, U, V>(bv1: T, bv2: U, bv3: V) -> BitVec<T::Block>
    where T: Bits,
          U: Bits<Block = T::Block>,
          V: Bits<Block = T::Block> {

    bv1.into_bit_or(bv2).into_bit_or(bv3).to_bit_vec()
}

Usage

It’s on crates.io, so you can add

[dependencies]
bv = "0.11.1"

to your Cargo.toml and

extern crate bv;

to your crate root.

This crate supports Rust version 1.31 and newer.

Modules

• adapter
  Lazy bit vector adapters.

Macros

• bit_vec
  Like vec! but for BitVec.

Structs

• BitSlice
  A slice of a bit-vector; akin to &'a [bool] but packed.
• BitSliceMut
  A mutable slice of a bit-vector; akin to &'a mut [bool] but packed.
• BitVec
  A bit-vector, akin to Vec<bool> but packed.

Traits

• BitSliceable
  Types that support slicing by ranges.
• BitSliceableMut
  Types that produce mutable slices.
• Bits
  Read-only bit vector operations.
• BitsExt
  Extension trait for adapter operations on bit slices.
• BitsMut
  Mutable bit vector operations that don’t affect the length.
• BitsMutExt
  Extension trait for mutable operations on bit slices.
• BitsPush
  Bit vector operations that change the length.
• BlockType
  Interface to primitive bit storage.