Struct zerovec::VarZeroVec

pub struct VarZeroVec<'a, T>(_);

A zero-copy vector for variable-width types.

VarZeroVec<T> is designed as a drop-in replacement for Vec<T> in situations where it is desirable to borrow data from an unaligned byte slice, such as zero-copy deserialization, and where T’s data is variable-length (e.g. String)

T must implement AsVarULE, which is already implemented for String. References are obtained as its AsVarULE::VarULE type, which in the case of String is str.

VarZeroVec<T> behaves much like std::borrow::Cow, where it can be constructed from owned data but can also borrow from some buffer.

How it Works

VarZeroVec<T>, when used with non-human-readable serializers (like bincode), will serialize to a specially formatted list of bytes. The format is:

• 4 bytes for length (interpreted as a little-endian u32)
• 4 * length bytes of indices (interpreted as little-endian u32)
• Remaining bytes for actual data

Each element in the indices array points to the starting index of its corresponding data part in the data list. The ending index can be calculated from the starting index of the next element (or the length of the slice if dealing with the last element).

Safety

VarZeroVec<T> is implemented with a fair amount of unsafe code, but is externally safe to use.

Example

use zerovec::VarZeroVec;

// The little-endian bytes correspond to the list of strings.
let strings = vec!["w".to_owned(), "ω".to_owned(), "文".to_owned(), "𑄃".to_owned()];
let bytes = &[
    4, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0,  3, 0, 0, 0,
    6, 0, 0, 0, 119, 207, 137, 230, 150, 135, 240, 145, 132, 131,
];

let zerovec: VarZeroVec<String> = VarZeroVec::try_from_bytes(bytes)?;

assert_eq!(zerovec.get(2), Some("文"));
assert_eq!(zerovec, &*strings);

Implementations

impl<'a, T: AsVarULE> VarZeroVec<'a, T>

pub fn len(&self) -> usize

Get the number of elements in this vector

Example

let strings = vec!["foo".to_owned(), "bar".to_owned(),
                   "baz".to_owned(), "quux".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();

let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;
assert_eq!(vec.len(), 4);

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

Examples

let strings: Vec<String> = vec![];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();

let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;
assert!(vec.is_empty());

pub fn try_from_bytes(
    slice: &'a [u8]
) -> Result<Self, VarZeroVecError<<<T as AsVarULE>::VarULE as VarULE>::Error>>

Parse a VarZeroVec from a slice of the appropriate format

Slices of the right format can be obtained via VarZeroVec::get_serializable_bytes()

Example

let strings = vec!["foo".to_owned(), "bar".to_owned(),
                   "baz".to_owned(), "quux".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();

let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;
assert_eq!(&vec[0], "foo");
assert_eq!(&vec[1], "bar");
assert_eq!(&vec[2], "baz");
assert_eq!(&vec[3], "quux");

pub fn iter<'b: 'a>(&'b self) -> impl Iterator<Item = &'b T::VarULE>

Obtain an iterator over VarZeroVec’s elements

Example

let strings = vec!["foo".to_owned(), "bar".to_owned(),
                   "baz".to_owned(), "quux".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();
let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;

let mut iter_results: Vec<&str> = vec.iter().collect();
assert_eq!(iter_results[0], "foo");
assert_eq!(iter_results[1], "bar");
assert_eq!(iter_results[2], "baz");
assert_eq!(iter_results[3], "quux");

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

Get one of VarZeroVec’s elements, returning None if the index is out of bounds

Example

let strings = vec!["foo".to_owned(), "bar".to_owned(),
                   "baz".to_owned(), "quux".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();
let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;

let mut iter_results: Vec<&str> = vec.iter().collect();
assert_eq!(vec.get(0), Some("foo"));
assert_eq!(vec.get(1), Some("bar"));
assert_eq!(vec.get(2), Some("baz"));
assert_eq!(vec.get(3), Some("quux"));
assert_eq!(vec.get(4), None);

pub fn into_owned(self) -> VarZeroVec<'static, T> where
    T: Clone, 

Converts a borrowed ZeroVec to an owned ZeroVec. No-op if already owned.

Example

let strings = vec!["foo".to_owned(), "bar".to_owned(),
                   "baz".to_owned(), "quux".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();
let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;

assert_eq!(vec.len(), 4);
// has 'static lifetime
let owned = vec.into_owned();

pub fn to_vec(&self) -> Vec<T> where
    T: Clone, 

Obtain an owned Vec<T> out of this

pub fn get_serializable_bytes(elements: &[T]) -> Option<Vec<u8>>

For a slice of T, get a list of bytes that can be passed to try_from_bytes to recoup the same data.

Returns None if the slice is too large to be represented in a list of bytes whose length fits in a u32.

Example

let strings = vec!["foo".to_owned(), "bar".to_owned(), "baz".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();

let mut borrowed: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;
assert_eq!(borrowed, &*strings);

impl<'a, T> VarZeroVec<'a, T> where
    T: AsVarULE,
    T::VarULE: Ord, 

pub fn binary_search(&self, x: &T::VarULE) -> Result<usize, usize>

Binary searches a sorted VarZeroVec<T> for the given element. For more information, see the primitive function binary_search.

Example

let strings = vec!["a".to_owned(), "b".to_owned(),
                   "f".to_owned(), "g".to_owned()];
let bytes = VarZeroVec::get_serializable_bytes(&strings).unwrap();
let mut vec: VarZeroVec<String> = VarZeroVec::try_from_bytes(&bytes)?;

assert_eq!(vec.binary_search("f"), Ok(2));
assert_eq!(vec.binary_search("e"), Err(2));

Trait Implementations

impl<'a, T: Clone> Clone for VarZeroVec<'a, T>

fn clone(&self) -> VarZeroVec<'a, T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: AsVarULE> Debug for VarZeroVec<'_, T> where
    T::VarULE: Debug, 

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

Formats the value using the given formatter.

impl<'de, 'a, T> Deserialize<'de> for VarZeroVec<'a, T> where
    T: 'de + Deserialize<'de> + AsVarULE,
    <<T as AsVarULE>::VarULE as VarULE>::Error: Display,
    'de: 'a, 

This impl can be made available by enabling the optional serde feature of the zerovec crate

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<'a, T> From<Vec<T, Global>> for VarZeroVec<'a, T>

fn from(other: Vec<T>) -> Self

Performs the conversion.

impl<'a, T: AsVarULE> Index<usize> for VarZeroVec<'a, T>

type Output = T::VarULE

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> PartialEq<&'_ [T]> for VarZeroVec<'_, T> where
    T: AsVarULE,
    T::VarULE: PartialEq, 

fn eq(&self, other: &&[T]) -> bool

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

#[must_use]

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

This method tests for !=.

impl<'a, 'b, T> PartialEq<VarZeroVec<'b, T>> for VarZeroVec<'a, T> where
    T: AsVarULE,
    T::VarULE: PartialEq, 

fn eq(&self, other: &VarZeroVec<'b, T>) -> bool

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

#[must_use]

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

This method tests for !=.

impl<T> Serialize for VarZeroVec<'_, T> where
    T: Serialize + AsVarULE + Clone, 

This impl can be made available by enabling the optional serde feature of the zerovec crate

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'a, T: 'static + AsVarULE> Yokeable<'a> for VarZeroVec<'static, T>

This impl can be made available by enabling the optional yoke feature of the zerovec crate

type Output = VarZeroVec<'a, T>

This type MUST be Self with the 'static replaced with 'a, i.e. Self<'a>

fn transform(&'a self) -> &'a VarZeroVec<'a, T>

This method must cast self between &'a Self<'static> and &'a Self<'a>.

unsafe fn make(from: VarZeroVec<'a, T>) -> Self

This method can be used to cast away Self<'a>’s lifetime.

fn with_mut<F>(&'a mut self, f: F) where
    F: 'static + for<'b> FnOnce(&'b mut Self::Output), 

This method must cast self between &'a mut Self<'static> and &'a mut Self<'a>, and pass it to f.

impl<'a, T> ZeroVecLike<'a, T> for VarZeroVec<'a, T> where
    T: AsVarULE + Clone,
    T::VarULE: Ord, 

type NeedleType = T::VarULE

The type received by Self::binary_search()

type GetType = T::VarULE

The type returned by Self::get()

fn binary_search(&self, k: &T::VarULE) -> Result<usize, usize>

Search for a key in a sorted vector, returns Ok(index) if found, returns Err(insert_index) if not found, where insert_index is the index where it should be inserted to maintain sort order.

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

Get element at index

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

Insert an element at index

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

Remove the element at index (panicking if nonexistant)

fn replace(&mut self, index: usize, value: T) -> T

Replace the element at index with another one, returning the old element

fn push(&mut self, value: T)

Push an element to the end of this vector

fn len(&self) -> usize

The length of this vector

fn new() -> Self

Create a new, empty vector

fn with_capacity(cap: usize) -> Self

Create a new, empty vector, with given capacity

fn clear(&mut self)

Remove all elements from the vector

fn reserve(&mut self, addl: usize)

Reserve space for addl additional elements

fn is_ascending(&self) -> bool

Check if this vector is in ascending order according to Ts Ord impl