Struct `Unique`

#[repr(transparent)]
pub struct Unique<T: PointeeSized> { pub(in ::ptr::unique) pointer: NonNull<T>, pub(in ::ptr::unique) _marker: PhantomData<T> }

A wrapper around a raw non-null *mut T that indicates that the possessor of this wrapper owns the referent. Useful for building abstractions like Box<T>, Vec<T>, String, and HashMap<K, V>.

Unlike *mut T, Unique<T> behaves "as if" it were an instance of T. It implements Send/Sync if T is Send/Sync. It also implies the kind of strong aliasing guarantees an instance of T can expect: the referent of the pointer should not be modified without a unique path to its owning Unique.

If you're uncertain of whether it's correct to use Unique for your purposes, consider using NonNull, which has weaker semantics.

Unlike *mut T, the pointer must always be non-null, even if the pointer is never dereferenced. This is so that enums may use this forbidden value as a discriminant -- Option<Unique<T>> has the same size as Unique<T>. However the pointer may still dangle if it isn't dereferenced.

Unlike *mut T, Unique<T> is covariant over T. This should always be correct for any type which upholds Unique's aliasing requirements.

Fields

pointer: NonNull<T>
_marker: PhantomData<T>

Implementations

`impl<T: PointeeSized> Unique<T>`

const unsafe fn new_unchecked(ptr: *mut T) -> Self

Creates a new Unique.

Safety

ptr must be non-null.

const fn new(ptr: *mut T) -> Option<Self>

Creates a new Unique if ptr is non-null.

const fn from_non_null(pointer: NonNull<T>) -> Self

Create a new Unique from a NonNull in const context.

const fn as_ptr(self) -> *mut T

Acquires the underlying *mut pointer.

const fn as_non_null_ptr(self) -> NonNull<T>

Acquires the underlying *mut pointer.

const unsafe fn as_ref(&self) -> &T

Dereferences the content.

The resulting lifetime is bound to self so this behaves "as if" it were actually an instance of T that is getting borrowed. If a longer (unbound) lifetime is needed, use &*my_ptr.as_ptr().

const unsafe fn as_mut(&mut self) -> &mut T

Mutably dereferences the content.

The resulting lifetime is bound to self so this behaves "as if" it were actually an instance of T that is getting borrowed. If a longer (unbound) lifetime is needed, use &mut *my_ptr.as_ptr().

const fn cast(self) -> Unique

Casts to a pointer of another type.

`impl<T: Sized> Unique<T>`

const fn dangling() -> Self

Creates a new Unique that is dangling, but well-aligned.

This is useful for initializing types which lazily allocate, like Vec::new does.

Note that the address of the returned pointer may potentially be that of a valid pointer, which means this must not be used as a "not yet initialized" sentinel value. Types that lazily allocate must track initialization by some other means.