pub struct OnceCell<T> { /* private fields */ }Expand description
A cell which can nominally be written to only once.
This allows obtaining a shared &T reference to its inner value without copying or replacing
it (unlike Cell), and without runtime borrow checks (unlike RefCell). However,
only immutable references can be obtained unless one has a mutable reference to the cell
itself. In the same vein, the cell can only be re-initialized with such a mutable reference.
For a thread-safe version of this struct, see std::sync::OnceLock.
§Examples
Implementations§
Source§impl<T> OnceCell<T>
impl<T> OnceCell<T>
1.70.0 · Sourcepub fn get(&self) -> Option<&T>
pub fn get(&self) -> Option<&T>
Gets the reference to the underlying value.
Returns None if the cell is empty.
1.70.0 · Sourcepub fn get_mut(&mut self) -> Option<&mut T>
pub fn get_mut(&mut self) -> Option<&mut T>
Gets the mutable reference to the underlying value.
Returns None if the cell is empty.
1.70.0 · Sourcepub fn set(&self, value: T) -> Result<(), T>
pub fn set(&self, value: T) -> Result<(), T>
Sourcepub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
🔬This is a nightly-only experimental API. (once_cell_try_insert #116693)
pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
once_cell_try_insert #116693)1.70.0 · Sourcepub fn get_or_init<F>(&self, f: F) -> &Twhere
F: FnOnce() -> T,
pub fn get_or_init<F>(&self, f: F) -> &Twhere
F: FnOnce() -> T,
Sourcepub fn get_mut_or_init<F>(&mut self, f: F) -> &mut Twhere
F: FnOnce() -> T,
🔬This is a nightly-only experimental API. (once_cell_get_mut #121641)
pub fn get_mut_or_init<F>(&mut self, f: F) -> &mut Twhere
F: FnOnce() -> T,
once_cell_get_mut #121641)Sourcepub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
🔬This is a nightly-only experimental API. (once_cell_try #109737)
pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
once_cell_try #109737)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.
§Examples
Sourcepub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
🔬This is a nightly-only experimental API. (once_cell_get_mut #121641)
pub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
once_cell_get_mut #121641)Gets the mutable reference of 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.
§Examples
#![feature(once_cell_get_mut)]
use std::cell::OnceCell;
let mut cell: OnceCell<u32> = OnceCell::new();
// Failed initializers do not change the value
assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
assert!(cell.get().is_none());
let value = cell.get_mut_or_try_init(|| "1234".parse());
assert_eq!(value, Ok(&mut 1234));
*value.unwrap() += 2;
assert_eq!(cell.get(), Some(&1236))