Struct alloc::rc::Rc

pub struct Rc<T: ?Sized> {
    // some fields omitted
}

A reference-counted pointer type over an immutable value.

See the module level documentation for more details.

Note: the inherent methods defined on Rc<T> are all associated functions, which means that you have to call them as e.g. Rc::get_mut(&value) instead of value.get_mut(). This is so that there are no conflicts with methods on the inner type T, which are what you want to call in the majority of cases.

Methods

impl<T> Rc<T>

fn new(value: T) -> Rc<T>

Constructs a new Rc<T>.

Examples

use std::rc::Rc;

let five = Rc::new(5);

fn try_unwrap(this: Self) -> Result<T, Self>

Unwraps the contained value if the Rc<T> has exactly one strong reference.

Otherwise, an Err is returned with the same Rc<T>.

This will succeed even if there are outstanding weak references.

Examples

use std::rc::Rc;

let x = Rc::new(3);
assert_eq!(Rc::try_unwrap(x), Ok(3));

let x = Rc::new(4);
let _y = x.clone();
assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4)));

fn would_unwrap(this: &Self) -> bool

Unstable (rc_would_unwrap #28356)

: just added for niche usecase

Checks if Rc::try_unwrap would return Ok.

Examples

#![feature(rc_would_unwrap)]

use std::rc::Rc;

let x = Rc::new(3);
assert!(Rc::would_unwrap(&x));
assert_eq!(Rc::try_unwrap(x), Ok(3));

let x = Rc::new(4);
let _y = x.clone();
assert!(!Rc::would_unwrap(&x));
assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4)));

impl<T: ?Sized> Rc<T>

fn downgrade(this: &Self) -> Weak<T>

Creates a new Weak<T> reference from this value.

Examples

use std::rc::Rc;

let five = Rc::new(5);

let weak_five = Rc::downgrade(&five);

fn weak_count(this: &Self) -> usize

Unstable (rc_counts #28356)

: not clearly useful

Get the number of weak references to this value.

fn strong_count(this: &Self) -> usize

Unstable (rc_counts #28356)

: not clearly useful

Get the number of strong references to this value.

fn is_unique(this: &Self) -> bool

Unstable (rc_counts #28356)

: uniqueness has unclear meaning

Returns true if there are no other Rc or Weak<T> values that share the same inner value.

Examples

#![feature(rc_counts)]

use std::rc::Rc;

let five = Rc::new(5);

assert!(Rc::is_unique(&five));

fn get_mut(this: &mut Self) -> Option<&mut T>

Returns a mutable reference to the contained value if the Rc<T> has one strong reference and no weak references.

Returns None if the Rc<T> is not unique.

Examples

use std::rc::Rc;

let mut x = Rc::new(3);
*Rc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = x.clone();
assert!(Rc::get_mut(&mut x).is_none());

impl<T: Clone> Rc<T>

fn make_mut(this: &mut Self) -> &mut T

Make a mutable reference into the given Rc<T> by cloning the inner data if the Rc<T> doesn't have one strong reference and no weak references.

This is also referred to as a copy-on-write.

Examples

use std::rc::Rc;

let mut data = Rc::new(5);

*Rc::make_mut(&mut data) += 1;             // Won't clone anything
let mut other_data = data.clone(); // Won't clone inner data
*Rc::make_mut(&mut data) += 1;             // Clones inner data
*Rc::make_mut(&mut data) += 1;             // Won't clone anything
*Rc::make_mut(&mut other_data) *= 2;       // Won't clone anything

// Note: data and other_data now point to different numbers
assert_eq!(*data, 8);
assert_eq!(*other_data, 12);

Trait Implementations

impl<T: ?Sized> !Send for Rc<T>

impl<T: ?Sized> !Sync for Rc<T>

impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Rc<U>> for Rc<T>

impl<T: ?Sized> Deref for Rc<T>

type Target = T

The resulting type after dereferencing

fn deref(&self) -> &T

The method called to dereference a value

impl<T: ?Sized> Drop for Rc<T>

fn drop(&mut self)

Drops the Rc<T>.

This will decrement the strong reference count. If the strong reference count becomes zero and the only other references are Weak<T> ones, drops the inner value.

Examples

use std::rc::Rc;

{
    let five = Rc::new(5);

    // stuff

    drop(five); // explicit drop
}
{
    let five = Rc::new(5);

    // stuff

} // implicit drop

impl<T: ?Sized> Clone for Rc<T>

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

Makes a clone of the Rc<T>.

When you clone an Rc<T>, it will create another pointer to the data and increase the strong reference counter.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five.clone();

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

Performs copy-assignment from source.

impl<T: Default> Default for Rc<T>

fn default() -> Rc<T>

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

Examples

use std::rc::Rc;

let x: Rc<i32> = Default::default();

impl<T: ?Sized + PartialEq> PartialEq for Rc<T>

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

Equality for two Rc<T>s.

Two Rc<T>s are equal if their inner value are equal.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five == Rc::new(5);

fn ne(&self, other: &Rc<T>) -> bool

Inequality for two Rc<T>s.

Two Rc<T>s are unequal if their inner value are unequal.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five != Rc::new(5);

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

impl<T: ?Sized + PartialOrd> PartialOrd for Rc<T>

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

Partial comparison for two Rc<T>s.

The two are compared by calling partial_cmp() on their inner values.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five.partial_cmp(&Rc::new(5));

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

Less-than comparison for two Rc<T>s.

The two are compared by calling < on their inner values.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five < Rc::new(5);

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

'Less-than or equal to' comparison for two Rc<T>s.

The two are compared by calling <= on their inner values.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five <= Rc::new(5);

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

Greater-than comparison for two Rc<T>s.

The two are compared by calling > on their inner values.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five > Rc::new(5);

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

'Greater-than or equal to' comparison for two Rc<T>s.

The two are compared by calling >= on their inner values.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five >= Rc::new(5);

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

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

Comparison for two Rc<T>s.

The two are compared by calling cmp() on their inner values.

Examples

use std::rc::Rc;

let five = Rc::new(5);

five.partial_cmp(&Rc::new(5));

impl<T: ?Sized + Hash> Hash for Rc<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the state given, updating the hasher as necessary.

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher

Feeds a slice of this type into the state provided.

impl<T: ?Sized + Display> Display for Rc<T>

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

Formats the value using the given formatter.

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

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

Formats the value using the given formatter.

impl<T: ?Sized> Pointer for Rc<T>

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

Formats the value using the given formatter.

impl<T> From<T> for Rc<T>

fn from(t: T) -> Self

Performs the conversion.

impl<T: ?Sized> Borrow<T> for Rc<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized> AsRef<T> for Rc<T>

fn as_ref(&self) -> &T

Performs the conversion.