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")]
6use alloc::borrow::{Cow, ToOwned};
7#[cfg(feature = "alloc")]
8use 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/// ```
55pub 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")]
66impl<'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")]
74impl<'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
81impl<'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")]
89impl<'zf> ZeroFrom<'zf, String> for &'zf str {
90 #[inline]
91 fn zero_from(other: &'zf String) -> Self {
92 other
93 }
94}
95
96impl<'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")]
109impl<'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
116impl<'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
123impl<'zf, T> ZeroFrom<'zf, [T]> for &'zf [T] {
124 #[inline]
125 fn zero_from(other: &'zf [T]) -> &'zf [T] {
126 other
127 }
128}
129