zerofrom/
zero_from.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).

use core::marker::PhantomData;

#[cfg(feature = "alloc")]
use alloc::borrow::{Cow, ToOwned};
#[cfg(feature = "alloc")]
use alloc::string::String;

/// Trait for types that can be created from a reference to a different type `C` with no allocations,
/// i.e. a zero-copy (zero-alloc) version of "From"
///
/// A type can be the `ZeroFrom` target of multiple other types.
///
/// The intention is for `ZeroFrom` to produce a struct from a other with as little work as
/// possible. Although it is technically possible to implement `ZeroFrom` without being
/// zero-copy (using heap allocations), doing so defeats the purpose of `ZeroFrom`.
///
/// For example, `impl ZeroFrom<C> for Cow<str>` should return a `Cow::Borrowed` pointing at
/// data in the other type `C`, even if the other type is itself fully owned.
///
/// One can use the [`#[derive(ZeroFrom)]`](zerofrom_derive::ZeroFrom) custom derive to automatically
/// implement this trait.
///
/// # Examples
///
/// Implementing `ZeroFrom` on a custom data struct:
///
/// ```
/// use std::borrow::Cow;
/// use zerofrom::ZeroFrom;
///
/// struct MyStruct<'data> {
///     message: Cow<'data, str>,
/// }
///
/// // Reference from a borrowed version of self
/// impl<'zf> ZeroFrom<'zf, MyStruct<'_>> for MyStruct<'zf> {
///     fn zero_from(other: &'zf MyStruct<'_>) -> Self {
///         MyStruct {
///             message: Cow::Borrowed(&other.message),
///         }
///     }
/// }
///
/// // Reference from a string slice directly
/// impl<'zf> ZeroFrom<'zf, str> for MyStruct<'zf> {
///     fn zero_from(other: &'zf str) -> Self {
///         MyStruct {
///             message: Cow::Borrowed(other),
///         }
///     }
/// }
/// ```
pub trait ZeroFrom<'zf, C: ?Sized>: 'zf {
    /// Clone the other `C` into a struct that may retain references into `C`.
    fn zero_from(other: &'zf C) -> Self;
}

// Note: The following could be blanket implementations, but that would require constraining the
// blanket `T` on `T: 'static`, which may not be desirable for all downstream users who may wish
// to customize their `ZeroFrom` impl. The blanket implementation may be safe once Rust has
// specialization.

#[cfg(feature = "alloc")]
impl<'zf> ZeroFrom<'zf, str> for Cow<'zf, str> {
    #[inline]
    fn zero_from(other: &'zf str) -> Self {
        Cow::Borrowed(other)
    }
}

#[cfg(feature = "alloc")]
impl<'zf> ZeroFrom<'zf, String> for Cow<'zf, str> {
    #[inline]
    fn zero_from(other: &'zf String) -> Self {
        Cow::Borrowed(other)
    }
}

impl<'zf> ZeroFrom<'zf, str> for &'zf str {
    #[inline]
    fn zero_from(other: &'zf str) -> Self {
        other
    }
}

#[cfg(feature = "alloc")]
impl<'zf> ZeroFrom<'zf, String> for &'zf str {
    #[inline]
    fn zero_from(other: &'zf String) -> Self {
        other
    }
}

impl<'zf, C, T: ZeroFrom<'zf, C>> ZeroFrom<'zf, Option<C>> for Option<T> {
    fn zero_from(other: &'zf Option<C>) -> Self {
        other.as_ref().map(|c| <T as ZeroFrom<C>>::zero_from(c))
    }
}

// These duplicate the functionality from above and aren't quite necessary due
// to deref coercions, however for the custom derive to work, there always needs
// to be `impl ZeroFrom<T> for T`, otherwise it may fail to perform the necessary
// type inference. Deref coercions do not typically work when sufficient generics
// or inference are involved, and the proc macro does not necessarily have
// enough type information to figure this out on its own.
#[cfg(feature = "alloc")]
impl<'zf, B: ToOwned + ?Sized> ZeroFrom<'zf, Cow<'_, B>> for Cow<'zf, B> {
    #[inline]
    fn zero_from(other: &'zf Cow<'_, B>) -> Self {
        Cow::Borrowed(other)
    }
}

impl<'zf, T: ?Sized> ZeroFrom<'zf, &'_ T> for &'zf T {
    #[inline]
    fn zero_from(other: &'zf &'_ T) -> &'zf T {
        other
    }
}

impl<'zf, T> ZeroFrom<'zf, [T]> for &'zf [T] {
    #[inline]
    fn zero_from(other: &'zf [T]) -> &'zf [T] {
        other
    }
}

impl<'zf, T: ?Sized + 'zf> ZeroFrom<'zf, PhantomData<T>> for PhantomData<T> {
    fn zero_from(other: &'zf PhantomData<T>) -> Self {
        *other
    }
}