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