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

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

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

A mutable memory location with dynamically checked borrow rules

See the module-level documentation for more.

## Methods

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

#### `fn new(value: T) -> RefCell<T>`

Creates a new `RefCell` containing `value`.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);Run

#### `fn into_inner(self) -> T`

Consumes the `RefCell`, returning the wrapped value.

# Examples

    use std::cell::RefCell;

    let c = RefCell::new(5);

    let five = c.into_inner();Run

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

#### `fn borrow_state(&self) -> BorrowState`

Deprecated since 1.15.0

: use `try_borrow` instead

Unstable (`borrow_state` #27733)

Query the current state of this `RefCell`

The returned value can be dispatched on to determine if a call to `borrow` or `borrow_mut` would succeed.

# Examples

    #![feature(borrow_state)]

    use std::cell::{BorrowState, RefCell};

    let c = RefCell::new(5);

    match c.borrow_state() {
        BorrowState::Writing => println!("Cannot be borrowed"),
        BorrowState::Reading => println!("Cannot be borrowed mutably"),
        BorrowState::Unused => println!("Can be borrowed (mutably as well)"),
    }Run

#### `fn borrow(&self) -> Ref<T>`

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:

    use std::cell::RefCell;
    use std::thread;

    let result = thread::spawn(move || {
       let c = RefCell::new(5);
       let m = c.borrow_mut();

       let b = c.borrow(); // this causes a panic
    }).join();

    assert!(result.is_err());Run

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

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

#### `fn borrow_mut(&self) -> RefMut<T>`

Mutably borrows the wrapped value.

The borrow lasts until the returned `RefMut` exits 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(5);

    *c.borrow_mut() = 7;

    assert_eq!(*c.borrow(), 7);Run

An example of panic:

    use std::cell::RefCell;
    use std::thread;

    let result = thread::spawn(move || {
       let c = RefCell::new(5);
       let m = c.borrow();

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

    assert!(result.is_err());Run

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

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

The borrow lasts until the returned `RefMut` exits 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

#### `unsafe fn as_unsafe_cell(&self) -> &UnsafeCell<T>`

Deprecated since 1.12.0

: renamed to as_ptr

Unstable (`as_unsafe_cell` #27708)

Returns a reference to the underlying `UnsafeCell`.

This can be used to circumvent `RefCell`'s safety checks.

This function is `unsafe` because `UnsafeCell`'s field is public.

# Examples

    #![feature(as_unsafe_cell)]

    use std::cell::RefCell;

    let c = RefCell::new(5);
    let c = unsafe { c.as_unsafe_cell() };Run

#### `fn as_ptr(&self) -> *mut T`
1.12.0

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

#### `fn get_mut(&mut self) -> &mut T`
1.11.0

Returns a mutable reference to the underlying data.

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

# Examples

    use std::cell::RefCell;

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

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

## Trait Implementations

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

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

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

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

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

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

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

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

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

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

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

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

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

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

This method returns an `Ordering` between `self` and `other`. Read more

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

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

Performs the conversion.

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

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

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

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

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

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

Returns a copy of the value. Read more

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

Performs copy-assignment from `source`. Read more

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

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

Formats the value using the given formatter.

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

#### `fn default() -> RefCell<T>`

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

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

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)