zerofrom/
zero_from.rs

Help
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
5use core::marker::PhantomData;
6
7#[cfg(feature = "alloc")]
8use alloc::borrow::{Cow, ToOwned};
9#[cfg(feature = "alloc")]
10use 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/// ```
57pub 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")]
68impl<'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")]
76impl<'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
83impl<'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")]
91impl<'zf> ZeroFrom<'zf, String> for &'zf str {
92    #[inline]
93    fn zero_from(other: &'zf String) -> Self {
94        other
95    }
96}
97
98impl<'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| <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")]
111impl<'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
118impl<'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
125impl<'zf, T> ZeroFrom<'zf, [T]> for &'zf [T] {
126    #[inline]
127    fn zero_from(other: &'zf [T]) -> &'zf [T] {
128        other
129    }
130}
131
132impl<'zf, T: ?Sized + 'zf> ZeroFrom<'zf, PhantomData<T>> for PhantomData<T> {
133    fn zero_from(other: &'zf PhantomData<T>) -> Self {
134        *other
135    }
136}
zerofrom/zero_from.rs

zerofrom/
zero_from.rs
