Rust Reference ยท Smart Pointers and Memory
Rust Cell<T> type
Reference for Rust Cell<T>: get, set, replace, take, swap and update through a shared reference, why it has no references to its contents, and when to use it.
Cell<T> lets you change a value through a shared reference (&Cell<T>). It achieves this safely by never handing out references to the inside: you can only copy a value out with get, or move a whole value in with set, replace or take. Since nobody can hold a reference into the cell, no aliasing rule can be broken.
There is no run-time bookkeeping and no panic, so Cell is the cheapest form of interior mutability. It is a good fit for counters, flags and caches of small Copy values inside structs that are otherwise used immutably. Cell<T> is Send (if T is) but never Sync; for threads use atomics or a Mutex.
use std::cell::Cell; let hits = Cell::new(0); hits.set(hits.get() + 1);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
pub struct Cell<T: ?Sized> { /* private */ } impl<T> Cell<T> { pub const fn new(value: T) -> Cell<T>; pub fn set(&self, val: T); pub fn replace(&self, val: T) -> T; pub fn swap(&self, other: &Cell<T>); pub fn into_inner(self) -> T; } impl<T: Copy> Cell<T> { pub fn get(&self) -> T; pub fn update(&self, f: impl FnOnce(T) -> T); } impl<T: Default> Cell<T> { pub fn take(&self) -> T; } impl<T: ?Sized> Cell<T> { pub fn get_mut(&mut self) -> &mut T; pub fn as_ptr(&self) -> *mut T; }
| Method | Description |
|---|---|
get |
Returns a copy of the contents; requires T: Copy. |
set |
Stores a new value and drops the old one. |
replace |
Stores a new value and returns the old one. |
take |
Replaces the value with T::default() and returns the old one. |
swap |
Exchanges contents with another cell. |
update |
Applies a function to a copy and stores the result (stable since Rust 1.88). |
get_mut |
Plain &mut T when you have &mut Cell<T>. |
Edge cases. Cell::swap on the same cell does nothing. Cell<T> where T is not Copy has no get; use take/replace instead, which is how Cell<Option<Box<T>>> is used.
Usage notes
- Prefer
Cellfor smallCopyvalues andRefCellwhen you need references into the contents. Cell<T>has the same layout asT, so it costs nothing extra.- It makes a type
!Sync. A struct with aCellfield cannot be shared between threads by reference; useAtomicUsizeand friends instead. Cell::from_mut(&mut x)andas_slice_of_cells()turn a&mut [T]into&[Cell<T>], a trick for indexing while mutating from several places.- A common mistake is
cell.get().push(..)on a non-Copyvalue: it will not compile, becausegetneedsCopy. UseRefCell.
Related
- RefCell, OnceCell and LazyCell, Rc
- Tutorial: RefCell and Cell, Atomics