projects / rustc.git / blame
| Commit | Line | Data |
|---|---|---|
| f035d41b XL |
1 | # thin-dst |
| 2 | ||
| 3 | Boxed custom DSTs that store a slice and the length of said slice inline. | |
| 4 | Uses the standard library collection types for full interoperability, | |
| 5 | and also provides thin owned pointers for space-conscious use. | |
| 6 | ||
| 7 | ## Alternative | |
| 8 | ||
| 9 | [slice-dst] is a successor to this crate, which, along with the other | |
| 10 | [pointer-utils] crates, offers a more composable API. | |
| 11 | ||
| 12 | This crate will continue to be reactively maintained, | |
| 13 | but any future development will focus on pointer-utils/slice-dst instead. | |
| 14 | ||
| 15 | [slice-dst]: <https://lib.rs/crates/slice-dst> | |
| 16 | [pointer-utils]: <https://github.com/CAD97/pointer-utils> | |
| 17 | ||
| 18 | ## Examples | |
| 19 | ||
| 20 | The simplest example is just a boxed slice: | |
| 21 | ||
| 22 | ```rust | |
| 23 | let boxed_slice = ThinBox::new((), vec![0, 1, 2, 3, 4, 5]); | |
| 24 | assert_eq!(&*boxed_slice, &[0, 1, 2, 3, 4, 5][..]); | |
| 25 | let boxed_slice: Box<ThinData<(), u32>> = boxed_slice.into(); | |
| 26 | ``` | |
| 27 | ||
| 28 | All of the thin collection types are constructed with a "head" and a "tail". | |
| 29 | The head is any `Sized` type that you would like to associate with the slice. | |
| 30 | The "tail" is the owned slice of data that you would like to store. | |
| 31 | ||
| 32 | This creates a collection of `ThinData`, which acts like `{ head, tail }`, | |
| 33 | and also handles the `unsafe` required for both custom slice DSTs and thin DST pointers. | |
| 34 | The most idiomatic usage is to encapsulate the use of thin-dst with a transparent newtype: | |
| 35 | ||
| 36 | ```rust | |
| 37 | #[repr(transparent)] | |
| 38 | struct NodeData(ThinData<NodeHead, Node>); | |
| 39 | struct Node(ThinArc<NodeHead, Node>); | |
| 40 | ``` | |
| 41 | ||
| 42 | And then use `NodeData` by transmuting and/or [ref-cast]ing as needed. | |
| 43 | ||
| 44 | [ref-cast]: <https://lib.rs/crates/ref-cast> | |
| 45 | ||
| 46 | ## License | |
| 47 | ||
| 48 | Licensed under either of | |
| 49 | ||
| 50 | * Apache License, Version 2.0 | |
| 51 | ([LICENSE/APACHE](LICENSE/APACHE) or http://www.apache.org/licenses/LICENSE-2.0) | |
| 52 | * MIT license | |
| 53 | ([LICENSE/MIT](LICENSE/MIT) or http://opensource.org/licenses/MIT) | |
| 54 | ||
| 55 | at your option. | |
| 56 | ||
| 57 | If you are a highly paid worker at any company that prioritises profit over | |
| 58 | people, you can still use this crate. I simply wish you will unionise and push | |
| 59 | back against the obsession for growth, control, and power that is rampant in | |
| 60 | your workplace. Please take a stand against the horrible working conditions | |
| 61 | they inflict on your lesser paid colleagues, and more generally their | |
| 62 | disrespect for the very human rights they claim to fight for. | |
| 63 | ||
| 64 | ## Contribution | |
| 65 | ||
| 66 | Unless you explicitly state otherwise, any contribution intentionally submitted | |
| 67 | for inclusion in the work by you, as defined in the Apache-2.0 license, shall be | |
| 68 | dual licensed as above, without any additional terms or conditions. |