Struct UncheckedRefCell 

pub struct UncheckedRefCell<T: ?Sized> { /* private fields */ }

A mutable memory location with dynamically checked borrow rules.

UncheckedRefCell behaves exactly like std::cell::RefCell when debug_assertions is enabled (debug builds). For release-like builds, UncheckedRefCell does not perform any borrow checking. Thus it is faster than RefCell (see benchmarks), but may lead to undefined behavior instead of panicking like RefCell. Only use this over RefCell for performance critical code where it is known a RefCell would never panic.

Enabling the checked feature flag (disabled by default) forces borrow checking in release builds too. This is only intended for use with debugging.

Implementations

impl<T> UncheckedRefCell<T>

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

Creates a new RefCell containing value.

Examples

use unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

pub fn into_inner(self) -> T

Consumes the RefCell, returning the wrapped value.

Examples

use unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

let five = c.into_inner();

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

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 unchecked_refcell::UncheckedRefCell;
let cell = UncheckedRefCell::new(5);
let old_value = cell.replace(6);
assert_eq!(old_value, 5);
assert_eq!(cell, UncheckedRefCell::new(6));

pub fn replace_with<F: FnOnce(&mut T) -> T>(&self, f: F) -> T

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 unchecked_refcell::UncheckedRefCell;
let cell = UncheckedRefCell::new(5);
let old_value = cell.replace_with(|&mut old| old + 1);
assert_eq!(old_value, 5);
assert_eq!(cell, UncheckedRefCell::new(6));

pub fn swap(&self, other: &Self)

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, or if self and other point to the same RefCell.

Examples

use unchecked_refcell::UncheckedRefCell;
let c = UncheckedRefCell::new(5);
let d = UncheckedRefCell::new(6);
c.swap(&d);
assert_eq!(c, UncheckedRefCell::new(6));
assert_eq!(d, UncheckedRefCell::new(5));

impl<T: ?Sized> UncheckedRefCell<T>

pub fn borrow(&self) -> UncheckedRef<'_, T>

Immutably borrows the wrapped value.

The borrow lasts until the returned UncheckedRef 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 unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

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

An example of panic:

use unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

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

pub fn try_borrow(&self) -> Result<UncheckedRef<'_, T>, BorrowError>

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

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

This is the non-panicking variant of borrow.

Examples

use unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

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

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

pub fn borrow_mut(&self) -> UncheckedRefMut<'_, T>

Mutably borrows the wrapped value.

The borrow lasts until the returned UncheckedRefMut or all UncheckedRefMuts 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 unchecked_refcell::UncheckedRefCell;

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

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

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

An example of panic:

use unchecked_refcell::UncheckedRefCell;

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

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

pub fn try_borrow_mut(&self) -> Result<UncheckedRefMut<'_, T>, BorrowMutError>

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

The borrow lasts until the returned UncheckedRefMut or all UncheckedRefMuts 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 unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

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

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

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

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

Examples

use unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::new(5);

let ptr = c.as_ptr();

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

Returns a mutable reference to the underlying data.

Since this method borrows RefCell mutably, it is statically guaranteed that no borrows to the underlying data exist. The dynamic checks inherent in borrow_mut and most other methods of RefCell are therefore unnecessary. Note that this method does not reset the borrowing state if borrows were previously leaked (e.g., via forget() on a UncheckedRef or UncheckedRefMut). For that purpose, consider using the unstable undo_leak method.

This method can only be called if RefCell can be mutably borrowed, which in general is only the case directly after the RefCell has been created. In these situations, skipping the aforementioned dynamic borrowing checks may yield better ergonomics and runtime-performance.

In most situations where RefCell is used, it can’t be borrowed mutably. Use borrow_mut to get mutable access to the underlying data then.

Examples

use unchecked_refcell::UncheckedRefCell;

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

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

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

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 UncheckedRef or UncheckedRefMut borrows have been leaked.

Examples

use unchecked_refcell::UncheckedRefCell;

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

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

pub const unsafe fn try_borrow_unguarded(&self) -> Result<&T, BorrowError>

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 UncheckedRef, thus leaving the borrow flag untouched. Mutably borrowing the RefCell while the reference returned by this method is alive is undefined behavior.

Examples

use unchecked_refcell::UncheckedRefCell;

let c = UncheckedRefCell::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());
}

impl<T: Default> UncheckedRefCell<T>

pub fn take(&self) -> T

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

Panics

Panics if the value is currently borrowed.

Examples

use unchecked_refcell::UncheckedRefCell;

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

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

Trait Implementations

impl<T: Clone> Clone for UncheckedRefCell<T>

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

Panics

Panics if the value is currently mutably borrowed.

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

Panics

Panics if source is currently mutably borrowed.

impl<T: ?Sized + Debug> Debug for UncheckedRefCell<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for UncheckedRefCell<T>

fn default() -> UncheckedRefCell<T>

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

impl<T> From<T> for UncheckedRefCell<T>

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

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

impl<T: ?Sized + Ord> Ord for UncheckedRefCell<T>

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

Panics

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

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: ?Sized + PartialEq> PartialEq for UncheckedRefCell<T>

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

Panics

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

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: ?Sized + PartialOrd> PartialOrd for UncheckedRefCell<T>

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

Panics

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

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

Panics

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

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

Panics

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

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

Panics

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

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

Panics

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

impl<T: ?Sized + Eq> Eq for UncheckedRefCell<T>

impl<T> Send for UncheckedRefCell<T>

where T: Send + ?Sized,