Struct zerovec::VarZeroSlice

pub struct VarZeroSlice<T: ?Sized, F = Index16> { /* 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 used inside VarZeroVec<T> and ZeroMap: This essentially allows for the construction of zero-copy types isomorphic to Vec<Vec<T>> by instead using VarZeroVec<ZeroSlice<T>>.

The F type parameter is a VarZeroVecFormat (see its docs for more details), which can be used to select the precise format of the backing buffer with various size and performance tradeoffs. It defaults to Index16.

This type can be nested within itself to allow for multi-level nested Vecs.

Examples

Nested Slices

The following code constructs the conceptual zero-copy equivalent of Vec<Vec<Vec<str>>>

use zerovec::{VarZeroSlice, VarZeroVec};
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, &*strings_2];
let strings_34 = vec![&*strings_3, &*strings_4];
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_bytes(bytes).unwrap();
assert_eq!(vzv_from_bytes, vzv_all);

Iterate over Windows

Although VarZeroSlice does not itself have a .windows iterator like core::slice::Windows, this behavior can be easily modeled using an iterator:

use zerovec::VarZeroVec;

let vzv = VarZeroVec::<str>::from(&["a", "b", "c", "d"]);

let mut it = vzv.iter().peekable();
while let (Some(x), Some(y)) = (it.next(), it.peek()) {
    // Evaluate (x, y) here.
}

Implementations

impl<T: VarULE + ?Sized, F: VarZeroVecFormat> VarZeroSlice<T, F>

pub const fn new_empty() -> &'static Self

Construct a new empty VarZeroSlice

pub const unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self

Uses a &[u8] buffer as a VarZeroSlice<T> without any verification.

Safety

bytes need to be an output from VarZeroSlice::as_bytes().

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 unsafe fn get_unchecked(&self, idx: usize) -> &T

Get one of this slice’s elements

Safety

index must be in range

Example

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

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

pub fn to_vec(&self) -> Vec<Box<T>>

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

pub const 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_bytes().

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_bytes(vzv.as_bytes()).unwrap());

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

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_bytes<'a>(slice: &'a [u8]) -> Result<&'a Self, UleError>

Parse a VarZeroSlice from a slice of the appropriate format

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

impl<T, F> VarZeroSlice<T, F>

where T: VarULE + ?Sized + Ord, F: VarZeroVecFormat,

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

impl<T, F> VarZeroSlice<T, F>

where T: VarULE + ?Sized, F: VarZeroVecFormat,

pub fn binary_search_by( &self, predicate: impl FnMut(&T) -> Ordering, ) -> Result<usize, usize>

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

Example

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

assert_eq!(vec.binary_search_by(|probe| probe.cmp("f")), Ok(2));
assert_eq!(vec.binary_search_by(|probe| probe.cmp("e")), Err(2));

pub fn binary_search_in_range_by( &self, predicate: impl FnMut(&T) -> Ordering, range: Range<usize>, ) -> Option<Result<usize, usize>>

Binary searches a VarZeroVec<T> for the given predicate 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_by(|v| v.cmp("g"), 0..7),
    Some(Ok(3))
);
assert_eq!(
    vec.binary_search_in_range_by(|v| v.cmp("h"), 0..7),
    Some(Err(4))
);

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

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

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

Trait Implementations

impl<T: ?Sized, F: VarZeroVecFormat> AsRef<VarZeroSlice<T, F>> for VarZeroSlice<T, F>

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

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: VarULE + ?Sized> Bake for &VarZeroSlice<T, Index16>

fn bake(&self, env: &CrateEnv) -> TokenStream

Returns a TokenStream that would evaluate to self.

impl<T: VarULE + ?Sized> Bake for &VarZeroSlice<T, Index32>

fn bake(&self, env: &CrateEnv) -> TokenStream

Returns a TokenStream that would evaluate to self.

impl<T: VarULE + ?Sized> BakeSize for &VarZeroSlice<T, Index16>

fn borrows_size(&self) -> usize

Returns the size

impl<T: VarULE + ?Sized> BakeSize for &VarZeroSlice<T, Index32>

fn borrows_size(&self) -> usize

Returns the size

impl<T, F: VarZeroVecFormat> Debug for VarZeroSlice<T, F>

where T: Debug + VarULE + ?Sized,

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

Formats the value using the given formatter.

impl<'de, 'a, T, F> Deserialize<'de> for &'a VarZeroSlice<T, F>

where T: VarULE + ?Sized, F: VarZeroVecFormat, 'de: 'a,

This impl requires enabling the optional serde Cargo 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<'de, T, F> Deserialize<'de> for Box<VarZeroSlice<T, F>>

where T: VarULE + ?Sized, Box<T>: Deserialize<'de>, F: VarZeroVecFormat,

This impl requires enabling the optional serde Cargo 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, F> EncodeAsVarULE<VarZeroSlice<T, F>> for &[E]

where T: VarULE + ?Sized, E: EncodeAsVarULE<T>, F: VarZeroVecFormat,

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, F> EncodeAsVarULE<VarZeroSlice<T, F>> for VarZeroVec<'_, T, F>

where T: VarULE + ?Sized, F: VarZeroVecFormat,

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, F> EncodeAsVarULE<VarZeroSlice<T, F>> for Vec<E>

where T: VarULE + ?Sized, E: EncodeAsVarULE<T>, F: VarZeroVecFormat,

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, F> From<&'a VarZeroSlice<T, F>> for VarZeroVec<'a, T, F>

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T: VarULE + ?Sized + Ord, F: VarZeroVecFormat> Ord for VarZeroSlice<T, F>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

impl<T, F> PartialEq for VarZeroSlice<T, F>

where T: VarULE + ?Sized + PartialEq, F: VarZeroVecFormat,

fn eq(&self, other: &VarZeroSlice<T, F>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: VarULE + ?Sized + PartialOrd, F: VarZeroVecFormat> PartialOrd for VarZeroSlice<T, F>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, F> Serialize for VarZeroSlice<T, F>

where T: Serialize + VarULE + ?Sized, F: VarZeroVecFormat,

This impl requires enabling the optional serde Cargo 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, F: VarZeroVecFormat> VarULE for VarZeroSlice<T, F>

fn validate_bytes(bytes: &[u8]) -> Result<(), UleError>

Validates a byte slice, &[u8].

unsafe fn from_bytes_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_bytes() with success.

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

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

fn parse_bytes(bytes: &[u8]) -> Result<&Self, UleError>

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<'zf, T> ZeroFrom<'zf, VarZeroSlice<T>> for &'zf VarZeroSlice<T>

where T: 'static + VarULE + ?Sized,

fn zero_from(other: &'zf VarZeroSlice<T>) -> Self

Clone the other C into a struct that may retain references into C.

impl<'zf, T, F: VarZeroVecFormat> ZeroFrom<'zf, VarZeroSlice<T, F>> for VarZeroVec<'zf, T, F>

where T: 'static + VarULE + ?Sized,

fn zero_from(other: &'zf VarZeroSlice<T, F>) -> Self

Clone the other C into a struct that may retain references into C.

impl<T, F> ZeroVecLike<T> for VarZeroSlice<T, F>

where T: VarULE + ?Sized, F: VarZeroVecFormat,

type GetType = T

The type returned by Self::get()

type SliceVariant = VarZeroSlice<T, F>

A fully borrowed version of this

fn zvl_new_borrowed() -> &'static Self::SliceVariant

Create a new, empty borrowed variant

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

where T: Ord,

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

where T: Ord,

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_binary_search_by( &self, predicate: impl FnMut(&T) -> Ordering, ) -> Result<usize, usize>

Search for a key in a sorted vector by a predicate, 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_by( &self, predicate: impl FnMut(&T) -> Ordering, range: Range<usize>, ) -> Option<Result<usize, usize>>

Search for a key within a certain range in a sorted vector by a predicate. 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_as_borrowed(&self) -> &VarZeroSlice<T, F>

Construct a borrowed variant by borrowing from &self.

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

Obtain a reference to T, passed to a closure

fn zvl_is_empty(&self) -> bool

Check if this vector is empty

impl<T, F> Eq for VarZeroSlice<T, F>

where T: VarULE + ?Sized + Eq, F: VarZeroVecFormat,