Struct vob::Vob [] [src]

pub struct Vob<T = usize> { /* fields omitted */ }

A Vob is a "vector of bits": a sequence of bits which exposes a Vec-like interface. Whereas Vec<bool> requires 1 byte of storage per bit, Vob requires only 1 bit of storage per bit. For larger numbers of bits, Vobs can lead to a significant memory decrease and performance increase.

Examples

The vob! macro makes creating small Vobs easy:

let mut v = vob![true, false, true];
assert_eq!(v[1], false);

Operations such as anding two Vobs together are quick; one can also quickly identify which bits are set:

use vob::Vob;
let mut v1 = Vob::from_elem(256, false);
let mut v2 = Vob::from_elem(256, false);
v1.set(67, true);
v2.set(67, true);
v1.set(188, true);
v1.and(&v2);
let num_bits_set = v1.iter_set_bits(..).count();
assert_eq!(num_bits_set, 1);

Storage backing type

Vobs default to using usize as a storage backing type. This is generally a substantial win over using smaller storage types if you use functions such as or(). In such cases, usize on a 64-bit machine is almost exactly twice as fast as using u32. If you only ever set and get individual bits, a smaller data type might be marginally more effective: for such use cases u32 is around 1% faster than usize on a 64-bit machine. You can choose your own storage type with the new_with_storage_type() constructor. In general we recommend using the default usize backing storage unless you have rigorously benchmarked your particular use case and are sure that a different storage type is superior.

Migrating from Vec<bool>

As far as possible, Vob is intended to have a superset of Vec<bool>'s interface, which should make porting most code fairly simple. However, Vec<bool> contains several functions which are not yet implemented in Vob: these are missing simply due to a lack of a current use-case rather than because of any fundamental incompatibilities.

There is one missing feature which, currently, is impossible to implement: assignment to an index. In other words one cannot currently express v[0] = true for a Vob v. Until IndexGet / IndexMove and equivalents are implemented in rustc, this restriction appears to be inevitable. Note that referencing by index works (though via a hack identical to that used in BitVec): one can write println!("{}", v[0]) for a Vob v, for example.

Migrating from BitVec

Vob is directly inspired by the BitVec, but aims to provide an interface more closely aligned to Vec<bool> Several functions in BitVec have different names in Vob, but porting is in general fairly simple. The main semantic difference is that Vobs clear() function empties the Vob of contents (i.e. sets its length to 0), whereas BitVec's function of the same name unsets all bits (keeping the length unchanged). The same effect as BitVec's clear can be achieved by using Vob's set_all(false) function.

Methods

impl Vob<usize>
[src]

[src]

Constructs a new, empty Vob (with usize backing storage, which is likely to be the best choice in nearly all situations).

The Vob will not allocate until elements are pushed onto it.

[src]

Constructs a new, empty Vob (with usize backing storage, which is likely to be the best choice in nearly all situations) with the specified capacity.

The Vob will be able to hold at least capacity elements without reallocating. If capacity is 0, the vector will not allocate.

[src]

Creates a Vob that holds len elements, setting each element to value.

Examples

use vob::Vob;
let v = Vob::from_elem(2, true);
assert_eq!(v.len(), 2);
assert_eq!(v.get(0), Some(true));

[src]

Create a Vob from a u8 slice. The most significant bit of each byte comes first in the resulting Vob.

Examples

#[macro_use] extern crate vob;
use vob::Vob;
fn main() {
    let v = Vob::from_bytes(&[0b10100000, 0b00010010]);
    assert_eq!(v, vob![true, false, true, false, false, false, false, false,
                       false, false, false, true, false, false, true, false]);
}

impl<T: Debug + PrimInt + One + Zero> Vob<T>
[src]

[src]

Constructs a new, empty Vob (with a user-defined backing storage type) with the given capacity.

Examples

use vob::Vob;
let mut v = Vob::<u32>::new_with_storage_type(0);
v.push(true);
assert_eq!(v[0], true);

[src]

Returns the number of bits the Vob can hold without reallocating.

Examples

use vob::Vob;
assert_eq!(Vob::new().capacity(), 0);
assert!(Vob::with_capacity(1).capacity() >= 1);

[src]

Reserves capacity for at least additional more bits to be inserted in the Vob. The Vob may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Examples

use vob::Vob;
let mut v = Vob::new();
v.reserve(1);
assert!(v.capacity() >= 1);

[src]

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

[src]

Shortens the Vob, keeping the first len elements and dropping the rest.

If len is greater than the vector's current length, this has no effect.

The drain method can emulate truncate, but causes the excess elements to be returned instead of dropped.

Note that this method has no effect on the allocated capacity of the vector.

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v = vob![true, false, true];
    v.truncate(2);
    assert_eq!(v, vob![true, false]);
}

[src]

Appends a bool to the back of the Vob.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(true);
v.push(false);
assert_eq!(v.get(0), Some(true));
assert_eq!(v.get(1), Some(false));

[src]

Removes the last element from the Vob and returns it, or None if it is empty.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(true);
assert_eq!(v.pop(), Some(true));
assert_eq!(v.pop(), None);

[src]

Returns the number of elements in the Vob.

[src]

Returns true if the Vob has a length of 0.

Examples

use vob::Vob;
assert_eq!(Vob::from_elem(2, true).is_empty(), false);
assert_eq!(Vob::new().is_empty(), true);

[src]

Splits the collection into two at the given index.

Returns a newly allocated Self. self contains elements [0, at), and the returned Self contains elements [at, len).

Note that the capacity of self does not change.

Examples

use vob::Vob;
let mut v1 = Vob::new();
v1.push(true);
v1.push(false);
let v2 = v1.split_off(1);
assert_eq!(v1, Vob::from_elem(1, true));
assert_eq!(v2, Vob::from_elem(1, false));

[src]

Returns the value of the element at position index or None if out of bounds.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(false);
assert_eq!(v.get(0), Some(false));
assert_eq!(v.get(1), None);

[src]

Sets the value of the element at position index or None if out of bounds. Returns true if this led to a change in the underlying storage or None if out of bounds.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(false);
v.set(0, true);
assert_eq!(v.get(0), Some(true));
assert_eq!(v.set(0, false), Some(true));
assert_eq!(v.set(0, false), Some(false));

Important traits for Iter<'a, T>
[src]

Returns an iterator over the slice.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(false);
v.push(true);
let mut iterator = v.iter();
assert_eq!(iterator.next(), Some(false));
assert_eq!(iterator.next(), Some(true));
assert_eq!(iterator.next(), None);

Important traits for IterSetBits<'a, T>
[src]

Returns an iterator which efficiently produces the index of each set bit in the specified range. Assuming appropriate support from your CPU, this is much more efficient than checking each bit individually.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(false);
v.push(true);
let mut iterator = v.iter_set_bits(..);
assert_eq!(iterator.next(), Some(1));
assert_eq!(iterator.next(), None);

Important traits for IterUnsetBits<'a, T>
[src]

Returns an iterator which efficiently produces the index of each unset bit in the specified range. Assuming appropriate support from your CPU, this is much more efficient than checking each bit individually.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(false);
v.push(true);
let mut iterator = v.iter_unset_bits(..);
assert_eq!(iterator.next(), Some(0));
assert_eq!(iterator.next(), None);

Important traits for StorageIter<'a, T>
[src]

Return an iterator over the underlying storage blocks. The last block is guaranteed to have "unused" bits (i.e. those past self.len()) set to 0.

Examples

use vob::Vob;
let v1 = Vob::from_elem(10, true);
assert_eq!(v1.iter_storage().next(), Some((1 << 10) - 1));
let v2 = Vob::from_elem(129, true);
assert_eq!(v2.iter_storage().last(), Some(1));

[src]

Resizes the Vob in-place so that len is equal to new_len.

If new_len is greater than len, the Vob is extended by the difference, with each additional slot filled with value. If new_len is less than len, the vob is simply truncated.

Examples

use vob::Vob;
let mut v = Vob::new();
v.push(false);
v.resize(129, true);
assert_eq!(v.len(), 129);
assert_eq!(v.get(0), Some(false));
assert_eq!(v.get(128), Some(true));

[src]

Appends all elements in a slice to the Vob.

Iterates over the slice other and appends elements in order.

Note that this function is same as extend except that it is specialized to work with slices instead. If and when Rust gets specialization this function will likely be deprecated (but still available).

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v = vob![true];
    v.extend_from_slice(&vec![false, true]);
    assert_eq!(v, vob![true, false, true]);
}

[src]

Clears the Vob, removing all values.

Note that this method has no effect on the allocated capacity of the Vob.

[src]

Sets all bits in the Vob to value. Notice that this does not change the number of bits stored in the Vob.

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v = vob![true, false, true];
    v.set_all(false);
    assert_eq!(v, vob![false, false, false]);
}

[src]

Negates all bits in the Vob.

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v = vob![true, false];
    v.negate();
    assert_eq!(v, vob![false, true]);
}

[src]

For each bit in this Vob, and it with the corresponding bit in other, returning true if this led to any changes or false otherwise. The two Vobs must have the same number of bits.

Panics

If the two Vobs are of different length.

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v1 = vob![true, false, false];
    let v2 = vob![true, true, false];
    v1.and(&v2);
    assert_eq!(v1, vob![true, false, false]);
}

[src]

For each bit in this Vob, or it with the corresponding bit in other, returning true if this led to any changes or false otherwise. The two Vobs must have the same number of bits.

Panics

If the two Vobs are of different length.

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v1 = vob![true, false, false];
    let v2 = vob![false, true, false];
    v1.or(&v2);
    assert_eq!(v1, vob![true, true, false]);
}

[src]

For each bit in this Vob, xor it with the corresponding bit in other, returning true if this led to any changes or false otherwise. The two Vobs must have the same number of bits.

Panics

If the two Vobs are of different length.

Examples

#[macro_use] extern crate vob;
fn main() {
    let mut v1 = vob![true, false, true];
    let v2 = vob![false, true, true];
    v1.xor(&v2);
    assert_eq!(v1, vob![true, true, false]);
}

Trait Implementations

impl<T: Clone> Clone for Vob<T>
[src]

[src]

Returns a copy of the value. Read more

1.0.0
[src]

Performs copy-assignment from source. Read more

impl Default for Vob<usize>
[src]

[src]

Returns the "default value" for a type. Read more

impl<T: Debug + One + PrimInt + Zero> Debug for Vob<T>
[src]

[src]

Formats the value using the given formatter. Read more

impl<T: Debug + One + PrimInt + Zero> Extend<bool> for Vob<T>
[src]

[src]

Extends a collection with the contents of an iterator. Read more

impl FromIterator<bool> for Vob<usize>
[src]

[src]

Create a Vob from an iterator.

Examples

use std::iter::FromIterator;
use vob::Vob;
let v = Vob::from_iter(vec![true, false]);
assert_eq!(v, Vob::from_iter(vec![true, false]));

impl<T: Debug + One + PrimInt + Zero> Index<usize> for Vob<T>
[src]

The returned type after indexing.

[src]

Performs the indexing (container[index]) operation.

impl<'a, T: Debug + One + PrimInt + Zero> IntoIterator for &'a Vob<T>
[src]

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Important traits for Iter<'a, T>
[src]

Creates an iterator from a value. Read more

impl<T: Debug + One + PrimInt + Zero> PartialEq for Vob<T>
[src]

[src]

This method tests for self and other values to be equal, and is used by ==. Read more

1.0.0
[src]

This method tests for !=.

impl<T: Debug + One + PrimInt + Zero> Eq for Vob<T>
[src]

impl<T: Debug + Hash + One + PrimInt + Zero> Hash for Vob<T>
[src]

[src]

Feeds this value into the given [Hasher]. Read more

1.3.0
[src]

Feeds a slice of this type into the given [Hasher]. Read more

Auto Trait Implementations

impl<T> Send for Vob<T> where
    T: Send

impl<T> Sync for Vob<T> where
    T: Sync