Struct ZeroSlice

struct ZeroSlice<T: AsULE>(_)

A zero-copy "slice", i.e. the zero-copy version of [T].

This behaves similarly to [ZeroVec<T>], however [ZeroVec<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>>. See the VarZeroVec docs for an example.

Examples

Const-construct a ZeroSlice of u16:

use zerovec::ule::AsULE;
use zerovec::ZeroSlice;

const DATA: &ZeroSlice<u16> =
    ZeroSlice::<u16>::from_ule_slice(&<u16 as AsULE>::ULE::from_array([
        211, 281, 421, 32973,
    ]));

assert_eq!(DATA.get(1), Some(281));

Implementations

impl ZeroSlice<bool>

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

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

This cannot be generic over T because of current limitations in const, but if this method is needed in a non-const context, check out [ZeroSlice::parse_bytes()] instead.

See [ZeroSlice::cast()] for an example.

impl ZeroSlice<u128>

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

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

This cannot be generic over T because of current limitations in const, but if this method is needed in a non-const context, check out [ZeroSlice::parse_bytes()] instead.

See [ZeroSlice::cast()] for an example.

impl ZeroSlice<u16>

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

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

This cannot be generic over T because of current limitations in const, but if this method is needed in a non-const context, check out [ZeroSlice::parse_bytes()] instead.

See [ZeroSlice::cast()] for an example.

impl ZeroSlice<u32>

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

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

This cannot be generic over T because of current limitations in const, but if this method is needed in a non-const context, check out [ZeroSlice::parse_bytes()] instead.

See [ZeroSlice::cast()] for an example.

impl ZeroSlice<u64>

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

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

This cannot be generic over T because of current limitations in const, but if this method is needed in a non-const context, check out [ZeroSlice::parse_bytes()] instead.

See [ZeroSlice::cast()] for an example.

impl ZeroSlice<u8>

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

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

This cannot be generic over T because of current limitations in const, but if this method is needed in a non-const context, check out [ZeroSlice::parse_bytes()] instead.

See [ZeroSlice::cast()] for an example.

impl<T> ZeroSlice<T>

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

Gets the element at the specified index. Returns None if out of range.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(zerovec.get(2), Some(421));
assert_eq!(zerovec.get(4), None);

fn get_as_array<N: usize>(self: &Self) -> Option<[T; N]>

Gets the entire slice as an array of length N. Returns None if the slice does not have exactly N elements.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");
let array: [u16; 4] =
    zerovec.get_as_array().expect("should be 4 items in array");

assert_eq!(array[2], 421);

fn get_subslice(self: &Self, range: Range<usize>) -> Option<&ZeroSlice<T>>

Gets a subslice of elements within a certain range. Returns None if the range is out of bounds of this ZeroSlice.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(
    zerovec.get_subslice(1..3),
    Some(&*ZeroVec::from_slice_or_alloc(&[0x0119, 0x01A5]))
);
assert_eq!(zerovec.get_subslice(3..5), None);

fn get_ule_ref(self: &Self, index: usize) -> Option<&<T as >::ULE>

Get a borrowed reference to the underlying ULE type at a specified index.

Prefer [Self::get()] over this method where possible since working directly with ULE types is less ergonomic

const fn cast<P>(self: &Self) -> &ZeroSlice<P>
where
    P: AsULE<ULE = <T as >::ULE>

Casts a ZeroSlice<T> to a compatible ZeroSlice<P>.

T and P are compatible if they have the same ULE representation.

If the ULEs of T and P are different, use [Self::try_as_converted()].

Examples

use zerovec::ZeroSlice;

const BYTES: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
const ZS_U16: &ZeroSlice<u16> = {
    match ZeroSlice::<u16>::try_from_bytes(BYTES) {
        Ok(s) => s,
        Err(_) => unreachable!(),
    }
};

let zs_i16: &ZeroSlice<i16> = ZS_U16.cast();

assert_eq!(ZS_U16.get(3), Some(32973));
assert_eq!(zs_i16.get(3), Some(-32563));

fn try_as_converted<P: AsULE>(self: &Self) -> Result<&ZeroSlice<P>, UleError>

Converts a &ZeroSlice<T> into a &ZeroSlice<P>.

The resulting slice will have the same length as the original slice if and only if T::ULE and P::ULE are the same size.

If T and P have the exact same ULE, use [Self::cast()].

Examples

use zerovec::ZeroSlice;

const BYTES: &[u8] = &[0x7F, 0xF3, 0x01, 0x00, 0x49, 0xF6, 0x01, 0x00];
const ZS_U32: &ZeroSlice<u32> = {
    match ZeroSlice::<u32>::try_from_bytes(BYTES) {
        Ok(s) => s,
        Err(_) => unreachable!(),
    }
};

let zs_u8_4: &ZeroSlice<[u8; 4]> =
    ZS_U32.try_as_converted().expect("valid code points");

assert_eq!(ZS_U32.get(0), Some(127871));
assert_eq!(zs_u8_4.get(0), Some([0x7F, 0xF3, 0x01, 0x00]));

fn first(self: &Self) -> Option<T>

Gets the first element. Returns None if empty.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(zerovec.first(), Some(211));

fn last(self: &Self) -> Option<T>

Gets the last element. Returns None if empty.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(zerovec.last(), Some(32973));

fn iter<'a>(self: &'a Self) -> ZeroSliceIter<'a, T>

Gets an iterator over the elements.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");
let mut it = zerovec.iter();

assert_eq!(it.next(), Some(211));
assert_eq!(it.next(), Some(281));
assert_eq!(it.next(), Some(421));
assert_eq!(it.next(), Some(32973));
assert_eq!(it.next(), None);

fn split_first(self: &Self) -> Option<(T, &ZeroSlice<T>)>

Returns a tuple with the first element and a subslice of the remaining elements.

Example

use zerovec::ule::AsULE;
use zerovec::ZeroSlice;

const DATA: &ZeroSlice<u16> =
    ZeroSlice::<u16>::from_ule_slice(&<u16 as AsULE>::ULE::from_array([
        211, 281, 421, 32973,
    ]));
const EXPECTED_VALUE: (u16, &ZeroSlice<u16>) = (
    211,
    ZeroSlice::<u16>::from_ule_slice(&<u16 as AsULE>::ULE::from_array([
        281, 421, 32973,
    ])),
);
assert_eq!(EXPECTED_VALUE, DATA.split_first().unwrap());

impl<T> ZeroSlice<T>

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

Binary searches a sorted ZeroVec<T> based on a given predicate. For more information, see the primitive function binary_search_by.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(zerovec.binary_search_by(|x| x.cmp(&281)), Ok(1));
assert_eq!(zerovec.binary_search_by(|x| x.cmp(&282)), Err(2));

impl<T> ZeroSlice<T>

const fn new_empty() -> &'static Self

Returns an empty slice.

const fn as_zerovec(self: &Self) -> ZeroVec<'_, T>

Get this ZeroSlice as a borrowed ZeroVec

ZeroSlice does not have most of the methods that ZeroVec does, so it is recommended to convert it to a ZeroVec before doing anything.

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

Attempt to construct a &ZeroSlice<T> from a byte slice, returning an error if it's not a valid byte sequence

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

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

Safety

bytes need to be an output from [ZeroSlice::as_bytes()].

const fn from_ule_slice(slice: &[<T as >::ULE]) -> &Self

Construct a &ZeroSlice<T> from a slice of ULEs.

This function can be used for constructing ZeroVecs in a const context, avoiding parsing checks.

See ZeroSlice for an example.

fn from_boxed_slice(slice: Box<[<T as >::ULE]>) -> Box<Self>

Construct a Box<ZeroSlice<T>> from a boxed slice of ULEs

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

Returns this slice as its underlying &[u8] byte buffer representation.

Useful for serialization.

Example

use zerovec::ZeroVec;

// The little-endian bytes correspond to the numbers on the following line.
let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let nums: &[u16] = &[211, 281, 421, 32973];

let zerovec = ZeroVec::alloc_from_slice(nums);

assert_eq!(bytes, zerovec.as_bytes());

const fn as_ule_slice(self: &Self) -> &[<T as >::ULE]

Dereferences this slice as &[T::ULE].

const fn len(self: &Self) -> usize

Returns the number of elements in this slice.

Example

use zerovec::ule::AsULE;
use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(4, zerovec.len());
assert_eq!(
    bytes.len(),
    zerovec.len() * std::mem::size_of::<<u16 as AsULE>::ULE>()
);

const fn is_empty(self: &Self) -> bool

Returns whether this slice is empty.

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");
assert!(!zerovec.is_empty());

let emptyvec: ZeroVec<u16> = ZeroVec::parse_bytes(&[]).expect("infallible");
assert!(emptyvec.is_empty());

impl<T> ZeroSlice<T>

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

Example

use zerovec::ZeroVec;

let bytes: &[u8] = &[0xD3, 0x00, 0x19, 0x01, 0xA5, 0x01, 0xCD, 0x80];
let zerovec: ZeroVec<u16> =
    ZeroVec::parse_bytes(bytes).expect("infallible");

assert_eq!(zerovec.binary_search(&281), Ok(1));
assert_eq!(zerovec.binary_search(&282), Err(2));

impl<'a, T> PartialEq for ZeroSlice<T>

fn eq(self: &Self, other: &ZeroVec<'a, T>) -> bool

impl<'a, T> ZeroMapKV for ZeroSlice<T>

impl<T> Any for ZeroSlice<T>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for ZeroSlice<T>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for ZeroSlice<T>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> Debug for ZeroSlice<T>

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

impl<T> EncodeAsVarULE for ZeroSlice<T>

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

impl<T> Eq for ZeroSlice<T>

impl<T> Freeze for ZeroSlice<T>

impl<T> PartialEq for ZeroSlice<T>

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

impl<T> PartialEq for ZeroSlice<T>

fn eq(self: &Self, other: &ZeroSlice<T>) -> bool

impl<T> RefUnwindSafe for ZeroSlice<T>

impl<T> Send for ZeroSlice<T>

impl<T> Sized for ZeroSlice<T>

impl<T> Sync for ZeroSlice<T>

impl<T> Unpin for ZeroSlice<T>

impl<T> UnsafeUnpin for ZeroSlice<T>

impl<T> UnwindSafe for ZeroSlice<T>

impl<T> ZeroVecLike for ZeroSlice<T>

fn zvl_new_borrowed() -> &'static <Self as >::SliceVariant
fn zvl_binary_search_in_range(self: &Self, k: &T, range: Range<usize>) -> Option<Result<usize, usize>>
where
    T: Ord
fn zvl_binary_search_by<impl FnMut(&T) -> Ordering: FnMut(&T) -> Ordering>(self: &Self, predicate: impl FnMut(&T) -> Ordering) -> Result<usize, usize>
fn zvl_binary_search_in_range_by<impl FnMut(&T) -> Ordering: FnMut(&T) -> Ordering>(self: &Self, predicate: impl FnMut(&T) -> Ordering, range: Range<usize>) -> Option<Result<usize, usize>>
fn zvl_get(self: &Self, index: usize) -> Option<&<T as >::ULE>
fn zvl_len(self: &Self) -> usize
fn zvl_as_borrowed(self: &Self) -> &ZeroSlice<T>
fn zvl_get_as_t<R, impl FnOnce(&T) -> R: FnOnce(&T) -> R>(g: &<Self as >::GetType, f: impl FnOnce(&T) -> R) -> R

impl<T: AsULE + 'static> VarULE for ZeroSlice<T>

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

impl<T: AsULE + Ord> Ord for ZeroSlice<T>

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

impl<T: AsULE + PartialOrd> PartialOrd for ZeroSlice<T>

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