Struct nucleic_acid::BitsVec

pub struct BitsVec<T: ReprUsize> { /* fields omitted */ }

A vector to hold values that have a known bit range.

For example, DNA nucleotides don't need 8 bits to represent them. We know they only have four possible values, so 2 bits would be enough.

use nucleic_acid::{BitsVec, ReprUsize};
use std::mem;

#[derive(Clone, Copy, Debug)]
#[repr(usize)]
enum Nucleotide {
    Adenine,
    Thymine,
    Guanine,
    Cytosine,
}

impl ReprUsize for Nucleotide {
    fn from_usize(i: usize) -> Self {
        assert!(i <= 3, "expected vales in the range [0, 3]");
        unsafe { mem::transmute(i) }
    }

    fn into_usize(self) -> usize {
        self as usize
    }
}

fn main() {
    let vec = BitsVec::with_elements(2, 100, Nucleotide::Adenine);
    assert!(vec.len() == 100);
    // depends on the architecture (since BitsVec internally uses Vec<usize>)
    assert!(vec.inner_len() == 2 || vec.inner_len() == 4);
}

The human genome has ~3 billion bases (that's 3 GB). Using 8 bits for each of them would be a waste of space. This representation reduces the memory consumed by a factor of 6.

Methods

impl<T: ReprUsize> BitsVec<T>

fn new(bits: usize) -> BitsVec<T>

Create a new vector that can hold values no larger than the specified bits

fn with_capacity(bits: usize, capacity: usize) -> BitsVec<T>

Creates a new vector that can hold the specified bits (atmost) and has capacity for "N" additional elements.

fn push(&mut self, value: T)

Push a value into the vector.

fn get(&self, i: usize) -> T

Get the value from an index in the vector. Note that this is similar to indexed getting, and so it panics when the index is out of bounds. For the non-panicking version, use checked_get

fn checked_get(&self, i: usize) -> Option<T>

Returns Some(T) if the element exists at the given index or None if it doesn't.

fn set(&mut self, i: usize, value: T)

Set a value at the given index. Note that this is similar to indexed setting, and so it panics when the index is out of bounds.

fn from_iter<I>(bits: usize, iterable: I) -> BitsVec<T> where
    I: Iterator<Item = T>, 

Creates a vector consuming an iterator of elements.

fn len(&self) -> usize

Returns the length of the vector. This only indicates the number of units it contains, and not the length of the inner vector.

fn is_empty(&self) -> bool

Returns true if the vector contains no values (or false otherwise).

fn reserve(&mut self, additional: usize)

Reserve space for "N" additional elements.

fn shrink_to_fit(&mut self)

Shrink the inner vector's capacity to fit to its length. It does nothing more than calling the same method in the inner vector.

fn truncate(&mut self, length: usize)

Truncate the vector to the given length, removing the out-of-bound elements. Note that this method panics when the length is greater than current length.

fn clear(&mut self)

Clears the inner vector. Note that this is similar to calling truncate with zero.

fn inner_len(&self) -> usize

Returns the length of the inner vector. Useful for measuring the memory consumption of the elements.

fn iter(&self) -> Iter<T>

Creates an iterator over the elements. Note that unlike other iterators, this gives the elements themselves, and not their references.

fn into_iter(self) -> IntoIter<T>

Creates an iterator consuming the vector.

impl<T: ReprUsize + Clone> BitsVec<T>

fn with_elements(bits: usize, length: usize, value: T) -> BitsVec<T>

Creates a vector initialized with "N" copies of the given element.

fn extend_with_element(&mut self, length: usize, value: T)

Extends the vector to the specified length, filling additional values with the given element. Note that this method panics when the specified length is shorter than the initial length.

impl<T: ReprUsize + PartialEq> BitsVec<T>

fn contains(&self, element: &T) -> bool

Checks whether the vector contains the given element in O(n) time.

Trait Implementations

impl<T: Clone + ReprUsize> Clone for BitsVec<T>

fn clone(&self) -> BitsVec<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Hash + ReprUsize> Hash for BitsVec<T>

fn hash<__HT: Hasher>(&self, __arg_0: &mut __HT)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

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

impl<T: ReprUsize + Debug> Debug for BitsVec<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: ReprUsize> PartialEq for BitsVec<T>

fn eq(&self, other: &Self) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, T: ReprUsize> IntoIterator for &'a BitsVec<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a, T>

Creates an iterator from a value.

impl<T: ReprUsize> IntoIterator for BitsVec<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<T>

Creates an iterator from a value.