Struct std::cell::OnceCell

1.70.0 · source ·

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

Expand description

一个 cell 只能写入一次。

这允许在不复制或替换它的情况下获取共享的 &T 引用其内部值 (与 Cell 不同)，并且无需运行时引用检查 (与 RefCell 不同)。

但是，除非对 cell 本身具有可变引用，否则只能获得不可更改引用。

有关此结构体的线程安全版本，请参见 std::sync::OnceLock。

Examples

use std::cell::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());

Run

Implementations§

source §

impl<T> OnceCell<T>

const: 1.70.0 · source

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

创建一个新的空 cell。

source

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

获取对底层值的引用。

如果 cell 为空，则返回 None。

source

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

获取对底层值的可变引用。

如果 cell 为空，则返回 None。

source

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

将 cell 的内容设置为 value。

Errors

如果 cell 为空，则此方法返回 Ok(()); 如果 cell 已满，则返回 Err(value)。

Examples

use std::cell::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());

Run

source

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

获取 cell 的内容，如果 cell 为空，则使用 f 对其进行初始化。

Panics

如果 f panics，则 panic 会传播给调用者，并且 cell 仍保持未初始化状态。

重新从 f 初始化 cell 是错误的。这样做会导致 panic。

Examples

use std::cell::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);

Run

source

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

🔬This is a nightly-only experimental API. (once_cell_try #109737)

获取 cell 的内容，如果 cell 为空，则使用 f 对其进行初始化。如果 cell 为空并且 f 失败，则返回错误。

Panics

如果 f panics，则 panic 会传播给调用者，并且 cell 仍保持未初始化状态。

重新从 f 初始化 cell 是错误的。这样做会导致 panic。

Examples

#![feature(once_cell_try)]

use std::cell::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))

Run

source

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

消费 cell，返回包装后的值。

如果 cell 为空，则返回 None。

Examples

use std::cell::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()));

Run

source

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

从 OnceCell 中取出值，将其移回未初始化状态。

无效，如果尚未初始化 OnceCell，则返回 None。

通过要求可变引用来保证安全。

Examples

use std::cell::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);