nordic-dev.net/bytemuck
2
0
Fork 0
mirror of https://github.com/Lokathor/bytemuck.git synced 2024-11-25 08:12:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

rename "unwrap" to "peel".

Browse Source
This commit is contained in:
Lokathor 2021-06-10 14:05:15 -06:00
parent cd8dbd64e9
commit 99ecb1f6cb
2 changed files with 32 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
src/transparent.rs
View File

@ -4,10 +4,11 @@ use super::*;
/// around the `Inner` value. /// around the `Inner` value.
/// ///
/// This allows safely copy transmuting between the `Inner` type and the /// This allows safely copy transmuting between the `Inner` type and the
/// `TransparentWrapper` type. /// `TransparentWrapper` type. Functions like `wrap_{}` convert from the inner
/// Functions like `wrap_{}` convert from the inner /// type to the wrapper type and `peel_{}` functions do the inverse conversion
/// type to the wrapper type and `unwrap_{}` functions do the inverse conversion /// from the wrapper type to the inner type. We deliberately do not call the
/// from the wrapper type to the inner type. /// wrapper-removing methods "unwrap" because at this point that word is too
/// strongly tied to the Option/ Result methods.
/// ///
/// # Safety /// # Safety
/// ///
@ -18,26 +19,25 @@ use super::*;
/// 1. `Wrapper` must be a wrapper around `Inner` with an identical data /// 1. `Wrapper` must be a wrapper around `Inner` with an identical data
/// representations. This either means that it must be a /// representations. This either means that it must be a
/// `#[repr(transparent)]` struct which contains a either a field of type /// `#[repr(transparent)]` struct which contains a either a field of type
/// `Inner` (or a field of some other transparent wrapper for `Inner`) as the /// `Inner` (or a field of some other transparent wrapper for `Inner`) as
/// only non-ZST field. /// the only non-ZST field.
/// ///
/// 2. Any fields *other* than the `Inner` field must be trivially /// 2. Any fields *other* than the `Inner` field must be trivially constructable
/// constructable ZSTs, for example `PhantomData`, `PhantomPinned`, etc. /// ZSTs, for example `PhantomData`, `PhantomPinned`, etc.
/// ///
/// 3. The `Wrapper` may not impose additional alignment requirements over /// 3. The `Wrapper` may not impose additional alignment requirements over
/// `Inner`. /// `Inner`.
/// - Note: this is currently guaranteed by `repr(transparent)`, but there /// - Note: this is currently guaranteed by `repr(transparent)`, but there
/// have been discussions of lifting it, so it's stated here explicitly. /// have been discussions of lifting it, so it's stated here explicitly.
/// ///
/// 4. All functions on /// 4. All functions on `TransparentWrapper` **may not** be overridden.
/// `TransparentWrapper` **may not** be overridden.
/// ///
/// ## Caveats /// ## Caveats
/// ///
/// If the wrapper imposes additional constraints upon the inner type which /// If the wrapper imposes additional constraints upon the inner type which are
/// are required for safety, it's responsible for ensuring those still hold -- /// required for safety, it's responsible for ensuring those still hold -- this
/// this generally requires preventing access to instances of the inner type, /// generally requires preventing access to instances of the inner type, as
/// as implementing `TransparentWrapper<U> for T` means anybody can call /// implementing `TransparentWrapper<U> for T` means anybody can call
/// `T::cast_ref(any_instance_of_u)`. /// `T::cast_ref(any_instance_of_u)`.
/// ///
/// For example, it would be invalid to implement TransparentWrapper for `str` /// For example, it would be invalid to implement TransparentWrapper for `str`
@ -103,7 +103,7 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
fn wrap_ref(s: &Inner) -> &Self { fn wrap_ref(s: &Inner) -> &Self {
unsafe { unsafe {
assert!(size_of::<*const Inner>() == size_of::<*const Self>()); assert!(size_of::<*const Inner>() == size_of::<*const Self>());
// A pointer cast does't work here because rustc can't tell that // A pointer cast doesn't work here because rustc can't tell that
// the vtables match (because of the `?Sized` restriction relaxation). // the vtables match (because of the `?Sized` restriction relaxation).
// A `transmute` doesn't work because the sizes are unspecified. // A `transmute` doesn't work because the sizes are unspecified.
// //
@ -121,7 +121,7 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
fn wrap_mut(s: &mut Inner) -> &mut Self { fn wrap_mut(s: &mut Inner) -> &mut Self {
unsafe { unsafe {
assert!(size_of::<*mut Inner>() == size_of::<*mut Self>()); assert!(size_of::<*mut Inner>() == size_of::<*mut Self>());
// A pointer cast does't work here because rustc can't tell that // A pointer cast doesn't work here because rustc can't tell that
// the vtables match (because of the `?Sized` restriction relaxation). // the vtables match (because of the `?Sized` restriction relaxation).
// A `transmute` doesn't work because the sizes are unspecified. // A `transmute` doesn't work because the sizes are unspecified.
// //
@ -168,7 +168,7 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
/// Convert the wrapper type into the inner type. /// Convert the wrapper type into the inner type.
#[inline] #[inline]
fn unwrap(s: Self) -> Inner fn peel(s: Self) -> Inner
where where
Self: Sized, Self: Sized,
Inner: Sized, Inner: Sized,
@ -179,10 +179,10 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
/// Convert a reference to the wrapper type into a reference to the inner /// Convert a reference to the wrapper type into a reference to the inner
/// type. /// type.
#[inline] #[inline]
fn unwrap_ref(s: &Self) -> &Inner { fn peel_ref(s: &Self) -> &Inner {
unsafe { unsafe {
assert!(size_of::<*const Inner>() == size_of::<*const Self>()); assert!(size_of::<*const Inner>() == size_of::<*const Self>());
// A pointer cast does't work here because rustc can't tell that // A pointer cast doesn't work here because rustc can't tell that
// the vtables match (because of the `?Sized` restriction relaxation). // the vtables match (because of the `?Sized` restriction relaxation).
// A `transmute` doesn't work because the sizes are unspecified. // A `transmute` doesn't work because the sizes are unspecified.
// //
@ -197,10 +197,10 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
/// Convert a mutable reference to the wrapper type into a mutable reference /// Convert a mutable reference to the wrapper type into a mutable reference
/// to the inner type. /// to the inner type.
#[inline] #[inline]
fn unwrap_mut(s: &mut Self) -> &mut Inner { fn peel_mut(s: &mut Self) -> &mut Inner {
unsafe { unsafe {
assert!(size_of::<*mut Inner>() == size_of::<*mut Self>()); assert!(size_of::<*mut Inner>() == size_of::<*mut Self>());
// A pointer cast does't work here because rustc can't tell that // A pointer cast doesn't work here because rustc can't tell that
// the vtables match (because of the `?Sized` restriction relaxation). // the vtables match (because of the `?Sized` restriction relaxation).
// A `transmute` doesn't work because the sizes are unspecified. // A `transmute` doesn't work because the sizes are unspecified.
// //
@ -214,7 +214,7 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
/// Convert a slice to the wrapped type into a slice to the inner type. /// Convert a slice to the wrapped type into a slice to the inner type.
#[inline] #[inline]
fn unwrap_slice(s: &[Self]) -> &[Inner] fn peel_slice(s: &[Self]) -> &[Inner]
where where
Self: Sized, Self: Sized,
Inner: Sized, Inner: Sized,
@ -231,7 +231,7 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
/// Convert a mutable slice to the wrapped type into a mutable slice to the /// Convert a mutable slice to the wrapped type into a mutable slice to the
/// inner type. /// inner type.
#[inline] #[inline]
fn unwrap_slice_mut(s: &mut [Self]) -> &mut [Inner] fn peel_slice_mut(s: &mut [Self]) -> &mut [Inner]
where where
Self: Sized, Self: Sized,
Inner: Sized, Inner: Sized,

14
tests/transparent.rs
View File

@ -21,35 +21,35 @@ fn test_transparent_wrapper() {
unsafe impl bytemuck::Pod for Wrapper {} unsafe impl bytemuck::Pod for Wrapper {}
let _: u8 = bytemuck::cast(Wrapper::wrap(Foreign::default())); let _: u8 = bytemuck::cast(Wrapper::wrap(Foreign::default()));
let _: Foreign = Wrapper::unwrap(bytemuck::cast(u8::default())); let _: Foreign = Wrapper::peel(bytemuck::cast(u8::default()));
let _: &u8 = bytemuck::cast_ref(Wrapper::wrap_ref(&Foreign::default())); let _: &u8 = bytemuck::cast_ref(Wrapper::wrap_ref(&Foreign::default()));
let _: &Foreign = Wrapper::unwrap_ref(bytemuck::cast_ref(&u8::default())); let _: &Foreign = Wrapper::peel_ref(bytemuck::cast_ref(&u8::default()));
let _: &mut u8 = let _: &mut u8 =
bytemuck::cast_mut(Wrapper::wrap_mut(&mut Foreign::default())); bytemuck::cast_mut(Wrapper::wrap_mut(&mut Foreign::default()));
let _: &mut Foreign = let _: &mut Foreign =
Wrapper::unwrap_mut(bytemuck::cast_mut(&mut u8::default())); Wrapper::peel_mut(bytemuck::cast_mut(&mut u8::default()));
let _: &[u8] = let _: &[u8] =
bytemuck::cast_slice(Wrapper::wrap_slice(&[Foreign::default()])); bytemuck::cast_slice(Wrapper::wrap_slice(&[Foreign::default()]));
let _: &[Foreign] = let _: &[Foreign] =
Wrapper::unwrap_slice(bytemuck::cast_slice(&[u8::default()])); Wrapper::peel_slice(bytemuck::cast_slice(&[u8::default()]));
let _: &mut [u8] = let _: &mut [u8] =
bytemuck::cast_slice_mut(Wrapper::wrap_slice_mut( bytemuck::cast_slice_mut(Wrapper::wrap_slice_mut(
&mut [Foreign::default()], &mut [Foreign::default()],
)); ));
let _: &mut [Foreign] = let _: &mut [Foreign] =
Wrapper::unwrap_slice_mut(bytemuck::cast_slice_mut(&mut [u8::default()])); Wrapper::peel_slice_mut(bytemuck::cast_slice_mut(&mut [u8::default()]));
let _: &[u8] = bytemuck::bytes_of(Wrapper::wrap_ref(&Foreign::default())); let _: &[u8] = bytemuck::bytes_of(Wrapper::wrap_ref(&Foreign::default()));
let _: &Foreign = Wrapper::unwrap_ref(bytemuck::from_bytes(&[u8::default()])); let _: &Foreign = Wrapper::peel_ref(bytemuck::from_bytes(&[u8::default()]));
let _: &mut [u8] = let _: &mut [u8] =
bytemuck::bytes_of_mut(Wrapper::wrap_mut(&mut Foreign::default())); bytemuck::bytes_of_mut(Wrapper::wrap_mut(&mut Foreign::default()));
let _: &mut Foreign = let _: &mut Foreign =
Wrapper::unwrap_mut(bytemuck::from_bytes_mut(&mut [u8::default()])); Wrapper::peel_mut(bytemuck::from_bytes_mut(&mut [u8::default()]));
// not sure if this is the right usage // not sure if this is the right usage
let _ = let _ =