1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

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 the `Wrapped`
/// type, using the `wrap_ref` and `wrap_mut` functions.
///
/// # Safety
///
/// The safety contract of `TransparentWrapper` is relatively simple:
///
/// For a given `Wrapper` which implements `TransparentWrapper<Wrapped>`:
///
/// 1. Wrapper must be a `#[repr(transparent)]` wrapper around `Wrapped`. This
///    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 `Wrapped` field must be trivially
///    constructable ZSTs, for example `PhantomData`, `PhantomPinned`, etc.
///
/// 3. The `Wrapper` may not impose additional alignment requirements over
///    `Wrapped`.
///     - Note: this is currently guaranteed by `repr(transparent)`, but there
///       have been discussions of lifting it, so it's stated here explicitly.
///
/// 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<U> for T` means anybody can call
/// `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.
///
/// # Examples
///
/// ## Basic
///
/// ```
/// use bytemuck::TransparentWrapper;
/// # #[derive(Default)]
/// # struct SomeStruct(u32);
///
/// #[repr(transparent)]
/// struct MyWrapper(SomeStruct);
///
/// unsafe impl TransparentWrapper<SomeStruct> for MyWrapper {}
///
/// // interpret a reference to &SomeStruct as a &MyWrapper
/// let thing = SomeStruct::default();
/// let wrapped_ref: &MyWrapper = MyWrapper::wrap_ref(&thing);
///
/// // Works with &mut too.
/// let mut mut_thing = SomeStruct::default();
/// let wrapped_mut: &mut MyWrapper = MyWrapper::wrap_mut(&mut mut_thing);
///
/// # let _ = (wrapped_ref, wrapped_mut); // silence warnings
/// ```
///
/// ## Use with dynamically sized types
///
/// ```
/// use bytemuck::TransparentWrapper;
///
/// #[repr(transparent)]
/// struct Slice<T>([T]);
///
/// unsafe impl<T> TransparentWrapper<[T]> for Slice<T> {}
///
/// let s = Slice::wrap_ref(&[1u32, 2, 3]);
/// assert_eq!(&s.0, &[1, 2, 3]);
///
/// let mut buf = [1, 2, 3u8];
/// let sm = Slice::wrap_mut(&mut buf);
/// ```
pub unsafe trait TransparentWrapper<Wrapped: ?Sized> {
  /// Convert a reference to a wrapped type into a reference to the wrapper.
  ///
  /// 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 `Wrapped` have unspecified
      // sizes still.
      let wrapped_ptr = s as *const Wrapped;
      let wrapper_ptr: *const Self = transmute_copy(&wrapped_ptr);
      &*wrapper_ptr
    }
  }

  /// Convert a mut reference to a wrapped type into a mut reference to the
  /// wrapper.
  ///
  /// This is a trait method so that you can write `MyType::wrap_mut(...)` 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_mut(s: &mut Wrapped) -> &mut Self {
    unsafe {
      assert!(size_of::<*mut Wrapped>() == size_of::<*mut 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 `Wrapped` have unspecified
      // sizes still.
      let wrapped_ptr = s as *mut Wrapped;
      let wrapper_ptr: *mut Self = transmute_copy(&wrapped_ptr);
      &mut *wrapper_ptr
    }
  }
}

unsafe impl<T> TransparentWrapper<T> for core::num::Wrapping<T> {}