1  #![allow(clippy::legacy_numeric_constants)]
2  
3  use super::*;
4  
5  /// A trait indicating that:
6  ///
7  /// 1. A type has an equivalent representation to some known integral type.
8  /// 2. All instances of this type fall in a fixed range of values.
9  /// 3. Within that range, there are no gaps.
10  ///
11  /// This is generally useful for fieldless enums (aka "c-style" enums), however
12  /// it's important that it only be used for those with an explicit `#[repr]`, as
13  /// `#[repr(Rust)]` fieldess enums have an unspecified layout.
14  ///
15  /// Additionally, you shouldn't assume that all implementations are enums. Any
16  /// type which meets the requirements above while following the rules under
17  /// "Safety" below is valid.
18  ///
19  /// # Example
20  ///
21  /// ```
22  /// # use bytemuck::Contiguous;
23  /// #[repr(u8)]
24  /// #[derive(Debug, Copy, Clone, PartialEq)]
25  /// enum Foo {
26  ///   A = 0,
27  ///   B = 1,
28  ///   C = 2,
29  ///   D = 3,
30  ///   E = 4,
31  /// }
32  /// unsafe impl Contiguous for Foo {
33  ///   type Int = u8;
34  ///   const MIN_VALUE: u8 = Foo::A as u8;
35  ///   const MAX_VALUE: u8 = Foo::E as u8;
36  /// }
37  /// assert_eq!(Foo::from_integer(3).unwrap(), Foo::D);
38  /// assert_eq!(Foo::from_integer(8), None);
39  /// assert_eq!(Foo::C.into_integer(), 2);
40  /// ```
41  /// # Safety
42  ///
43  /// This is an unsafe trait, and incorrectly implementing it is undefined
44  /// behavior.
45  ///
46  /// Informally, by implementing it, you're asserting that `C` is identical to
47  /// the integral type `C::Int`, and that every `C` falls between `C::MIN_VALUE`
48  /// and `C::MAX_VALUE` exactly once, without any gaps.
49  ///
50  /// Precisely, the guarantees you must uphold when implementing `Contiguous` for
51  /// some type `C` are:
52  ///
53  /// 1. The size of `C` and `C::Int` must be the same, and neither may be a ZST.
54  ///    (Note: alignment is explicitly allowed to differ)
55  ///
56  /// 2. `C::Int` must be a primitive integer, and not a wrapper type. In the
57  ///    future, this may be lifted to include cases where the behavior is
58  ///    identical for a relevant set of traits (Ord, arithmetic, ...).
59  ///
60  /// 3. All `C::Int`s which are in the *inclusive* range between `C::MIN_VALUE`
61  ///    and `C::MAX_VALUE` are bitwise identical to unique valid instances of
62  ///    `C`.
63  ///
64  /// 4. There exist no instances of `C` such that their bitpatterns, when
65  ///    interpreted as instances of `C::Int`, fall outside of the `MAX_VALUE` /
66  ///    `MIN_VALUE` range -- It is legal for unsafe code to assume that if it
67  ///    gets a `C` that implements `Contiguous`, it is in the appropriate range.
68  ///
69  /// 5. Finally, you promise not to provide overridden implementations of
70  ///    `Contiguous::from_integer` and `Contiguous::into_integer`.
71  ///
72  /// For clarity, the following rules could be derived from the above, but are
73  /// listed explicitly:
74  ///
75  /// - `C::MAX_VALUE` must be greater or equal to `C::MIN_VALUE` (therefore, `C`
76  ///   must be an inhabited type).
77  ///
78  /// - There exist no two values between `MIN_VALUE` and `MAX_VALUE` such that
79  ///   when interpreted as a `C` they are considered identical (by, say, match).
80  pub unsafe trait Contiguous: Copy + 'static {
81    /// The primitive integer type with an identical representation to this
82    /// type.
83    ///
84    /// Contiguous is broadly intended for use with fieldless enums, and for
85    /// these the correct integer type is easy: The enum should have a
86    /// `#[repr(Int)]` or `#[repr(C)]` attribute, (if it does not, it is
87    /// *unsound* to implement `Contiguous`!).
88    ///
89    /// - For `#[repr(Int)]`, use the listed `Int`. e.g. `#[repr(u8)]` should use
90    ///   `type Int = u8`.
91    ///
92    /// - For `#[repr(C)]`, use whichever type the C compiler will use to
93    ///   represent the given enum. This is usually `c_int` (from `std::os::raw`
94    ///   or `libc`), but it's up to you to make the determination as the
95    ///   implementer of the unsafe trait.
96    ///
97    /// For precise rules, see the list under "Safety" above.
98    type Int: Copy + Ord;
99  
100    /// The upper *inclusive* bound for valid instances of this type.
101    const MAX_VALUE: Self::Int;
102  
103    /// The lower *inclusive* bound for valid instances of this type.
104    const MIN_VALUE: Self::Int;
105  
106    /// If `value` is within the range for valid instances of this type,
107    /// returns `Some(converted_value)`, otherwise, returns `None`.
108    ///
109    /// This is a trait method so that you can write `value.into_integer()` in
110    /// your code. It is a contract of this trait that if you implement
111    /// `Contiguous` on your type you **must not** override this method.
112    ///
113    /// # Panics
114    ///
115    /// We will not panic for any correct implementation of `Contiguous`, but
116    /// *may* panic if we detect an incorrect one.
117    ///
118    /// This is undefined behavior regardless, so it could have been the nasal
119    /// demons at that point anyway ;).
120    #[inline]
121    #[cfg_attr(feature = "track_caller", track_caller)]
from_integer(value: Self::Int) -> Option<Self>122    fn from_integer(value: Self::Int) -> Option<Self> {
123      // Guard against an illegal implementation of Contiguous. Annoyingly we
124      // can't rely on `transmute` to do this for us (see below), but
125      // whatever, this gets compiled into nothing in release.
126      assert!(size_of::<Self>() == size_of::<Self::Int>());
127      if Self::MIN_VALUE <= value && value <= Self::MAX_VALUE {
128        // SAFETY: We've checked their bounds (and their size, even though
129        // they've sworn under the Oath Of Unsafe Rust that that already
130        // matched) so this is allowed by `Contiguous`'s unsafe contract.
131        //
132        // So, the `transmute!`. ideally we'd use transmute here, which
133        // is more obviously safe. Sadly, we can't, as these types still
134        // have unspecified sizes.
135        Some(unsafe { transmute!(value) })
136      } else {
137        None
138      }
139    }
140  
141    /// Perform the conversion from `C` into the underlying integral type. This
142    /// mostly exists otherwise generic code would need unsafe for the `value as
143    /// integer`
144    ///
145    /// This is a trait method so that you can write `value.into_integer()` in
146    /// your code. It is a contract of this trait that if you implement
147    /// `Contiguous` on your type you **must not** override this method.
148    ///
149    /// # Panics
150    ///
151    /// We will not panic for any correct implementation of `Contiguous`, but
152    /// *may* panic if we detect an incorrect one.
153    ///
154    /// This is undefined behavior regardless, so it could have been the nasal
155    /// demons at that point anyway ;).
156    #[inline]
157    #[cfg_attr(feature = "track_caller", track_caller)]
into_integer(self) -> Self::Int158    fn into_integer(self) -> Self::Int {
159      // Guard against an illegal implementation of Contiguous. Annoyingly we
160      // can't rely on `transmute` to do the size check for us (see
161      // `from_integer's comment`), but whatever, this gets compiled into
162      // nothing in release. Note that we don't check the result of cast
163      assert!(size_of::<Self>() == size_of::<Self::Int>());
164  
165      // SAFETY: The unsafe contract requires that these have identical
166      // representations, and that the range be entirely valid. Using
167      // transmute! instead of transmute here is annoying, but is required
168      // as `Self` and `Self::Int` have unspecified sizes still.
169      unsafe { transmute!(self) }
170    }
171  }
172  
173  macro_rules! impl_contiguous {
174    ($($src:ty as $repr:ident in [$min:expr, $max:expr];)*) => {$(
175      unsafe impl Contiguous for $src {
176        type Int = $repr;
177        const MAX_VALUE: $repr = $max;
178        const MIN_VALUE: $repr = $min;
179      }
180    )*};
181  }
182  
183  impl_contiguous! {
184    bool as u8 in [0, 1];
185  
186    u8 as u8 in [0, u8::max_value()];
187    u16 as u16 in [0, u16::max_value()];
188    u32 as u32 in [0, u32::max_value()];
189    u64 as u64 in [0, u64::max_value()];
190    u128 as u128 in [0, u128::max_value()];
191    usize as usize in [0, usize::max_value()];
192  
193    i8 as i8 in [i8::min_value(), i8::max_value()];
194    i16 as i16 in [i16::min_value(), i16::max_value()];
195    i32 as i32 in [i32::min_value(), i32::max_value()];
196    i64 as i64 in [i64::min_value(), i64::max_value()];
197    i128 as i128 in [i128::min_value(), i128::max_value()];
198    isize as isize in [isize::min_value(), isize::max_value()];
199  
200    NonZeroU8 as u8 in [1, u8::max_value()];
201    NonZeroU16 as u16 in [1, u16::max_value()];
202    NonZeroU32 as u32 in [1, u32::max_value()];
203    NonZeroU64 as u64 in [1, u64::max_value()];
204    NonZeroU128 as u128 in [1, u128::max_value()];
205    NonZeroUsize as usize in [1, usize::max_value()];
206  }
207