Struct Rc

pub struct Rc<T: PtrEq + ?Sized>(/* private fields */);

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.

Implementations

impl<T: PtrEq> Rc<T>

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

Constructs a new Rc<T>.

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq)]
struct Test(i64);
 
let five = Rc::new(Test(5));

pub fn pin(value: T) -> Pin<Rc<T>>

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: Self) -> Result<T, Self>

Returns the inner 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 ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);

let x = Rc::new(Test(3));
assert_eq!(Rc::try_unwrap(x).unwrap().0, 3);

let x = Rc::new(Test(4));
let _y = Rc::clone(&x);
assert_eq!(Rc::try_unwrap(x).unwrap_err().0, 4);

impl<T: PtrEq + ?Sized> Rc<T>

pub fn into_raw(this: Self) -> *const T

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 ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);
 
let x = Rc::new(Test(42));
let x_ptr = Rc::into_raw(x);
assert_eq!(unsafe { &*x_ptr }.0, 42);

pub fn as_ptr(this: &Self) -> *const T

Provides a raw pointer to the data.

The counts are not affected in any way and the Rc is not consumed. The pointer is valid for as long there are strong counts in the Rc.

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);

let x = Rc::new(Test(42));
let y = Rc::clone(&x);
let x_ptr = Rc::as_ptr(&x);
assert_eq!(x_ptr, Rc::as_ptr(&y));
assert_eq!(unsafe { &*x_ptr }.0, 42);

pub unsafe fn from_raw(ptr: *const T) -> Self

Constructs an Rc<T> from a raw pointer.

The raw pointer must have been previously returned by a call to Rc<U>::into_raw where U must have the same size and alignment as T. This is trivially true if U is T. Note that if U is not T but has the same size and alignment, this is basically like transmuting references of different types. See mem::transmute for more information on what restrictions apply in this case.

The user of from_raw has to make sure a specific value of T is only dropped once.

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

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);
 
let x = Rc::new(Test(42));
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.0, 42);

    // 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!

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

Creates a new Weak pointer to this allocation.

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);
 
let five = Rc::new(Test(5));

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

pub fn weak_count(this: &Self) -> usize

Gets the number of Weak pointers to this allocation.

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);
 
let five = Rc::new(Test(5));
let _weak_five = Rc::downgrade(&five);

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

pub fn strong_count(this: &Self) -> usize

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

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);
 
let five = Rc::new(Test(5));
let _also_five = Rc::clone(&five);

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

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

Returns a mutable reference into the given Rc, if there are no other Rc or Weak pointers to the same allocation.

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

See also make_mut, which will clone the inner value when there are other pointers.

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug)]
struct Test(i64);
 
let mut x = Rc::new(Test(3));
*Rc::get_mut(&mut x).unwrap() = Test(4);
assert_eq!(x.0, 4);

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

impl<T: PtrEq + Clone> Rc<T>

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

Makes a mutable reference into the given Rc.

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

If there are no other Rc pointers to this allocation, then Weak pointers to this allocation will be disassociated.

See also get_mut, which will fail rather than cloning.

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug, Clone)]
struct Test(i64);

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

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

// Now `data` and `other_data` point to different allocations.
assert_eq!(data.0, 8);
assert_eq!(other_data.0, 12);

Weak pointers will be disassociated:

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Debug, Clone)]
struct Test(i64);

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

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

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

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

Trait Implementations

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

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

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

fn borrow(&self) -> &T

Immutably borrows from an owned value.

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

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

Makes a clone of the Rc pointer.

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

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq)]
struct Test(i64);

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

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

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Rc<T>

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

Examples

use ptr_eq::rc::Rc;
use ptr_eq::PtrEq;
 
#[derive(PtrEq, Default)]
struct Test(i64);

let x: Rc<Test> = Default::default();
assert_eq!(x.0, 0);

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

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: PtrEq> From<T> for Rc<T>

fn from(t: T) -> Self

Converts to this type from the input type.

impl<T> From<Vec<T>> for Rc<[T]>

where [T]: PtrEq,

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

Converts to this type from the input type.

impl<T> FromIterator<T> for Rc<[T]>

where [T]: PtrEq,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Rc<[T]>

Creates a value from an iterator.

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

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

Formats the value using the given formatter.