static_rc/lib.rs
1//! `StaticRc`, resp. `StaticRcRef`, use Rust's affine type system and const generics to track the shared ownership
2//! of a heap-allocated, resp. reference, value safely at compile-time, with no run-time overhead.
3//!
4//! The amount of `unsafe` used within is minimal, `StaticRc` mostly leverages `Box` for most of the heavy-duty
5//! operations.
6//!
7//! # Example of usage.
8//!
9//! ```
10//! use static_rc::StaticRc;
11//!
12//! type Full<T> = StaticRc<T, 3, 3>;
13//! type TwoThird<T> = StaticRc<T, 2, 3>;
14//! type OneThird<T> = StaticRc<T, 1, 3>;
15//!
16//! let mut full = Full::new("Hello, world!".to_string());
17//!
18//! assert_eq!("Hello, world!", &*full);
19//!
20//! // Mutation is allowed when having full ownership, just like for `Box`.
21//! *full = "Hello, you!".to_string();
22//!
23//! assert_eq!("Hello, you!", &*full);
24//!
25//! // Mutation is no longer allowed from now on, due to aliasing, just like for `Rc`.
26//! let (two_third, one_third) = Full::split::<2, 1>(full);
27//!
28//! assert_eq!("Hello, you!", &*two_third);
29//! assert_eq!("Hello, you!", &*one_third);
30//!
31//! let mut full = Full::join(one_third, two_third);
32//!
33//! assert_eq!("Hello, you!", &*full);
34//!
35//! // Mutation is allowed again, since `full` has full ownership.
36//! *full = "Hello, world!".to_string();
37//!
38//! assert_eq!("Hello, world!", &*full);
39//!
40//! // Finally, the value is dropped when `full` is.
41//! ```
42//!
43//! # Options
44//!
45//! The crate is defined for `no_std` environment and only relies on `core` and `alloc` by default.
46//!
47//! The `alloc` crate can be opted out of, though this disables `StaticRc`.
48//!
49//! The crate only uses stable features by default, with a MSRV of 1.51 due to the use of const generics.
50//!
51//! Additional, the crate offers several optional features which unlock additional capabilities by using nightly.
52//! Please see `Cargo.toml` for an up-to-date list of features, and their effects.
53
54// Regular features
55#![cfg_attr(not(test), no_std)]
56
57// Nightly features
58#![cfg_attr(feature = "compile-time-ratio", allow(incomplete_features))]
59#![cfg_attr(feature = "compile-time-ratio", feature(generic_const_exprs))]
60#![cfg_attr(feature = "nightly-async-iterator", feature(async_iterator))]
61#![cfg_attr(feature = "nightly-coerce-unsized", feature(coerce_unsized))]
62#![cfg_attr(feature = "nightly-dispatch-from-dyn", feature(dispatch_from_dyn))]
63#![cfg_attr(any(feature = "nightly-dispatch-from-dyn", feature = "nightly-coerce-unsized"), feature(unsize))]
64#![cfg_attr(feature = "nightly-generator-trait", feature(generator_trait))]
65
66// Lints
67#![deny(missing_docs)]
68
69#[cfg(feature = "alloc")]
70extern crate alloc;
71
72#[macro_use]
73mod utils;
74
75pub mod rcref;
76
77pub use self::rcref::StaticRcRef;
78
79#[cfg(feature = "alloc")]
80pub mod rc;
81
82#[cfg(feature = "alloc")]
83pub use self::rc::StaticRc;
84
85#[cfg(feature = "experimental-lift")]
86pub mod lift;
87
88#[cfg(feature = "experimental-lift")]
89pub use self::lift::{lift, lift_with, lift_with_mut};