Implement FromBytes::{mut,ref}_from_with_trailing_elements

Makes progress on #29

Author: jswrenn

src/lib.rs

@@ -1380,7 +1380,7 @@ pub unsafe trait TryFromBytes {
     /// #[derive(TryFromBytes, Immutable, KnownLayout)]
     /// #[repr(C)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -1476,7 +1476,7 @@ pub unsafe trait TryFromBytes {
     /// #[derive(TryFromBytes, Immutable, KnownLayout)]
     /// #[repr(C)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -2499,7 +2499,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
     /// #[repr(C, packed)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -2573,7 +2573,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
     /// #[repr(C, packed)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -2647,7 +2647,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
     /// #[repr(C, packed)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -2692,6 +2692,79 @@ pub unsafe trait FromBytes: FromZeros {
         mut_from_prefix_suffix(bytes, None, CastType::Suffix).map(swap)
     }
 
+    /// Interprets the given `bytes` as a `&Self` with a DST length equal to
+    /// `count`.
+    ///
+    /// This method verifies that `bytes.len() == size_of::<T>() * count` and
+    /// that `bytes` is aligned to `align_of::<T>()`. It also ensures that
+    /// `sizeof::<T>() * count` does not overflow a `usize`. If any of the
+    /// length, alignment, or overflow checks fail, it returns `Err`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use zerocopy::FromBytes;
+    /// # use zerocopy_derive::*;
+    ///
+    /// # #[derive(Debug, PartialEq, Eq)]
+    /// #[derive(FromBytes, Immutable)]
+    /// #[repr(C)]
+    /// struct Pixel {
+    ///     r: u8,
+    ///     g: u8,
+    ///     b: u8,
+    ///     a: u8,
+    /// }
+    ///
+    /// let bytes = &[0, 1, 2, 3, 4, 5, 6, 7][..];
+    ///
+    /// let pixels = <[Pixel]>::ref_from_with_trailing_elements(bytes, 2).unwrap();
+    ///
+    /// assert_eq!(pixels, &[
+    ///     Pixel { r: 0, g: 1, b: 2, a: 3 },
+    ///     Pixel { r: 4, g: 5, b: 6, a: 7 },
+    /// ]);
+    ///
+    /// ```
+    ///
+    /// Since an explicit `count` is provided, this method supports types with
+    /// zero-sided trailing slice elements. Methods such as [`ref_from`]
+    /// which do not take an explicit count do not support such types.
+    ///
+    /// ```
+    /// use zerocopy::*;
+    /// # use zerocopy_derive::*;
+    ///
+    /// #[derive(FromBytes, Immutable, KnownLayout)]
+    /// #[repr(C)]
+    /// struct ZSTy {
+    ///     leading_sized: [u8; 2],
+    ///     trailing_dst: [()],
+    /// }
+    ///
+    /// let src = &[85, 85][..];
+    /// let zsty = ZSTy::ref_from_with_trailing_elements(src, 42).unwrap();
+    /// assert_eq!(zsty.trailing_dst.len(), 42);
+    /// ```
+    ///
+    /// [`ref_from`]: FromBytes::ref_from
+    #[must_use = "has no side effects"]
+    #[inline]
+    fn ref_from_with_trailing_elements(
+        bytes: &[u8],
+        count: usize,
+    ) -> Result<&Self, CastError<&[u8], Self>>
+    where
+        Self: KnownLayout<PointerMetadata = usize> + Immutable,
+    {
+        let bytes = Ptr::from_ref(bytes);
+        let maybe_slf = bytes.try_cast_into_no_leftover::<_, BecauseImmutable>(Some(count));
+        match maybe_slf {
+            Ok(slf) => Ok(slf.bikeshed_recall_valid().as_ref()),
+            Err(err) => Err(err.map_src(|s| s.as_ref())),
+        }
+    }
+
     /// Interprets the prefix of the given `bytes` as a `&[Self]` with length
     /// equal to `count` without copying.
     ///
@@ -2742,7 +2815,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, Immutable, KnownLayout)]
     /// #[repr(C)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -2828,7 +2901,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, Immutable, KnownLayout)]
     /// #[repr(C)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -2875,6 +2948,82 @@ pub unsafe trait FromBytes: FromZeros {
         <[Self]>::mut_from(bytes).ok()
     }
 
+    /// Interprets the given `bytes` as a `&mut Self` with a DST length equal to
+    /// `count`.
+    ///
+    /// This method verifies that `bytes.len() == size_of::<T>() * count` and
+    /// that `bytes` is aligned to `align_of::<T>()`. It also ensures that
+    /// `sizeof::<T>() * count` does not overflow a `usize`. If any of the
+    /// length, alignment, or overflow checks fail, it returns `Err`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use zerocopy::FromBytes;
+    /// # use zerocopy_derive::*;
+    ///
+    /// # #[derive(Debug, PartialEq, Eq)]
+    /// #[derive(KnownLayout, FromBytes, IntoBytes, Immutable)]
+    /// #[repr(C)]
+    /// struct Pixel {
+    ///     r: u8,
+    ///     g: u8,
+    ///     b: u8,
+    ///     a: u8,
+    /// }
+    ///
+    /// let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7][..];
+    ///
+    /// let pixels = <[Pixel]>::mut_from_with_trailing_elements(bytes, 2).unwrap();
+    ///
+    /// assert_eq!(pixels, &[
+    ///     Pixel { r: 0, g: 1, b: 2, a: 3 },
+    ///     Pixel { r: 4, g: 5, b: 6, a: 7 },
+    /// ]);
+    ///
+    /// pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };
+    ///
+    /// assert_eq!(bytes, [0, 1, 2, 3, 0, 0, 0, 0]);
+    /// ```
+    ///
+    /// Since an explicit `count` is provided, this method supports types with
+    /// zero-sided trailing slice elements. Methods such as [`mut_from`] which
+    /// do not take an explicit count do not support such types.
+    ///
+    /// ```
+    /// use zerocopy::*;
+    /// # use zerocopy_derive::*;
+    ///
+    /// #[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
+    /// #[repr(C, packed)]
+    /// struct ZSTy {
+    ///     leading_sized: [u8; 2],
+    ///     trailing_dst: [()],
+    /// }
+    ///
+    /// let src = &mut [85, 85][..];
+    /// let zsty = ZSTy::mut_from_with_trailing_elements(src, 42).unwrap();
+    /// assert_eq!(zsty.trailing_dst.len(), 42);
+    /// ```
+    ///
+    /// [`mut_from`]: FromBytes::mut_from
+    #[must_use = "has no side effects"]
+    #[inline]
+    fn mut_from_with_trailing_elements(
+        bytes: &mut [u8],
+        count: usize,
+    ) -> Result<&mut Self, CastError<&mut [u8], Self>>
+    where
+        Self: IntoBytes + KnownLayout<PointerMetadata = usize> + Immutable,
+    {
+        let bytes = Ptr::from_mut(bytes);
+        let maybe_slf = bytes.try_cast_into_no_leftover::<_, BecauseImmutable>(Some(count));
+        match maybe_slf {
+            Ok(slf) => Ok(slf.bikeshed_recall_valid().as_mut()),
+            Err(err) => Err(err.map_src(|s| s.as_mut())),
+        }
+    }
+
     /// Interprets the prefix of the given `bytes` as a `&mut [Self]` with
     /// length equal to `count` without copying.
     ///
@@ -2930,7 +3079,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
     /// #[repr(C, packed)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///
@@ -3021,7 +3170,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// #[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
     /// #[repr(C, packed)]
     /// struct ZSTy {
-    ///     leading_sized: u16,
+    ///     leading_sized: [u8; 2],
     ///     trailing_dst: [()],
     /// }
     ///