Struct packedvec::PackedVec

pub struct PackedVec<T, StorageT = usize> { /* fields omitted */ }

A PackedVec stores vectors of integers efficiently while providing an API similar to Vec. The basic idea is to store each element using the minimum number of bits needed to represent every element in the Vec. For example, if we have a Vec<u64> with elements [20, 30, 140], every element wastes most of its 64 bits: 7 bits is sufficient to represent the range of elements in the vector. Given this input vector, PackedVec stores each elements using exactly 7 bits, saving substantial memory. For vectors which often contain small ranges of numbers, and which are created rarely, but read from frequently, this can be a significant memory and performance win.

Examples

PackedVec has two main API differences from Vec: a PackedVec is created from a Vec; and a PackedVec returns values rather than references. Both points can be seen in this example:

use packedvec::PackedVec;
let v = vec![-1, 30, 120];
let pv = PackedVec::new(v.clone());
assert_eq!(pv.get(0), Some(-1));
assert_eq!(pv.get(2), Some(120));
assert_eq!(pv.get(3), None);
assert_eq!(v.iter().cloned().collect::<Vec<_>>(), pv.iter().collect::<Vec<_>>());

Storage backing type

PackedVec defaults to using usize as a storage backing type. You can choose your own storage type with the new_with_storaget() 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.

Implementations

impl<'a, T> PackedVec<T, usize> where
    T: 'static + AsPrimitive<usize> + FromPrimitive + Ord + PrimInt + ToPrimitive,
    usize: AsPrimitive<T>, 

pub fn new(vec: Vec<T>) -> Self

Constructs a new PackedVec from vec. The PackedVec has usize backing storage, which is likely to be the best choice in nearly all situations.

impl<'a, T, StorageT> PackedVec<T, StorageT> where
    T: 'static + AsPrimitive<StorageT> + FromPrimitive + Ord + PrimInt + ToPrimitive,
    StorageT: AsPrimitive<T> + PrimInt + Unsigned, 

pub fn new_with_storaget(vec: Vec<T>) -> PackedVec<T, StorageT>

Constructs a new PackedVec from vec (with a user-defined backing storage type).

pub fn get(&self, index: usize) -> Option<T>

Return the value at the specified index.

Example

use packedvec::PackedVec;
let v: Vec<u8> = vec![1, 2, 3, 4];
let packedvec = PackedVec::new(v);
let val: Option<u8> = packedvec.get(3);
assert_eq!(val, Some(4));

pub unsafe fn get_unchecked(&self, index: usize) -> T

Returns a reference to an element or subslice, without doing bounds checking.

This is generally not recommended, use with caution! For a safe alternative see get().

Safety

The caller must ensure that the index specified does not exceed this PackedVec’s bound.

Example

use packedvec::PackedVec;
let v: Vec<u8> = vec![1, 2, 3, 4];
let packedvec = PackedVec::new(v);
assert_eq!(unsafe { packedvec.get_unchecked(3) }, 4);

pub fn is_empty(&self) -> bool

Returns true if the PackedVec has no elements.

Example

use packedvec::PackedVec;
let v: Vec<u16> = vec![];
let packedvec = PackedVec::new(v);
assert_eq!(packedvec.is_empty(), true);
let v: Vec<u16> = vec![1, 2, 3, 4];
let packedvec = PackedVec::new(v);
assert_eq!(packedvec.is_empty(), false);

pub fn len(&self) -> usize

Return the number of elements in this PackedVec.

Example

use packedvec::PackedVec;
let v: Vec<u16> = vec![1, 2, 3, 4];
let packedvec = PackedVec::new(v);
assert_eq!(packedvec.len(), 4);

pub fn bwidth(&self) -> usize

How many bits does each packed element consume?

Example

use packedvec::PackedVec;
let packedvec = PackedVec::new(vec![1, 2, 3, 4]);
assert_eq!(packedvec.bwidth(), 2);

pub fn iter(&'a self) -> PackedVecIter<'a, T, StorageT>

Returns an iterator over the PackedVec.

Trait Implementations

impl<T: Clone, StorageT: Clone> Clone for PackedVec<T, StorageT>

fn clone(&self) -> PackedVec<T, StorageT>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, StorageT: Debug> Debug for PackedVec<T, StorageT>

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

Formats the value using the given formatter.

impl<T: Debug + Hash> Hash for PackedVec<T>

fn hash<H: Hasher>(&self, state: &mut H)

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: PartialEq> PartialEq<PackedVec<T, usize>> for PackedVec<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<T: Debug + PartialEq> Eq for PackedVec<T>