Struct unique::Unique [−][src]
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.
assert_eq!(size_of::<Unique<u8>>(), size_of::<Option<Unique<u8>>>()); assert_eq!(size_of::<Unique<u8>>(), size_of::<*const u8>());
Unlike *mut T
, Unique<T>
is covariant over T
. This should always be correct
for any type which upholds Unique’s aliasing requirements.
Implementations
impl<T: Sized> Unique<T>
[src]
pub const fn dangling() -> Self
[src]
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 pointer value may potentially represent a valid pointer to
a T
, 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.
impl<T: ?Sized> Unique<T>
[src]
pub const unsafe fn new_unchecked(ptr: *mut T) -> Self
[src]
pub fn new(ptr: *mut T) -> Option<Self>
[src]
Creates a new Unique
if ptr
is non-null.
pub const fn as_ptr(self) -> *mut T
[src]
Acquires the underlying *mut
pointer.
pub unsafe fn as_ref(&self) -> &T
[src]
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()
.
pub unsafe fn as_mut(&mut self) -> &mut T
[src]
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()
.
pub const fn cast<U>(self) -> Unique<U>
[src]
Casts to a pointer of another type.
Trait Implementations
impl<T: ?Sized> Clone for Unique<T>
[src]
fn clone(&self) -> Self
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl<T: ?Sized> Copy for Unique<T>
[src]
impl<T: ?Sized> Debug for Unique<T>
[src]
impl<T: ?Sized> From<&'_ mut T> for Unique<T>
[src]
impl<T: ?Sized> Pointer for Unique<T>
[src]
impl<T: Send + ?Sized> Send for Unique<T>
[src]
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: Sync + ?Sized> Sync for Unique<T>
[src]
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.
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,