core::ptr::Unique - Rust
Description: API documentation for the Rust `Unique` struct in crate `core`.
Keywords: rust, rustlang, rust-lang, Unique

# Struct core::ptr::Unique [−] [src]

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

🔬 This is a nightly-only experimental API. (`unique` #27730)

needs an RFC to flesh out design

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 `Shared`, 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: Sized> Unique<T>`
[src]

#### `pub fn empty() -> Self`
[src]

🔬 This is a nightly-only experimental API. (`unique` #27730)

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: ?Sized> Unique<T>`
[src]

#### `pub const unsafe fn new_unchecked(ptr: *mut T) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`unique` #27730)

Creates a new `Unique`.

# Safety

`ptr` must be non-null.

#### `pub fn new(ptr: *mut T) -> Option<Self>`
[src]

🔬 This is a nightly-only experimental API. (`unique` #27730)

Creates a new `Unique` if `ptr` is non-null.

#### `pub fn as_ptr(self) -> *mut T`
[src]

🔬 This is a nightly-only experimental API. (`unique` #27730)

Acquires the underlying `*mut` pointer.

#### `pub unsafe fn as_ref(&self) -> &T`
[src]

🔬 This is a nightly-only experimental API. (`unique` #27730)

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

#### `pub unsafe fn as_mut(&mut self) -> &mut T`
[src]

🔬 This is a nightly-only experimental API. (`unique` #27730)

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

## Trait Implementations

### `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.

### `impl<T: ?Sized> Clone for Unique<T>`
[src]

#### `fn clone(&self) -> Self`
[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`
1.0.0
[src]

Performs copy-assignment from `source`. Read more

### `impl<T: ?Sized> Copy for Unique<T>`
[src]

### `impl<T: ?Sized, U: ?Sized> CoerceUnsized<Unique<U>> for Unique<T> where
T: Unsize<U>,`
[src]

### `impl<T: ?Sized> Pointer for Unique<T>`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`
[src]

Formats the value using the given formatter.

### `impl<'a, T: ?Sized> From<&'a mut T> for Unique<T>`
[src]

#### `fn from(reference: &'a mut T) -> Self`
[src]

Performs the conversion.

### `impl<'a, T: ?Sized> From<&'a T> for Unique<T>`
[src]

#### `fn from(reference: &'a T) -> Self`
[src]

Performs the conversion.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)