nordic-dev.net/bytemuck
2
0
Fork 0
mirror of https://github.com/Lokathor/bytemuck.git synced 2024-11-21 14:22: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

50
src/transparent.rs
View File

@ -4,10 +4,11 @@ use super::*;
/// around the `Inner` value.
///
/// This allows safely copy transmuting between the `Inner` type and the
/// `TransparentWrapper` type.
/// Functions like `wrap_{}` convert from the inner
/// type to the wrapper type and `unwrap_{}` functions do the inverse conversion
/// from the wrapper type to the inner type.
/// `TransparentWrapper` type. Functions like `wrap_{}` convert from the inner
/// type to the wrapper type and `peel_{}` functions do the inverse conversion
/// from the wrapper type to the inner type. We deliberately do not call the
/// wrapper-removing methods "unwrap" because at this point that word is too
/// strongly tied to the Option/ Result methods.
///
/// # Safety
///
@ -16,28 +17,27 @@ use super::*;
/// For a given `Wrapper` which implements `TransparentWrapper<Inner>`:
///
/// 1. `Wrapper` must be a wrapper around `Inner` with an identical data
/// representations. This either means that it must be a
/// `#[repr(transparent)]` struct which contains a either a field of type
/// `Inner` (or a field of some other transparent wrapper for `Inner`) as the
/// only non-ZST field.
/// representations. This either means that it must be a
/// `#[repr(transparent)]` struct which contains a either a field of type
/// `Inner` (or a field of some other transparent wrapper for `Inner`) as
/// the only non-ZST field.
///
/// 2. Any fields *other* than the `Inner` field must be trivially
/// constructable ZSTs, for example `PhantomData`, `PhantomPinned`, etc.
/// 2. Any fields *other* than the `Inner` field must be trivially constructable
/// ZSTs, for example `PhantomData`, `PhantomPinned`, etc.
///
/// 3. The `Wrapper` may not impose additional alignment requirements over
/// `Inner`.
/// - Note: this is currently guaranteed by `repr(transparent)`, but there
/// have been discussions of lifting it, so it's stated here explicitly.
///
/// 4. All functions on
/// `TransparentWrapper` **may not** be overridden.
/// 4. All functions on `TransparentWrapper` **may not** be overridden.
///
/// ## Caveats
///
/// If the wrapper imposes additional constraints upon the inner type which
/// are required for safety, it's responsible for ensuring those still hold --
/// this generally requires preventing access to instances of the inner type,
/// as implementing `TransparentWrapper<U> for T` means anybody can call
/// If the wrapper imposes additional constraints upon the inner type which are
/// required for safety, it's responsible for ensuring those still hold -- this
/// generally requires preventing access to instances of the inner 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`
@ -103,7 +103,7 @@ pub unsafe trait TransparentWrapper<Inner: ?Sized> {
fn wrap_ref(s: &Inner) -> &Self {
unsafe {
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).
// 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 {
unsafe {
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).
// 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.
#[inline]
fn unwrap(s: Self) -> Inner
fn peel(s: Self) -> Inner
where
Self: 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
/// type.
#[inline]
fn unwrap_ref(s: &Self) -> &Inner {
fn peel_ref(s: &Self) -> &Inner {
unsafe {
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).
// 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
/// to the inner type.
#[inline]
fn unwrap_mut(s: &mut Self) -> &mut Inner {
fn peel_mut(s: &mut Self) -> &mut Inner {
unsafe {
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).
// 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.
#[inline]
fn unwrap_slice(s: &[Self]) -> &[Inner]
fn peel_slice(s: &[Self]) -> &[Inner]
where
Self: 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
/// inner type.
#[inline]
fn unwrap_slice_mut(s: &mut [Self]) -> &mut [Inner]
fn peel_slice_mut(s: &mut [Self]) -> &mut [Inner]
where
Self: Sized,
Inner: Sized,

14
tests/transparent.rs
View File

@ -21,35 +21,35 @@ fn test_transparent_wrapper() {
unsafe impl bytemuck::Pod for Wrapper {}
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 _: &Foreign = Wrapper::unwrap_ref(bytemuck::cast_ref(&u8::default()));
let _: &Foreign = Wrapper::peel_ref(bytemuck::cast_ref(&u8::default()));
let _: &mut u8 =
bytemuck::cast_mut(Wrapper::wrap_mut(&mut Foreign::default()));
let _: &mut Foreign =
Wrapper::unwrap_mut(bytemuck::cast_mut(&mut u8::default()));
Wrapper::peel_mut(bytemuck::cast_mut(&mut u8::default()));
let _: &[u8] =
bytemuck::cast_slice(Wrapper::wrap_slice(&[Foreign::default()]));
let _: &[Foreign] =
Wrapper::unwrap_slice(bytemuck::cast_slice(&[u8::default()]));
Wrapper::peel_slice(bytemuck::cast_slice(&[u8::default()]));
let _: &mut [u8] =
bytemuck::cast_slice_mut(Wrapper::wrap_slice_mut(
&mut [Foreign::default()],
));
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 _: &Foreign = Wrapper::unwrap_ref(bytemuck::from_bytes(&[u8::default()]));
let _: &Foreign = Wrapper::peel_ref(bytemuck::from_bytes(&[u8::default()]));
let _: &mut [u8] =
bytemuck::bytes_of_mut(Wrapper::wrap_mut(&mut Foreign::default()));
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
let _ =