Struct zerovec::VarZeroVec[][src]

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

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

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);

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());

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");

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");

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);

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();

Obtain an owned Vec<T> out of this

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);

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

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

Deserialize this value from the given Serde deserializer. Read more

Performs the conversion.

The returned type after indexing.

Performs the indexing (container[index]) operation. Read more

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

This method tests for !=.

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

This method tests for !=.

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

Serialize this value into the given Serde serializer. Read more

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

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

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

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

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

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

Clone the cart C into a Yokeable struct, which may retain references into C.

The type received by Self::binary_search()

The type returned by Self::get()

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. Read more

Get element at index

Insert an element at index

Remove the element at index (panicking if nonexistant)

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

Push an element to the end of this vector

The length of this vector

Create a new, empty vector

Create a new, empty vector, with given capacity

Remove all elements from the vector

Reserve space for addl additional elements

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

Check if this vector is empty

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.