Skip to content
Tutorials Center
My learning

Topics

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.

Rust
use std::cell::Cell;

let hits = Cell::new(0);
hits.set(hits.get() + 1);

Try it

Rust A counter inside an immutable struct

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.

Rust replace, take, swap and update

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

Rust
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 Cell for small Copy values and RefCell when you need references into the contents.
  • Cell<T> has the same layout as T, so it costs nothing extra.
  • It makes a type !Sync. A struct with a Cell field cannot be shared between threads by reference; use AtomicUsize and friends instead.
  • Cell::from_mut(&mut x) and as_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-Copy value: it will not compile, because get needs Copy. Use RefCell.