Constructs a newRc<T>.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);

Constructs a newRc<T> while giving you aWeak<T> to the allocation,to allow you to construct aT which holds a weak pointer to itself.

Generally, a structure circularly referencing itself, either directly orindirectly, should not hold a strong reference to itself to prevent a memory leak.Using this function, you get access to the weak pointer during theinitialization ofT, before theRc<T> is created, such that you canclone and store it inside theT.

new_cyclic first allocates the managed allocation for theRc<T>,then calls your closure, giving it aWeak<T> to this allocation,and only afterwards completes the construction of theRc<T> by placingtheT returned from your closure into the allocation.

Since the newRc<T> is not fully-constructed untilRc<T>::new_cyclicreturns, callingupgrade on the weak reference inside your closure willfail and result in aNone value.

§Panics

Ifdata_fn panics, the panic is propagated to the caller, and thetemporaryWeak<T> is dropped normally.

§Examples

usestd::rc::{Rc, Weak};structGadget {    me: Weak<Gadget>,}implGadget {/// Constructs a reference counted Gadget.fnnew() -> Rc<Self> {// `me` is a `Weak<Gadget>` pointing at the new allocation of the        // `Rc` we're constructing.Rc::new_cyclic(|me| {// Create the actual struct here.Gadget { me: me.clone() }        })    }/// Returns a reference counted pointer to Self.fnme(&self) -> Rc<Self> {self.me.upgrade().unwrap()    }}

Constructs a newRc with uninitialized contents.

§Examples

usestd::rc::Rc;letmutfive = Rc::<u32>::new_uninit();// Deferred initialization:Rc::get_mut(&mutfive).unwrap().write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5)

Constructs a newRc with uninitialized contents, with the memorybeing filled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

usestd::rc::Rc;letzero = Rc::<u32>::new_zeroed();letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0)

Constructs a newRc<T>, returning an error if the allocation fails

§Examples

#![feature(allocator_api)]usestd::rc::Rc;letfive = Rc::try_new(5);

Constructs a newRc with uninitialized contents, returning an error if the allocation fails

§Examples

#![feature(allocator_api)]usestd::rc::Rc;letmutfive = Rc::<u32>::try_new_uninit()?;// Deferred initialization:Rc::get_mut(&mutfive).unwrap().write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5);

Constructs a newRc with uninitialized contents, with the memorybeing filled with0 bytes, returning an error if the allocation fails

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;letzero = Rc::<u32>::try_new_zeroed()?;letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0);

Constructs a newPin<Rc<T>>. IfT does not implementUnpin, thenvalue will be pinned in memory and unable to be moved.

Maps the value in anRc, reusing the allocation if possible.

f is called on a reference to the value in theRc, and the result is returned, also inanRc.

Note: this is an associated function, which means that you haveto call it asRc::map(r, f) instead ofr.map(f). Thisis so that there is no conflict with a method on the inner type.

§Examples

#![feature(smart_pointer_try_map)]usestd::rc::Rc;letr = Rc::new(7);letnew = Rc::map(r, |i| i +7);assert_eq!(*new,14);

Attempts to map the value in anRc, reusing the allocation if possible.

f is called on a reference to the value in theRc, and if the operation succeeds, theresult is returned, also in anRc.

Note: this is an associated function, which means that you haveto call it asRc::try_map(r, f) instead ofr.try_map(f). Thisis so that there is no conflict with a method on the inner type.

§Examples

#![feature(smart_pointer_try_map)]usestd::rc::Rc;letb = Rc::new(7);letnew = Rc::try_map(b, |&i| u32::try_from(i)).unwrap();assert_eq!(*new,7);

Constructs a newRc in the provided allocator.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letfive = Rc::new_in(5, System);

Constructs a newRc with uninitialized contents in the provided allocator.

§Examples

#![feature(get_mut_unchecked)]#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letmutfive = Rc::<u32,_>::new_uninit_in(System);letfive =unsafe{// Deferred initialization:Rc::get_mut_unchecked(&mutfive).as_mut_ptr().write(5);    five.assume_init()};assert_eq!(*five,5)

Constructs a newRc with uninitialized contents, with the memorybeing filled with0 bytes, in the provided allocator.

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letzero = Rc::<u32,_>::new_zeroed_in(System);letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0)

Constructs a newRc<T, A> in the given allocator while giving you aWeak<T, A> to the allocation,to allow you to construct aT which holds a weak pointer to itself.

Generally, a structure circularly referencing itself, either directly orindirectly, should not hold a strong reference to itself to prevent a memory leak.Using this function, you get access to the weak pointer during theinitialization ofT, before theRc<T, A> is created, such that you canclone and store it inside theT.

new_cyclic_in first allocates the managed allocation for theRc<T, A>,then calls your closure, giving it aWeak<T, A> to this allocation,and only afterwards completes the construction of theRc<T, A> by placingtheT returned from your closure into the allocation.

Since the newRc<T, A> is not fully-constructed untilRc<T, A>::new_cyclic_inreturns, callingupgrade on the weak reference inside your closure willfail and result in aNone value.

§Panics

Ifdata_fn panics, the panic is propagated to the caller, and thetemporaryWeak<T, A> is dropped normally.

§Examples

Seenew_cyclic.

Constructs a newRc<T> in the provided allocator, returning an error if the allocationfails

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letfive = Rc::try_new_in(5, System);

Constructs a newRc with uninitialized contents, in the provided allocator, returning anerror if the allocation fails

§Examples

#![feature(allocator_api)]#![feature(get_mut_unchecked)]usestd::rc::Rc;usestd::alloc::System;letmutfive = Rc::<u32,_>::try_new_uninit_in(System)?;letfive =unsafe{// Deferred initialization:Rc::get_mut_unchecked(&mutfive).as_mut_ptr().write(5);    five.assume_init()};assert_eq!(*five,5);

Constructs a newRc with uninitialized contents, with the memorybeing filled with0 bytes, in the provided allocator, returning an error if the allocationfails

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letzero = Rc::<u32,_>::try_new_zeroed_in(System)?;letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0);

Constructs a newPin<Rc<T>> in the provided allocator. IfT does not implementUnpin, thenvalue will be pinned in memory and unable to be moved.

Returns the inner value, if theRc has exactly one strong reference.

Otherwise, anErr is returned with the sameRc that waspassed in.

This will succeed even if there are outstanding weak references.

§Examples

usestd::rc::Rc;letx = Rc::new(3);assert_eq!(Rc::try_unwrap(x),Ok(3));letx = Rc::new(4);let_y = Rc::clone(&x);assert_eq!(*Rc::try_unwrap(x).unwrap_err(),4);

Returns the inner value, if theRc has exactly one strong reference.

Otherwise,None is returned and theRc is dropped.

This will succeed even if there are outstanding weak references.

IfRc::into_inner is called on every clone of thisRc,it is guaranteed that exactly one of the calls returns the inner value.This means in particular that the inner value is not dropped.

Rc::try_unwrap is conceptually similar toRc::into_inner.And while they are meant for different use-cases,Rc::into_inner(this)is in fact equivalent toRc::try_unwrap(this).ok().(Note that the same kind of equivalence doesnot hold true forArc, due to race conditions that do not apply toRc!)

§Examples

usestd::rc::Rc;letx = Rc::new(3);assert_eq!(Rc::into_inner(x),Some(3));letx = Rc::new(4);lety = Rc::clone(&x);assert_eq!(Rc::into_inner(y),None);assert_eq!(Rc::into_inner(x),Some(4));

Constructs a new reference-counted slice with uninitialized contents.

§Examples

usestd::rc::Rc;letmutvalues = Rc::<[u32]>::new_uninit_slice(3);// Deferred initialization:letdata = Rc::get_mut(&mutvalues).unwrap();data[0].write(1);data[1].write(2);data[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs a new reference-counted slice with uninitialized contents, with the memory beingfilled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

usestd::rc::Rc;letvalues = Rc::<[u32]>::new_zeroed_slice(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0])

Converts the reference-counted slice into a reference-counted array.

This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.

IfN is not exactly equal to the length ofself, then this method returnsNone.

Constructs a new reference-counted slice with uninitialized contents.

§Examples

#![feature(get_mut_unchecked)]#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letmutvalues = Rc::<[u32],_>::new_uninit_slice_in(3, System);letvalues =unsafe{// Deferred initialization:Rc::get_mut_unchecked(&mutvalues)[0].as_mut_ptr().write(1);    Rc::get_mut_unchecked(&mutvalues)[1].as_mut_ptr().write(2);    Rc::get_mut_unchecked(&mutvalues)[2].as_mut_ptr().write(3);    values.assume_init()};assert_eq!(*values, [1,2,3])

Constructs a new reference-counted slice with uninitialized contents, with the memory beingfilled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letvalues = Rc::<[u32],_>::new_zeroed_slice_in(3, System);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0])

Converts toRc<T>.

§Safety

As withMaybeUninit::assume_init,it is up to the caller to guarantee that the inner valuereally is in an initialized state.Calling this when the content is not yet fully initializedcauses immediate undefined behavior.

§Examples

usestd::rc::Rc;letmutfive = Rc::<u32>::new_uninit();// Deferred initialization:Rc::get_mut(&mutfive).unwrap().write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5)

Constructs a newRc<T> with a clone ofvalue.

§Examples

#![feature(clone_from_ref)]usestd::rc::Rc;lethello: Rc<str> = Rc::clone_from_ref("hello");

Constructs a newRc<T> with a clone ofvalue, returning an error if allocation fails

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::rc::Rc;lethello: Rc<str> = Rc::try_clone_from_ref("hello")?;

Constructs a newRc<T> with a clone ofvalue in the provided allocator.

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;lethello: Rc<str, System> = Rc::clone_from_ref_in("hello", System);

Constructs a newRc<T> with a clone ofvalue in the provided allocator, returning an error if allocation fails

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;lethello: Rc<str, System> = Rc::try_clone_from_ref_in("hello", System)?;

Converts toRc<[T]>.

§Safety

As withMaybeUninit::assume_init,it is up to the caller to guarantee that the inner valuereally is in an initialized state.Calling this when the content is not yet fully initializedcauses immediate undefined behavior.

§Examples

usestd::rc::Rc;letmutvalues = Rc::<[u32]>::new_uninit_slice(3);// Deferred initialization:letdata = Rc::get_mut(&mutvalues).unwrap();data[0].write(1);data[1].write(2);data[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs anRc<T> from a raw pointer.

The raw pointer must have been previously returned by a call toRc<U>::into_raw with the following requirements:

• IfU is sized, it must have the same size and alignment asT. Thisis trivially true ifU isT.
• IfU is unsized, its data pointer must have the same size andalignment asT. This is trivially true ifRc<U> was constructedthroughRc<T> and then converted toRc<U> through anunsizedcoercion.

Note that ifU orU’s data pointer is notT but has the same sizeand alignment, this is basically like transmuting references ofdifferent types. Seemem::transmute for more informationon what restrictions apply in this case.

The raw pointer must point to a block of memory allocated by the global allocator

The user offrom_raw has to make sure a specific value ofT is onlydropped once.

This function is unsafe because improper use may lead to memory unsafety,even if the returnedRc<T> is never accessed.

§Examples

usestd::rc::Rc;letx = Rc::new("hello".to_owned());letx_ptr = Rc::into_raw(x);unsafe{// Convert back to an `Rc` to prevent leak.letx = 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!

Convert a slice back into its original array:

usestd::rc::Rc;letx: Rc<[u32]> = Rc::new([1,2,3]);letx_ptr:*const[u32] = Rc::into_raw(x);unsafe{letx: Rc<[u32;3]> = Rc::from_raw(x_ptr.cast::<[u32;3]>());assert_eq!(&*x,&[1,2,3]);}

Consumes theRc, returning the wrapped pointer.

To avoid a memory leak the pointer must be converted back to anRc usingRc::from_raw.

§Examples

usestd::rc::Rc;letx = Rc::new("hello".to_owned());letx_ptr = Rc::into_raw(x);assert_eq!(unsafe{&*x_ptr },"hello");

Increments the strong reference count on theRc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughRc::into_raw and must satisfy thesame layout requirements specified inRc::from_raw_in.The associatedRc instance must be valid (i.e. the strong count must be atleast 1) for the duration of this method, andptr must point to a block of memoryallocated by the global allocator.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);unsafe{letptr = Rc::into_raw(five);    Rc::increment_strong_count(ptr);letfive = Rc::from_raw(ptr);assert_eq!(2, Rc::strong_count(&five));}

Decrements the strong reference count on theRc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughRc::into_rawand must satisfy thesame layout requirements specified inRc::from_raw_in.The associatedRc instance must be valid (i.e. the strong count must be atleast 1) when invoking this method, andptr must point to a block of memoryallocated by the global allocator. This method can be used to release the finalRc andbacking storage, butshould not be called after the finalRc has been released.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);unsafe{letptr = Rc::into_raw(five);    Rc::increment_strong_count(ptr);letfive = Rc::from_raw(ptr);assert_eq!(2, Rc::strong_count(&five));    Rc::decrement_strong_count(ptr);assert_eq!(1, Rc::strong_count(&five));}

Returns a reference to the underlying allocator.

Note: this is an associated function, which means that you haveto call it asRc::allocator(&r) instead ofr.allocator(). Thisis so that there is no conflict with a method on the inner type.

Consumes theRc, returning the wrapped pointer and allocator.

To avoid a memory leak the pointer must be converted back to anRc usingRc::from_raw_in.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letx = Rc::new_in("hello".to_owned(), System);let(ptr, alloc) = Rc::into_raw_with_allocator(x);assert_eq!(unsafe{&*ptr },"hello");letx =unsafe{ Rc::from_raw_in(ptr, alloc) };assert_eq!(&*x,"hello");

Provides a raw pointer to the data.

The counts are not affected in any way and theRc is not consumed. The pointer is validfor as long as there are strong counts in theRc.

§Examples

usestd::rc::Rc;letx = Rc::new(0);lety = Rc::clone(&x);letx_ptr = Rc::as_ptr(&x);assert_eq!(x_ptr, Rc::as_ptr(&y));assert_eq!(unsafe{*x_ptr },0);

Constructs anRc<T, A> from a raw pointer in the provided allocator.

The raw pointer must have been previously returned by a call toRc<U, A>::into_raw with the following requirements:

• IfU is sized, it must have the same size and alignment asT. Thisis trivially true ifU isT.
• IfU is unsized, its data pointer must have the same size andalignment asT. This is trivially true ifRc<U> was constructedthroughRc<T> and then converted toRc<U> through anunsizedcoercion.

Note that ifU orU’s data pointer is notT but has the same sizeand alignment, this is basically like transmuting references ofdifferent types. Seemem::transmute for more informationon what restrictions apply in this case.

The raw pointer must point to a block of memory allocated byalloc

The user offrom_raw has to make sure a specific value ofT is onlydropped once.

This function is unsafe because improper use may lead to memory unsafety,even if the returnedRc<T> is never accessed.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letx = Rc::new_in("hello".to_owned(), System);let(x_ptr, _alloc) = Rc::into_raw_with_allocator(x);unsafe{// Convert back to an `Rc` to prevent leak.letx = Rc::from_raw_in(x_ptr, System);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!

Convert a slice back into its original array:

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letx: Rc<[u32],_> = Rc::new_in([1,2,3], System);letx_ptr:*const[u32] = Rc::into_raw_with_allocator(x).0;unsafe{letx: Rc<[u32;3],_> = Rc::from_raw_in(x_ptr.cast::<[u32;3]>(), System);assert_eq!(&*x,&[1,2,3]);}

Creates a newWeak pointer to this allocation.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);letweak_five = Rc::downgrade(&five);

Gets the number ofWeak pointers to this allocation.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);let_weak_five = Rc::downgrade(&five);assert_eq!(1, Rc::weak_count(&five));

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

§Examples

usestd::rc::Rc;letfive = Rc::new(5);let_also_five = Rc::clone(&five);assert_eq!(2, Rc::strong_count(&five));

Increments the strong reference count on theRc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughRc::into_raw and must satisfy thesame layout requirements specified inRc::from_raw_in.The associatedRc instance must be valid (i.e. the strong count must be atleast 1) for the duration of this method, andptr must point to a block of memoryallocated byalloc.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letfive = Rc::new_in(5, System);unsafe{let(ptr, _alloc) = Rc::into_raw_with_allocator(five);    Rc::increment_strong_count_in(ptr, System);letfive = Rc::from_raw_in(ptr, System);assert_eq!(2, Rc::strong_count(&five));}

Decrements the strong reference count on theRc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughRc::into_rawand must satisfy thesame layout requirements specified inRc::from_raw_in.The associatedRc instance must be valid (i.e. the strong count must be atleast 1) when invoking this method, andptr must point to a block of memoryallocated byalloc. This method can be used to release the finalRc andbacking storage, butshould not be called after the finalRc has been released.

§Examples

#![feature(allocator_api)]usestd::rc::Rc;usestd::alloc::System;letfive = Rc::new_in(5, System);unsafe{let(ptr, _alloc) = Rc::into_raw_with_allocator(five);    Rc::increment_strong_count_in(ptr, System);letfive = Rc::from_raw_in(ptr, System);assert_eq!(2, Rc::strong_count(&five));    Rc::decrement_strong_count_in(ptr, System);assert_eq!(1, Rc::strong_count(&five));}

Returns a mutable reference into the givenRc, if there areno otherRc orWeak pointers to the same allocation.

ReturnsNone otherwise, because it is not safe tomutate a shared value.

See alsomake_mut, which willclonethe inner value when there are otherRc pointers.

§Examples

usestd::rc::Rc;letmutx = Rc::new(3);*Rc::get_mut(&mutx).unwrap() =4;assert_eq!(*x,4);let_y = Rc::clone(&x);assert!(Rc::get_mut(&mutx).is_none());

Returns a mutable reference into the givenRc,without any check.

See alsoget_mut, which is safe and does appropriate checks.

§Safety

If any otherRc orWeak pointers to the same allocation exist, thenthey must not be dereferenced or have active borrows for the durationof the returned borrow, and their inner type must be exactly the same as theinner type of this Rc (including lifetimes). This is trivially the case if nosuch pointers exist, for example immediately afterRc::new.

§Examples

#![feature(get_mut_unchecked)]usestd::rc::Rc;letmutx = Rc::new(String::new());unsafe{    Rc::get_mut_unchecked(&mutx).push_str("foo")}assert_eq!(*x,"foo");

OtherRc pointers to the same allocation must be to the same type.

#![feature(get_mut_unchecked)]usestd::rc::Rc;letx: Rc<str> = Rc::from("Hello, world!");letmuty: Rc<[u8]> = x.clone().into();unsafe{// this is Undefined Behavior, because x's inner type is str, not [u8]Rc::get_mut_unchecked(&muty).fill(0xff);// 0xff is invalid in UTF-8}println!("{}",&*x);// Invalid UTF-8 in a str

OtherRc pointers to the same allocation must be to the exact same type, including lifetimes.

#![feature(get_mut_unchecked)]usestd::rc::Rc;letx: Rc<&str> = Rc::new("Hello, world!");{lets = String::from("Oh, no!");letmuty: Rc<&str> = x.clone();unsafe{// this is Undefined Behavior, because x's inner type        // is &'long str, not &'short str*Rc::get_mut_unchecked(&muty) =&s;    }}println!("{}",&*x);// Use-after-free

Returnstrue if the twoRcs point to the same allocation in a vein similar toptr::eq. This function ignores the metadata ofdyn Trait pointers.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);letsame_five = Rc::clone(&five);letother_five = Rc::new(5);assert!(Rc::ptr_eq(&five,&same_five));assert!(!Rc::ptr_eq(&five,&other_five));

Makes a mutable reference into the givenRc.

If there are otherRc pointers to the same allocation, thenmake_mut willclone the inner value to a new allocation to ensure unique ownership. This is alsoreferred to as clone-on-write.

However, if there are no otherRc pointers to this allocation, but someWeakpointers, then theWeak pointers will be disassociated and the inner value will notbe cloned.

See alsoget_mut, which will fail rather than cloning the inner valueor disassociatingWeak pointers.

§Examples

usestd::rc::Rc;letmutdata = Rc::new(5);*Rc::make_mut(&mutdata) +=1;// Won't clone anythingletmutother_data = Rc::clone(&data);// Won't clone inner data*Rc::make_mut(&mutdata) +=1;// Clones inner data*Rc::make_mut(&mutdata) +=1;// Won't clone anything*Rc::make_mut(&mutother_data)*=2;// Won't clone anything// Now `data` and `other_data` point to different allocations.assert_eq!(*data,8);assert_eq!(*other_data,12);

Weak pointers will be disassociated:

usestd::rc::Rc;letmutdata = Rc::new(75);letweak = Rc::downgrade(&data);assert!(75==*data);assert!(75==*weak.upgrade().unwrap());*Rc::make_mut(&mutdata) +=1;assert!(76==*data);assert!(weak.upgrade().is_none());

If we have the only reference toT then unwrap it. Otherwise, cloneT and return theclone.

Assumingrc_t is of typeRc<T>, this function is functionally equivalent to(*rc_t).clone(), but will avoid cloning the inner value where possible.

§Examples

letinner = String::from("test");letptr = inner.as_ptr();letrc = Rc::new(inner);letinner = Rc::unwrap_or_clone(rc);// The inner value was not clonedassert!(ptr::eq(ptr, inner.as_ptr()));letrc = Rc::new(inner);letrc2 = rc.clone();letinner = Rc::unwrap_or_clone(rc);// Because there were 2 references, we had to clone the inner value.assert!(!ptr::eq(ptr, inner.as_ptr()));// `rc2` is the last reference, so when we unwrap it we get back// the original `String`.letinner = Rc::unwrap_or_clone(rc2);assert!(ptr::eq(ptr, inner.as_ptr()));

Attempts to downcast theRc<dyn Any> to a concrete type.

§Examples

usestd::any::Any;usestd::rc::Rc;fnprint_if_string(value: Rc<dynAny>) {if letOk(string) = value.downcast::<String>() {println!("String ({}): {}", string.len(), string);    }}letmy_string ="Hello World".to_string();print_if_string(Rc::new(my_string));print_if_string(Rc::new(0i8));

Downcasts theRc<dyn Any> to a concrete type.

For a safe alternative seedowncast.

§Examples

#![feature(downcast_unchecked)]usestd::any::Any;usestd::rc::Rc;letx: Rc<dynAny> = Rc::new(1_usize);unsafe{assert_eq!(*x.downcast_unchecked::<usize>(),1);}

§Safety

The contained value must be of typeT. Calling this methodwith the incorrect type isundefined behavior.

Makes a clone of theRc pointer.

This creates another pointer to the same allocation, increasing thestrong reference count.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);let _= Rc::clone(&five);

Creates an empty[T] inside anRc.

This may or may not share an allocation with other Rcs on the same thread.

Creates an empty CStr inside an Rc

This may or may not share an allocation with other Rcs on the same thread.

Creates a newRc<T>, with theDefault value forT.

§Examples

usestd::rc::Rc;letx: Rc<i32> = Default::default();assert_eq!(*x,0);

Creates an emptystr inside anRc.

This may or may not share an allocation with other Rcs on the same thread.

Drops theRc.

This will decrement the strong reference count. If the strong referencecount reaches zero then the only other references (if any) areWeak, so wedrop the inner value.

§Examples

usestd::rc::Rc;structFoo;implDropforFoo {fndrop(&mutself) {println!("dropped!");    }}letfoo  = Rc::new(Foo);letfoo2 = Rc::clone(&foo);drop(foo);// Doesn't print anythingdrop(foo2);// Prints "dropped!"

Allocates a reference-counted slice and fills it by cloningv’s items.

§Example

letoriginal:&[i32] =&[1,2,3];letshared: Rc<[i32]> = Rc::from(original);assert_eq!(&[1,2,3],&shared[..]);

Converts a&CStr into aRc<CStr>,by copying the contents into a newly allocatedRc.

Copies the string into a newly allocatedRc<OsStr>.

Converts aPath into anRc by copying thePath data into a newRc buffer.

Allocates a reference-counted slice and fills it by cloningv’s items.

§Example

letmutoriginal = [1,2,3];letoriginal:&mut[i32] =&mutoriginal;letshared: Rc<[i32]> = Rc::from(original);assert_eq!(&[1,2,3],&shared[..]);

Converts a&mut CStr into aRc<CStr>,by copying the contents into a newly allocatedRc.

Copies the string into a newly allocatedRc<OsStr>.

Converts aPath into anRc by copying thePath data into a newRc buffer.

Allocates a reference-counted string slice and copiesv into it.

§Example

letmutoriginal = String::from("statue");letoriginal:&mutstr =&mutoriginal;letshared: Rc<str> = Rc::from(original);assert_eq!("statue",&shared[..]);

Allocates a reference-counted string slice and copiesv into it.

§Example

letshared: Rc<str> = Rc::from("statue");assert_eq!("statue",&shared[..]);

Converts a[T; N] into anRc<[T]>.

The conversion moves the array into a newly allocatedRc.

§Example

letoriginal: [i32;3] = [1,2,3];letshared: Rc<[i32]> = Rc::from(original);assert_eq!(&[1,2,3],&shared[..]);

Move a boxed object to a new, reference counted, allocation.

§Example

letoriginal: Box<i32> = Box::new(1);letshared: Rc<i32> = Rc::from(original);assert_eq!(1,*shared);

Converts aCString into anRc<CStr> by moving theCStringdata into a newRc buffer.

Creates a reference-counted pointer from a clone-on-write pointer bycopying its content.

§Example

letcow: Cow<'_, str> = Cow::Borrowed("eggplant");letshared: Rc<str> = Rc::from(cow);assert_eq!("eggplant",&shared[..]);

Converts anOsString into anRc<OsStr> by moving theOsStringdata into a newRc buffer.

Converts aPathBuf into anRc<Path> by moving thePathBuf data intoa newRc buffer.

Use aWake-able type as aLocalWaker.

No heap allocations or atomic operations are used for this conversion.

Use aWake-able type as aRawWaker.

No heap allocations or atomic operations are used for this conversion.

Converts a reference-counted string slice into a byte slice.

§Example

letstring: Rc<str> = Rc::from("eggplant");letbytes: Rc<[u8]> = Rc::from(string);assert_eq!("eggplant".as_bytes(), bytes.as_ref());

Allocates a reference-counted string slice and copiesv into it.

§Example

letoriginal: String ="statue".to_owned();letshared: Rc<str> = Rc::from(original);assert_eq!("statue",&shared[..]);

Converts a generic typeT into anRc<T>

The conversion allocates on the heap and movestfrom the stack into it.

§Example

letx =5;letrc = Rc::new(5);assert_eq!(Rc::from(x), rc);

Allocates a reference-counted slice and movesv’s items into it.

§Example

letunique: Vec<i32> =vec![1,2,3];letshared: Rc<[i32]> = Rc::from(unique);assert_eq!(&[1,2,3],&shared[..]);

Takes each element in theIterator and collects it into anRc<[T]>.

§Performance characteristics

§The general case

In the general case, collecting intoRc<[T]> is done by firstcollecting into aVec<T>. That is, when writing the following:

letevens: Rc<[u8]> = (0..10).filter(|&x| x %2==0).collect();

this behaves as if we wrote:

letevens: Rc<[u8]> = (0..10).filter(|&x| x %2==0)    .collect::<Vec<_>>()// The first set of allocations happens here..into();// A second allocation for `Rc<[T]>` happens here.

This will allocate as many times as needed for constructing theVec<T>and then it will allocate once for turning theVec<T> into theRc<[T]>.

§Iterators of known length

When yourIterator implementsTrustedLen and is of an exact size,a single allocation will be made for theRc<[T]>. For example:

letevens: Rc<[u8]> = (0..10).collect();// Just a single allocation happens here.

Comparison for twoRcs.

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

§Examples

usestd::rc::Rc;usestd::cmp::Ordering;letfive = Rc::new(5);assert_eq!(Ordering::Less, five.cmp(&Rc::new(6)));

Equality for twoRcs.

TwoRcs are equal if their inner values are equal, even if they arestored in different allocation.

IfT also implementsEq (implying reflexivity of equality),twoRcs that point to the same allocation arealways equal.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);assert!(five == Rc::new(5));

Inequality for twoRcs.

TwoRcs are not equal if their inner values are not equal.

IfT also implementsEq (implying reflexivity of equality),twoRcs that point to the same allocation arealways equal.

§Examples

usestd::rc::Rc;letfive = Rc::new(5);assert!(five != Rc::new(6));

Partial comparison for twoRcs.

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

§Examples

usestd::rc::Rc;usestd::cmp::Ordering;letfive = Rc::new(5);assert_eq!(Some(Ordering::Less), five.partial_cmp(&Rc::new(6)));

Less-than comparison for twoRcs.

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

§Examples

usestd::rc::Rc;letfive = Rc::new(5);assert!(five < Rc::new(6));

‘Less than or equal to’ comparison for twoRcs.

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

§Examples

usestd::rc::Rc;letfive = Rc::new(5);assert!(five <= Rc::new(5));

Greater-than comparison for twoRcs.

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

§Examples

usestd::rc::Rc;letfive = Rc::new(5);assert!(five > Rc::new(4));

‘Greater than or equal to’ comparison for twoRcs.

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

§Examples

usestd::rc::Rc;letfive = Rc::new(5);assert!(five >= Rc::new(5));

Returns the argument unchanged.

CallsU::from(self).

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