1//! # Note on version 0.10.3
2//!
3//! This version of `self_cell` is a re-export of the `self_cell` version `1`
4//! meant for backwards-compatibly allowing `0.10` users to get current and
5//! future soundness fixes. If you are adding `self_cell` as a dependency,
6//! please use an up-to-date version directly.
7//!
8//! # Overview
9//!
10//! `self_cell` provides one macro-rules macro: [`self_cell`][`self_cell!`]. With this macro
11//! you can create self-referential structs that are safe-to-use in stable Rust,
12//! without leaking the struct internal lifetime.
13//!
14//! In a nutshell, the API looks *roughly* like this:
15//!
16//! ```ignore
17//! // User code:
18//!
19//! self_cell!(
20//! struct NewStructName {
21//! owner: Owner,
22//!
23//! #[covariant]
24//! dependent: Dependent,
25//! }
26//!
27//! impl {Debug}
28//! );
29//!
30//! // Generated by macro:
31//!
32//! struct NewStructName(...);
33//!
34//! impl NewStructName {
35//! fn new(
36//! owner: Owner,
37//! dependent_builder: impl for<'a> FnOnce(&'a Owner) -> Dependent<'a>
38//! ) -> NewStructName { ... }
39//! fn borrow_owner<'a>(&'a self) -> &'a Owner { ... }
40//! fn borrow_dependent<'a>(&'a self) -> &'a Dependent<'a> { ... }
41//! }
42//!
43//! impl Debug for NewStructName { ... }
44//! ```
45//!
46//! Self-referential structs are currently not supported with safe vanilla Rust.
47//! The only reasonable safe alternative is to have the user juggle 2 separate
48//! data structures which is a mess. The library solution ouroboros is really
49//! expensive to compile due to its use of procedural macros.
50//!
51//! This alternative is `no_std`, uses no proc-macros, some self contained
52//! unsafe and works on stable Rust, and is miri tested. With a total of less
53//! than 300 lines of implementation code, which consists mostly of type and
54//! trait implementations, this crate aims to be a good minimal solution to the
55//! problem of self-referential structs.
56//!
57//! It has undergone [community code
58//! review](https://users.rust-lang.org/t/experimental-safe-to-use-proc-macro-free-self-referential-structs-in-stable-rust/52775)
59//! from experienced Rust users.
60//!
61//! ### Fast compile times
62//!
63//! ```txt
64//! $ rm -rf target && cargo +nightly build -Z timings
65//!
66//! Compiling self_cell v0.7.0
67//! Completed self_cell v0.7.0 in 0.2s
68//! ```
69//!
70//! Because it does **not** use proc-macros, and has 0 dependencies
71//! compile-times are fast.
72//!
73//! Measurements done on a slow laptop.
74//!
75//! ### A motivating use case
76//!
77//! ```rust
78//! use self_cell::self_cell;
79//!
80//! #[derive(Debug, Eq, PartialEq)]
81//! struct Ast<'a>(pub Vec<&'a str>);
82//!
83//! self_cell!(
84//! struct AstCell {
85//! owner: String,
86//!
87//! #[covariant]
88//! dependent: Ast,
89//! }
90//!
91//! impl {Debug, Eq, PartialEq}
92//! );
93//!
94//! fn build_ast_cell(code: &str) -> AstCell {
95//! // Create owning String on stack.
96//! let pre_processed_code = code.trim().to_string();
97//!
98//! // Move String into AstCell, then build Ast inplace.
99//! AstCell::new(
100//! pre_processed_code,
101//! |code| Ast(code.split(' ').filter(|word| word.len() > 1).collect())
102//! )
103//! }
104//!
105//! fn main() {
106//! let ast_cell = build_ast_cell("fox = cat + dog");
107//!
108//! println!("ast_cell -> {:?}", &ast_cell);
109//! println!("ast_cell.borrow_owner() -> {:?}", ast_cell.borrow_owner());
110//! println!("ast_cell.borrow_dependent().0[1] -> {:?}", ast_cell.borrow_dependent().0[1]);
111//! }
112//! ```
113//!
114//! ```txt
115//! $ cargo run
116//!
117//! ast_cell -> AstCell { owner: "fox = cat + dog", dependent: Ast(["fox", "cat", "dog"]) }
118//! ast_cell.borrow_owner() -> "fox = cat + dog"
119//! ast_cell.borrow_dependent().0[1] -> "cat"
120//! ```
121//!
122//! There is no way in safe Rust to have an API like `build_ast_cell`, as soon
123//! as `Ast` depends on stack variables like `pre_processed_code` you can't
124//! return the value out of the function anymore. You could move the
125//! pre-processing into the caller but that gets ugly quickly because you can't
126//! encapsulate things anymore. Note this is a somewhat niche use case,
127//! self-referential structs should only be used when there is no good
128//! alternative.
129//!
130//! Under the hood, it heap allocates a struct which it initializes first by
131//! moving the owner value to it and then using the reference to this now
132//! Pin/Immovable owner to construct the dependent inplace next to it. This
133//! makes it safe to move the generated SelfCell but you have to pay for the
134//! heap allocation.
135//!
136//! See the documentation for [`self_cell`][`self_cell!`] to dive further into the details.
137//!
138//! Or take a look at the advanced examples:
139//! - [Example how to handle dependent construction that can
140//! fail](https://github.com/Voultapher/self_cell/tree/main/examples/fallible_dependent_construction)
141//!
142//! - [How to build a lazy AST with
143//! self_cell](https://github.com/Voultapher/self_cell/tree/main/examples/lazy_ast)
144//!
145//! - [How to use an owner type with
146//! lifetime](https://github.com/Voultapher/self_cell/tree/main/examples/owner_with_lifetime)
147//!
148//! ### Min required rustc version
149//!
150//! By default the minimum required rustc version is 1.51.
151//!
152//! There is an optional feature you can enable called "old_rust" that enables
153//! support down to rustc version 1.36. However this requires polyfilling std
154//! library functionality for older rustc with technically UB versions. Testing
155//! does not show older rustc versions (ab)using this. Use at your own risk.
156//!
157//! The minimum versions are a best effor and may change with any new major
158//! release.
159
160#![no_std]
161
162pub use new_self_cell::self_cell;
163