Struct std::ptr::Unique

pub struct Unique<T> where
    T: ?Sized,  { /* fields omitted */ }

🔬 This is a nightly-only experimental API. (ptr_internals)

use NonNull instead and consider PhantomData<T> (if you also use #[may_dangle]), Send, and/or Sync

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.

Methods

impl<T> Unique<T>

pub fn empty() -> Unique<T>

🔬 This is a nightly-only experimental API. (ptr_internals)

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

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

impl<T> Unique<T> where
    T: ?Sized, 

pub const unsafe fn new_unchecked(ptr: *mut T) -> Unique<T>

🔬 This is a nightly-only experimental API. (ptr_internals)

Creates a new Unique.

Safety

ptr must be non-null.

pub fn new(ptr: *mut T) -> Option<Unique<T>>

🔬 This is a nightly-only experimental API. (ptr_internals)

Creates a new Unique if ptr is non-null.

pub fn as_ptr(self) -> *mut T

🔬 This is a nightly-only experimental API. (ptr_internals)

Acquires the underlying *mut pointer.

Important traits for &'a mut I

impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W

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

🔬 This is a nightly-only experimental API. (ptr_internals)

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().

Important traits for &'a mut I

impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W

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

🔬 This is a nightly-only experimental API. (ptr_internals)

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().

Trait Implementations

impl<T> Pointer for Unique<T> where
    T: ?Sized, 

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

Formats the value using the given formatter.

impl<T> Debug for Unique<T> where
    T: ?Sized, 

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

Formats the value using the given formatter.

impl<T> Sync for Unique<T> where
    T: Sync + ?Sized, 

Unique pointers are Sync if T is Sync because the data they reference is unaliased. Note that this aliasing invariant is unenforced by the type system; the abstraction using the Unique must enforce it.

impl<T> Send for Unique<T> where
    T: Send + ?Sized, 

Unique pointers are Send if T is Send because the data they reference is unaliased. Note that this aliasing invariant is unenforced by the type system; the abstraction using the Unique must enforce it.

impl<T, U> CoerceUnsized<Unique<U>> for Unique<T> where
    T: Unsize<U> + ?Sized,
    U: ?Sized, 

impl<T> Clone for Unique<T> where
    T: ?Sized, 

fn clone(&self) -> Unique<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, T> From<&'a T> for Unique<T> where
    T: ?Sized, 

fn from(reference: &'a T) -> Unique<T>

Performs the conversion.

impl<'a, T> From<NonNull<T>> for Unique<T> where
    T: ?Sized, 

fn from(p: NonNull<T>) -> Unique<T>

Performs the conversion.

impl<'a, T> From<&'a mut T> for Unique<T> where
    T: ?Sized, 

fn from(reference: &'a mut T) -> Unique<T>

Performs the conversion.

impl<T> From<Unique<T>> for NonNull<T> where
    T: ?Sized, 

fn from(unique: Unique<T>) -> NonNull<T>

Performs the conversion.

impl<T> Copy for Unique<T> where
    T: ?Sized, 

impl<T: UnwindSafe + ?Sized> UnwindSafe for Unique<T>