Struct nbits_vec::NbitsVec
[−]
[src]
pub struct NbitsVec<N: Unsigned + NonZero, Block: PrimInt = usize> { /* fields omitted */ }
Implement vector contains small N
-bits values using Block
as unit
buffer.
The N
is an typenum which is nonzero and smaller than the size of Block
.
The 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:
- Use exact size
Block
, means to useu8
,u64
, notusize
. - Prefer
u64
in an long vector. - Prefer
u8
in an short vector. - Prefer
u64
/u32
thanu8
if caresinsert
/remove
. - Anytime ignore the
u16
from your choise unless you really want it.
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, N2}; type NVec = NbitsVec<N2, u8>; fn main() { // News. let _: NbitsVec<N2, usize> = NbitsVec::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<N: Unsigned + NonZero, Block: PrimInt> NbitsVec<N, Block>
[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 Block
unit bits is smaller than N
bits.
This should panic in new
, with_capacity
, from_raw_parts
methods.
fn with_capacity(capacity: usize) -> Self
Constructs a new, empty Vec
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 Block,
length: usize,
capacity: usize
) -> Self
ptr: *mut Block,
length: usize,
capacity: usize
) -> Self
Constructs a NbitsVec<N, Block>
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 viaVec<T>/NbitsVec<N, Block>
.length
needs to be the length that less than or equal tocapacity
.capacity
needs to be thecapacity
as aNbitsVec<N, Block>
, 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); assert!(v.capacity() >= 10); assert_eq!(v.capacity(), std::mem::size_of::<usize>() * 8);
fn reserve(&mut self, additional: usize)
Reserves capacity for at least additional more elements to be inserted in the given
NbitsVec
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: 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) -> 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) -> 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: 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<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: 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, u8> = 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: Block)
Fill vector buf as value
from index
with size length
.
Examples
let mut vec: NbitsVec<N2, u8> = 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: 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: Block)
Set length
bits of buf at offset
th 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 index
th unit of offset
bit.
fn get(&self, index: usize) -> 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) -> Block
Get length
bits of buf at offset
th 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 Block
Returns mutable ptr of Block
.
fn raw_ptr(&self) -> *const Block
Returns ptr of Block
.
fn as_raw_slice(&self) -> &[Block]
Return raw slice of Block
.
fn as_mut_raw_slice(&mut self) -> &mut [Block]
Returns mutable raw slice of Block
.
fn into_raw_boxed_slice(self) -> Box<[Block]>
Returns raw boxed slice of Block
.
fn nbits() -> usize
Returns N
in usize.
fn mask() -> Block
Bit mask.
Trait Implementations
impl<N: Unsigned + NonZero, Block: PrimInt> Default for NbitsVec<N, Block>
[src]
impl<N: Unsigned + NonZero, Block: PrimInt + LowerHex> Debug for NbitsVec<N, Block>
[src]
impl<N: Unsigned + NonZero, Block: PrimInt + Hash> Hash for NbitsVec<N, Block>
[src]
fn hash<H: Hasher>(&self, state: &mut H)
Feeds this value into the given [Hasher
]. Read more
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0
H: Hasher,
Feeds a slice of this type into the given [Hasher
]. Read more
impl<N: Unsigned + NonZero, Block: PrimInt> PartialEq for NbitsVec<N, Block>
[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<N: Unsigned + NonZero, Block: PrimInt> Eq for NbitsVec<N, Block>
[src]
impl<N: Unsigned + NonZero, Block: PrimInt> Clone for NbitsVec<N, Block>
[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<N: Unsigned + NonZero, Block: PrimInt> PartialOrd for NbitsVec<N, Block>
[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<N: Unsigned + NonZero, Block: PrimInt> Ord for NbitsVec<N, Block>
[src]
fn cmp(&self, other: &Self) -> Ordering
This method returns an Ordering
between self
and other
. Read more