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