# 1.0.0[−][src]Struct std::rc::Rc

    #[lang = "rc"]
    pub struct Rc<T> where
        T: ?Sized,  { /* fields omitted */ }

A single-threaded reference-counting pointer. 'Rc' stands for 'Reference Counted'.

See the module-level documentation for more details.

The inherent methods of `Rc` are all associated functions, which means that you have to call them as e.g., `Rc::get_mut(&mut value)` instead of `value.get_mut()`. This avoids conflicts with methods of the inner type `T`.

## Methods

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

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

Constructs a new `Rc<T>`.

# Examples

    use std::rc::Rc;

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

####
ⓘImportant traits for Pin<P>

### Important traits for Pin<P>

`impl<P> Future for Pin<P> where
P: Unpin + DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;`
`pub fn pin(value: T) -> Pin<Rc<T>>`1.33.0[src]

Constructs a new `Pin<Rc<T>>`. If `T` does not implement `Unpin`, then `value` will be pinned in memory and unable to be moved.

#### `pub fn try_unwrap(this: Rc<T>) -> Result<T, Rc<T>>`1.4.0[src]

Returns the contained value, if the `Rc` has exactly one strong reference.

Otherwise, an `Err` is returned with the same `Rc` that was passed in.

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 = Rc::clone(&x);
    assert_eq!(*Rc::try_unwrap(x).unwrap_err(), 4);Run

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

#### `pub fn into_raw(this: Rc<T>) -> *const T` 1.17.0[src]

Consumes the `Rc`, returning the wrapped pointer.

To avoid a memory leak the pointer must be converted back to an `Rc` using `Rc::from_raw`.

# Examples

    use std::rc::Rc;

    let x = Rc::new("hello".to_owned());
    let x_ptr = Rc::into_raw(x);
    assert_eq!(unsafe { &*x_ptr }, "hello");Run

#### `pub unsafe fn from_raw(ptr: *const T) -> Rc<T>`1.17.0[src]

Constructs an `Rc` from a raw pointer.

The raw pointer must have been previously returned by a call to a `Rc::into_raw`.

This function is unsafe because improper use may lead to memory problems. For example, a double-free may occur if the function is called twice on the same raw pointer.

# Examples

    use std::rc::Rc;

    let x = Rc::new("hello".to_owned());
    let x_ptr = Rc::into_raw(x);

    unsafe {
        // Convert back to an `Rc` to prevent leak.
        let x = Rc::from_raw(x_ptr);
        assert_eq!(&*x, "hello");

        // Further calls to `Rc::from_raw(x_ptr)` would be memory unsafe.
    }

    // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Run

#### `pub fn into_raw_non_null(this: Rc<T>) -> NonNull<T>`[src]

🔬 This is a nightly-only experimental API. (`rc_into_raw_non_null` #47336)

Consumes the `Rc`, returning the wrapped pointer as `NonNull<T>`.

# Examples

    #![feature(rc_into_raw_non_null)]

    use std::rc::Rc;

    let x = Rc::new("hello".to_owned());
    let ptr = Rc::into_raw_non_null(x);
    let deref = unsafe { ptr.as_ref() };
    assert_eq!(deref, "hello");Run

#### `pub fn downgrade(this: &Rc<T>) -> Weak<T>`1.4.0[src]

Creates a new `Weak` pointer to this value.

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

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

#### `pub fn weak_count(this: &Rc<T>) -> usize` 1.15.0[src]

Gets the number of `Weak` pointers to this value.

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);
    let _weak_five = Rc::downgrade(&five);

    assert_eq!(1, Rc::weak_count(&five));Run

#### `pub fn strong_count(this: &Rc<T>) -> usize` 1.15.0[src]

Gets the number of strong (`Rc`) pointers to this value.

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);
    let _also_five = Rc::clone(&five);

    assert_eq!(2, Rc::strong_count(&five));Run

#### `pub fn get_mut(this: &mut Rc<T>) -> Option<&mut T>`1.4.0[src]

Returns a mutable reference to the inner value, if there are no other `Rc` or `Weak` pointers to the same value.

Returns `None` otherwise, because it is not safe to mutate a shared value.

See also `make_mut`, which will `clone` the inner value when it's shared.

# Examples

    use std::rc::Rc;

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

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

#### `pub fn ptr_eq(this: &Rc<T>, other: &Rc<T>) -> bool` 1.17.0[src]

Returns `true` if the two `Rc`s point to the same value (not just values that compare as equal).

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);
    let same_five = Rc::clone(&five);
    let other_five = Rc::new(5);

    assert!(Rc::ptr_eq(&five, &same_five));
    assert!(!Rc::ptr_eq(&five, &other_five));Run

### `impl<T> Rc<T> where
T: Clone,` [src]

####
ⓘImportant traits for &'_ mut F

### Important traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`pub fn make_mut(this: &mut Rc<T>) -> &mut T` 1.4.0[src]

Makes a mutable reference into the given `Rc`.

If there are other `Rc` pointers to the same value, then `make_mut` will `clone` the inner value to ensure unique ownership. This is also referred to as clone-on-write.

If there are no other `Rc` pointers to this value, then `Weak` pointers to this value will be dissassociated.

See also `get_mut`, which will fail rather than cloning.

# 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 = Rc::clone(&data);    // 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

    // Now `data` and `other_data` point to different values.
    assert_eq!(*data, 8);
    assert_eq!(*other_data, 12);Run

`Weak` pointers will be dissassociated:

    use std::rc::Rc;

    let mut data = Rc::new(75);
    let weak = Rc::downgrade(&data);

    assert!(75 == *data);
    assert!(75 == *weak.upgrade().unwrap());

    *Rc::make_mut(&mut data) += 1;

    assert!(76 == *data);
    assert!(weak.upgrade().is_none());Run

### `impl Rc<dyn Any + 'static>`[src]

#### `pub fn downcast<T>(self) -> Result<Rc<T>, Rc<dyn Any + 'static>> where
T: Any,` 1.29.0[src]

Attempt to downcast the `Rc<dyn Any>` to a concrete type.

# Examples

    use std::any::Any;
    use std::rc::Rc;

    fn print_if_string(value: Rc<dyn Any>) {
        if let Ok(string) = value.downcast::<String>() {
            println!("String ({}): {}", string.len(), string);
        }
    }

    fn main() {
        let my_string = "Hello World".to_string();
        print_if_string(Rc::new(my_string));
        print_if_string(Rc::new(0i8));
    }Run

## Trait Implementations

### `impl<T> Display for Rc<T> where
T: Display + ?Sized,` [src]

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

Formats the value using the given formatter. Read more

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

### `impl<T, U> DispatchFromDyn<Rc<U>> for Rc<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,` [src]

### `impl<T> AsRef<T> for Rc<T> where
T: ?Sized,` 1.5.0[src]

####
ⓘImportant traits for &'_ mut F

### Important traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`fn as_ref(&self) -> &T`[src]

Performs the conversion.

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

### `impl<T> Hash for Rc<T> where
T: Hash + ?Sized,` [src]

#### `fn hash<H>(&self, state: &mut H) where
H: Hasher,` [src]

Feeds this value into the given [`Hasher`]. Read more

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

Feeds a slice of this type into the given [`Hasher`]. Read more

### `impl<T> From<Vec<T>> for Rc<[T]>`1.21.0[src]

#### `fn from(v: Vec<T>) -> Rc<[T]>`[src]

Performs the conversion.

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

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

Performs the conversion.

### `impl<T> From<Box<T>> for Rc<T> where
T: ?Sized,` 1.21.0[src]

#### `fn from(v: Box<T>) -> Rc<T>`[src]

Performs the conversion.

### `impl<'_> From<&'_ str> for Rc<str>`1.21.0[src]

#### `fn from(v: &str) -> Rc<str>`[src]

Performs the conversion.

### `impl<'_, T> From<&'_ [T]> for Rc<[T]> where
T: Clone,` 1.21.0[src]

#### `fn from(v: &[T]) -> Rc<[T]>`[src]

Performs the conversion.

### `impl From<String> for Rc<str>`1.21.0[src]

#### `fn from(v: String) -> Rc<str>`[src]

Performs the conversion.

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

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

Formats the value using the given formatter. Read more

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

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

Comparison for two `Rc`s.

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

# Examples

    use std::rc::Rc;
    use std::cmp::Ordering;

    let five = Rc::new(5);

    assert_eq!(Ordering::Less, five.cmp(&Rc::new(6)));Run

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

Compares and returns the maximum of two values. Read more

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

Compares and returns the minimum of two values. Read more

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

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

Restrict a value to a certain interval. Read more

### `impl<T, U> CoerceUnsized<Rc<U>> for Rc<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,` [src]

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

#### `fn drop(&mut self)`[src]

Drops the `Rc`.

This will decrement the strong reference count. If the strong reference count reaches zero then the only other references (if any) are `Weak`, so we `drop` the inner value.

# Examples

    use std::rc::Rc;

    struct Foo;

    impl Drop for Foo {
        fn drop(&mut self) {
            println!("dropped!");
        }
    }

    let foo  = Rc::new(Foo);
    let foo2 = Rc::clone(&foo);

    drop(foo);    // Doesn't print anything
    drop(foo2);   // Prints "dropped!"Run

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

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

Equality for two `Rc`s.

Two `Rc`s are equal if their inner values are equal.

If `T` also implements `Eq`, two `Rc`s that point to the same value are always equal.

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    assert!(five == Rc::new(5));Run

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

Inequality for two `Rc`s.

Two `Rc`s are unequal if their inner values are unequal.

If `T` also implements `Eq`, two `Rc`s that point to the same value are never unequal.

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    assert!(five != Rc::new(6));Run

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

#### `type Target = T`

The resulting type after dereferencing.

####
ⓘImportant traits for &'_ mut F

### Important traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

Dereferences the value.

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

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

Makes a clone of the `Rc` pointer.

This creates another pointer to the same inner value, increasing the strong reference count.

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    let _ = Rc::clone(&five);Run

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

Performs copy-assignment from `source`. Read more

### `impl<T> Unpin for Rc<T> where
T: ?Sized,` 1.33.0[src]

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

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

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

# Examples

    use std::rc::Rc;

    let x: Rc<i32> = Default::default();
    assert_eq!(*x, 0);Run

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

####
ⓘImportant traits for &'_ mut F

### Important traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

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

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

Formats the value using the given formatter.

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

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

Partial comparison for two `Rc`s.

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

# Examples

    use std::rc::Rc;
    use std::cmp::Ordering;

    let five = Rc::new(5);

    assert_eq!(Some(Ordering::Less), five.partial_cmp(&Rc::new(6)));Run

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

Less-than comparison for two `Rc`s.

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

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    assert!(five < Rc::new(6));Run

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

'Less than or equal to' comparison for two `Rc`s.

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

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    assert!(five <= Rc::new(5));Run

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

Greater-than comparison for two `Rc`s.

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

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    assert!(five > Rc::new(4));Run

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

'Greater than or equal to' comparison for two `Rc`s.

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

# Examples

    use std::rc::Rc;

    let five = Rc::new(5);

    assert!(five >= Rc::new(5));Run

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

### `impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Rc<T>`1.9.0[src]

### `impl From<CString> for Rc<CStr>`1.24.0[src]

#### `fn from(s: CString) -> Rc<CStr>`[src]

Converts a `CString` into a `Rc``<CStr>` without copying or allocating.

### `impl<'_> From<&'_ CStr> for Rc<CStr>`1.24.0[src]

#### `fn from(s: &CStr) -> Rc<CStr>`[src]

Performs the conversion.

### `impl From<OsString> for Rc<OsStr>`1.24.0[src]

#### `fn from(s: OsString) -> Rc<OsStr>`[src]

Converts a `OsString` into a `Rc``<OsStr>` without copying or allocating.

### `impl<'_> From<&'_ OsStr> for Rc<OsStr>`1.24.0[src]

#### `fn from(s: &OsStr) -> Rc<OsStr>`[src]

Performs the conversion.

### `impl From<PathBuf> for Rc<Path>`1.24.0[src]

#### `fn from(s: PathBuf) -> Rc<Path>`[src]

Converts a Path into a Rc by copying the Path data into a new Rc buffer.

### `impl<'_> From<&'_ Path> for Rc<Path>`1.24.0[src]

#### `fn from(s: &Path) -> Rc<Path>`[src]

Converts a Path into a Rc by copying the Path data into a new Rc buffer.

## Auto Trait Implementations

### `impl<T> !RefUnwindSafe for Rc<T>`

## Blanket Implementations

### `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(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[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> From<T> for T`[src]

#### `fn from(t: T) -> T`[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.

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

####
ⓘImportant traits for &'_ mut F

### Important traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

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

####
ⓘImportant traits for &'_ mut F

### Important traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, R: Read + ?Sized> Read for &'_ mut Rimpl<'_, W: Write + ?Sized> Write for &'_ mut W`
`fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `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> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

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

Creates owned data from borrowed data, usually by cloning. Read more

#### `fn clone_into(&self, target: &mut T)`[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into` #41263)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T> ToString for T where
T: Display + ?Sized,` [src]

#### `default fn to_string(&self) -> String`[src]

Converts the given value to a `String`. Read more

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse 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`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)