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