Struct nbits_vec::NbitsVec [−] [src]

pub struct NbitsVec<T: Value> {
    // some fields omitted
}

Implement vector contains small N-bits values using T::Block as unit buffer.

The N is an typenum which is nonzero and smaller than the size of T::Block. The T::Block is a PrimInt - primitive iterger type, we expect as Unsigned, suck as u8, u32, u64, but it's ok to use i32,i64,etc.

According to the benchmarks, we sugguest that:

Note that the result only based on my machine. Anyone is welcome for sugguestions to use.

Examples

extern crate nbits_vec as nbits_vec;
use nbits_vec::NbitsVec;
use nbits_vec::consts::N2B64 as N2;
type NVec = NbitsVec<N2>;
fn main() {
    // News.
    let _ = NVec::with_capacity(5);
    let mut vec = NVec::new();
    // Pushes and pops.
    vec.push(0b11);
    vec.push(0b10);
    let val = vec.pop();
    // Resizes and reserves.
    vec.resize(10, 0b01);
    vec.reserve(12);
    assert!(vec.capacity() >= 10 + 12);
    // Gets and sets.
    vec.set(7, 0b10);
    let _ = vec.get(7);
    // Inserts and removes.
    vec.insert(4, 0b01);
    let _ = vec.remove(4);
    // Fills `8` values from `2` as `0b11`.
    vec.fill(2, 8, 0b11);
}

Methods

impl<T: ValueExt> NbitsVec<T>
[src]

fn new() -> Self

Constructs a new, empty NbitsVec

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

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();

Panics

Constructor will panic if the T::Block unit bits is smaller than Nbits. This should panic in new, with_capacity, from_raw_parts methods.

fn with_capacity(capacity: usize) -> Self

Constructs a new, empty Vec with the specified capacity.

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

It is important to note that this function does not specify the length of the returned vector, but only the capacity.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
assert!(vec.capacity() >= 10);

unsafe fn from_raw_parts(ptr: *mut T::Block, length: usize, capacity: usize) -> Self

Constructs a NbitsVec<T> directly from the raw components of another vector, like standard Vec does.

Safety

This is highly unsafe, due to the number of invariants that aren't checked:

  • ptr needs to have been previously allocated via Vec<T>/NbitsVec<T>.
  • length needs to be the length that less than or equal to capacity.
  • capacity needs to be the capacity as a NbitsVec<T>, not the size that the pointer was allocated with.

Examples

use std::mem;
fn main() {
    let mut v: NbitsVec<N2> = NbitsVec::with_capacity(10);
    v.push(1); v.push(2); v.push(3);
    let p = v.raw_mut_ptr();
    let len = v.len();
    let cap = v.capacity();
    unsafe {
        mem::forget(v);
        let rebuilt: NbitsVec<N2> = NbitsVec::from_raw_parts(p, len, cap);
        assert!(cap == rebuilt.capacity());
    }
}

fn capacity(&self) -> usize

Returns the number of elements the vector can hold without reallocating.

Examples

let v: NbitsVec<N1> = NbitsVec::with_capacity(10);
println!("{:?}", v);
assert!(v.capacity() >= 10);
assert_eq!(v.capacity(), 64);

fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the given NbitsVec. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new capacity overflows usize.

Examples

let mut v: NbitsVec<N2> = NbitsVec::new();
assert!(v.capacity() == 0);
v.reserve(100);
assert!(v.capacity() >= 100);

fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more elements to be inserted in the given NbitsVec<N>. Does nothing if the capacity is already sufficient.

Panics

Panics if the new capacity overflows usize.

Examples

use nbits_vec::*;
let mut v: NbitsVec<N2> = NbitsVec::new();
assert!(v.capacity() == 0);
v.reserve_exact(64);
assert_eq!(v.capacity(), 64);
v.reserve_exact(127);
assert!(v.capacity() >= 127);
v.reserve_exact(128);
assert_eq!(v.capacity(), 128);

fn shrink_to_fit(&mut self)

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.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
vec.shrink_to_fit();
assert_eq!(vec.capacity(), 0);

fn truncate(&mut self, len: usize)

Shorten a vector to be len elements long, dropping excess elements.

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

Examples

let mut vec: NbitsVec<N2> = NbitsVec::with_capacity(2);
unsafe { vec.set_len(2) }
vec.truncate(3);
assert_eq!(vec.len(), 2);
vec.truncate(1);
assert_eq!(vec.len(), 1);

unsafe fn set_len(&mut self, len: usize)

Sets the length of a vector.

This will explicitly set the size of the vector, without actually modifying its buffers or reserving additional capacity as needed, so it is up to the caller to ensure that the vector is actually the specified size.

Recommend to use resize() when you actually want to resize the vector.

Examples

let mut v: NbitsVec<N2> = NbitsVec::new();
unsafe {
    v.set_len(3);
}

fn insert(&mut self, index: usize, element: T::Block)

Examples

let mut v: NbitsVec<N2> = NbitsVec::new();
v.push(0b01);
v.push(0b10);
assert_eq!(v.len(), 2);
v.insert(1, 0b11);
assert_eq!(v.get(1), 0b11);
assert_eq!(v.get(2), 0b10);

fn remove(&mut self, index: usize) -> T::Block

Removes and returns the element at position index within the vector, shifting all elements after position index one position to the left.

Panics

Panics if index is out of bounds.

Examples

let mut v: NbitsVec<N2> = NbitsVec::new();
v.push(0b01);
v.push(0b10);
assert_eq!(v.remove(0), 0b01);

fn swap_remove(&mut self, index: usize) -> T::Block

Removes an element from anywhere in the vector and return it, replacing it with the last element.

Panics

Panics if index is out of bounds. Panics if vector is empty.

Examples

let mut v: NbitsVec<N2> = NbitsVec::new();
v.push(0b01);
v.push(0b10);
v.push(0b11);
assert_eq!(v.len(), 3);
println!("{:?}", v);
assert_eq!(v.swap_remove(0), 0b01);
println!("{:?}", v);
assert_eq!(v.len(), 2);
assert_eq!(v.get(0), 0b11);
assert_eq!(v.get(1), 0b10);
println!("{:?}", v);
assert_eq!(v.swap_remove(0), 0b11);

fn append(&mut self, other: &mut Self)

Moves all the elements of other into Self, leaving other empty.

Panics

Panics if the number of elements in the vector overflows a usize.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
let mut other: NbitsVec<N2> = NbitsVec::new();
other.resize(2, 0b10);
vec.append(&mut other);
assert_eq!(vec.len(), 2);
assert_eq!(other.len(), 0);

fn clear(&mut self)

Simplely sets the len as 0.

fn len(&self) -> usize

Returns the number of values.

fn bits(&self) -> usize

Returns the number of bits in current length.

It is related to the element numbers - not the capacity.

Examples

let vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
assert_eq!(vec.bits(), 0);

fn cap_bits(&self) -> usize

Total bits in buf.

Examples

let vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
assert_eq!(vec.cap_bits(), std::mem::size_of::<usize>() * 8);

fn is_empty(&self) -> bool

Returns whether or not the vector is empty.

Alias to len() == 0.

Examples

let vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
assert!(vec.is_empty());

fn push(&mut self, value: T::Block)

Appends an element to the back of a collection.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
vec.push(0b10);
vec.push(0b01);
assert_eq!(vec.len(), 2);

fn pop(&mut self) -> Option<T::Block>

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

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
vec.push(0b10);
vec.push(0b11);
assert_eq!(vec.pop(), Some(0b11));
assert_eq!(vec.pop(), Some(0b10));
assert_eq!(vec.len(), 0);

fn resize(&mut self, new_len: usize, value: T::Block)

Resizes the Vec in-place so that len() is equal to new_len.

If new_len is greater than len(), the Vec is extended by the difference, with each additional slot filled with value. If new_len is less than len(), the Vec is simply truncated. Note that resize expand memeory will use reserve_exact method to fit size.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
vec.resize(10, 0);

fn align(&mut self, from: usize, to: usize)

Move a value flag from from to to, mask or zero the interval bits.

Indeed, it means to insert or remove to - from count of values.

Show what it does:

  • from < to:
  - Before-align: -----1-------------0--------
                       |from         |to
  - After-align:  -----000000000000001--------------0------
                                     |`from`        |`to`
  • from > to:
  - Before-align: -----1-------------0--------
                       |to           |from
  - After-align:  -----0--------
                       |from, to

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
// Prepare data.
vec.resize(24, 0);
vec.fill(0, 12, 1);
vec.fill(12, 12, 2);
// Left align will reduce the length.
vec.align(1, 0);
vec.align(11, 3);
// Right align will expand the length.
vec.align(6, 7);
vec.align(13, 33);
println!("{:?}", vec);

fn fill(&mut self, index: usize, length: usize, value: T::Block)

Fill vector buf as value from index with size length.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
vec.resize(24, 0);
vec.fill(1, 2, 2); // length < buf_unit
vec.fill(0, 8, 1); // offset: 0, 0
vec.fill(7, 10, 2); // offset: n, n
vec.fill(8, 11, 1); // offset: 0, n

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

Examples

let mut vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
unsafe { vec.set_len(2) }
vec.set(0, 0b11);
assert_eq!(vec.get(0), 0b11);

unsafe fn set_raw_bits(&mut self, pos: usize, length: usize, value: T::Block)

Set length bits of buf at offsetth bit as value.

Unsafety

set_raw_bits will not check the offset. Users should ensure to do this manually.

Panics

This method should panic while required length is longer than the buf unit bits size.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::with_capacity(10);

unsafe {
    println!("Set buf 0 as 1");
    vec.set_raw_bits(0, 1, 1);
    println!("Set buf bits [1, 2] as `10`");
    vec.set_raw_bits(1, 2, 2);
    println!("Set buf bits [3, 6] as `1010`");
    vec.set_raw_bits(3, 4, 0b1010);
}
println!("{:?}", vec);
unsafe {
    assert_eq!(vec.get_raw_bits(0, 1), 1);
    assert_eq!(vec.get_raw_bits(1, 2), 2);
    assert_eq!(vec.get_raw_bits(3, 4), 0b1010);
}

unsafe fn set_raw_bit(&mut self, offset: usize, bit: bool)

Set buf unit bit at indexth unit of offsetbit.

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

Get N bits value as B.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::with_capacity(10);
unsafe { vec.set_len(2) }
vec.set(0, 0b11);
assert_eq!(vec.get(0), 0b11);

unsafe fn get_raw_bits(&self, pos: usize, length: usize) -> T::Block

Get length bits of buf at offsetth bit.

Unsafety

get_raw_bits will not check the offset. Users should ensure to do this manually.

Panics

This method should panic while required length is longer than the buf unit bits size.

Examples

let mut vec: NbitsVec<N2> = NbitsVec::new();
vec.resize(10, 0);
println!("{:?}", vec);
for i in 0..8 {
    unsafe { vec.set_raw_bit(i, if i % 2 == 0 { true } else { false }); }
}
println!("{:?}", vec);
unsafe {
    println!("Get buf bits at 0 with length 1");
    assert_eq!(vec.get_raw_bits(0, 1), 1);
    println!("Get buf bits at 1 with length 2");
    assert_eq!(vec.get_raw_bits(1, 2), 2);
    println!("Get buf bits at 3 with length 4");
    assert_eq!(vec.get_raw_bits(3, 4), 0b1010);
}

unsafe fn get_raw_bit(&self, pos: usize) -> bool

Get raw bit at pos.

fn raw_mut_ptr(&mut self) -> *mut T::Block

Returns mutable ptr of T::Block.

fn raw_ptr(&self) -> *const T::Block

Returns ptr of T::Block.

fn as_raw_slice(&self) -> &[T::Block]

Return raw slice of T::Block.

fn as_mut_raw_slice(&mut self) -> &mut [T::Block]

Returns mutable raw slice of T::Block.

fn into_raw_boxed_slice(self) -> Box<[T::Block]>

Returns raw boxed slice of T::Block.

Trait Implementations

impl<T: ValueExt> Default for NbitsVec<T>
[src]

fn default() -> Self

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

impl<T: Value> Debug for NbitsVec<T>
[src]

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

Formats the value using the given formatter.

impl<T: ValueExt> Hash for NbitsVec<T>
[src]

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

Feeds this value into the state given, updating the hasher as necessary.

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

Feeds a slice of this type into the state provided.

impl<T: ValueExt> PartialEq for NbitsVec<T>
[src]

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

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

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

This method tests for !=.

impl<T: ValueExt> Eq for NbitsVec<T>
[src]

impl<T: ValueExt> Clone for NbitsVec<T>
[src]

fn clone(&self) -> Self

Returns a copy of the value. Read more

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

Performs copy-assignment from source. Read more

impl<T: ValueExt> PartialOrd for NbitsVec<T>
[src]

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more

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

This method tests less than (for self and other) and is used by the < operator. Read more

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

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

This method tests greater than (for self and other) and is used by the > operator. Read more

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

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

impl<T: ValueExt> Ord for NbitsVec<T>
[src]

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other. Read more

impl<T: ValueExt> Send for NbitsVec<T>
[src]

impl<T: ValueExt> Sync for NbitsVec<T>
[src]