Struct OnceCell

pub struct OnceCell<T> { /* private fields */ }

Available on crate feature __base only.

A cell which can be written to only once. It is not thread safe.

Unlike std::cell::RefCell, a OnceCell provides simple & references to the contents.

Example

use once_cell::unsync::OnceCell;

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

let value: &String = cell.get_or_init(|| {
    "Hello, World!".to_string()
});
assert_eq!(value, "Hello, World!");
assert!(cell.get().is_some());

Implementations

impl<T> OnceCell<T>

pub const fn new() -> OnceCell<T>

Available on crate features __ecma and ecma_ast only.

Creates a new empty cell.

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

Available on crate features __ecma and ecma_ast only.

Creates a new initialized cell.

pub fn get(&self) -> Option<&T>

Available on crate features __ecma and ecma_ast only.

Gets a reference to the underlying value.

Returns None if the cell is empty.

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

Available on crate features __ecma and ecma_ast only.

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));

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

Available on crate features __ecma and ecma_ast only.

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());

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

Available on crate features __ecma and ecma_ast only.

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());

pub fn get_or_init<F>(&self, f: F) -> &T

where F: FnOnce() -> T,

Available on crate features __ecma and ecma_ast only.

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);

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

where F: FnOnce() -> Result<T, E>,

Available on crate features __ecma and ecma_ast only.

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))

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

Available on crate features __ecma and ecma_ast only.

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();

pub fn into_inner(self) -> Option<T>

Available on crate features __ecma and ecma_ast only.

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()));

Trait Implementations

impl<T> Clone for OnceCell<T>

where T: Clone,

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

Returns a copy of the value.

fn clone_from(&mut self, source: &OnceCell<T>)

Performs copy-assignment from source.

impl<T> Debug for OnceCell<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Default for OnceCell<T>

fn default() -> OnceCell<T>

Returns the “default value” for a type.

impl<T> From<T> for OnceCell<T>

fn from(value: T) -> OnceCell<T>

Converts to this type from the input type.

impl<T> PartialEq for OnceCell<T>

where T: PartialEq,

fn eq(&self, other: &OnceCell<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Eq for OnceCell<T>

where T: Eq,

impl<T> RefUnwindSafe for OnceCell<T>

where T: RefUnwindSafe + UnwindSafe,

impl<T> UnwindSafe for OnceCell<T>

where T: UnwindSafe,