Struct UninitView

pub struct UninitView<'a, T: ?Sized> { /* private fields */ }

A non-mutable view on a region used in an Uninit.

Makes it possible to utilize the traversal methods (split*, cast*, ..) without requiring a mutable reference to the original Uninit. It will also never expose mutable pointers or accidentally offer an aliased mutable reference. Prefer this to instead avoiding the borrow of the Uninit and manually managing pointers to the region.

Implementations

impl UninitView<'_, ()>

pub unsafe fn from_memory(ptr: NonNull<u8>, len: usize) -> Self

Create a uninit view from raw memory.

Safety

A valid allocation must exist at the pointer with length at least len.

In particular, it is UB to create this from a reference to a variable of a type for which a completely uninitialized content is not valid. The standard type for avoiding the UB is core::mem::MaybeUninit.

When in doubt, refactor code such that utilization of from_maybe_uninit is possible.

pub fn split_layout(&mut self, layout: Layout) -> Option<Self>

Split so that the second part fits the layout.

See Uninit::split_layout for more details.

impl<'a> UninitView<'a, ()>

pub fn split_cast<U>(&mut self) -> Option<UninitView<'a, U>>

Split so that the tail is aligned and valid for a U.

pub fn split_slice<U>(&mut self) -> Option<UninitView<'a, [U]>>

Split so that the tail is aligned for a slice [U].

impl<T> UninitView<'_, T>

pub fn invent_for_zst() -> Self

Invent a new uninit allocation for a zero-sized type (ZST).

Panics

This method panics when the type parameter is not a zero sized type.

impl<'a, T> UninitView<'a, T>

pub fn split_at_byte(&mut self, at: usize) -> Option<UninitView<'a, ()>>

Split the uninit view at a byte boundary.

See Uninit::split_at_byte for more details.

pub fn from_maybe_uninit(mem: &'a MaybeUninit<T>) -> Self

Create an view to the inner bytes of a MaybeUninit.

This is hardly useful on its own but since UninitView mirrors the traversal methods of Uninit it can be used to get pointers to already initialized elements in an immutable context.

pub fn cast_slice<U>(self) -> Result<UninitView<'a, [U]>, Self>

Try to cast to an UninitView for a slice type.

pub fn split_to_fit(&mut self) -> UninitView<'a, ()>

Split off the tail that is not required for holding an instance of T.

pub fn into_maybe_uninit(self) -> &'a MaybeUninit<T>

Turn this into a reference to standard MaybeUninit.

This is mainly useful for interfacing with other consumers which expect standard library types and to mirror Uninit.

Note that the sequence from_maybe_uninit, into_maybe_uninit is a no-op. The converse is however not the case, as it will potentially discard unused padding present in the original Uninit.

impl<'a, T: ?Sized> UninitView<'a, T>

pub unsafe fn new(ptr: NonNull<T>, len: usize) -> Self

Create a reference to typed uninitialized memory.

It is given a capacity of memory to which it refers in bytes.

Safety

The ptr must describe a valid, sized region. Refer to Layout::for_value_raw for details. This criteria is trivially fulfilled for any sized T.

A valid allocation must exist at the pointer with length at least len.

In particular, it is UB to create this from a reference to a variable of a type for which a completely uninitialized content is not valid. The standard type for avoiding the UB is core::mem::MaybeUninit.

When in doubt, refactor code such that utilization of from_maybe_uninit is possible.

pub fn byte_capacity(&self) -> usize

Return the number of bytes this may refer to.

pub fn cast<U>(self) -> Result<UninitView<'a, U>, Self>

Try to cast to an UninitView for another type.

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

Acquires the underlying *const T pointer.

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

Acquires the underlying pointer as a NonNull.

pub unsafe fn as_ref(&self) -> &T

Dereferences the content.

The resulting lifetime is bound to self so this behaves “as if” it were actually an instance of T that is getting borrowed. If a longer lifetime is needed, use into_ref.

Safety

The caller must ensure that the content has already been initialized.

pub unsafe fn into_ref(self) -> &'a T

Turn this into a reference to the content.

Safety

The caller must ensure that the content has already been initialized.

impl<'a, T> UninitView<'a, [T]>

pub fn empty() -> Self

Creates a pointer to an empty slice.

Note that it will not be a mutable empty slice which means that it would be UB to use it as an Uninit.

pub fn from_maybe_uninit_slice(mem: &'a [MaybeUninit<T>]) -> Self

Create an view on potentially uninitialized memory bytes of a slice of MaybeUninit.

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

Get the pointer to the first element of the slice.

pub fn capacity(&self) -> usize

Calculate the theoretical capacity of a slice in the pointed-to allocation.

pub fn split_at(&mut self, at: usize) -> Option<Self>

Split the slice at an index.

pub fn shrink_to_fit(&mut self) -> UninitView<'a, ()>

Get the trailing bytes behind the slice.

The underlying allocation need not be a multiple of the slice element size which may leave unusable bytes. This splits these unusable bytes into an untyped Uninit which can be reused arbitrarily.

This operation is idempotent.

pub fn split_first(&mut self) -> Option<UninitView<'a, T>>

Split the first element from the slice.

pub fn split_last(&mut self) -> Option<UninitView<'a, T>>

Split the last element from the slice.

pub fn into_maybe_uninit_slice(self) -> &'a [MaybeUninit<T>]

Turn this into a slice of standard MaybeUninits.

This is mainly useful for interfacing with other consumers which expect standard library types and to mirror Uninit.

Note that the sequence from_maybe_uninit_slice, into_maybe_uninit_slice is a no-op. The converse is however not the case, as it will potentially discard unused padding present in the original Uninit.

impl<'a, T: ?Sized> UninitView<'a, T>

pub fn fits(&self, layout: Layout) -> bool

Check if the view fits some layout.

The cast to a type of the provided layout will work without error.

pub fn borrow(&self) -> UninitView<'_, T>

Borrow another view of the Uninit region.

pub const fn size(&self) -> usize

Get the byte size of the total allocation.

Trait Implementations

impl<T: ?Sized> Clone for UninitView<'_, T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, T, U: ?Sized> CoerciblePtr<U> for UninitView<'a, T>

type Pointee = T

The type we point to. This influences which kinds of unsizing are possible.

type Output = UninitView<'a, U>

The output type when unsizing the pointee to U.

fn as_sized_ptr(&mut self) -> *mut T

Get the raw inner pointer.

unsafe fn replace_ptr(self, new: *mut U) -> UninitView<'a, U>

Replace the container inner pointer with an unsized version.

impl<T: ?Sized> Debug for UninitView<'_, T>

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

Formats the value using the given formatter.

impl<T> Default for UninitView<'_, [T]>

fn default() -> Self

Returns the “default value” for a type.

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

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

Converts to this type from the input type.

impl<'a, T> From<&'a MaybeUninit<T>> for UninitView<'a, T>

fn from(mem: &'a MaybeUninit<T>) -> Self

Converts to this type from the input type.

impl<'a, T> From<Uninit<'a, T>> for UninitView<'a, T>

fn from(uninit: Uninit<'a, T>) -> Self

Converts to this type from the input type.

impl<T: ?Sized> Copy for UninitView<'_, T>