pub struct OnceCell<T> { /* private fields */ }
Expand description
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§
Source§impl<T> OnceCell<T>
impl<T> OnceCell<T>
Sourcepub const fn with_value(value: T) -> OnceCell<T>
pub const fn with_value(value: T) -> OnceCell<T>
Creates a new initialized cell.
Sourcepub fn get(&self) -> Option<&T>
pub fn get(&self) -> Option<&T>
Gets a reference to the underlying value.
Returns None
if the cell is empty.
Sourcepub fn get_mut(&mut self) -> Option<&mut T>
pub fn get_mut(&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));
Sourcepub fn set(&self, value: T) -> Result<(), T>
pub fn set(&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());
Sourcepub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
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,
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);
Sourcepub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
pub fn get_or_try_init<F, E>(&self, f: F) -> 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))
Sourcepub fn take(&mut self) -> Option<T>
pub fn take(&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();
Sourcepub fn into_inner(self) -> Option<T>
pub fn into_inner(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()));