Crate slice_rc 

slice-rc provides a variant of the std’s Rc type, and more generally the contents of the module std::rc.

If you are not familiar with those, you should read their documentation before trying to use this crate.

• Src<T> (which, as the crate name suggests, stands for ‘Slice Reference Counted’) is a variant of std::rc::Rc<T>
• WeakSrc<T> is a variant of std::rc::Weak<T>
• UniqueSrc<T> is a variant of the currently-unstable std::rc::UniqueRc<T>
• UninitSrc<T> is a variant of the as-yet-only-hypothetical std::rc::UninitRc<T>

How do this crate’s types differ from the std::rc ones?

Notably, Rc<[T]> is already a valid, usable type; why do we need a special slice Rc when Rc already supports slices?

The answer can be found in one method (well, two: one on Src, and its analog on WeakSrc): Src::slice allows us to acquire a sub-slice of the contents of the Src which still uses the reference-counting mechanism rather than using lifetime-style references; e.g.:

use slice_rc::Src;
 
let whole: Src<str> = Src::new("Hello World!");
let world: Src<str> = whole.slice(6..=10);
assert_eq!(&*world, "World");

This is useful because:

• Src<T>: 'static where T: 'static, and therefore this is useful where lifetimes are difficult or impossible to accomodate.
• Via WeakSrc and constructor functions like Src::cyclic_from_fn, it allows constructing collections of self-referential objects, and unlike e.g. Vec<Rc<T>>, in a Src<[T]>, the actual T’s are contiguous, which makes it possible to obtain a &[T].

Root

Many methods in this crate refer to a “root” pointer (e.g., root Src). This refers to any Src-family pointer that refers to the whole allocation; its len is the number of elements in the whole allocation, and every non-root pointer to the allocation references either an element or a subslice of if.

Note that it is not just the “original” Src that can be root:

let root = Src::from_array([1, 2, 3]);
 
assert!(Src::is_root(&root));
 
let slice = root.slice(1..);
 
assert!(!Src::is_root(&slice));
 
let also_root = Src::root(&slice);
 
assert!(Src::is_root(&also_root));

Structs

Src

A single-threaded sliceable reference-counting pointer. ‘Src’ stands for ‘Slice Reference Counted’.

UninitSrc

UninitSrc is a version of Src that uniquely owns a new allocation before its body is initialized. This is primarily used to construct self-referential data structures: the downgrade method allows aquiring weak references to this allocation before its body is initialized.

UniqueSrc

A uniquely owned Src.

WeakSrc

WeakSrc is a version of Src that holds a non-owning reference to the managed allocation.

Traits

SrcIndex

A helper trait for Src::slice. Analagous to SliceIndex.

SrcSlice

A sealed trait to encode the subset of SrcTarget that can contain multiple elements.

SrcTarget

A sealed trait to encode types that can can be used in the Src-family of pointers.

WeakSrcIndex

A helper trait for WeakSrc::slice.