1 | // This file is part of ICU4X. For terms of use, please see the file |
2 | // called LICENSE at the top level of the ICU4X source tree |
3 | // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). |
4 | |
5 | #[cfg (feature = "alloc" )] |
6 | use alloc::borrow::{Cow, ToOwned}; |
7 | #[cfg (feature = "alloc" )] |
8 | use alloc::string::String; |
9 | |
10 | /// Trait for types that can be created from a reference to a different type `C` with no allocations, |
11 | /// i.e. a zero-copy (zero-alloc) version of "From" |
12 | /// |
13 | /// A type can be the `ZeroFrom` target of multiple other types. |
14 | /// |
15 | /// The intention is for `ZeroFrom` to produce a struct from a other with as little work as |
16 | /// possible. Although it is technically possible to implement `ZeroFrom` without being |
17 | /// zero-copy (using heap allocations), doing so defeats the purpose of `ZeroFrom`. |
18 | /// |
19 | /// For example, `impl ZeroFrom<C> for Cow<str>` should return a `Cow::Borrowed` pointing at |
20 | /// data in the other type `C`, even if the other type is itself fully owned. |
21 | /// |
22 | /// One can use the [`#[derive(ZeroFrom)]`](zerofrom_derive::ZeroFrom) custom derive to automatically |
23 | /// implement this trait. |
24 | /// |
25 | /// # Examples |
26 | /// |
27 | /// Implementing `ZeroFrom` on a custom data struct: |
28 | /// |
29 | /// ``` |
30 | /// use std::borrow::Cow; |
31 | /// use zerofrom::ZeroFrom; |
32 | /// |
33 | /// struct MyStruct<'data> { |
34 | /// message: Cow<'data, str>, |
35 | /// } |
36 | /// |
37 | /// // Reference from a borrowed version of self |
38 | /// impl<'zf> ZeroFrom<'zf, MyStruct<'_>> for MyStruct<'zf> { |
39 | /// fn zero_from(other: &'zf MyStruct<'_>) -> Self { |
40 | /// MyStruct { |
41 | /// message: Cow::Borrowed(&other.message), |
42 | /// } |
43 | /// } |
44 | /// } |
45 | /// |
46 | /// // Reference from a string slice directly |
47 | /// impl<'zf> ZeroFrom<'zf, str> for MyStruct<'zf> { |
48 | /// fn zero_from(other: &'zf str) -> Self { |
49 | /// MyStruct { |
50 | /// message: Cow::Borrowed(other), |
51 | /// } |
52 | /// } |
53 | /// } |
54 | /// ``` |
55 | pub trait ZeroFrom<'zf, C: ?Sized>: 'zf { |
56 | /// Clone the other `C` into a struct that may retain references into `C`. |
57 | fn zero_from(other: &'zf C) -> Self; |
58 | } |
59 | |
60 | // Note: The following could be blanket implementations, but that would require constraining the |
61 | // blanket `T` on `T: 'static`, which may not be desirable for all downstream users who may wish |
62 | // to customize their `ZeroFrom` impl. The blanket implementation may be safe once Rust has |
63 | // specialization. |
64 | |
65 | #[cfg (feature = "alloc" )] |
66 | impl<'zf> ZeroFrom<'zf, str> for Cow<'zf, str> { |
67 | #[inline ] |
68 | fn zero_from(other: &'zf str) -> Self { |
69 | Cow::Borrowed(other) |
70 | } |
71 | } |
72 | |
73 | #[cfg (feature = "alloc" )] |
74 | impl<'zf> ZeroFrom<'zf, String> for Cow<'zf, str> { |
75 | #[inline ] |
76 | fn zero_from(other: &'zf String) -> Self { |
77 | Cow::Borrowed(other) |
78 | } |
79 | } |
80 | |
81 | impl<'zf> ZeroFrom<'zf, str> for &'zf str { |
82 | #[inline ] |
83 | fn zero_from(other: &'zf str) -> Self { |
84 | other |
85 | } |
86 | } |
87 | |
88 | #[cfg (feature = "alloc" )] |
89 | impl<'zf> ZeroFrom<'zf, String> for &'zf str { |
90 | #[inline ] |
91 | fn zero_from(other: &'zf String) -> Self { |
92 | other |
93 | } |
94 | } |
95 | |
96 | impl<'zf, C, T: ZeroFrom<'zf, C>> ZeroFrom<'zf, Option<C>> for Option<T> { |
97 | fn zero_from(other: &'zf Option<C>) -> Self { |
98 | other.as_ref().map(|c: &C| <T as ZeroFrom<C>>::zero_from(c)) |
99 | } |
100 | } |
101 | |
102 | // These duplicate the functionality from above and aren't quite necessary due |
103 | // to deref coercions, however for the custom derive to work, there always needs |
104 | // to be `impl ZeroFrom<T> for T`, otherwise it may fail to perform the necessary |
105 | // type inference. Deref coercions do not typically work when sufficient generics |
106 | // or inference are involved, and the proc macro does not necessarily have |
107 | // enough type information to figure this out on its own. |
108 | #[cfg (feature = "alloc" )] |
109 | impl<'zf, B: ToOwned + ?Sized> ZeroFrom<'zf, Cow<'_, B>> for Cow<'zf, B> { |
110 | #[inline ] |
111 | fn zero_from(other: &'zf Cow<'_, B>) -> Self { |
112 | Cow::Borrowed(other) |
113 | } |
114 | } |
115 | |
116 | impl<'zf, T: ?Sized> ZeroFrom<'zf, &'_ T> for &'zf T { |
117 | #[inline ] |
118 | fn zero_from(other: &'zf &'_ T) -> &'zf T { |
119 | other |
120 | } |
121 | } |
122 | |
123 | impl<'zf, T> ZeroFrom<'zf, [T]> for &'zf [T] { |
124 | #[inline ] |
125 | fn zero_from(other: &'zf [T]) -> &'zf [T] { |
126 | other |
127 | } |
128 | } |
129 | |