Creates a new MaybeUninit<T> initialized with the given value. It is safe to call assume_init on the return value of this function.

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

Creates a new MaybeUninit<T> in an uninitialized state.

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

See the type-level documentation for some examples.

Create a new array of MaybeUninit<T> items, in an uninitialized state.

Note: in a future Rust version this method may become unnecessary when array literal syntax allows repeating const expressions. The example below could then use let mut buf = [MaybeUninit::<u8>::uninit(); 32];.

Examples

#![feature(maybe_uninit_uninit_array, maybe_uninit_extra, maybe_uninit_slice_assume_init)]

use std::mem::MaybeUninit;

extern "C" {
    fn read_into_buffer(ptr: *mut u8, max_len: usize) -> usize;
}

/// Returns a (possibly smaller) slice of data that was actually read
fn read(buf: &mut [MaybeUninit<u8>]) -> &[u8] {
    unsafe {
        let len = read_into_buffer(buf.as_mut_ptr() as *mut u8, buf.len());
        MaybeUninit::slice_get_ref(&buf[..len])
    }
}

let mut buf: [MaybeUninit<u8>; 32] = MaybeUninit::uninit_array();
let data = read(&mut buf);

A promotable constant, equivalent to uninit().

Creates a new MaybeUninit<T> 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<T> will never call T's drop code. It is your responsibility to make sure T gets dropped if it got initialized.

Example

Correct usage of this function: initializing a struct with zero, where all fields of the struct can hold the bit-pattern 0 as a valid value.

use std::mem::MaybeUninit;

let x = MaybeUninit::<(u8, bool)>::zeroed();
let x = unsafe { x.assume_init() };
assert_eq!(x, (0, false));

Incorrect usage of this function: calling x.zeroed().assume_init() when 0 is not a valid bit-pattern for the type:

use std::mem::MaybeUninit;

enum NotZero { One = 1, Two = 2 };

let x = MaybeUninit::<(u8, NotZero)>::zeroed();
let x = unsafe { x.assume_init() };
// Inside a pair, we create a `NotZero` that does not have a valid discriminant.
// This is undefined behavior. ⚠️

Sets the value of the MaybeUninit<T>. This overwrites any previous value without dropping it, so be careful not to use this twice unless you want to skip running the destructor. For your convenience, this also returns a mutable reference to the (now safely initialized) contents of self.

Gets a pointer to the contained value. Reading from this pointer or turning it into a reference is undefined behavior unless the MaybeUninit<T> is initialized. Writing to memory that this pointer (non-transitively) points to is undefined behavior (except inside an UnsafeCell<T>).

Examples

Correct usage of this method:

use std::mem::MaybeUninit;

let mut x = MaybeUninit::<Vec<u32>>::uninit();
unsafe { x.as_mut_ptr().write(vec![0,1,2]); }
// Create a reference into the `MaybeUninit<T>`. This is okay because we initialized it.
let x_vec = unsafe { &*x.as_ptr() };
assert_eq!(x_vec.len(), 3);

Incorrect usage of this method:

use std::mem::MaybeUninit;

let x = MaybeUninit::<Vec<u32>>::uninit();
let x_vec = unsafe { &*x.as_ptr() };
// We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️

(Notice that the rules around references to uninitialized data are not finalized yet, but until they are, it is advisable to avoid them.)

Gets a mutable pointer to the contained value. Reading from this pointer or turning it into a reference is undefined behavior unless the MaybeUninit<T> is initialized.

Examples

Correct usage of this method:

use std::mem::MaybeUninit;

let mut x = MaybeUninit::<Vec<u32>>::uninit();
unsafe { x.as_mut_ptr().write(vec![0,1,2]); }
// Create a reference into the `MaybeUninit<Vec<u32>>`.
// This is okay because we initialized it.
let x_vec = unsafe { &mut *x.as_mut_ptr() };
x_vec.push(3);
assert_eq!(x_vec.len(), 4);

Incorrect usage of this method:

use std::mem::MaybeUninit;

let mut x = MaybeUninit::<Vec<u32>>::uninit();
let x_vec = unsafe { &mut *x.as_mut_ptr() };
// We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️

(Notice that the rules around references to uninitialized data are not finalized yet, but until they are, it is advisable to avoid them.)

Extracts the value from the MaybeUninit<T> 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.

Safety

It is up to the caller to guarantee that the MaybeUninit<T> really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior. The type-level documentation contains more information about this initialization invariant.

On top of that, remember that most types have additional invariants beyond merely being considered initialized at the type level. For example, a 1-initialized [Vec<T>] is considered initialized (under the current implementation; this does not constitute a stable guarantee) because the only requirement the compiler knows about it is that the data pointer must be non-null. Creating such a Vec<T> does not cause immediate undefined behavior, but will cause undefined behavior with most safe operations (including dropping it).

Examples

Correct usage of this method:

use std::mem::MaybeUninit;

let mut x = MaybeUninit::<bool>::uninit();
unsafe { x.as_mut_ptr().write(true); }
let x_init = unsafe { x.assume_init() };
assert_eq!(x_init, true);

Incorrect usage of this method:

use std::mem::MaybeUninit;

let x = MaybeUninit::<Vec<u32>>::uninit();
let x_init = unsafe { x.assume_init() };
// `x` had not been initialized yet, so this last line caused undefined behavior. ⚠️

Reads the value from the MaybeUninit<T> container. The resulting T is subject to the usual drop handling.

Whenever possible, it is preferable to use assume_init instead, which prevents duplicating the content of the MaybeUninit<T>.

Safety

It is up to the caller to guarantee that the MaybeUninit<T> really is in an initialized state. Calling this when the content is not yet fully initialized causes undefined behavior. The type-level documentation contains more information about this initialization invariant.

Moreover, this leaves a copy of the same data behind in the MaybeUninit<T>. When using multiple copies of the data (by calling read multiple times, or first calling read and then assume_init), it is your responsibility to ensure that that data may indeed be duplicated.

Examples

Correct usage of this method:

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

let mut x = MaybeUninit::<u32>::uninit();
x.write(13);
let x1 = unsafe { x.read() };
// `u32` is `Copy`, so we may read multiple times.
let x2 = unsafe { x.read() };
assert_eq!(x1, x2);

let mut x = MaybeUninit::<Option<Vec<u32>>>::uninit();
x.write(None);
let x1 = unsafe { x.read() };
// Duplicating a `None` value is okay, so we may read multiple times.
let x2 = unsafe { x.read() };
assert_eq!(x1, x2);

Incorrect usage of this method:

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

let mut x = MaybeUninit::<Option<Vec<u32>>>::uninit();
x.write(Some(vec![0,1,2]));
let x1 = unsafe { x.read() };
let x2 = unsafe { x.read() };
// We now created two copies of the same vector, leading to a double-free ⚠️ when
// they both get dropped!

Gets a shared reference to the contained value.

This can be useful when we want to access a MaybeUninit that has been initialized but don't have ownership of the MaybeUninit (preventing the use of .assume_init()).

Safety

Calling this when the content is not yet fully initialized causes undefined behavior: it is up to the caller to guarantee that the MaybeUninit<T> really is in an initialized state.

Examples

Correct usage of this method:

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

let mut x = MaybeUninit::<Vec<u32>>::uninit();
// Initialize `x`:
unsafe { x.as_mut_ptr().write(vec![1, 2, 3]); }
// Now that our `MaybeUninit<_>` is known to be initialized, it is okay to
// create a shared reference to it:
let x: &Vec<u32> = unsafe {
    // Safety: `x` has been initialized.
    x.get_ref()
};
assert_eq!(x, &vec![1, 2, 3]);

Incorrect usages of this method:

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

let x = MaybeUninit::<Vec<u32>>::uninit();
let x_vec: &Vec<u32> = unsafe { x.get_ref() };
// We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️

#![feature(maybe_uninit_ref)]
use std::{cell::Cell, mem::MaybeUninit};

let b = MaybeUninit::<Cell<bool>>::uninit();
// Initialize the `MaybeUninit` using `Cell::set`:
unsafe {
    b.get_ref().set(true);
 // ^^^^^^^^^^^
 // Reference to an uninitialized `Cell<bool>`: UB!
}

Gets a mutable (unique) reference to the contained value.

This can be useful when we want to access a MaybeUninit that has been initialized but don't have ownership of the MaybeUninit (preventing the use of .assume_init()).

Safety

Calling this when the content is not yet fully initialized causes undefined behavior: it is up to the caller to guarantee that the MaybeUninit<T> really is in an initialized state. For instance, .get_mut() cannot be used to initialize a MaybeUninit.

Examples

Correct usage of this method:

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

extern "C" {
    /// Initializes *all* the bytes of the input buffer.
    fn initialize_buffer(buf: *mut [u8; 2048]);
}

let mut buf = MaybeUninit::<[u8; 2048]>::uninit();

// Initialize `buf`:
unsafe { initialize_buffer(buf.as_mut_ptr()); }
// Now we know that `buf` has been initialized, so we could `.assume_init()` it.
// However, using `.assume_init()` may trigger a `memcpy` of the 2048 bytes.
// To assert our buffer has been initialized without copying it, we upgrade
// the `&mut MaybeUninit<[u8; 2048]>` to a `&mut [u8; 2048]`:
let buf: &mut [u8; 2048] = unsafe {
    // Safety: `buf` has been initialized.
    buf.get_mut()
};

// Now we can use `buf` as a normal slice:
buf.sort_unstable();
assert!(
    buf.windows(2).all(|pair| pair[0] <= pair[1]),
    "buffer is sorted",
);

Incorrect usages of this method:

You cannot use .get_mut() to initialize a value:

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

let mut b = MaybeUninit::<bool>::uninit();
unsafe {
    *b.get_mut() = true;
    // We have created a (mutable) reference to an uninitialized `bool`!
    // This is undefined behavior. ⚠️
}

For instance, you cannot Read into an uninitialized buffer:

#![feature(maybe_uninit_ref)]
use std::{io, mem::MaybeUninit};

fn read_chunk (reader: &'_ mut dyn io::Read) -> io::Result<[u8; 64]>
{
    let mut buffer = MaybeUninit::<[u8; 64]>::uninit();
    reader.read_exact(unsafe { buffer.get_mut() })?;
                            // ^^^^^^^^^^^^^^^^
                            // (mutable) reference to uninitialized memory!
                            // This is undefined behavior.
    Ok(unsafe { buffer.assume_init() })
}

Nor can you use direct field access to do field-by-field gradual initialization:

#![feature(maybe_uninit_ref)]
use std::{mem::MaybeUninit, ptr};

struct Foo {
    a: u32,
    b: u8,
}

let foo: Foo = unsafe {
    let mut foo = MaybeUninit::<Foo>::uninit();
    ptr::write(&mut foo.get_mut().a as *mut u32, 1337);
                 // ^^^^^^^^^^^^^
                 // (mutable) reference to uninitialized memory!
                 // This is undefined behavior.
    ptr::write(&mut foo.get_mut().b as *mut u8, 42);
                 // ^^^^^^^^^^^^^
                 // (mutable) reference to uninitialized memory!
                 // This is undefined behavior.
    foo.assume_init()
};

Assuming all the elements are initialized, get a slice to them.

Safety

It is up to the caller to guarantee that the MaybeUninit<T> elements really are in an initialized state. Calling this when the content is not yet fully initialized causes undefined behavior.

Assuming all the elements are initialized, get a mutable slice to them.

Safety

It is up to the caller to guarantee that the MaybeUninit<T> elements really are in an initialized state. Calling this when the content is not yet fully initialized causes undefined behavior.

Gets a pointer to the first element of the array.

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