Rework TransparentWrapper to not require that the wrapped type be public

src/transparent.rs

@@ -3,33 +3,38 @@ use super::*;
 /// A trait which indicates that a type is a `repr(transparent)` wrapper around
 /// the `Wrapped` value.
 ///
-/// This allows safely creating references to `T` from those to `T::Wrapped`,
+/// This allows safely creating references to `T` from those to the `Wrapped`
-/// using the [`wrap_ref`] and [`wrap_mut`] functions.
+/// type, using the `wrap_ref` and `wrap_mut` functions.
 ///
 /// # Safety
 ///
 /// The safety contract of `TransparentWrapper` is relatively simple:
 ///
-/// For a given `T` which implements `TransparentWrapper`:
+/// For a given `Wrapper` which implements `TransparentWrapper<Wrapped>`:
 ///
-/// 1. T must be a `#[repr(transparent)]` struct and contain a field of type
+/// 1. Wrapper must be a `#[repr(transparent)]` wrapper around `Wrapped`. This
-///    `T::Wrapped`.
+///    either means that it must be a `#[repr(transparent)]` struct which
+///    contains a either a field of type `Wrapped` (or a field of some other
+///    transparent wrapper for `Wrapped`) as the only non-ZST field.
 ///
-/// 2. Any fields *other* than the `T::Wrapped` field must be trivially
+/// 2. Any fields *other* than the `Wrapped` field must be trivially
 ///    constructable ZSTs, for example `PhantomData`, `PhantomPinned`, etc.
 ///
-/// 3. The `T` may not impose additional alignment requirements over
+/// 3. The `Wrapper` may not impose additional alignment requirements over
-///    `T::Wrapped`.
+///    `Wrapped`.
 ///     - Note: this is currently guaranteed by repr(transparent), but there
 ///       have been discussions of lifting it, so it's stated here explictly.
 ///
+/// 4. The `wrap_ref` and `wrap_mut` functions on `TransparentWrapper` may not
+///    be overridden.
+///
 /// ## Caveats
 ///
 /// If the wrapper imposes additional constraints upon the wrapped type which
 /// are required for safety, it's responsible for ensuring those still hold --
 /// this generally requires preventing access to instances of the wrapped type,
-/// as implementing `TransparentWrapper` means anybody can call
+/// as implementing `TransparentWrapper<U> for T` means anybody can call
-/// `bytemuck::cast_ref`.
+/// `T::cast_ref(any_instance_of_u)`.
 ///
 /// For example, it would be invalid to implement TransparentWrapper for `str`
 /// to implement `TransparentWrapper` around `[u8]` because of this.
@@ -39,24 +44,22 @@ use super::*;
 /// ## Basic
 ///
 /// ```
-/// use bytemuck::{wrap_ref, wrap_mut, TransparentWrapper};
+/// use bytemuck::TransparentWrapper;
 /// # #[derive(Default)]
 /// # struct SomeStruct(u32);
 ///
 /// #[repr(transparent)]
 /// struct MyWrapper(SomeStruct);
 ///
-/// unsafe impl TransparentWrapper for MyWrapper {
+/// unsafe impl TransparentWrapper<SomeStruct> for MyWrapper {}
-///   type Wrapped = SomeStruct;
-/// }
 ///
 /// // interpret a reference to &SomeStruct as a &MyWrapper
 /// let thing = SomeStruct::default();
-/// let wrapped_ref: &MyWrapper = wrap_ref(&thing);
+/// let wrapped_ref: &MyWrapper = MyWrapper::wrap_ref(&thing);
 ///
 /// // Works with &mut too.
 /// let mut mut_thing = SomeStruct::default();
-/// let wrapped_mut: &mut MyWrapper = wrap_mut(&mut mut_thing);
+/// let wrapped_mut: &mut MyWrapper = MyWrapper::wrap_mut(&mut mut_thing);
 ///
 /// # let _ = (wrapped_ref, wrapped_mut); // silence warnings
 /// ```
@@ -64,73 +67,71 @@ use super::*;
 /// ## Use with dynamically sized types
 ///
 /// ```
-/// use bytemuck::{wrap_ref, wrap_mut, TransparentWrapper};
+/// use bytemuck::TransparentWrapper;
 ///
 /// #[repr(transparent)]
 /// struct Slice<T>([T]);
 ///
-/// unsafe impl<T> TransparentWrapper for Slice<T> {
+/// unsafe impl<T> TransparentWrapper<[T]> for Slice<T> {}
-///     type Wrapped = [T];
-/// }
 ///
-/// let s = wrap_ref::<Slice<_>>(&[1u32, 2, 3]);
+/// let s = Slice::wrap_ref(&[1u32, 2, 3]);
 /// assert_eq!(&s.0, &[1, 2, 3]);
 ///
-/// // Otherwise you'd need separate Slice<'a, T> and SliceMut<'a, T>, for example
 /// let mut buf = [1, 2, 3u8];
-/// let sm = wrap_mut::<Slice<_>>(&mut buf);
+/// let sm = Slice::wrap_mut(&mut buf);
-/// assert_eq!(&s.0, &[1, 2, 3]);
 /// ```
-pub unsafe trait TransparentWrapper {
+pub unsafe trait TransparentWrapper<Wrapped: ?Sized> {
-  /// The wrapped type.
+  /// Convert a reference to a wrapped type into a reference to the wrapper.
-  type Wrapped: ?Sized;
+  ///
-}
+  /// This is a trait method so that you can write `MyType::wrap_ref(...)` in
+  /// your code. It is part of the safety contract for this trait that if you
+  /// implement `TransparentWrapper<_>` for your type you **must not** override
+  /// this method.
+  #[inline]
+  fn wrap_ref(s: &Wrapped) -> &Self {
+    unsafe {
+      assert!(size_of::<*const Wrapped>() == size_of::<*const Self>());
+      // Using a pointer cast doesn't work here because rustc can't tell that the
+      // vtables match (if we lifted the ?Sized restriction, this would go away),
+      // and transmute doesn't work for the usual reasons it doesn't work inside
+      // generic functions.
+      //
+      // SAFETY: The unsafe contract requires that these have identical
+      // representations. Using this transmute_copy instead of transmute here is
+      // annoying, but is required as `Self` and `Self::Int` have unspecified
+      // sizes still.
+      let wrapped_ptr = s as *const Wrapped;
+      let wrapper_ptr: *const Self = transmute_copy(&wrapped_ptr);
+      &*wrapper_ptr
+    }
+  }
 
-/// Convert a reference to a wrapped type into a reference to the wrapper.
+  /// Convert a mut reference to a wrapped type into a mut reference to the
-///
+  /// wrapper.
-/// See [`TransparentWrapper`] for details.
+  ///
-#[inline]
+  /// This is a trait method so that you can write `MyType::wrap_mut(...)` in
-pub fn wrap_ref<W: TransparentWrapper + ?Sized>(r: &W::Wrapped) -> &W {
+  /// your code. It is part of the safety contract for this trait that if you implement
-  unsafe {
+  /// `TransparentWrapper<_>` for your type you **must not** override this method.
-    // Ideally we'd check more than just this, but...
+  #[inline]
-    assert!(size_of::<*const W::Wrapped>() == size_of::<*const W>());
+  fn wrap_mut(s: &mut Wrapped) -> &mut Self {
-    // Using a pointer cast doesn't work here because rustc can't tell that the
+    unsafe {
-    // vtables match (if we lifted the ?Sized restriction, this would go away),
+      assert!(size_of::<*mut Wrapped>() == size_of::<*mut Self>());
-    // and transmute doesn't work for the usual reasons it doesn't work inside
+      // Using a pointer cast doesn't work here because rustc can't tell that the
-    // generic functions.
+      // vtables match (if we lifted the ?Sized restriction, this would go away),
-    //
+      // and transmute doesn't work for the usual reasons it doesn't work inside
-    // SAFETY: The unsafe contract requires that these have identical
+      // generic functions.
-    // representations. Using this transmute_copy instead of transmute here is
+      //
-    // annoying, but is required as `Self` and `Self::Int` have unspecified
+      // SAFETY: The unsafe contract requires that these have identical
-    // sizes still.
+      // representations. Using this transmute_copy instead of transmute here is
-    let wrapped_ptr = r as *const W::Wrapped;
+      // annoying, but is required as `Self` and `Self::Int` have unspecified
-    let wrapper_ptr: *const W = transmute_copy(&wrapped_ptr);
+      // sizes still.
-    &*wrapper_ptr
+      let wrapped_ptr = s as *mut Wrapped;
+      let wrapper_ptr: *mut Self = transmute_copy(&wrapped_ptr);
+      &mut *wrapper_ptr
+    }
   }
 }
 
-/// Convert a mut reference to a wrapped type into a mut reference to the
-/// wrapper.
-///
-/// See [`TransparentWrapper`] for details.
-#[inline]
-pub fn wrap_mut<W: TransparentWrapper + ?Sized>(r: &mut W::Wrapped) -> &mut W {
-  unsafe {
-    assert!(size_of::<*mut W::Wrapped>() == size_of::<*mut W>());
-    // Using a pointer cast doesn't work here because rustc can't tell that the
-    // vtables match (if we lifted the ?Sized restriction, this would go away),
-    // and transmute doesn't work for the usual reasons it doesn't work inside
-    // generic functions.
-    //
-    // SAFETY: The unsafe contract requires that these have identical
-    // representations. Using this transmute_copy instead of transmute here is
-    // annoying, but is required as `Self` and `Self::Int` have unspecified
-    // sizes still.
-    let wrapped_ptr = r as *mut W::Wrapped;
-    let wrapper_ptr: *mut W = transmute_copy(&wrapped_ptr);
-    &mut *wrapper_ptr
-  }
-}
 #[cfg(all(test, feature = "extern_crate_alloc"))]
 mod test {
   use super::*;
@@ -141,9 +142,7 @@ mod test {
   #[repr(transparent)]
   struct DisplayTraitObj(dyn Display);
 
-  unsafe impl TransparentWrapper for DisplayTraitObj {
+  unsafe impl TransparentWrapper<dyn Display> for DisplayTraitObj {}
-    type Wrapped = dyn Display;
-  }
 
   impl Display for DisplayTraitObj {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
@@ -153,12 +152,12 @@ mod test {
 
   #[test]
   fn test_vtabled() {
-    let v: &DisplayTraitObj = wrap_ref(&5i32 as &dyn Display);
+    let v = DisplayTraitObj::wrap_ref(&5i32);
     let s = format!("{}", v);
     assert_eq!(s, "5");
 
     let mut x = 100i32;
-    let v_mut: &mut DisplayTraitObj = wrap_mut(&mut x as &mut dyn Display);
+    let v_mut = DisplayTraitObj::wrap_mut(&mut x);
     let s = format!("{}", v_mut);
     assert_eq!(s, "100");
   }