Struct Cell

pub struct Cell<T>
where
    T: ?Sized,
{ /* private fields */ }

A mutable memory location.

Memory layout

Cell<T> has the same memory layout and caveats as UnsafeCell<T>. In particular, this means that Cell<T> has the same in-memory representation as its inner type T.

Examples

In this example, you can see that Cell<T> enables mutation inside an immutable struct. In other words, it enables “interior mutability”.

use std::cell::Cell;

struct SomeStruct {
    regular_field: u8,
    special_field: Cell<u8>,
}

let my_struct = SomeStruct {
    regular_field: 0,
    special_field: Cell::new(1),
};

let new_value = 100;

// ERROR: `my_struct` is immutable
// my_struct.regular_field = new_value;

// WORKS: although `my_struct` is immutable, `special_field` is a `Cell`,
// which can always be mutated
my_struct.special_field.set(new_value);
assert_eq!(my_struct.special_field.get(), new_value);

See the module-level documentation for more.

Implementations

impl<T> Cell<T>

pub const fn new(value: T) -> Cell<T>

Creates a new Cell containing the given value.

Examples

use std::cell::Cell;

let c = Cell::new(5);

pub fn set(&self, val: T)

Sets the contained value.

Examples

use std::cell::Cell;

let c = Cell::new(5);

c.set(10);

pub fn swap(&self, other: &Cell<T>)

Swaps the values of two Cells.

The difference with std::mem::swap is that this function doesn’t require a &mut reference.

Panics

This function will panic if self and other are different Cells that partially overlap. (Using just standard library methods, it is impossible to create such partially overlapping Cells. However, unsafe code is allowed to e.g. create two &Cell<[i32; 2]> that partially overlap.)

Examples

use std::cell::Cell;

let c1 = Cell::new(5i32);
let c2 = Cell::new(10i32);
c1.swap(&c2);
assert_eq!(10, c1.get());
assert_eq!(5, c2.get());

pub const fn replace(&self, val: T) -> T

Replaces the contained value with val, and returns the old contained value.

Examples

use std::cell::Cell;

let cell = Cell::new(5);
assert_eq!(cell.get(), 5);
assert_eq!(cell.replace(10), 5);
assert_eq!(cell.get(), 10);

pub const fn into_inner(self) -> T

Unwraps the value, consuming the cell.

Examples

use std::cell::Cell;

let c = Cell::new(5);
let five = c.into_inner();

assert_eq!(five, 5);

impl<T> Cell<T>

where T: Copy,

pub const fn get(&self) -> T

Returns a copy of the contained value.

Examples

use std::cell::Cell;

let c = Cell::new(5);

let five = c.get();

pub fn update(&self, f: impl FnOnce(T) -> T)

Updates the contained value using a function.

Examples

use std::cell::Cell;

let c = Cell::new(5);
c.update(|x| x + 1);
assert_eq!(c.get(), 6);

impl<T> Cell<T>

where T: ?Sized,

pub const fn as_ptr(&self) -> *mut T

Returns a raw pointer to the underlying data in this cell.

Examples

use std::cell::Cell;

let c = Cell::new(5);

let ptr = c.as_ptr();

pub const fn get_mut(&mut self) -> &mut T

Returns a mutable reference to the underlying data.

This call borrows Cell mutably (at compile-time) which guarantees that we possess the only reference.

However be cautious: this method expects self to be mutable, which is generally not the case when using a Cell. If you require interior mutability by reference, consider using RefCell which provides run-time checked mutable borrows through its borrow_mut method.

Examples

use std::cell::Cell;

let mut c = Cell::new(5);
*c.get_mut() += 1;

assert_eq!(c.get(), 6);

pub const fn from_mut(t: &mut T) -> &Cell<T>

Returns a &Cell<T> from a &mut T

Examples

use std::cell::Cell;

let slice: &mut [i32] = &mut [1, 2, 3];
let cell_slice: &Cell<[i32]> = Cell::from_mut(slice);
let slice_cell: &[Cell<i32>] = cell_slice.as_slice_of_cells();

assert_eq!(slice_cell.len(), 3);

impl<T> Cell<T>

where T: Default,

pub fn take(&self) -> T

Takes the value of the cell, leaving Default::default() in its place.

Examples

use std::cell::Cell;

let c = Cell::new(5);
let five = c.take();

assert_eq!(five, 5);
assert_eq!(c.into_inner(), 0);

impl<T> Cell<[T]>

pub const fn as_slice_of_cells(&self) -> &[Cell<T>]

Returns a &[Cell<T>] from a &Cell<[T]>

Examples

use std::cell::Cell;

let slice: &mut [i32] = &mut [1, 2, 3];
let cell_slice: &Cell<[i32]> = Cell::from_mut(slice);
let slice_cell: &[Cell<i32>] = cell_slice.as_slice_of_cells();

assert_eq!(slice_cell.len(), 3);

impl<T, const N: usize> Cell<[T; N]>

pub const fn as_array_of_cells(&self) -> &[Cell<T>; N]

🔬This is a nightly-only experimental API. (as_array_of_cells)

Returns a &[Cell<T>; N] from a &Cell<[T; N]>

Examples

#![feature(as_array_of_cells)]
use std::cell::Cell;

let mut array: [i32; 3] = [1, 2, 3];
let cell_array: &Cell<[i32; 3]> = Cell::from_mut(&mut array);
let array_cell: &[Cell<i32>; 3] = cell_array.as_array_of_cells();

Trait Implementations

impl<T> AbsDiffEq for Cell<T>

where T: AbsDiffEq + Copy,

type Epsilon = <T as AbsDiffEq>::Epsilon

Used for specifying relative comparisons.

fn default_epsilon() -> <T as AbsDiffEq>::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq( &self, other: &Cell<T>, epsilon: <T as AbsDiffEq>::Epsilon, ) -> bool

A test for equality that uses the absolute difference to compute the approximate equality of two numbers.

fn abs_diff_ne(&self, other: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl<T> Clone for Cell<T>

where T: Copy,

fn clone(&self) -> Cell<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Cell<T>

where T: Copy + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for Cell<T>

where T: Default,

fn default() -> Cell<T>

Creates a Cell<T>, with the Default value for T.

impl<'de, T> Deserialize<'de> for Cell<T>

where T: Deserialize<'de> + Copy,

fn deserialize<D>( deserializer: D, ) -> Result<Cell<T>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> From<T> for Cell<T>

fn from(t: T) -> Cell<T>

Creates a new Cell<T> containing the given value.

impl<T> InspectCell<T> for Cell<T>

fn inspect<R>(&self, f: impl Fn(&T) -> R) -> R

impl<T> Ord for Cell<T>

where T: Ord + Copy,

fn cmp(&self, other: &Cell<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq for Cell<T>

where T: PartialEq + Copy,

fn eq(&self, other: &Cell<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Cell<T>

where T: PartialOrd + Copy,

fn partial_cmp(&self, other: &Cell<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Cell<T>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Cell<T>) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Cell<T>) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Cell<T>) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> RelativeEq for Cell<T>

where T: RelativeEq + Copy,

fn default_max_relative() -> <T as AbsDiffEq>::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Cell<T>, epsilon: <T as AbsDiffEq>::Epsilon, max_relative: <T as AbsDiffEq>::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl<T> Serialize for Cell<T>

where T: Serialize + Copy,

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> UlpsEq for Cell<T>

where T: UlpsEq + Copy,

fn default_max_ulps() -> u32

The default ULPs to tolerate when testing values that are far-apart.

fn ulps_eq( &self, other: &Cell<T>, epsilon: <T as AbsDiffEq>::Epsilon, max_ulps: u32, ) -> bool

A test for equality that uses units in the last place (ULP) if the values are far apart.

fn ulps_ne(&self, other: &Rhs, epsilon: Self::Epsilon, max_ulps: u32) -> bool

The inverse of UlpsEq::ulps_eq.

impl<T> Zeroable for Cell<T>

where T: Zeroable,

fn zeroed() -> Self

Calls zeroed.

impl<T, U> CoerceUnsized<Cell<U>> for Cell<T>

where T: CoerceUnsized<U>,

impl<T, U> DispatchFromDyn<Cell<U>> for Cell<T>

where T: DispatchFromDyn<U>,

impl<T> Eq for Cell<T>

where T: Eq + Copy,

impl<T> PinCoerceUnsized for Cell<T>

where T: ?Sized,

impl<T> PointerLike for Cell<T>

where T: PointerLike,

impl<T> Send for Cell<T>

where T: Send + ?Sized,

impl<T> !Sync for Cell<T>

where T: ?Sized,