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

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

    pub struct Unique<T> where
        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> Unique<T>`
[src]

#### `pub fn empty() -> Unique<T>`
[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> Unique<T> where
T: ?Sized,`
[src]

#### `pub const unsafe fn new_unchecked(ptr: *mut T) -> Unique<T>`
[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<Unique<T>>`
[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.

####
ⓘImportant traits for &'a mut I

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

####
ⓘImportant traits for &'a mut I

### 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`
[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> Clone for Unique<T> where
T: ?Sized,`
[src]

#### `fn clone(&self) -> Unique<T>`
[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> From<Unique<T>> for Shared<T> where
T: ?Sized,`
[src]

#### `fn from(unique: Unique<T>) -> Shared<T>`
[src]

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

### `impl<T> Send for Unique<T> where
T: Send + ?Sized,`
[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, U> CoerceUnsized<Unique<U>> for Unique<T> where
T: Unsize<U> + ?Sized,
U: ?Sized,`
[src]

### `impl<T> Sync for Unique<T> where
T: Sync + ?Sized,`
[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> Pointer for Unique<T> where
T: ?Sized,`
[src]

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

Formats the value using the given formatter.

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
↑
  Move up in search results
↓
  Move down in search results
↹
  Switch tab
⏎
  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`)