Union core::mem::MaybeUninit

pub union MaybeUninit<T> {
    // some fields omitted
}

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

A newtype to construct uninitialized instances of T.

The compiler, in general, assumes that variables are properly initialized at their respective type. For example, a variable of reference type must be aligned and non-NULL. This is an invariant that must always be upheld, even in unsafe code. As a consequence, zero-initializing a variable of reference type causes instantaneous undefined behavior, no matter whether that reference ever gets used to access memory:

use std::mem;

let x: &i32 = unsafe { mem::zeroed() }; // undefined behavior!

This is exploited by the compiler for various optimizations, such as eliding run-time checks and optimizing enum layout.

Not initializing memory at all (instead of zero--initializing it) causes the same issue: after all, the initial value of the variable might just happen to be one that violates the invariant.

MaybeUninit serves to enable unsafe code to deal with uninitialized data: it is a signal to the compiler indicating that the data here might not be initialized:

#![feature(maybe_uninit)]
use std::mem::MaybeUninit;

// Create an explicitly uninitialized reference.
let mut x = MaybeUninit::<&i32>::uninitialized();
// Set it to a valid value.
x.set(&0);
// Extract the initialized data -- this is only allowed *after* properly
// initializing `x`!
let x = unsafe { x.into_initialized() };

The compiler then knows to not optimize this code.

Methods

impl<T> MaybeUninit<T>

pub const fn new(val: T) -> MaybeUninit<T>

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Create a new MaybeUninit initialized with the given value.

Note that dropping a MaybeUninit will never call T's drop code. It is your responsibility to make sure T gets dropped if it got initialized.

pub const fn uninitialized() -> MaybeUninit<T>

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Creates a new MaybeUninit in an uninitialized state.

Note that dropping a MaybeUninit will never call T's drop code. It is your responsibility to make sure T gets dropped if it got initialized.

pub fn zeroed() -> MaybeUninit<T>

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Creates a new MaybeUninit in an uninitialized state, with the memory being filled with 0 bytes. It depends on T whether that already makes for proper initialization. For example, MaybeUninit<usize>::zeroed() is initialized, but MaybeUninit<&'static i32>::zeroed() is not because references must not be null.

Note that dropping a MaybeUninit will never call T's drop code. It is your responsibility to make sure T gets dropped if it got initialized.

pub fn set(&mut self, val: T) -> &mut T

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Sets the value of the MaybeUninit. This overwrites any previous value without dropping it. For your convenience, this also returns a mutable reference to the (now safely initialized) contents of self.

pub unsafe fn into_initialized(self) -> T

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Extracts the value from the MaybeUninit container. This is a great way to ensure that the data will get dropped, because the resulting T is subject to the usual drop handling.

Unsafety

It is up to the caller to guarantee that the MaybeUninit really is in an initialized state, otherwise this will immediately cause undefined behavior.

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

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Gets a reference to the contained value.

Unsafety

It is up to the caller to guarantee that the MaybeUninit really is in an initialized state, otherwise this will immediately cause undefined behavior.

pub unsafe fn get_mut(&mut self) -> &mut T

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Gets a mutable reference to the contained value.

Unsafety

It is up to the caller to guarantee that the MaybeUninit really is in an initialized state, otherwise this will immediately cause undefined behavior.

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

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Gets a pointer to the contained value. Reading from this pointer or turning it into a reference will be undefined behavior unless the MaybeUninit is initialized.

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

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Get sa mutable pointer to the contained value. Reading from this pointer or turning it into a reference will be undefined behavior unless the MaybeUninit is initialized.

pub fn first_ptr(this: &[MaybeUninit<T>]) -> *const T

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Gets a pointer to the first element of the array.

pub fn first_ptr_mut(this: &mut [MaybeUninit<T>]) -> *mut T

🔬 This is a nightly-only experimental API. (maybe_uninit #53491)

Gets a mutable pointer to the first element of the array.