core::cell::RefCell - Rust
Description: API documentation for the Rust `RefCell` struct in crate `core`.
Keywords: rust, rustlang, rust-lang, RefCell

# 1.0.0[−][src]Struct core::cell::RefCell

    pub struct RefCell<T: ?Sized> { /* fields omitted */ }

A mutable memory location with dynamically checked borrow rules

See the module-level documentation for more.

## Implementations

### `impl<T> RefCell<T>`[src]

#### `pub const fn new(value: T) -> RefCell<T>`[src]

Creates a new `RefCell` containing `value`.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

Run

#### `pub fn into_inner(self) -> T`[src]

Consumes the `RefCell`, returning the wrapped value.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    let five = c.into_inner();

Run

#### `pub fn replace(&self, t: T) -> T`1.24.0[src]

Replaces the wrapped value with a new one, returning the old value, without deinitializing either one.

This function corresponds to `std::mem::replace`.

# Panics

Panics if the value is currently borrowed.

# Examples

    use std::cell::RefCell;
    let cell = RefCell::new(5);
    let old_value = cell.replace(6);
    assert_eq!(old_value, 5);
    assert_eq!(cell, RefCell::new(6));

Run

#### `pub fn replace_with<F: FnOnce(&mut T) -> T>(&self, f: F) -> T`1.35.0[src]

Replaces the wrapped value with a new one computed from `f`, returning the old value, without deinitializing either one.

# Panics

Panics if the value is currently borrowed.

# Examples

    use std::cell::RefCell;
    let cell = RefCell::new(5);
    let old_value = cell.replace_with(|&mut old| old + 1);
    assert_eq!(old_value, 5);
    assert_eq!(cell, RefCell::new(6));

Run

#### `pub fn swap(&self, other: &Self)`1.24.0[src]

Swaps the wrapped value of `self` with the wrapped value of `other`, without deinitializing either one.

This function corresponds to `std::mem::swap`.

# Panics

Panics if the value in either `RefCell` is currently borrowed.

# Examples

    use std::cell::RefCell;
    let c = RefCell::new(5);
    let d = RefCell::new(6);
    c.swap(&d);
    assert_eq!(c, RefCell::new(6));
    assert_eq!(d, RefCell::new(5));

Run

### `impl<T: ?Sized> RefCell<T>`[src]

#### `pub fn borrow(&self) -> Ref<T>`[src]

Immutably borrows the wrapped value.

The borrow lasts until the returned `Ref` exits scope. Multiple immutable borrows can be taken out at the same time.

# Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use `try_borrow`.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    let borrowed_five = c.borrow();
    let borrowed_five2 = c.borrow();

Run

An example of panic:

ⓘThis example panics

    use std::cell::RefCell;

    let c = RefCell::new(5);

    let m = c.borrow_mut();
    let b = c.borrow(); // this causes a panic

Run

#### `pub fn try_borrow(&self) -> Result<Ref<T>, BorrowError>`1.13.0[src]

Immutably borrows the wrapped value, returning an error if the value is currently mutably borrowed.

The borrow lasts until the returned `Ref` exits scope. Multiple immutable borrows can be taken out at the same time.

This is the non-panicking variant of `borrow`.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    {
        let m = c.borrow_mut();
        assert!(c.try_borrow().is_err());
    }

    {
        let m = c.borrow();
        assert!(c.try_borrow().is_ok());
    }

Run

#### `pub fn borrow_mut(&self) -> RefMut<T>`[src]

Mutably borrows the wrapped value.

The borrow lasts until the returned `RefMut` or all `RefMut`s derived from it exit scope. The value cannot be borrowed while this borrow is active.

# Panics

Panics if the value is currently borrowed. For a non-panicking variant, use `try_borrow_mut`.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new("hello".to_owned());

    *c.borrow_mut() = "bonjour".to_owned();

    assert_eq!(&*c.borrow(), "bonjour");

Run

An example of panic:

ⓘThis example panics

    use std::cell::RefCell;

    let c = RefCell::new(5);
    let m = c.borrow();

    let b = c.borrow_mut(); // this causes a panic

Run

#### `pub fn try_borrow_mut(&self) -> Result<RefMut<T>, BorrowMutError>`1.13.0[src]

Mutably borrows the wrapped value, returning an error if the value is currently borrowed.

The borrow lasts until the returned `RefMut` or all `RefMut`s derived from it exit scope. The value cannot be borrowed while this borrow is active.

This is the non-panicking variant of `borrow_mut`.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    {
        let m = c.borrow();
        assert!(c.try_borrow_mut().is_err());
    }

    assert!(c.try_borrow_mut().is_ok());

Run

#### `pub fn as_ptr(&self) -> *mut T`1.12.0[src]

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

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    let ptr = c.as_ptr();

Run

#### `pub fn get_mut(&mut self) -> &mut T`1.11.0[src]

Returns a mutable reference to the underlying data.

This call borrows `RefCell` mutably (at compile-time) so there is no need for dynamic checks.

However be cautious: this method expects `self` to be mutable, which is generally not the case when using a `RefCell`. Take a look at the `borrow_mut` method instead if `self` isn't mutable.

Also, please be aware that this method is only for special circumstances and is usually not what you want. In case of doubt, use `borrow_mut` instead.

# Examples

    use std::cell::RefCell;

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

    assert_eq!(c, RefCell::new(6));

Run

#### `pub fn undo_leak(&mut self) -> &mut T`[src]

🔬 This is a nightly-only experimental API. (`cell_leak` #69099)

Undo the effect of leaked guards on the borrow state of the `RefCell`.

This call is similar to `get_mut` but more specialized. It borrows `RefCell` mutably to ensure no borrows exist and then resets the state tracking shared borrows. This is relevant if some `Ref` or `RefMut` borrows have been leaked.

# Examples

    #![feature(cell_leak)]
    use std::cell::RefCell;

    let mut c = RefCell::new(0);
    std::mem::forget(c.borrow_mut());

    assert!(c.try_borrow().is_err());
    c.undo_leak();
    assert!(c.try_borrow().is_ok());

Run

#### `pub unsafe fn try_borrow_unguarded(&self) -> Result<&T, BorrowError>`1.37.0[src]

Immutably borrows the wrapped value, returning an error if the value is currently mutably borrowed.

# Safety

Unlike `RefCell::borrow`, this method is unsafe because it does not return a `Ref`, thus leaving the borrow flag untouched. Mutably borrowing the `RefCell` while the reference returned by this method is alive is undefined behaviour.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    {
        let m = c.borrow_mut();
        assert!(unsafe { c.try_borrow_unguarded() }.is_err());
    }

    {
        let m = c.borrow();
        assert!(unsafe { c.try_borrow_unguarded() }.is_ok());
    }

Run

### `impl<T: Default> RefCell<T>`[src]

#### `pub fn take(&self) -> T`[src]

🔬 This is a nightly-only experimental API. (`refcell_take` #71395)

Takes the wrapped value, leaving `Default::default()` in its place.

# Panics

Panics if the value is currently borrowed.

# Examples

    #![feature(refcell_take)]
    use std::cell::RefCell;

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

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

Run

## Trait Implementations

### `impl<T: Clone> Clone for RefCell<T>`[src]

#### `fn clone(&self) -> RefCell<T>`[src]

# Panics

Panics if the value is currently mutably borrowed.

#### `fn clone_from(&mut self, source: &Self)`[src]

Performs copy-assignment from `source`. Read more

### `impl<T: CoerceUnsized<U>, U> CoerceUnsized<RefCell<U>> for RefCell<T>`[src]

### `impl<T: ?Sized + Debug> Debug for RefCell<T>`[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl<T: Default> Default for RefCell<T>`[src]

#### `fn default() -> RefCell<T>`[src]

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

### `impl<T: ?Sized + Eq> Eq for RefCell<T>`1.2.0[src]

### `impl<T> From<T> for RefCell<T>`1.12.0[src]

#### `fn from(t: T) -> RefCell<T>`[src]

Performs the conversion.

### `impl<T: ?Sized + Ord> Ord for RefCell<T>`1.10.0[src]

#### `fn cmp(&self, other: &RefCell<T>) -> Ordering`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

#### `#[must_use]fn max(self, other: Self) -> Self where
Self: Sized,` 1.21.0[src]

Compares and returns the maximum of two values. Read more

#### `#[must_use]fn min(self, other: Self) -> Self where
Self: Sized,` 1.21.0[src]

Compares and returns the minimum of two values. Read more

#### `#[must_use]fn clamp(self, min: Self, max: Self) -> Self where
Self: Sized,` [src]

🔬 This is a nightly-only experimental API. (`clamp` #44095)

Restrict a value to a certain interval. Read more

### `impl<T: ?Sized + PartialEq> PartialEq<RefCell<T>> for RefCell<T>`[src]

#### `fn eq(&self, other: &RefCell<T>) -> bool`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

#### `#[must_use]fn ne(&self, other: &Rhs) -> bool`[src]

This method tests for `!=`.

### `impl<T: ?Sized + PartialOrd> PartialOrd<RefCell<T>> for RefCell<T>`1.10.0[src]

#### `fn partial_cmp(&self, other: &RefCell<T>) -> Option<Ordering>`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

#### `fn lt(&self, other: &RefCell<T>) -> bool`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

#### `fn le(&self, other: &RefCell<T>) -> bool`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

#### `fn gt(&self, other: &RefCell<T>) -> bool`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

#### `fn ge(&self, other: &RefCell<T>) -> bool`[src]

# Panics

Panics if the value in either `RefCell` is currently borrowed.

### `impl<T: ?Sized> Send for RefCell<T> where
T: Send,` [src]

### `impl<T: ?Sized> !Sync for RefCell<T>`[src]

## Auto Trait Implementations

### `impl<T: ?Sized> Unpin for RefCell<T> where
T: Unpin,`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&Self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&Self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut Self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<!> for T`[src]

#### `fn from(!) -> T`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `fn from(T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(Self) -> U`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(Self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.