Struct Cell

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

Available on crate feature std only.

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 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 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<F>(&self, f: F) -> T

where F: FnOnce(T) -> T,

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

Updates the contained value using a function and returns the new value.

Examples

#![feature(cell_update)]

use std::cell::Cell;

let c = Cell::new(5);
let new = c.update(|x| x + 1);

assert_eq!(new, 6);
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 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 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 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<F> ArchiveWith<Cell<F>> for Unsafe

where F: Archive,

type Archived = <F as Archive>::Archived

The archived type of Self with F.

type Resolver = <F as Archive>::Resolver

The resolver of a Self with F.

fn resolve_with( field: &Cell<F>, resolver: <Unsafe as ArchiveWith<Cell<F>>>::Resolver, out: Place<<Unsafe as ArchiveWith<Cell<F>>>::Archived>, )

Resolves the archived type using a reference to the field type F.

impl<T, C> CheckBytes<C> for Cell<T>

where T: CheckBytes<C> + ?Sized, C: Fallible + ?Sized, <C as Fallible>::Error: Trace,

unsafe fn check_bytes( value: *const Cell<T>, c: &mut C, ) -> Result<(), <C as Fallible>::Error>

Checks whether the given pointer points to a valid value within the given context.

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: ConstDefault> ConstDefault for Cell<T>

const DEFAULT: Self

Returns the compile-time “default value” for a type.

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<F, D> DeserializeWith<<F as Archive>::Archived, Cell<F>, D> for Unsafe

where F: Archive, <F as Archive>::Archived: Deserialize<F, D>, D: Fallible + ?Sized,

fn deserialize_with( field: &<F as Archive>::Archived, deserializer: &mut D, ) -> Result<Cell<F>, <D as Fallible>::Error>

Deserializes the field type F using the given deserializer.

impl<'a, T> Destructure for &'a Cell<T>

where T: ?Sized,

type Underlying = T

The underlying type that is destructured.

type Destructuring = Borrow

The type of destructuring to perform.

fn underlying(&mut self) -> *mut <&'a Cell<T> as Destructure>::Underlying

Returns a mutable pointer to the underlying type.

impl<'a, T> Destructure for &'a mut Cell<T>

where T: ?Sized,

type Underlying = T

The underlying type that is destructured.

type Destructuring = Borrow

The type of destructuring to perform.

fn underlying(&mut self) -> *mut <&'a mut Cell<T> as Destructure>::Underlying

Returns a mutable pointer to the underlying type.

impl<T> Destructure for Cell<T>

type Underlying = T

The underlying type that is destructured.

type Destructuring = Move

The type of destructuring to perform.

fn underlying(&mut self) -> *mut <Cell<T> as Destructure>::Underlying

Returns a mutable pointer to the underlying type.

impl<T> ExtCellOption<T> for Cell<Option<T>>

fn modify<F: FnOnce(T) -> T>(&self, func: F)

Modifies the value inside the Cell<Option<T>> by applying the provided closure to a mutable reference of the current value if present.

fn modify_ret<F: FnOnce(T) -> T>(&self, func: F) -> Option<T>

where T: Clone,

Modifies the value inside the Cell<Option<T>> by applying the provided function and returns the old contained value.

fn modify_mut<R, F: FnOnce(&mut T) -> R>(&self, func: F) -> Option<R>

Modifies the value inside the Cell<Option<T>> by applying the provided closure to a mutable reference of the current value if present, and returns a result.

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

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

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

impl<'py, T> FromPyObject<'py> for Cell<T>

where T: FromPyObject<'py>,

fn extract_bound(ob: &Bound<'py, PyAny>) -> Result<Cell<T>, PyErr>

Extracts Self from the bound smart pointer obj.

impl<T> IntoPy<Py<PyAny>> for Cell<T>

where T: Copy + IntoPy<Py<PyAny>>,

fn into_py(self, py: Python<'_>) -> Py<PyAny>

👎Deprecated since 0.23.0: IntoPy is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Performs the conversion.

impl<'py, T> IntoPyObject<'py> for &Cell<T>

where T: Copy + IntoPyObject<'py>,

type Target = <T as IntoPyObject<'py>>::Target

The Python output type

type Output = <T as IntoPyObject<'py>>::Output

The smart pointer type to use.

type Error = <T as IntoPyObject<'py>>::Error

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<&Cell<T> as IntoPyObject<'py>>::Output, <&Cell<T> as IntoPyObject<'py>>::Error>

Performs the conversion.

impl<'py, T> IntoPyObject<'py> for Cell<T>

where T: Copy + IntoPyObject<'py>,

type Target = <T as IntoPyObject<'py>>::Target

The Python output type

type Output = <T as IntoPyObject<'py>>::Output

The smart pointer type to use.

type Error = <T as IntoPyObject<'py>>::Error

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Cell<T> as IntoPyObject<'py>>::Output, <Cell<T> as IntoPyObject<'py>>::Error>

Performs the conversion.

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<'a, T, U> Restructure<U> for &'a Cell<T>

where U: 'a + ?Sized, T: ?Sized,

type Restructured = &'a Cell<U>

The restructured version of this type.

unsafe fn restructure( &self, ptr: *mut U, ) -> <&'a Cell<T> as Restructure<U>>::Restructured

Restructures a pointer to this type into the target type.

impl<'a, T, U> Restructure<U> for &'a mut Cell<T>

where U: 'a + ?Sized, T: ?Sized,

type Restructured = &'a mut Cell<U>

The restructured version of this type.

unsafe fn restructure( &self, ptr: *mut U, ) -> <&'a mut Cell<T> as Restructure<U>>::Restructured

Restructures a pointer to this type into the target type.

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

type Restructured = Cell<U>

The restructured version of this type.

unsafe fn restructure( &self, ptr: *mut U, ) -> <Cell<T> as Restructure<U>>::Restructured

Restructures a pointer to this type into the target type.

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<F, S> SerializeWith<Cell<F>, S> for Unsafe

where F: Serialize<S>, S: Fallible + ?Sized,

fn serialize_with( field: &Cell<F>, serializer: &mut S, ) -> Result<<Unsafe as ArchiveWith<Cell<F>>>::Resolver, <S as Fallible>::Error>

Serializes the field type F using the given serializer.

impl<T> ToPyObject for Cell<T>

where T: Copy + ToPyObject,

fn to_object(&self, py: Python<'_>) -> Py<PyAny>

👎Deprecated since 0.23.0: ToPyObject is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Converts self into a Python object.

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,