Struct zerocopy::util::ptr::Ptr

pub struct Ptr<'a, T: 'a + ?Sized> {
    ptr: NonNull<T>,
    _lifetime: PhantomData<&'a ()>,
}

A raw pointer with more restrictions.

Ptr<T> is similar to NonNull<T>, but it is more restrictive in the following ways:

• It must derive from a valid allocation
• It must reference a byte range which is contained inside the allocation from which it derives
  • As a consequence, the byte range it references must have a size which does not overflow isize
• It must satisfy T’s alignment requirement

Thanks to these restrictions, it is easier to prove the soundness of some operations using Ptrs.

Ptr<'a, T> is covariant in 'a and T.

Fields

ptr: NonNull<T>

_lifetime: PhantomData<&'a ()>

Implementations

impl<'a, T: ?Sized> Ptr<'a, T>

pub(crate) unsafe fn as_ref(&self) -> &'a T

Returns a shared reference to the value.

Safety

For the duration of 'a:

• The referenced memory must contain a validly-initialized T for the duration of 'a.
• The referenced memory must not also be referenced by any mutable references.
• The referenced memory must not be mutated, even via an UnsafeCell.
• There must not exist any references to the same memory region which contain UnsafeCells at byte ranges which are not identical to the byte ranges at which T contains UnsafeCells.

pub(crate) unsafe fn cast_unsized<U: 'a + ?Sized, F: FnOnce(*mut T) -> *mut U>( self, cast: F, ) -> Ptr<'a, U>

Casts to a different (unsized) target type.

Safety

The caller promises that

• cast(p) is implemented exactly as follows: |p: *mut T| p as *mut U.
• The size of the object referenced by the resulting pointer is less than or equal to the size of the object referenced by self.
• The alignment of U is less than or equal to the alignment of T.

impl<'a> Ptr<'a, [u8]>

pub(crate) fn try_cast_into<U: 'a + ?Sized + KnownLayout>( &self, cast_type: _CastType, ) -> Option<(Ptr<'a, U>, usize)>

Attempts to cast self to a U using the given cast type.

Returns None if the resulting U would be invalidly-aligned or if no U can fit in self. On success, returns a pointer to the largest-possible U which fits in self.

Safety

The caller may assume that this implementation is correct, and may rely on that assumption for the soundness of their code. In particular, the caller may assume that, if try_cast_into returns Some((ptr, split_at)), then:

• If this is a prefix cast, ptr refers to the byte range [0, split_at) in self.
• If this is a suffix cast, ptr refers to the byte range [split_at, self.len()) in self.

Panics

Panics if U is a DST whose trailing slice element is zero-sized.

pub(crate) fn try_cast_into_no_leftover<U: 'a + ?Sized + KnownLayout>( &self, ) -> Option<Ptr<'a, U>>

Attempts to cast self into a U, failing if all of the bytes of self cannot be treated as a U.

In particular, this method fails if self is not validly-aligned for U or if self’s size is not a valid size for U.

Safety

On success, the caller may assume that the returned pointer references the same byte range as self.

impl<'a, T> Ptr<'a, [T]>

fn len(&self) -> usize

The number of slice elements referenced by self.

Safety

Unsafe code my rely on len satisfying the above contract.

pub(crate) fn iter(&self) -> impl Iterator<Item = Ptr<'a, T>>

Trait Implementations

impl<'a, T: ?Sized> Clone for Ptr<'a, T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, T: 'a + ?Sized> Debug for Ptr<'a, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T: 'a + ?Sized> From<&'a T> for Ptr<'a, T>

fn from(t: &'a T) -> Ptr<'a, T>

Converts to this type from the input type.

impl<'a, T: ?Sized> Copy for Ptr<'a, T>