Struct possibly_uninit::slice::OutSlice

pub struct OutSlice<T>(_);

A slice of T that may be uninitialized, but might also be borrowed from &mut [T].

One would normally expect this to be &mut [MaybeUninit<T>], however, that wouldn’t be sound. Consider this code:

use core::mem::MaybeUninit;
 
fn cast_mut<T>(val: &mut [T]) -> &mut [MaybeUninit<T>] {
    unsafe {
        core::slice::from_raw_parts_mut(val.as_mut_ptr() as *mut MaybeUninit<T>, val.len())
    }
}
 
// No unsafe code here
fn main() {
    let mut message = ["Hello world!".to_string()];
    core::mem::replace(&mut cast_mut(&mut message)[0], MaybeUninit::uninit());
    println!("This is now garbage: {}", message[0]);
}

The code above triggers UB. Thus the users of the slice must be prevented from writing invalid values into the slice. That’s only possible by creating a newtype like this one.

While the newtype itself doesn’t track initializedness, so its use may be limited in safe code, it’s a base building block allowing sound implementations of wrappers tracking initializedness. See Cursor type in this crate.

Implementations

impl<T> OutSlice<T>

pub fn at<I: SliceIndex<[MaybeUninit<T>], Output = MaybeUninit<T>>>(
    &self,
    index: I
) -> &MaybeUninit<T>

Accesses the value at given index.

Note that this is useless unless you know that the value is initialized. Declare so by unsafely calling assume_init_ref.

pub fn at_mut<I: SliceIndex<[MaybeUninit<T>], Output = MaybeUninit<T>>>(
    &mut self,
    index: I
) -> Out<'_, T>

Accesses value at given index.

A special reference wrapper is returned that allows you to only write valid values.

pub fn len(&self) -> usize

Returns the length of the slice.

pub fn is_empty(&self) -> bool

Returns true if the slice is empty.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns an iterator that allows initializing the slice

pub fn split_at_mut(
    &mut self,
    mid: usize
) -> (&mut OutSlice<T>, &mut OutSlice<T>)

Splits the slice at given index into two parts.

Panics

Panics if mid is out of bounds.

pub unsafe fn assume_init(&self) -> &[T]

Transforms the slice into initialized version.

Safety

This method is unsafe because it may only be called when the whole slice was initialized. Use indexing operator to get a subslice if only a part of the slice was initialized.

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

Transforms the slice into initialized mutable version.

Safety

This method is unsafe because it may only be called when the whole slice was initialized. Use indexing operator to get a subslice if only a part of the slice was initialized.

pub fn as_non_null(&mut self) -> NonNull<T>

Returns non-null pointer to the first element of the slice.

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

Returns mutable raw pointer to the first element of the slice.

Note that this is in fact non-null, it’s just sometimes more useful than as_non_null.

pub fn write_zeroes(&mut self) -> &mut [T] where
    T: ZeroValid, 

Initializes the whole slice by overwriting it with zeroes.

This is only possible if Item allows safely initializing itself with zeroes. (e.g. in case of integer types)

You may implement ZeroValid if zero bit pattern is valid for your type.

pub fn init_from_iter<I>(&mut self, iter: I) -> &mut [T] where
    I: IntoIterator,
    I::Item: TakeItem<T>, 

Uses the iterator to initialize the slice

pub fn copy_from_slice(&mut self, slice: &[T]) -> &mut [T] where
    T: Copy, 

Initializes the slice by copying another slice into it.

This is a specialized version of init_from_iter, which may be more performant.

Panics

The method panics if the slices are of different lengths. Use indexing opertors to make the lengths same.

Trait Implementations

impl<'a, T> BorrowOutSlice<T> for OutSlice<T>

fn borrow_out_slice(&mut self) -> &mut OutSlice<T>

Borrows the value as a mutable slice of MaybeUninit<Item>

fn zero_if_needed(&mut self) -> &mut [Item] where
    Item: ZeroValid, 

Zeroes the buffer if it’s needed and returns it as initialized.

fn init_with_copy_from_slice(&mut self, slice: &[Item]) -> &mut [Item] where
    Item: Copy, 

Initializes the slice by copying from another slice.

fn init_with_copy_from_slice_min(&mut self, slice: &[Item]) -> &mut [Item] where
    Item: Copy, 

Initializes a subslice by copying from another slice.

unsafe fn assume_init_mut(&mut self) -> &mut [Item]

Treat the slice as initialized.

impl<T> BorrowUninitSlice<T> for OutSlice<T>

fn borrow_uninit_slice(&self) -> &[MaybeUninit<T>]

Borrows the value as a slice of MaybeUninit<Item>

unsafe fn assume_init(&self) -> &[Item]

Treat the slice as initialized.

impl<'a, T> From<&'a [MaybeUninit<T>]> for &'a OutSlice<T>

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

Performs the conversion.

impl<'a, T> From<&'a [T]> for &'a OutSlice<T>

fn from(value: &'a [T]) -> Self

Performs the conversion.

impl<'a, T> From<&'a mut [MaybeUninit<T>]> for &'a mut OutSlice<T>

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

Performs the conversion.

impl<'a, T> From<&'a mut [T]> for &'a mut OutSlice<T>

fn from(value: &'a mut [T]) -> Self

Performs the conversion.

impl<T, R: SliceIndex<[MaybeUninit<T>], Output = [MaybeUninit<T>]>> Index<R> for OutSlice<T>

type Output = Self

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T, R: SliceIndex<[MaybeUninit<T>], Output = [MaybeUninit<T>]>> IndexMut<R> for OutSlice<T>

fn index_mut(&mut self, range: R) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T> IntoIterator for &'a mut OutSlice<T>

type Item = Out<'a, T>

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.