# Struct std::rc::UniqueRc

source ·

    pub struct UniqueRc<T> { /* private fields */ }

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)
Expand description

A uniquely owned `Rc`

This represents an `Rc` that is known to be uniquely owned – that is, have exactly one strong reference. Multiple weak pointers can be created, but attempts to upgrade those to strong references will fail unless the `UniqueRc` they point to has been converted into a regular `Rc`.

Because they are uniquely owned, the contents of a `UniqueRc` can be freely mutated. A common use case is to have an object be mutable during its initialization phase but then have it become immutable and converted to a normal `Rc`.

This can be used as a flexible way to create cyclic data structures, as in the example below.

    #![feature(unique_rc_arc)]
    use std::rc::{Rc, Weak, UniqueRc};

    struct Gadget {
        #[allow(dead_code)]
        me: Weak<Gadget>,
    }

    fn create_gadget() -> Option<Rc<Gadget>> {
        let mut rc = UniqueRc::new(Gadget {
            me: Weak::new(),
        });
        rc.me = UniqueRc::downgrade(&rc);
        Some(UniqueRc::into_rc(rc))
    }

    create_gadget().unwrap();

Run

An advantage of using `UniqueRc` over `Rc::new_cyclic` to build cyclic data structures is that `Rc::new_cyclic`’s `data_fn` parameter cannot be async or return a `Result`. As shown in the previous example, `UniqueRc` allows for more flexibility in the construction of cyclic data, including fallible or async constructors.

## Implementations§

source§

### impl<T> UniqueRc<T>

source

#### pub fn new(value: T) -> UniqueRc<T>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

Creates a new `UniqueRc`

Weak references to this `UniqueRc` can be created with `UniqueRc::downgrade`. Upgrading these weak references will fail before the `UniqueRc` has been converted into an `Rc`. After converting the `UniqueRc` into an `Rc`, any weak references created beforehand will point to the new `Rc`.

source

#### pub fn downgrade(this: &UniqueRc<T>) -> Weak<T>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

Creates a new weak reference to the `UniqueRc`

Attempting to upgrade this weak reference will fail before the `UniqueRc` has been converted to a `Rc` using `UniqueRc::into_rc`.

source

#### pub fn into_rc(this: UniqueRc<T>) -> Rc<T>

🔬This is a nightly-only experimental API. (`unique_rc_arc` #112566)

Converts the `UniqueRc` into a regular `Rc`

This consumes the `UniqueRc` and returns a regular `Rc` that contains the `value` that is passed to `into_rc`.

Any weak references created before this method is called can now be upgraded to strong references.

## Trait Implementations§

source§

### impl<T> Debug for UniqueRc<T>where T: Debug,

source§

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

Formats the value using the given formatter. Read more
source§

### impl<T> Deref for UniqueRc<T>

§

#### type Target = T

The resulting type after dereferencing.
source§

#### fn deref(&self) -> &T

Dereferences the value.
source§

### impl<T> DerefMut for UniqueRc<T>

source§

#### fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.
source§

### impl<T> Drop for UniqueRc<T>

source§

#### fn drop(&mut self)

Executes the destructor for this type. Read more

## Auto Trait Implementations§

§

### impl<T> !RefUnwindSafe for UniqueRc<T>

§

### impl<T> !Send for UniqueRc<T>

§

### impl<T> !Sync for UniqueRc<T>

§

### impl<T> Unpin for UniqueRc<T>where T: Unpin,

§

### impl<T> !UnwindSafe for UniqueRc<T>

## Blanket Implementations§

source§

### impl<T> Any for Twhere T: 'static + ?Sized,

source§

#### fn type_id(&self) -> TypeId

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

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

### impl<T, U> Into<U> for Twhere U: From<T>,

source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.