Trait Transparent

pub unsafe trait Transparent {
    type Wrapped: ?Sized;

    // Provided methods
    fn from_ref(wrapped: &Self::Wrapped) -> &Self { ... }
    fn from_ref_mut(wrapped: &mut Self::Wrapped) -> &mut Self { ... }
}

Transparent is a trait that indicates that the implementor is a transparent wrapper around some type, and should be treated interoperably with wrapped type.

This allows for internal types to be treated as references of the wrapper type, and vice-versa.

Note

This trait only allows for conversions between references of objects; this means that the formed references will become ephemeral references of a different type – but the lifetime of the object will still be tied to the lifetime of the source.

Acknowledgements

The approach to use this trait is heavily inspired by the bytemuck crate, which is licensed under ZLib OR MIT OR Apache-2. The idea has been adapted for this library’s specific needs.

Safety

The safety contract for this type requires two things:

• The wrapper type implementing this must be #[repr(transparent)]
• The implementation must not override the function definitions in the trait.

Required Associated Types

type Wrapped: ?Sized

The type that is wrapped by the Transparent impl.

Provided Methods

fn from_ref(wrapped: &Self::Wrapped) -> &Self

Converts a reference to a type into a reference of the wrapper type.

Safety

The safety contract for this type requires two things:

• The wrapper type implementing this must be #[repr(transparent)]
• This function must not be implemented in impls.

fn from_ref_mut(wrapped: &mut Self::Wrapped) -> &mut Self

Converts a mut reference to a wrapped type into a mut reference to the wrapper.

Safety

The safety contract for this type requires two things:

• The wrapper type implementing this must be #[repr(transparent)]
• This function must not be implemented in impls.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<T> Transparent for *const T

where T: Transparent,

type Wrapped = *const <T as Transparent>::Wrapped

impl<T> Transparent for *mut T

where T: Transparent,

type Wrapped = *mut <T as Transparent>::Wrapped

impl<T> Transparent for [T]

where T: Transparent, T::Wrapped: Sized,

Slices which are Transparent are convertible to their wrapped types.

type Wrapped = [<T as Transparent>::Wrapped]

impl<T> Transparent for Box<T>

where T: Transparent,

type Wrapped = Box<<T as Transparent>::Wrapped>

impl<T> Transparent for Rc<T>

where T: Transparent,

type Wrapped = Rc<<T as Transparent>::Wrapped>

impl<T> Transparent for Arc<T>

where T: Transparent,

type Wrapped = Arc<<T as Transparent>::Wrapped>

impl<T> Transparent for Vec<T>

where T: Transparent, T::Wrapped: Sized,

type Wrapped = Vec<<T as Transparent>::Wrapped>

impl<const N: usize, T> Transparent for [T; N]

where T: Transparent, T::Wrapped: Sized,

Arrays which are Transparent are convertible to their wrapped types.

type Wrapped = [<T as Transparent>::Wrapped; N]

Implementors

impl Transparent for Uuid

type Wrapped = [u8; 16]