Struct zerovec::VarZeroSlice

#[repr(transparent)]
pub struct VarZeroSlice<T: ?Sized> { /* private fields */ }

A zero-copy “slice”, that works for unsized types, i.e. the zero-copy version of [T] where T is not Sized.

This behaves similarly to VarZeroVec<T>, however VarZeroVec<T> is allowed to contain owned data and as such is ideal for deserialization since most human readable serialization formats cannot unconditionally deserialize zero-copy.

This type can be nested within VarZeroVec<T> to allow for multi-level nested Vecs, for example the following code constructs the conceptual zero-copy equivalent of Vec<Vec<Vec<str>>>

use zerovec::VarZeroVec;
use zerovec::ZeroVec;
use zerovec::varzerovec::VarZeroSlice;
use zerovec::ule::*;
let strings_1: Vec<&str> = vec!["foo", "bar", "baz"];
let strings_2: Vec<&str> = vec!["twelve", "seventeen", "forty two"];
let strings_3: Vec<&str> = vec!["我", "喜歡", "烏龍茶"];
let strings_4: Vec<&str> = vec!["w", "ω", "文", "𑄃"];
let strings_12 = vec![strings_1.clone(), strings_2.clone()];
let strings_34 = vec![strings_3.clone(), strings_4.clone()];
let all_strings = vec![strings_12, strings_34];

let vzv_1: VarZeroVec<str> = VarZeroVec::from(&strings_1);
let vzv_2: VarZeroVec<str> = VarZeroVec::from(&strings_2);
let vzv_3: VarZeroVec<str> = VarZeroVec::from(&strings_3);
let vzv_4: VarZeroVec<str> = VarZeroVec::from(&strings_4);
let vzv_12 = VarZeroVec::from(&[vzv_1.as_slice(), vzv_2.as_slice()]);
let vzv_34 = VarZeroVec::from(&[vzv_3.as_slice(), vzv_4.as_slice()]);
let vzv_all = VarZeroVec::from(&[vzv_12.as_slice(), vzv_34.as_slice()]);

let reconstructed: Vec<Vec<Vec<String>>> = vzv_all.iter()
       .map(|v: &VarZeroSlice<VarZeroSlice<str>>| {
            v.iter().map(|x: &VarZeroSlice<_>| x.as_varzerovec().iter().map(|s| s.to_owned()).collect::<Vec<String>>())
             .collect::<Vec<_>>()
        }).collect::<Vec<_>>();
assert_eq!(reconstructed, all_strings);

let bytes = vzv_all.as_bytes();
let vzv_from_bytes: VarZeroVec<VarZeroSlice<VarZeroSlice<str>>> = VarZeroVec::parse_byte_slice(bytes).unwrap();
assert_eq!(vzv_from_bytes, vzv_all);

Implementations

impl<T: VarULE + ?Sized> VarZeroSlice<T>

pub fn new_empty() -> &'static Self

Construct a new empty VarZeroSlice

pub fn len(&self) -> usize

Get the number of elements in this slice

Example

let strings = vec!["foo", "bar", "baz", "quux"];
let vec = VarZeroVec::<str>::from(&strings);

assert_eq!(vec.len(), 4);

pub fn is_empty(&self) -> bool

Returns true if the slice contains no elements.

Examples

let strings: Vec<String> = vec![];
let vec = VarZeroVec::<str>::from(&strings);

assert!(vec.is_empty());

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

Obtain an iterator over this slice’s elements

Example

let strings = vec!["foo", "bar", "baz", "quux"];
let vec = VarZeroVec::<str>::from(&strings);

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>

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

Example

let strings = vec!["foo", "bar", "baz", "quux"];
let vec = VarZeroVec::<str>::from(&strings);

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 to_vec(&self) -> Vec<Box<T>>

Obtain an owned Vec<Box<T>> out of this

pub fn as_bytes(&self) -> &[u8]

Get a reference to the entire encoded backing buffer of this slice

The bytes can be passed back to Self::parse_byte_slice().

To take the bytes as a vector, see VarZeroVec::into_bytes().

Example

let strings = vec!["foo", "bar", "baz"];
let vzv = VarZeroVec::<str>::from(&strings);

assert_eq!(vzv, VarZeroVec::parse_byte_slice(vzv.as_bytes()).unwrap());

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

Get this VarZeroSlice as a borrowed VarZeroVec

If you wish to repeatedly call methods on this VarZeroSlice, it is more efficient to perform this conversion first

pub fn parse_byte_slice<'a>(slice: &'a [u8]) -> Result<&'a Self, ZeroVecError>

Parse a VarZeroSlice from a slice of the appropriate format

Slices of the right format can be obtained via VarZeroSlice::as_bytes()

impl<T> VarZeroSlice<T> where
    T: VarULE,
    T: ?Sized,
    T: Ord, 

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

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

Example

let strings = vec!["a", "b", "f", "g"];
let vec = VarZeroVec::<str>::from(&strings);

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

pub fn binary_search_in_range(
    &self,
    x: &T,
    range: Range<usize>
) -> Option<Result<usize, usize>>

Binary searches a VarZeroVec<T> for the given element within a certain sorted range.

If the range is out of bounds, returns None. Otherwise, returns a Result according to the behavior of the standard library function binary_search.

The index is returned relative to the start of the range.

Example

let strings = vec!["a", "b", "f", "g", "m", "n", "q"];
let vec = VarZeroVec::<str>::from(&strings);

// Same behavior as binary_search when the range covers the whole slice:
assert_eq!(vec.binary_search_in_range("g", 0..7), Some(Ok(3)));
assert_eq!(vec.binary_search_in_range("h", 0..7), Some(Err(4)));

// Will not look outside of the range:
assert_eq!(vec.binary_search_in_range("g", 0..1), Some(Err(1)));
assert_eq!(vec.binary_search_in_range("g", 6..7), Some(Err(0)));

// Will return indices relative to the start of the range:
assert_eq!(vec.binary_search_in_range("g", 1..6), Some(Ok(2)));
assert_eq!(vec.binary_search_in_range("h", 1..6), Some(Err(3)));

// Will return None if the range is out of bounds:
assert_eq!(vec.binary_search_in_range("x", 100..200), None);
assert_eq!(vec.binary_search_in_range("x", 0..200), None);

Trait Implementations

impl<T: ?Sized> AsRef<VarZeroSlice<T>> for VarZeroSlice<T>

fn as_ref(&self) -> &VarZeroSlice<T>

Performs the conversion.

impl<'a, T> BorrowedZeroVecLike<'a, T> for &'a VarZeroSlice<T> where
    T: VarULE,
    T: Ord,
    T: ?Sized, 

fn zvl_get_borrowed(&self, index: usize) -> Option<&'a T>

Get element at index, with a longer lifetime

impl<T: VarULE + ?Sized> Debug for VarZeroSlice<T> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<'de, 'a, T> Deserialize<'de> for &'a VarZeroSlice<T> where
    T: VarULE + ?Sized,
    Box<T>: Deserialize<'de>,
    '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<T, E> EncodeAsVarULE<VarZeroSlice<T>> for &[E] where
    T: VarULE + ?Sized,
    E: EncodeAsVarULE<T>, 

fn encode_var_ule_as_slices<R>(&self, _: impl FnOnce(&[&[u8]]) -> R) -> R

Calls cb with a piecewise list of byte slices that when concatenated produce the memory pattern of the corresponding instance of T.

fn encode_var_ule_len(&self) -> usize

Return the length, in bytes, of the corresponding VarULE type

fn encode_var_ule_write(&self, dst: &mut [u8])

Write the corresponding VarULE type to the dst buffer. dst should be the size of Self::encode_var_ule_len()

impl<T, E> EncodeAsVarULE<VarZeroSlice<T>> for Vec<E> where
    T: VarULE + ?Sized,
    E: EncodeAsVarULE<T>, 

fn encode_var_ule_as_slices<R>(&self, _: impl FnOnce(&[&[u8]]) -> R) -> R

Calls cb with a piecewise list of byte slices that when concatenated produce the memory pattern of the corresponding instance of T.

fn encode_var_ule_len(&self) -> usize

Return the length, in bytes, of the corresponding VarULE type

fn encode_var_ule_write(&self, dst: &mut [u8])

Write the corresponding VarULE type to the dst buffer. dst should be the size of Self::encode_var_ule_len()

impl<T> EncodeAsVarULE<VarZeroSlice<T>> for VarZeroVec<'_, T> where
    T: VarULE + ?Sized, 

fn encode_var_ule_as_slices<R>(&self, _: impl FnOnce(&[&[u8]]) -> R) -> R

Calls cb with a piecewise list of byte slices that when concatenated produce the memory pattern of the corresponding instance of T.

fn encode_var_ule_len(&self) -> usize

Return the length, in bytes, of the corresponding VarULE type

fn encode_var_ule_write(&self, dst: &mut [u8])

Write the corresponding VarULE type to the dst buffer. dst should be the size of Self::encode_var_ule_len()

impl<'a, T: ?Sized + VarULE> From<&'a VarZeroSlice<T>> for VarZeroVecOwned<T>

fn from(other: &'a VarZeroSlice<T>) -> Self

Performs the conversion.

impl<'a, T: ?Sized> From<&'a VarZeroSlice<T>> for VarZeroVec<'a, T>

fn from(other: &'a VarZeroSlice<T>) -> Self

Performs the conversion.

impl<T: VarULE + ?Sized> Index<usize> for VarZeroSlice<T>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T> PartialEq<VarZeroSlice<T>> for VarZeroSlice<T> where
    T: VarULE,
    T: ?Sized,
    T: PartialEq, 

fn eq(&self, other: &VarZeroSlice<T>) -> 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 !=.

impl<T> Serialize for VarZeroSlice<T> where
    T: Serialize + VarULE + ?Sized, 

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<T: VarULE + ?Sized + 'static> VarULE for VarZeroSlice<T>

fn validate_byte_slice(bytes: &[u8]) -> Result<(), ZeroVecError>

Validates a byte slice, &[u8].

unsafe fn from_byte_slice_unchecked(bytes: &[u8]) -> &Self

Takes a byte slice, &[u8], and return it as &Self with the same lifetime, assuming that this byte slice has previously been run through Self::parse_byte_slice() with success.

fn as_byte_slice(&self) -> &[u8]

Given &Self, returns a &[u8] with the same lifetime.

fn parse_byte_slice(bytes: &[u8]) -> Result<&Self, ZeroVecError>

Parses a byte slice, &[u8], and return it as &Self with the same lifetime.

fn to_boxed(&self) -> Box<Self>

Allocate on the heap as a Box<T>

impl<'a, T> ZeroVecLike<'a, T> for &'a VarZeroSlice<T> where
    T: VarULE,
    T: Ord,
    T: ?Sized, 

type GetType = T

The type returned by Self::get()

type BorrowedVariant = &'a VarZeroSlice<T>

A fully borrowed version of this

fn zvl_new() -> Self

Create a new, empty vector

fn zvl_binary_search(&self, k: &T) -> 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 zvl_binary_search_in_range(
    &self,
    k: &T,
    range: Range<usize>
) -> Option<Result<usize, usize>>

Search for a key within a certain range in a sorted vector. Returns None if the range is out of bounds, and Ok or Err in the same way as zvl_binary_search. Indices are returned relative to the start of the range.

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

Get element at index

fn zvl_len(&self) -> usize

The length of this vector

fn zvl_is_ascending(&self) -> bool

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

fn zvl_as_borrowed(&'a self) -> &'a VarZeroSlice<T>

Construct a borrowed variant by borrowing from &self.

fn zvl_as_borrowed_inner(&self) -> Option<&'a VarZeroSlice<T>>

Extract the inner borrowed variant if possible. Returns None if the data is owned.

fn zvl_from_borrowed(b: &'a VarZeroSlice<T>) -> Self

Construct from the borrowed version of the type

fn t_cmp_get(t: &T, g: &Self::GetType) -> Ordering

Compare this type with a Self::GetType. This must produce the same result as if g were converted to Self

fn get_cmp_get(a: &Self::GetType, b: &Self::GetType) -> Ordering

Compare two values of Self::GetType. This must produce the same result as if both a and b were converted to Self

fn t_with_ser<R>(g: &Self::GetType, f: impl FnOnce(&T) -> R) -> R

Obtain a version of T suitable for serialization

fn zvl_is_empty(&self) -> bool

Check if this vector is empty