README.md
1# pin-project-lite
2
3[![crates-badge]][crates-url]
4[![docs-badge]][docs-url]
5[![license-badge]][license]
6[![rustc-badge]][rustc-url]
7
8[crates-badge]: https://img.shields.io/crates/v/pin-project-lite.svg
9[crates-url]: https://crates.io/crates/pin-project-lite
10[docs-badge]: https://docs.rs/pin-project-lite/badge.svg
11[docs-url]: https://docs.rs/pin-project-lite
12[license-badge]: https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg
13[license]: #license
14[rustc-badge]: https://img.shields.io/badge/rustc-1.37+-lightgray.svg
15[rustc-url]: https://blog.rust-lang.org/2019/08/15/Rust-1.37.0.html
16
17A lightweight version of [pin-project] written with declarative macros.
18
19## Usage
20
21Add this to your `Cargo.toml`:
22
23```toml
24[dependencies]
25pin-project-lite = "0.1"
26```
27
28The current pin-project-lite requires Rust 1.37 or later.
29
30## Examples
31
32[`pin_project!`] macro creates a projection type covering all the fields of struct.
33
34```rust
35use pin_project_lite::pin_project;
36use std::pin::Pin;
37
38pin_project! {
39 struct Struct<T, U> {
40 #[pin]
41 pinned: T,
42 unpinned: U,
43 }
44}
45
46impl<T, U> Struct<T, U> {
47 fn method(self: Pin<&mut Self>) {
48 let this = self.project();
49 let _: Pin<&mut T> = this.pinned; // Pinned reference to the field
50 let _: &mut U = this.unpinned; // Normal reference to the field
51 }
52}
53```
54
55## [pin-project] vs pin-project-lite
56
57Here are some similarities and differences compared to [pin-project].
58
59### Similar: Safety
60
61pin-project-lite guarantees safety in much the same way as [pin-project]. Both are completely safe unless you write other unsafe code.
62
63### Different: Minimal design
64
65This library does not tackle as expansive of a range of use cases as [pin-project] does. If your use case is not already covered, please use [pin-project].
66
67### Different: No proc-macro related dependencies
68
69This is the **only** reason to use this crate. However, **if you already have proc-macro related dependencies in your crate's dependency graph, there is no benefit from using this crate.** (Note: There is almost no difference in the amount of code generated between [pin-project] and pin-project-lite.)
70
71### Different: No useful error messages
72
73This macro does not handle any invalid input. So error messages are not to be useful in most cases. If you do need useful error messages, then upon error you can pass the same input to [pin-project] to receive a helpful description of the compile error.
74
75### Different: Structs only
76
77pin-project-lite will refuse anything other than a braced struct with named fields. Enums and tuple structs are not supported.
78
79### Different: No support for custom Drop implementation
80
81pin-project supports this by [`#[pinned_drop]`][pinned-drop].
82
83### Different: No support for custom Unpin implementation
84
85pin-project supports this by [`UnsafeUnpin`][unsafe-unpin] and [`!Unpin`][not-unpin].
86
87### Different: No support for pattern matching and destructing
88
89[pin-project supports this.][naming]
90
91[`pin_project!`]: https://docs.rs/pin-project-lite/0.1/pin_project_lite/macro.pin_project.html
92[naming]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html
93[not-unpin]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unpin
94[pin-project]: https://github.com/taiki-e/pin-project
95[pinned-drop]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#pinned_drop
96[unsafe-unpin]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unsafeunpin
97
98## License
99
100Licensed under either of
101
102* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
103* MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
104
105at your option.
106
107### Contribution
108
109Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
110
