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

where T: Default,

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]

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

Examples

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();

impl<T> Cell<T>

where T: CloneFromCell,

pub fn get_cloned(&self) -> Cell<T>

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

Get a clone of the Cell that contains a copy of the original value.

This allows a cheaply Clone-able type like an Rc to be stored in a Cell, exposing the cheaper clone() method.

Examples

#![feature(cell_get_cloned)]

use core::cell::Cell;
use std::rc::Rc;

let rc = Rc::new(1usize);
let c1 = Cell::new(rc);
let c2 = c1.get_cloned();
assert_eq!(*c2.into_inner(), 1);

Trait Implementations

impl<T> Clone for Cell<T>

where T: Copy,

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

Returns a duplicate 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<T> Eq for Cell<T>

where T: Eq + Copy,

#[doc(hidden)] fn assert_receiver_is_total_eq(&self)

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

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

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

impl<T: ?Sized + FromBytes> FromBytes for Cell<T>

fn only_derive_is_allowed_to_implement_this_trait()

fn mut_from_bytes( source: &mut [u8], ) -> Result<&mut Self, CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the given source as a &mut Self.

fn mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the prefix of the given source as a &mut Self without copying.

fn mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the suffix of the given source as a &mut Self without copying.

fn mut_from_prefix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the prefix of the given source as a &mut Self with DST length equal to count.

fn mut_from_suffix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the suffix of the given source as a &mut Self with DST length equal to count.

fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the given source.

fn read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the prefix of the given source.

fn read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the suffix of the given source.

#[doc(hidden)] fn mut_from(source: &mut [u8]) -> Option<&mut Self>

where Self: KnownLayout + IntoBytes,

👎Deprecated since 0.8.0: renamed to FromBytes::mut_from_bytes

#[doc(hidden)] fn mut_slice_from_prefix( source: &mut [u8], count: usize, ) -> Option<(&mut [Self], &mut [u8])>

where Self: Sized + IntoBytes,

👎Deprecated since 0.8.0: renamed to FromBytes::mut_from_prefix_with_elems

#[doc(hidden)] fn mut_slice_from_suffix( source: &mut [u8], count: usize, ) -> Option<(&mut [u8], &mut [Self])>

where Self: Sized + IntoBytes,

👎Deprecated since 0.8.0: renamed to FromBytes::mut_from_suffix_with_elems

#[doc(hidden)] fn read_from(source: &[u8]) -> Option<Self>

where Self: Sized,

👎Deprecated since 0.8.0: renamed to FromBytes::read_from_bytes

impl<T: ?Sized + FromZeros> FromZeros for Cell<T>

fn only_derive_is_allowed_to_implement_this_trait()

fn zero(&mut self)

Overwrites self with zeros.

fn new_zeroed() -> Self

where Self: Sized,

Creates an instance of Self from zeroed bytes.

impl<T: ?Sized + IntoBytes> IntoBytes for Cell<T>

fn only_derive_is_allowed_to_implement_this_trait()

fn as_mut_bytes(&mut self) -> &mut [u8]

where Self: FromBytes,

Gets the bytes of this value mutably.

#[doc(hidden)] fn as_bytes_mut(&mut self) -> &mut [u8]

where Self: FromBytes,

👎Deprecated since 0.8.0: IntoBytes::as_bytes_mut was renamed to as_mut_bytes

impl<T: ?Sized + KnownLayout> KnownLayout for Cell<T>

const LAYOUT: DstLayout = <T as KnownLayout>::LAYOUT

The layout of Self.

type PointerMetadata = <T as KnownLayout>::PointerMetadata

The type of metadata stored in a pointer to Self.

type MaybeUninit = <T as KnownLayout>::MaybeUninit

A maybe-uninitialized analog of Self

fn only_derive_is_allowed_to_implement_this_trait()

fn raw_from_ptr_len( bytes: NonNull<u8>, meta: <T as KnownLayout>::PointerMetadata, ) -> NonNull<Self>

SAFETY: The returned pointer has the same address and provenance as bytes. If Self is a DST, the returned pointer’s referent has elems elements in its trailing slice.

fn pointer_to_metadata(ptr: *mut Self) -> Self::PointerMetadata

Extracts the metadata from a pointer to Self.

#[doc(hidden)] fn size_of_val_raw(ptr: NonNull<Self>) -> Option<usize>

Computes the length of the byte range addressed by ptr.

#[doc(hidden)] fn raw_dangling() -> NonNull<Self>

fn size_for_metadata(meta: Self::PointerMetadata) -> Option<usize>

Computes the size of an object of type Self with the given pointer metadata.

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.

#[doc(hidden)] fn __chaining_lt(&self, other: &Rhs) -> ControlFlow<bool>

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

If self == other, returns ControlFlow::Continue(()). Otherwise, returns ControlFlow::Break(self < other).

#[doc(hidden)] fn __chaining_le(&self, other: &Rhs) -> ControlFlow<bool>

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

Same as __chaining_lt, but for <= instead of <.

#[doc(hidden)] fn __chaining_gt(&self, other: &Rhs) -> ControlFlow<bool>

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

Same as __chaining_lt, but for > instead of <.

#[doc(hidden)] fn __chaining_ge(&self, other: &Rhs) -> ControlFlow<bool>

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

Same as __chaining_lt, but for >= instead of <.

impl<T: ?Sized + TryFromBytes> TryFromBytes for Cell<T>

fn only_derive_is_allowed_to_implement_this_trait()

fn is_bit_valid<A: Reference>(candidate: Maybe<'_, Self, A>) -> bool

Does a given memory range contain a valid instance of Self?

fn try_mut_from_bytes( bytes: &mut [u8], ) -> Result<&mut Self, TryCastError<&mut [u8], Self>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the given source as a &mut Self without copying.

fn try_mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), TryCastError<&mut [u8], Self>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the prefix of the given source as a &mut Self.

fn try_mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), TryCastError<&mut [u8], Self>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the suffix of the given source as a &mut Self.

fn try_mut_from_bytes_with_elems( source: &mut [u8], count: usize, ) -> Result<&mut Self, TryCastError<&mut [u8], Self>>

where Self: KnownLayout<PointerMetadata = usize> + IntoBytes,

Attempts to interpret the given source as a &mut Self with a DST length equal to count.

fn try_mut_from_prefix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut Self, &mut [u8]), TryCastError<&mut [u8], Self>>

where Self: KnownLayout<PointerMetadata = usize> + IntoBytes,

Attempts to interpret the prefix of the given source as a &mut Self with a DST length equal to count.

fn try_mut_from_suffix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut [u8], &mut Self), TryCastError<&mut [u8], Self>>

where Self: KnownLayout<PointerMetadata = usize> + IntoBytes,

Attempts to interpret the suffix of the given source as a &mut Self with a DST length equal to count.

fn try_read_from_bytes(source: &[u8]) -> Result<Self, TryReadError<&[u8], Self>>

where Self: Sized,

Attempts to read the given source as a Self.

fn try_read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), TryReadError<&[u8], Self>>

where Self: Sized,

Attempts to read a Self from the prefix of the given source.

fn try_read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), TryReadError<&[u8], Self>>

where Self: Sized,

Attempts to read a Self from the suffix of the given source.

impl<T: ?Sized + Unaligned> Unaligned for Cell<T>

fn only_derive_is_allowed_to_implement_this_trait()

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> PinCoerceUnsized for Cell<T>

where T: ?Sized,

impl<T> Send for Cell<T>

where T: Send + ?Sized,

impl<T> !Sync for Cell<T>

where T: ?Sized,