Struct fixed_slice_vec::vec::FixedSliceVec

pub struct FixedSliceVec<'a, T: Sized> { /* fields omitted */ }

Vec-like structure backed by a storage slice of possibly uninitialized data.

The maximum length (the capacity) is fixed at runtime to the length of the provided storage slice.

Implementations

impl<'a, T: Sized> FixedSliceVec<'a, T>

pub fn new(storage: &'a mut [MaybeUninit<T>]) -> Self

Create a FixedSliceVec backed by a slice of possibly-uninitialized data. The backing storage slice is used as capacity for Vec-like operations,

The initial length of the FixedSliceVec is 0.

pub unsafe fn from_bytes(bytes: &'a mut [u8]) -> FixedSliceVec<'a, T>

Create a well-aligned FixedSliceVec backed by a slice of the provided bytes. The slice is as large as possible given the item type and alignment of the provided bytes.

If you are interested in recapturing the prefix and suffix bytes on either side of the carved-out FixedSliceVec buffer, consider using align_from_bytes instead:

let vec = unsafe { fixed_slice_vec::FixedSliceVec::from_bytes(&mut bytes[..]) };

The bytes are treated as if they might be uninitialized, so even if T is u8, the length of the returned FixedSliceVec will be zero.

Safety

If the item type T of the FixedSliceVec contains any padding bytes then those padding bytes may be observable in the provided slice after the FixedSliceVec is dropped. Observing padding bytes is undefined behavior.

pub fn from_uninit_bytes(
    bytes: &'a mut [MaybeUninit<u8>]
) -> FixedSliceVec<'a, T>

Create a well-aligned FixedSliceVec backed by a slice of the provided uninitialized bytes. The typed slice is as large as possible given its item type and the alignment of the provided bytes.

If you are interested in recapturing the prefix and suffix bytes on either side of the carved-out FixedSliceVec buffer, consider using align_from_uninit_bytes:

pub unsafe fn align_from_bytes(
    bytes: &'a mut [u8]
) -> (&'a mut [u8], FixedSliceVec<'a, T>, &'a mut [u8])

Create a well-aligned FixedSliceVec backed by a slice of the provided bytes. The slice is as large as possible given the item type and alignment of the provided bytes. Returns the unused prefix and suffix bytes on either side of the carved-out FixedSliceVec.

let mut bytes = [3u8, 1, 4, 1, 5, 9];
let (prefix, vec, suffix) = unsafe { fixed_slice_vec::FixedSliceVec::align_from_bytes(&mut bytes[..]) };
let vec: fixed_slice_vec::FixedSliceVec<u16> = vec;

The bytes are treated as if they might be uninitialized, so even if T is u8, the length of the returned FixedSliceVec will be zero.

Safety

If the item type T of the FixedSliceVec contains any padding bytes then those padding bytes may be observable in the provided slice after the FixedSliceVec is dropped. Observing padding bytes is undefined behavior.

pub fn align_from_uninit_bytes(
    bytes: &'a mut [MaybeUninit<u8>]
) -> (&'a mut [MaybeUninit<u8>], FixedSliceVec<'a, T>, &'a mut [MaybeUninit<u8>])

Create a well-aligned FixedSliceVec backed by a slice of the provided bytes. The slice is as large as possible given the item type and alignment of the provided bytes. Returns the unused prefix and suffix bytes on either side of the carved-out FixedSliceVec.

let mut bytes: [MaybeUninit<u8>; 15] = unsafe { MaybeUninit::uninit().assume_init() };
let (prefix, vec, suffix) = fixed_slice_vec::FixedSliceVec::align_from_uninit_bytes(&mut
bytes[..]);
let vec: fixed_slice_vec::FixedSliceVec<u16> = vec;

The length of the returned FixedSliceVec will be zero.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns an unsafe mutable pointer to the FixedSliceVec's buffer.

The caller must ensure that the FixedSliceVec and the backing storage data for the FixedSliceVec (provided at construction) outlives the pointer this function returns.

Furthermore, the contents of the buffer are not guaranteed to have been initialized at indices < len.

Examples

use core::mem::MaybeUninit;
let mut storage: [MaybeUninit<u8>; 16] = unsafe { MaybeUninit::uninit().assume_init() };
let mut x: fixed_slice_vec::FixedSliceVec<u16> = fixed_slice_vec::FixedSliceVec::from_uninit_bytes(&mut storage[..]);
assert!(x.try_extend([1u16, 2, 4, 8].iter().copied()).is_ok());
let size = x.len();
let x_ptr = x.as_mut_ptr();

// Set elements via raw pointer writes.
unsafe {
    for i in 0..size {
        *x_ptr.add(i) = i as u16;
    }
}
assert_eq!(&*x, &[0,1,2,3]);

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to the FixedSliceVec's buffer.

The caller must ensure that the FixedSliceVec and the backing storage data for the FixedSliceVec (provided at construction) outlives the pointer this function returns.

Furthermore, the contents of the buffer are not guaranteed to have been initialized at indices < len.

The caller must also ensure that the memory the pointer (non-transitively) points to is never written to using this pointer or any pointer derived from it.

If you need to mutate the contents of the slice with pointers, use as_mut_ptr.

Examples

use core::mem::MaybeUninit;
let mut storage: [MaybeUninit<u8>; 16] = unsafe { MaybeUninit::uninit().assume_init() };
let mut x: fixed_slice_vec::FixedSliceVec<u16> = fixed_slice_vec::FixedSliceVec::from_uninit_bytes(&mut storage[..]);
x.extend([1u16, 2, 4].iter().copied());
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(*x_ptr.add(i), 1 << i);
    }
}

pub fn len(&self) -> usize

The length of the FixedSliceVec. The number of initialized values that have been added to it.

pub fn capacity(&self) -> usize

The maximum amount of items that can live in this FixedSliceVec

pub fn is_empty(&self) -> bool

Returns true if there are no items present.

pub fn is_full(&self) -> bool

Returns true if the FixedSliceVec is full to capacity.

pub fn try_push(&mut self, value: T) -> Result<(), StorageError<T>>

Attempt to add a value to the FixedSliceVec.

Returns an error if there is not enough capacity to hold another item.

pub fn push(&mut self, value: T)

Attempt to add a value to the FixedSliceVec.

Panics

Panics if there is not sufficient capacity to hold another item.

pub fn try_extend(
    &mut self,
    iterable: impl IntoIterator<Item = T>
) -> Result<(), impl Iterator<Item = T>>

Attempt to add as many values as will fit from an iterable.

Returns Ok(()) if all of the items in the iterator can fit into self. Returns an Err containing the iterator if self fills up and there are items remaining in the iterator.

pub fn pop(&mut self) -> Option<T>

Remove the last item from the FixedSliceVec.

pub fn clear(&mut self)

Removes the FixedSliceVec's tracking of all items in it while retaining the same capacity.

pub fn truncate(&mut self, len: usize)

Shortens the FixedSliceVec, keeping the first len elements and dropping the rest.

If len is greater than the current length, this has no effect. Note that this method has no effect on the capacity of the FixedSliceVec.

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

Removes and returns the element at position index within the FixedSliceVec, shifting all elements after it to the left.

Panics

Panics if index is out of bounds.

pub fn try_remove(&mut self, index: usize) -> Result<T, IndexError>

Removes and returns the element at position index within the FixedSliceVec, shifting all elements after it to the left.

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

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Panics

Panics if index is out of bounds.

pub fn try_swap_remove(&mut self, index: usize) -> Result<T, IndexError>

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

pub fn as_slice(&self) -> &[T]

Obtain an immutable slice view on the initialized portion of the FixedSliceVec.

pub fn as_mut_slice(&mut self) -> &mut [T]

Obtain a mutable slice view on the initialized portion of the FixedSliceVec.

Trait Implementations

impl<'a, T: Sized> AsMut<[T]> for FixedSliceVec<'a, T>

fn as_mut(&mut self) -> &mut [T]

Performs the conversion.

impl<'a, T: Sized> AsRef<[T]> for FixedSliceVec<'a, T>

fn as_ref(&self) -> &[T]

Performs the conversion.

impl<'a, T: Sized> Borrow<[T]> for FixedSliceVec<'a, T>

fn borrow(&self) -> &[T]

Immutably borrows from an owned value.

impl<'a, T: Sized> BorrowMut<[T]> for FixedSliceVec<'a, T>

fn borrow_mut(&mut self) -> &mut [T]

Mutably borrows from an owned value.

impl<'a, T: Sized> Debug for FixedSliceVec<'a, T> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<'a, T: Sized> Deref for FixedSliceVec<'a, T>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a, T: Sized> DerefMut for FixedSliceVec<'a, T>

fn deref_mut(&mut self) -> &mut [T]

Mutably dereferences the value.

impl<'a, T: Sized> Drop for FixedSliceVec<'a, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T: Sized> Eq for FixedSliceVec<'a, T> where
    T: Eq, 

impl<'a, T: Sized> Extend<T> for FixedSliceVec<'a, T>

Adds as many items from the provided iterable as can fit.

Gives no indication of how many were extracted or if some could not fit.

Use FixedSliceVec::try_extend if you require more fine- grained signal about the outcome of attempted extension.

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<'a, T: Sized> From<&'a mut [MaybeUninit<T>]> for FixedSliceVec<'a, T>

fn from(v: &'a mut [MaybeUninit<T>]) -> Self

Performs the conversion.

impl<'a, T: Sized> Hash for FixedSliceVec<'a, T> where
    T: Hash, 

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'a, T: Sized> PartialEq<[T]> for FixedSliceVec<'a, T> where
    T: 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, T: Sized> PartialEq<FixedSliceVec<'a, T>> for FixedSliceVec<'a, T> where
    T: PartialEq, 

fn eq(&self, other: &Self) -> 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, T: Sized> PartialOrd<FixedSliceVec<'a, T>> for FixedSliceVec<'a, T> where
    T: PartialOrd, 

fn partial_cmp(&self, other: &FixedSliceVec<'a, T>) -> Option<Ordering>

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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