impl<T> OnceCell<T>

const fn new() -> OnceCell<T>

Creates a new empty cell.

const fn with_value(value: T) -> OnceCell<T>

Creates a new initialized cell.

fn get(self: &Self) -> Option<&T>

Gets a reference to the underlying value.

Returns None if the cell is empty.

fn get_mut(self: &mut Self) -> Option<&mut T>

Gets a mutable reference to the underlying value.

Returns None if the cell is empty.

This method is allowed to violate the invariant of writing to a OnceCell at most once because it requires &mut access to self. As with all interior mutability, &mut access permits arbitrary modification:

use once_cell::unsync::OnceCell;

let mut cell: OnceCell<u32> = OnceCell::new();
cell.set(92).unwrap();
*cell.get_mut().unwrap() = 93;
assert_eq!(cell.get(), Some(&93));

fn set(self: &Self, value: T) -> Result<(), T>

Sets the contents of this cell to value.

Returns Ok(()) if the cell was empty and Err(value) if it was full.

Example

use once_cell::unsync::OnceCell;

let cell = OnceCell::new();
assert!(cell.get().is_none());

assert_eq!(cell.set(92), Ok(()));
assert_eq!(cell.set(62), Err(62));

assert!(cell.get().is_some());

fn try_insert(self: &Self, value: T) -> Result<&T, (&T, T)>

Like set, but also returns a reference to the final cell value.

Example

use once_cell::unsync::OnceCell;

let cell = OnceCell::new();
assert!(cell.get().is_none());

assert_eq!(cell.try_insert(92), Ok(&92));
assert_eq!(cell.try_insert(62), Err((&92, 62)));

assert!(cell.get().is_some());

fn get_or_init<F>(self: &Self, f: F) -> &T
where
    F: FnOnce() -> T

Gets the contents of the cell, initializing it with f if the cell was empty.

Panics

If f panics, the panic is propagated to the caller, and the cell remains uninitialized.

It is an error to reentrantly initialize the cell from f. Doing so results in a panic.

Example

use once_cell::unsync::OnceCell;

let cell = OnceCell::new();
let value = cell.get_or_init(|| 92);
assert_eq!(value, &92);
let value = cell.get_or_init(|| unreachable!());
assert_eq!(value, &92);

fn get_or_try_init<F, E>(self: &Self, f: F) -> Result<&T, E>
where
    F: FnOnce() -> Result<T, E>

Gets the contents of the cell, initializing it with f if the cell was empty. If the cell was empty and f failed, an error is returned.

Panics

If f panics, the panic is propagated to the caller, and the cell remains uninitialized.

It is an error to reentrantly initialize the cell from f. Doing so results in a panic.

Example

use once_cell::unsync::OnceCell;

let cell = OnceCell::new();
assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
assert!(cell.get().is_none());
let value = cell.get_or_try_init(|| -> Result<i32, ()> {
    Ok(92)
});
assert_eq!(value, Ok(&92));
assert_eq!(cell.get(), Some(&92))

fn take(self: &mut Self) -> Option<T>

Takes the value out of this OnceCell, moving it back to an uninitialized state.

Has no effect and returns None if the OnceCell hasn't been initialized.

Examples

use once_cell::unsync::OnceCell;

let mut cell: OnceCell<String> = OnceCell::new();
assert_eq!(cell.take(), None);

let mut cell = OnceCell::new();
cell.set("hello".to_string()).unwrap();
assert_eq!(cell.take(), Some("hello".to_string()));
assert_eq!(cell.get(), None);

This method is allowed to violate the invariant of writing to a OnceCell at most once because it requires &mut access to self. As with all interior mutability, &mut access permits arbitrary modification:

use once_cell::unsync::OnceCell;

let mut cell: OnceCell<u32> = OnceCell::new();
cell.set(92).unwrap();
cell = OnceCell::new();

fn into_inner(self: Self) -> Option<T>

Consumes the OnceCell, returning the wrapped value.

Returns None if the cell was empty.

Examples

use once_cell::unsync::OnceCell;

let cell: OnceCell<String> = OnceCell::new();
assert_eq!(cell.into_inner(), None);

let cell = OnceCell::new();
cell.set("hello".to_string()).unwrap();
assert_eq!(cell.into_inner(), Some("hello".to_string()));

impl<T> Any for OnceCell<T>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for OnceCell<T>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for OnceCell<T>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for OnceCell<T>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> Default for OnceCell<T>

fn default() -> Self

impl<T> Freeze for OnceCell<T>

impl<T> From for OnceCell<T>

fn from(t: never) -> T

impl<T> From for OnceCell<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> From for OnceCell<T>

fn from(value: T) -> Self

impl<T> Send for OnceCell<T>

impl<T> Sync for OnceCell<T>

impl<T> ToOwned for OnceCell<T>

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T> Unpin for OnceCell<T>

impl<T> UnsafeUnpin for OnceCell<T>

impl<T, U> Into for OnceCell<T>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for OnceCell<T>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for OnceCell<T>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<T: Clone> Clone for OnceCell<T>

fn clone(self: &Self) -> OnceCell<T>

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

impl<T: Eq> Eq for OnceCell<T>

impl<T: PartialEq> PartialEq for OnceCell<T>

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

impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceCell<T>

impl<T: UnwindSafe> UnwindSafe for OnceCell<T>

impl<T: fmt::Debug> Debug for OnceCell<T>

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