aboutsummaryrefslogtreecommitdiff
path: root/src/checked.rs
diff options
context:
space:
mode:
Diffstat (limited to 'src/checked.rs')
-rw-r--r--src/checked.rs527
1 files changed, 527 insertions, 0 deletions
diff --git a/src/checked.rs b/src/checked.rs
new file mode 100644
index 0000000..2d97340
--- /dev/null
+++ b/src/checked.rs
@@ -0,0 +1,527 @@
+//! Checked versions of the casting functions exposed in crate root
+//! that support [`CheckedBitPattern`] types.
+
+use crate::{
+ internal::{self, something_went_wrong},
+ AnyBitPattern, NoUninit,
+};
+
+/// A marker trait that allows types that have some invalid bit patterns to be
+/// used in places that otherwise require [`AnyBitPattern`] or [`Pod`] types by
+/// performing a runtime check on a perticular set of bits. This is particularly
+/// useful for types like fieldless ('C-style') enums, [`char`], bool, and
+/// structs containing them.
+///
+/// To do this, we define a `Bits` type which is a type with equivalent layout
+/// to `Self` other than the invalid bit patterns which disallow `Self` from
+/// being [`AnyBitPattern`]. This `Bits` type must itself implement
+/// [`AnyBitPattern`]. Then, we implement a function that checks whether a
+/// certain instance of the `Bits` is also a valid bit pattern of `Self`. If
+/// this check passes, then we can allow casting from the `Bits` to `Self` (and
+/// therefore, any type which is able to be cast to `Bits` is also able to be
+/// cast to `Self`).
+///
+/// [`AnyBitPattern`] is a subset of [`CheckedBitPattern`], meaning that any `T:
+/// AnyBitPattern` is also [`CheckedBitPattern`]. This means you can also use
+/// any [`AnyBitPattern`] type in the checked versions of casting functions in
+/// this module. If it's possible, prefer implementing [`AnyBitPattern`] for
+/// your type directly instead of [`CheckedBitPattern`] as it gives greater
+/// flexibility.
+///
+/// # Derive
+///
+/// A `#[derive(CheckedBitPattern)]` macro is provided under the `derive`
+/// feature flag which will automatically validate the requirements of this
+/// trait and implement the trait for you for both enums and structs. This is
+/// the recommended method for implementing the trait, however it's also
+/// possible to do manually.
+///
+/// # Example
+///
+/// If manually implementing the trait, we can do something like so:
+///
+/// ```rust
+/// use bytemuck::{CheckedBitPattern, NoUninit};
+///
+/// #[repr(u32)]
+/// #[derive(Copy, Clone)]
+/// enum MyEnum {
+/// Variant0 = 0,
+/// Variant1 = 1,
+/// Variant2 = 2,
+/// }
+///
+/// unsafe impl CheckedBitPattern for MyEnum {
+/// type Bits = u32;
+///
+/// fn is_valid_bit_pattern(bits: &u32) -> bool {
+/// match *bits {
+/// 0 | 1 | 2 => true,
+/// _ => false,
+/// }
+/// }
+/// }
+///
+/// // It is often useful to also implement `NoUninit` on our `CheckedBitPattern` types.
+/// // This will allow us to do casting of mutable references (and mutable slices).
+/// // It is not always possible to do so, but in this case we have no padding so it is.
+/// unsafe impl NoUninit for MyEnum {}
+/// ```
+///
+/// We can now use relevant casting functions. For example,
+///
+/// ```rust
+/// # use bytemuck::{CheckedBitPattern, NoUninit};
+/// # #[repr(u32)]
+/// # #[derive(Copy, Clone, PartialEq, Eq, Debug)]
+/// # enum MyEnum {
+/// # Variant0 = 0,
+/// # Variant1 = 1,
+/// # Variant2 = 2,
+/// # }
+/// # unsafe impl NoUninit for MyEnum {}
+/// # unsafe impl CheckedBitPattern for MyEnum {
+/// # type Bits = u32;
+/// # fn is_valid_bit_pattern(bits: &u32) -> bool {
+/// # match *bits {
+/// # 0 | 1 | 2 => true,
+/// # _ => false,
+/// # }
+/// # }
+/// # }
+/// use bytemuck::{bytes_of, bytes_of_mut};
+/// use bytemuck::checked;
+///
+/// let bytes = bytes_of(&2u32);
+/// let result = checked::try_from_bytes::<MyEnum>(bytes);
+/// assert_eq!(result, Ok(&MyEnum::Variant2));
+///
+/// // Fails for invalid discriminant
+/// let bytes = bytes_of(&100u32);
+/// let result = checked::try_from_bytes::<MyEnum>(bytes);
+/// assert!(result.is_err());
+///
+/// // Since we implemented NoUninit, we can also cast mutably from an original type
+/// // that is `NoUninit + AnyBitPattern`:
+/// let mut my_u32 = 2u32;
+/// {
+/// let as_enum_mut = checked::cast_mut::<_, MyEnum>(&mut my_u32);
+/// assert_eq!(as_enum_mut, &mut MyEnum::Variant2);
+/// *as_enum_mut = MyEnum::Variant0;
+/// }
+/// assert_eq!(my_u32, 0u32);
+/// ```
+///
+/// # Safety
+///
+/// * `Self` *must* have the same layout as the specified `Bits` except for
+/// the possible invalid bit patterns being checked during
+/// [`is_valid_bit_pattern`].
+/// * This almost certainly means your type must be `#[repr(C)]` or a similar
+/// specified repr, but if you think you know better, you probably don't. If
+/// you still think you know better, be careful and have fun. And don't mess
+/// it up (I mean it).
+/// * If [`is_valid_bit_pattern`] returns true, then the bit pattern contained
+/// in `bits` must also be valid for an instance of `Self`.
+/// * Probably more, don't mess it up (I mean it 2.0)
+///
+/// [`is_valid_bit_pattern`]: CheckedBitPattern::is_valid_bit_pattern
+/// [`Pod`]: crate::Pod
+pub unsafe trait CheckedBitPattern: Copy {
+ /// `Self` *must* have the same layout as the specified `Bits` except for
+ /// the possible invalid bit patterns being checked during
+ /// [`is_valid_bit_pattern`].
+ ///
+ /// [`is_valid_bit_pattern`]: CheckedBitPattern::is_valid_bit_pattern
+ type Bits: AnyBitPattern;
+
+ /// If this function returns true, then it must be valid to reinterpret `bits`
+ /// as `&Self`.
+ fn is_valid_bit_pattern(bits: &Self::Bits) -> bool;
+}
+
+unsafe impl<T: AnyBitPattern> CheckedBitPattern for T {
+ type Bits = T;
+
+ #[inline(always)]
+ fn is_valid_bit_pattern(_bits: &T) -> bool {
+ true
+ }
+}
+
+unsafe impl CheckedBitPattern for char {
+ type Bits = u32;
+
+ #[inline]
+ fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
+ core::char::from_u32(*bits).is_some()
+ }
+}
+
+unsafe impl CheckedBitPattern for bool {
+ type Bits = u8;
+
+ #[inline]
+ fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
+ match *bits {
+ 0 | 1 => true,
+ _ => false,
+ }
+ }
+}
+
+macro_rules! impl_checked_for_nonzero {
+ ($($nonzero:ty: $primitive:ty),* $(,)?) => {
+ $(
+ unsafe impl CheckedBitPattern for $nonzero {
+ type Bits = $primitive;
+
+ #[inline]
+ fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
+ // Note(zachs18): The size and alignment check are almost certainly
+ // not necessary, but Rust currently doesn't explicitly document that
+ // NonZero[int] has the same layout as [int], so we check it to be safe.
+ // In a const to reduce debug-profile overhead.
+ const LAYOUT_SAME: bool =
+ core::mem::size_of::<$nonzero>() == core::mem::size_of::<$primitive>()
+ && core::mem::align_of::<$nonzero>() == core::mem::align_of::<$primitive>();
+ LAYOUT_SAME && *bits != 0
+ }
+ }
+ )*
+ };
+}
+impl_checked_for_nonzero! {
+ core::num::NonZeroU8: u8,
+ core::num::NonZeroI8: i8,
+ core::num::NonZeroU16: u16,
+ core::num::NonZeroI16: i16,
+ core::num::NonZeroU32: u32,
+ core::num::NonZeroI32: i32,
+ core::num::NonZeroU64: u64,
+ core::num::NonZeroI64: i64,
+ core::num::NonZeroI128: i128,
+ core::num::NonZeroU128: u128,
+ core::num::NonZeroUsize: usize,
+ core::num::NonZeroIsize: isize,
+}
+
+/// The things that can go wrong when casting between [`CheckedBitPattern`] data
+/// forms.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum CheckedCastError {
+ /// An error occurred during a true-[`Pod`] cast
+ ///
+ /// [`Pod`]: crate::Pod
+ PodCastError(crate::PodCastError),
+ /// When casting to a [`CheckedBitPattern`] type, it is possible that the
+ /// original data contains an invalid bit pattern. If so, the cast will
+ /// fail and this error will be returned. Will never happen on casts
+ /// between [`Pod`] types.
+ ///
+ /// [`Pod`]: crate::Pod
+ InvalidBitPattern,
+}
+
+#[cfg(not(target_arch = "spirv"))]
+impl core::fmt::Display for CheckedCastError {
+ fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+ write!(f, "{:?}", self)
+ }
+}
+#[cfg(feature = "extern_crate_std")]
+impl std::error::Error for CheckedCastError {}
+
+impl From<crate::PodCastError> for CheckedCastError {
+ fn from(err: crate::PodCastError) -> CheckedCastError {
+ CheckedCastError::PodCastError(err)
+ }
+}
+
+/// Re-interprets `&[u8]` as `&T`.
+///
+/// ## Failure
+///
+/// * If the slice isn't aligned for the new type
+/// * If the slice's length isn’t exactly the size of the new type
+/// * If the slice contains an invalid bit pattern for `T`
+#[inline]
+pub fn try_from_bytes<T: CheckedBitPattern>(
+ s: &[u8],
+) -> Result<&T, CheckedCastError> {
+ let pod = unsafe { internal::try_from_bytes(s) }?;
+
+ if <T as CheckedBitPattern>::is_valid_bit_pattern(pod) {
+ Ok(unsafe { &*(pod as *const <T as CheckedBitPattern>::Bits as *const T) })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Re-interprets `&mut [u8]` as `&mut T`.
+///
+/// ## Failure
+///
+/// * If the slice isn't aligned for the new type
+/// * If the slice's length isn’t exactly the size of the new type
+/// * If the slice contains an invalid bit pattern for `T`
+#[inline]
+pub fn try_from_bytes_mut<T: CheckedBitPattern + NoUninit>(
+ s: &mut [u8],
+) -> Result<&mut T, CheckedCastError> {
+ let pod = unsafe { internal::try_from_bytes_mut(s) }?;
+
+ if <T as CheckedBitPattern>::is_valid_bit_pattern(pod) {
+ Ok(unsafe { &mut *(pod as *mut <T as CheckedBitPattern>::Bits as *mut T) })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Reads from the bytes as if they were a `T`.
+///
+/// ## Failure
+/// * If the `bytes` length is not equal to `size_of::<T>()`.
+/// * If the slice contains an invalid bit pattern for `T`
+#[inline]
+pub fn try_pod_read_unaligned<T: CheckedBitPattern>(
+ bytes: &[u8],
+) -> Result<T, CheckedCastError> {
+ let pod = unsafe { internal::try_pod_read_unaligned(bytes) }?;
+
+ if <T as CheckedBitPattern>::is_valid_bit_pattern(&pod) {
+ Ok(unsafe { transmute!(pod) })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Try to cast `T` into `U`.
+///
+/// Note that for this particular type of cast, alignment isn't a factor. The
+/// input value is semantically copied into the function and then returned to a
+/// new memory location which will have whatever the required alignment of the
+/// output type is.
+///
+/// ## Failure
+///
+/// * If the types don't have the same size this fails.
+/// * If `a` contains an invalid bit pattern for `B` this fails.
+#[inline]
+pub fn try_cast<A: NoUninit, B: CheckedBitPattern>(
+ a: A,
+) -> Result<B, CheckedCastError> {
+ let pod = unsafe { internal::try_cast(a) }?;
+
+ if <B as CheckedBitPattern>::is_valid_bit_pattern(&pod) {
+ Ok(unsafe { transmute!(pod) })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Try to convert a `&T` into `&U`.
+///
+/// ## Failure
+///
+/// * If the reference isn't aligned in the new type
+/// * If the source type and target type aren't the same size.
+/// * If `a` contains an invalid bit pattern for `B` this fails.
+#[inline]
+pub fn try_cast_ref<A: NoUninit, B: CheckedBitPattern>(
+ a: &A,
+) -> Result<&B, CheckedCastError> {
+ let pod = unsafe { internal::try_cast_ref(a) }?;
+
+ if <B as CheckedBitPattern>::is_valid_bit_pattern(pod) {
+ Ok(unsafe { &*(pod as *const <B as CheckedBitPattern>::Bits as *const B) })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Try to convert a `&mut T` into `&mut U`.
+///
+/// As [`try_cast_ref`], but `mut`.
+#[inline]
+pub fn try_cast_mut<
+ A: NoUninit + AnyBitPattern,
+ B: CheckedBitPattern + NoUninit,
+>(
+ a: &mut A,
+) -> Result<&mut B, CheckedCastError> {
+ let pod = unsafe { internal::try_cast_mut(a) }?;
+
+ if <B as CheckedBitPattern>::is_valid_bit_pattern(pod) {
+ Ok(unsafe { &mut *(pod as *mut <B as CheckedBitPattern>::Bits as *mut B) })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Try to convert `&[A]` into `&[B]` (possibly with a change in length).
+///
+/// * `input.as_ptr() as usize == output.as_ptr() as usize`
+/// * `input.len() * size_of::<A>() == output.len() * size_of::<B>()`
+///
+/// ## Failure
+///
+/// * If the target type has a greater alignment requirement and the input slice
+/// isn't aligned.
+/// * If the target element type is a different size from the current element
+/// type, and the output slice wouldn't be a whole number of elements when
+/// accounting for the size change (eg: 3 `u16` values is 1.5 `u32` values, so
+/// that's a failure).
+/// * Similarly, you can't convert between a [ZST](https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts)
+/// and a non-ZST.
+/// * If any element of the converted slice would contain an invalid bit pattern
+/// for `B` this fails.
+#[inline]
+pub fn try_cast_slice<A: NoUninit, B: CheckedBitPattern>(
+ a: &[A],
+) -> Result<&[B], CheckedCastError> {
+ let pod = unsafe { internal::try_cast_slice(a) }?;
+
+ if pod.iter().all(|pod| <B as CheckedBitPattern>::is_valid_bit_pattern(pod)) {
+ Ok(unsafe {
+ core::slice::from_raw_parts(pod.as_ptr() as *const B, pod.len())
+ })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Try to convert `&mut [A]` into `&mut [B]` (possibly with a change in
+/// length).
+///
+/// As [`try_cast_slice`], but `&mut`.
+#[inline]
+pub fn try_cast_slice_mut<
+ A: NoUninit + AnyBitPattern,
+ B: CheckedBitPattern + NoUninit,
+>(
+ a: &mut [A],
+) -> Result<&mut [B], CheckedCastError> {
+ let pod = unsafe { internal::try_cast_slice_mut(a) }?;
+
+ if pod.iter().all(|pod| <B as CheckedBitPattern>::is_valid_bit_pattern(pod)) {
+ Ok(unsafe {
+ core::slice::from_raw_parts_mut(pod.as_mut_ptr() as *mut B, pod.len())
+ })
+ } else {
+ Err(CheckedCastError::InvalidBitPattern)
+ }
+}
+
+/// Re-interprets `&[u8]` as `&T`.
+///
+/// ## Panics
+///
+/// This is [`try_from_bytes`] but will panic on error.
+#[inline]
+pub fn from_bytes<T: CheckedBitPattern>(s: &[u8]) -> &T {
+ match try_from_bytes(s) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("from_bytes", e),
+ }
+}
+
+/// Re-interprets `&mut [u8]` as `&mut T`.
+///
+/// ## Panics
+///
+/// This is [`try_from_bytes_mut`] but will panic on error.
+#[inline]
+pub fn from_bytes_mut<T: NoUninit + CheckedBitPattern>(s: &mut [u8]) -> &mut T {
+ match try_from_bytes_mut(s) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("from_bytes_mut", e),
+ }
+}
+
+/// Reads the slice into a `T` value.
+///
+/// ## Panics
+/// * This is like `try_pod_read_unaligned` but will panic on failure.
+#[inline]
+pub fn pod_read_unaligned<T: CheckedBitPattern>(bytes: &[u8]) -> T {
+ match try_pod_read_unaligned(bytes) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("pod_read_unaligned", e),
+ }
+}
+
+/// Cast `T` into `U`
+///
+/// ## Panics
+///
+/// * This is like [`try_cast`](try_cast), but will panic on a size mismatch.
+#[inline]
+pub fn cast<A: NoUninit, B: CheckedBitPattern>(a: A) -> B {
+ match try_cast(a) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("cast", e),
+ }
+}
+
+/// Cast `&mut T` into `&mut U`.
+///
+/// ## Panics
+///
+/// This is [`try_cast_mut`] but will panic on error.
+#[inline]
+pub fn cast_mut<
+ A: NoUninit + AnyBitPattern,
+ B: NoUninit + CheckedBitPattern,
+>(
+ a: &mut A,
+) -> &mut B {
+ match try_cast_mut(a) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("cast_mut", e),
+ }
+}
+
+/// Cast `&T` into `&U`.
+///
+/// ## Panics
+///
+/// This is [`try_cast_ref`] but will panic on error.
+#[inline]
+pub fn cast_ref<A: NoUninit, B: CheckedBitPattern>(a: &A) -> &B {
+ match try_cast_ref(a) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("cast_ref", e),
+ }
+}
+
+/// Cast `&[A]` into `&[B]`.
+///
+/// ## Panics
+///
+/// This is [`try_cast_slice`] but will panic on error.
+#[inline]
+pub fn cast_slice<A: NoUninit, B: CheckedBitPattern>(a: &[A]) -> &[B] {
+ match try_cast_slice(a) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("cast_slice", e),
+ }
+}
+
+/// Cast `&mut [T]` into `&mut [U]`.
+///
+/// ## Panics
+///
+/// This is [`try_cast_slice_mut`] but will panic on error.
+#[inline]
+pub fn cast_slice_mut<
+ A: NoUninit + AnyBitPattern,
+ B: NoUninit + CheckedBitPattern,
+>(
+ a: &mut [A],
+) -> &mut [B] {
+ match try_cast_slice_mut(a) {
+ Ok(t) => t,
+ Err(e) => something_went_wrong("cast_slice_mut", e),
+ }
+}
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-20 04:28:53 +0000