README.md
1# pin-project
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.svg
9[crates-url]: https://crates.io/crates/pin-project
10[docs-badge]: https://docs.rs/pin-project/badge.svg
11[docs-url]: https://docs.rs/pin-project
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.34+-lightgray.svg
15[rustc-url]: https://blog.rust-lang.org/2019/04/11/Rust-1.34.0.html
16
17A crate for safe and ergonomic [pin-projection].
18
19## Usage
20
21Add this to your `Cargo.toml`:
22
23```toml
24[dependencies]
25pin-project = "0.4"
26```
27
28The current pin-project requires Rust 1.34 or later.
29
30## Examples
31
32[`#[pin_project]`][`pin_project`] attribute creates projection types
33covering all the fields of struct or enum.
34
35```rust
36use pin_project::pin_project;
37use std::pin::Pin;
38
39#[pin_project]
40struct Struct<T, U> {
41 #[pin]
42 pinned: T,
43 unpinned: U,
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[*code like this will be generated*][struct-default-expanded]
56
57See [documentation][docs-url] for more details, and
58see [examples] directory for more examples and generated code.
59
60[`pin_project`]: https://docs.rs/pin-project/0.4/pin_project/attr.pin_project.html
61[examples]: examples/README.md
62[pin-projection]: https://doc.rust-lang.org/nightly/std/pin/index.html#projections-and-structural-pinning
63[struct-default-expanded]: examples/struct-default-expanded.rs
64
65## Related Projects
66
67* [pin-project-lite]: A lightweight version of pin-project written with declarative macros.
68
69[pin-project-lite]: https://github.com/taiki-e/pin-project-lite
70
71## License
72
73Licensed under either of
74
75* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
76* MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
77
78at your option.
79
80### Contribution
81
82Unless 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.
83
