Struct header_vec::HeaderVec

pub struct HeaderVec<H, T> { /* fields omitted */ }

A vector with a header of your choosing, behind a thin pointer

Example

use core::mem::size_of_val;
use header_vec::HeaderVec;

#[derive(Debug)]
struct OurHeaderType {
    a: usize,
}

let h = OurHeaderType{ a: 2 };
let mut hv = HeaderVec::<OurHeaderType, char>::new(h);
hv.push('x');
hv.push('z');

println!("HeaderVec itself consists solely of a pointer, it's only {} bytes big.", size_of_val(&hv));
println!("All of the data, like our header, {:?}, and the length of the vector: {}, resides on the other side of the pointer.", &*hv, hv.len());

HeaderVec itself consists solely of a pointer, it's only 8 bytes big.
All of the data, like our header, OurHeaderType { a: 2 }, and the length of the vector: 2, resides on the other side of the pointer.

Implementations

impl<H, T> HeaderVec<H, T>

pub fn new(head: H) -> Self

pub fn with_capacity(capacity: usize, head: H) -> Self

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn capacity(&self) -> usize

pub fn as_slice(&self) -> &[T]

pub fn as_mut_slice(&mut self) -> &mut [T]

pub fn ptr(&self) -> *const ()

This is useful to check if two nodes are the same. Use it with HeaderVec::is.

pub fn is(&self, ptr: *const ()) -> bool

This is used to check if this is the HeaderVec that corresponds to the given pointer. This is useful for updating weak references after HeaderVec::push returns the pointer.

pub unsafe fn weak(&self) -> HeaderVecWeak<H, T>

Create a (dangerous) weak reference to the HeaderVec. This is useful to be able to create, for instance, graph data structures. Edges can utilize HeaderVecWeak so that they can traverse the graph immutably without needing to go to memory twice to look up first the pointer to the underlying dynamic edge store (like a Vec). The caveat is that the user is responsible for updating all HeaderVecWeak if the HeaderVec needs to reallocate when HeaderVec::push is called. HeaderVec::push returns true when it reallocates, and this indicates that the HeaderVecWeak need to be updated. Therefore, this works best for implemented undirected graphs where it is easy to find neighbor nodes. Directed graphs with an alternative method to traverse directed edges backwards should also work with this technique.

Safety

A HeaderVecWeak can only be used while its corresponding HeaderVec is still alive. HeaderVecWeak also MUST be updated manually by the user when HeaderVec::push returns true, since the pointer has now changed. As there is no reference counting mechanism, or method by which all the weak references could be updated, it is up to the user to do this. That is why this is unsafe. Make sure you update your HeaderVecWeak appropriately.

pub unsafe fn update(&mut self, weak: HeaderVecWeak<H, T>)

If a HeaderVec is updated through a weak reference and reallocates, you must use this method to update the internal pointer to the HeaderVec (along with any other weak references).

Safety

See the safety section in HeaderVec::weak for an explanation of why this is necessary.

pub fn push(&mut self, item: T) -> Option<*const ()>

Adds an item to the end of the list.

Returns true if the memory was moved to a new location. In this case, you are responsible for updating the weak nodes.

pub fn retain(&mut self, f: impl FnMut(&T) -> bool)

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&e) returns false. This method operates in place, visiting each element exactly once in the original order, and preserves the order of the retained elements.

Trait Implementations

impl<H, T> Clone for HeaderVec<H, T> where
    H: Clone,
    T: Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<H, T> Debug for HeaderVec<H, T> where
    H: Debug,
    T: Debug, 

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

Formats the value using the given formatter.

impl<H, T> Deref for HeaderVec<H, T>

type Target = H

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<H, T> DerefMut for HeaderVec<H, T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<H, T> Drop for HeaderVec<H, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<H, T, I> Index<I> for HeaderVec<H, T> where
    I: SliceIndex<[T]>, 

type Output = I::Output

The returned type after indexing.

fn index(&self, index: I) -> &I::Output

Performs the indexing (container[index]) operation.

impl<H, T, I> IndexMut<I> for HeaderVec<H, T> where
    I: SliceIndex<[T]>, 

fn index_mut(&mut self, index: I) -> &mut I::Output

Performs the mutable indexing (container[index]) operation.

impl<H, T> PartialEq<HeaderVec<H, T>> for HeaderVec<H, T> where
    H: PartialEq,
    T: PartialEq, 

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 !=.