Rename FromBytes::ref_from[_with_elems] (#1278)

...to `ref_from_bytes[_with_elems]`. This brings the names in line with
the `Ref` methods of the same names, and avoids the awkward name
`ref_from_with_elems`.

Similarly, rename `Ref::unaligned_from` to `unaligned_from_bytes`. We
had already renamed `unaligned_from_with_elems` to
`unaligned_from_bytes_with_elems`.

Makes progress on #871

src/deprecated.rs

@@ -76,7 +76,7 @@ where
     #[doc(hidden)]
     #[inline(always)]
     pub fn new_slice_unaligned(bytes: B) -> Option<Ref<B, [T]>> {
-        Ref::unaligned_from(bytes).ok()
+        Ref::unaligned_from_bytes(bytes).ok()
     }
 }
 

src/error.rs

@@ -7,7 +7,7 @@
 //! - [`SizeError`]: the conversion source was of incorrect size
 //! - [`ValidityError`]: the conversion source contained invalid data
 //!
-//! Methods that only have one failure mode, like [`Ref::unaligned_from`],
+//! Methods that only have one failure mode, like [`Ref::unaligned_from_bytes`],
 //! return that mode's corresponding error type directly.
 //!
 //! ## Compound errors
@@ -44,11 +44,11 @@ mod private {
     /// - [`ValidityError`]: the conversion source contained invalid data
     ///
     /// However, not all conversions produce all errors. For instance,
-    /// [`FromBytes::ref_from`] may fail due to alignment or size issues, but not
-    /// validity issues. This generic error type captures these (im)possibilities
-    /// via parameterization: `A` is parameterized with [`AlignmentError`], `S` is
-    /// parameterized with [`SizeError`], and `V` is parameterized with
-    /// [`Infallible`].
+    /// [`FromBytes::ref_from_bytes`] may fail due to alignment or size issues,
+    /// but not validity issues. This generic error type captures these
+    /// (im)possibilities via parameterization: `A` is parameterized with
+    /// [`AlignmentError`], `S` is parameterized with [`SizeError`], and `V` is
+    /// parameterized with [`Infallible`].
     ///
     /// Zerocopy never uses this type directly in its API. Rather, we provide three
     /// pre-parameterized aliases:
@@ -297,7 +297,7 @@ impl<Src, Dst: ?Sized + TryFromBytes, A, S> From<ValidityError<Src, Dst>>
 
 /// The error type of reference conversions.
 ///
-/// Reference conversions, like [`FromBytes::ref_from`] may emit
+/// Reference conversions, like [`FromBytes::ref_from_bytes`] may emit
 /// [alignment](AlignmentError) and [size](SizeError) errors.
 // Bounds on generic parameters are not enforced in type aliases, but they do
 // appear in rustdoc.

src/lib.rs

@@ -2298,7 +2298,7 @@ pub unsafe trait FromBytes: FromZeros {
     ///     trailing_dst: [()],
     /// }
     ///
-    /// let _ = ZSTy::ref_from(0u16.as_bytes()); // ⚠ Compile Error!
+    /// let _ = ZSTy::ref_from_bytes(0u16.as_bytes()); // ⚠ Compile Error!
     /// ```
     ///
     /// # Examples
@@ -2326,7 +2326,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// // These bytes encode a `Packet`.
     /// let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11][..];
     ///
-    /// let packet = Packet::ref_from(bytes).unwrap();
+    /// let packet = Packet::ref_from_bytes(bytes).unwrap();
     ///
     /// assert_eq!(packet.header.src_port, [0, 1]);
     /// assert_eq!(packet.header.dst_port, [2, 3]);
@@ -2336,7 +2336,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// ```
     #[must_use = "has no side effects"]
     #[inline]
-    fn ref_from(source: &[u8]) -> Result<&Self, CastError<&[u8], Self>>
+    fn ref_from_bytes(source: &[u8]) -> Result<&Self, CastError<&[u8], Self>>
     where
         Self: KnownLayout + Immutable,
     {
@@ -2724,7 +2724,7 @@ pub unsafe trait FromBytes: FromZeros {
     ///
     /// let bytes = &[0, 1, 2, 3, 4, 5, 6, 7][..];
     ///
-    /// let pixels = <[Pixel]>::ref_from_with_elems(bytes, 2).unwrap();
+    /// let pixels = <[Pixel]>::ref_from_bytes_with_elems(bytes, 2).unwrap();
     ///
     /// assert_eq!(pixels, &[
     ///     Pixel { r: 0, g: 1, b: 2, a: 3 },
@@ -2734,7 +2734,7 @@ pub unsafe trait FromBytes: FromZeros {
     /// ```
     ///
     /// Since an explicit `count` is provided, this method supports types with
-    /// zero-sized trailing slice elements. Methods such as [`ref_from`]
+    /// zero-sized trailing slice elements. Methods such as [`ref_from_bytes`]
     /// which do not take an explicit count do not support such types.
     ///
     /// ```
@@ -2749,14 +2749,17 @@ pub unsafe trait FromBytes: FromZeros {
     /// }
     ///
     /// let src = &[85, 85][..];
-    /// let zsty = ZSTy::ref_from_with_elems(src, 42).unwrap();
+    /// let zsty = ZSTy::ref_from_bytes_with_elems(src, 42).unwrap();
     /// assert_eq!(zsty.trailing_dst.len(), 42);
     /// ```
     ///
-    /// [`ref_from`]: FromBytes::ref_from
+    /// [`ref_from_bytes`]: FromBytes::ref_from_bytes
     #[must_use = "has no side effects"]
     #[inline]
-    fn ref_from_with_elems(source: &[u8], count: usize) -> Result<&Self, CastError<&[u8], Self>>
+    fn ref_from_bytes_with_elems(
+        source: &[u8],
+        count: usize,
+    ) -> Result<&Self, CastError<&[u8], Self>>
     where
         Self: KnownLayout<PointerMetadata = usize> + Immutable,
     {
@@ -3325,7 +3328,7 @@ pub unsafe trait FromBytes: FromZeros {
     where
         Self: Sized + Immutable,
     {
-        <[Self]>::ref_from(source).ok()
+        <[Self]>::ref_from_bytes(source).ok()
     }
 }
 
@@ -5811,7 +5814,7 @@ mod tests {
             Align::<[u8; 16], AU64>::new([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]);
 
         assert_eq!(
-            AU64::ref_from(&buf.t[8..]).unwrap().0.to_ne_bytes(),
+            AU64::ref_from_bytes(&buf.t[8..]).unwrap().0.to_ne_bytes(),
             [8, 9, 10, 11, 12, 13, 14, 15]
         );
         let suffix = AU64::mut_from(&mut buf.t[8..]).unwrap();
@@ -5843,16 +5846,16 @@ mod tests {
         // Fail because the buffer is too large.
         let mut buf = Align::<[u8; 16], AU64>::default();
         // `buf.t` should be aligned to 8, so only the length check should fail.
-        assert!(AU64::ref_from(&buf.t[..]).is_err());
+        assert!(AU64::ref_from_bytes(&buf.t[..]).is_err());
         assert!(AU64::mut_from(&mut buf.t[..]).is_err());
-        assert!(<[u8; 8]>::ref_from(&buf.t[..]).is_err());
+        assert!(<[u8; 8]>::ref_from_bytes(&buf.t[..]).is_err());
         assert!(<[u8; 8]>::mut_from(&mut buf.t[..]).is_err());
 
         // Fail because the buffer is too small.
         let mut buf = Align::<[u8; 4], AU64>::default();
-        assert!(AU64::ref_from(&buf.t[..]).is_err());
+        assert!(AU64::ref_from_bytes(&buf.t[..]).is_err());
         assert!(AU64::mut_from(&mut buf.t[..]).is_err());
-        assert!(<[u8; 8]>::ref_from(&buf.t[..]).is_err());
+        assert!(<[u8; 8]>::ref_from_bytes(&buf.t[..]).is_err());
         assert!(<[u8; 8]>::mut_from(&mut buf.t[..]).is_err());
         assert!(AU64::ref_from_prefix(&buf.t[..]).is_err());
         assert!(AU64::mut_from_prefix(&mut buf.t[..]).is_err());
@@ -5865,9 +5868,9 @@ mod tests {
 
         // Fail because the alignment is insufficient.
         let mut buf = Align::<[u8; 13], AU64>::default();
-        assert!(AU64::ref_from(&buf.t[1..]).is_err());
+        assert!(AU64::ref_from_bytes(&buf.t[1..]).is_err());
         assert!(AU64::mut_from(&mut buf.t[1..]).is_err());
-        assert!(AU64::ref_from(&buf.t[1..]).is_err());
+        assert!(AU64::ref_from_bytes(&buf.t[1..]).is_err());
         assert!(AU64::mut_from(&mut buf.t[1..]).is_err());
         assert!(AU64::ref_from_prefix(&buf.t[1..]).is_err());
         assert!(AU64::mut_from_prefix(&mut buf.t[1..]).is_err());

src/ref.rs

@@ -539,11 +539,11 @@ where
     ///     trailing_dst: [()],
     /// }
     ///
-    /// let f = Ref::<&[u8], ZSTy>::unaligned_from(&b"UU"[..]); // ⚠ Compile Error!
+    /// let f = Ref::<&[u8], ZSTy>::unaligned_from_bytes(&b"UU"[..]); // ⚠ Compile Error!
     /// ```
     #[must_use = "has no side effects"]
     #[inline(always)]
-    pub fn unaligned_from(source: B) -> Result<Ref<B, T>, SizeError<B, T>> {
+    pub fn unaligned_from_bytes(source: B) -> Result<Ref<B, T>, SizeError<B, T>> {
         static_assert_dst_is_not_zst!(T);
         match Ref::from_bytes(source) {
             Ok(dst) => Ok(dst),
@@ -1160,7 +1160,7 @@ mod tests {
         // for `new_slice`.
 
         let mut buf = [0u8; 8];
-        test_new_helper_unaligned(Ref::<_, [u8; 8]>::unaligned_from(&mut buf[..]).unwrap());
+        test_new_helper_unaligned(Ref::<_, [u8; 8]>::unaligned_from_bytes(&mut buf[..]).unwrap());
         {
             // In a block so that `r` and `suffix` don't live too long.
             buf = [0u8; 8];
@@ -1178,7 +1178,10 @@ mod tests {
         let mut buf = [0u8; 16];
         // `buf.t` should be aligned to 8 and have a length which is a multiple
         // of `size_of::AU64>()`, so this should always succeed.
-        test_new_helper_slice_unaligned(Ref::<_, [u8]>::unaligned_from(&mut buf[..]).unwrap(), 16);
+        test_new_helper_slice_unaligned(
+            Ref::<_, [u8]>::unaligned_from_bytes(&mut buf[..]).unwrap(),
+            16,
+        );
 
         buf = [0u8; 16];
         let r = Ref::<_, [u8]>::unaligned_from_bytes_with_elems(&mut buf[..], 16).unwrap();
@@ -1253,15 +1256,15 @@ mod tests {
         let buf = Align::<[u8; 16], AU64>::default();
         // `buf.t` should be aligned to 8, so only the length check should fail.
         assert!(Ref::<_, AU64>::from_bytes(&buf.t[..]).is_err());
-        assert!(Ref::<_, [u8; 8]>::unaligned_from(&buf.t[..]).is_err());
+        assert!(Ref::<_, [u8; 8]>::unaligned_from_bytes(&buf.t[..]).is_err());
 
         // Fail because the buffer is too small.
 
         // A buffer with an alignment of 8.
         let buf = Align::<[u8; 4], AU64>::default();
         // `buf.t` should be aligned to 8, so only the length check should fail.
         assert!(Ref::<_, AU64>::from_bytes(&buf.t[..]).is_err());
-        assert!(Ref::<_, [u8; 8]>::unaligned_from(&buf.t[..]).is_err());
+        assert!(Ref::<_, [u8; 8]>::unaligned_from_bytes(&buf.t[..]).is_err());
         assert!(Ref::<_, AU64>::from_prefix(&buf.t[..]).is_err());
         assert!(Ref::<_, AU64>::from_suffix(&buf.t[..]).is_err());
         assert!(Ref::<_, [u8; 8]>::unaligned_from_prefix(&buf.t[..]).is_err());
@@ -1272,7 +1275,7 @@ mod tests {
         let buf = Align::<[u8; 12], AU64>::default();
         // `buf.t` has length 12, but element size is 8.
         assert!(Ref::<_, [AU64]>::from_bytes(&buf.t[..]).is_err());
-        assert!(Ref::<_, [[u8; 8]]>::unaligned_from(&buf.t[..]).is_err());
+        assert!(Ref::<_, [[u8; 8]]>::unaligned_from_bytes(&buf.t[..]).is_err());
 
         // Fail because the buffer is too short.
         let buf = Align::<[u8; 12], AU64>::default();