std::ops::Deref - Rust
Description: API documentation for the Rust `Deref` trait in crate `std`.
Keywords: rust, rustlang, rust-lang, Deref

# 1.0.0[−][src]Trait std::ops::Deref

    #[lang = "deref"]
    pub trait Deref {
        type Target: ?Sized;
        #[must_use]
    fn deref(&self) -> &Self::Target;
    }

Used for immutable dereferencing operations, like `*v`.

In addition to being used for explicit dereferencing operations with the (unary) `*` operator in immutable contexts, `Deref` is also used implicitly by the compiler in many circumstances. This mechanism is called '`Deref` coercion'. In mutable contexts, `DerefMut` is used.

Implementing `Deref` for smart pointers makes accessing the data behind them convenient, which is why they implement `Deref`. On the other hand, the rules regarding `Deref` and `DerefMut` were designed specifically to accommodate smart pointers. Because of this, `Deref` should only be implemented for smart pointers to avoid confusion.

For similar reasons, this trait should never fail. Failure during dereferencing can be extremely confusing when `Deref` is invoked implicitly.

# More on `Deref` coercion

If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:

- In immutable contexts, `*x` on non-pointer types is equivalent to `*Deref::deref(&x)`.
- Values of type `&T` are coerced to values of type `&U`
- `T` implicitly implements all the (immutable) methods of the type `U`.

For more details, visit the chapter in The Rust Programming Language as well as the reference sections on the dereference operator, method resolution and type coercions.

# Examples

A struct with a single field which is accessible by dereferencing the struct.

    use std::ops::Deref;

    struct DerefExample<T> {
        value: T
    }

    impl<T> Deref for DerefExample<T> {
        type Target = T;

        fn deref(&self) -> &Self::Target {
            &self.value
        }
    }

    let x = DerefExample { value: 'a' };
    assert_eq!('a', *x);Run

## Associated Types

### `type Target: ?Sized`

The resulting type after dereferencing.

Loading content...

## Required methods

### `
#[must_use]
fn deref(&self) -> &Self::Target`

Dereferences the value.

Loading content...

## Implementors

### `impl Deref for CString`[src]

#### `type Target = CStr`

#### `fn deref(&self) -> &CStr`[src]

### `impl Deref for OsString`[src]

#### `type Target = OsStr`

#### `fn deref(&self) -> &OsStr`[src]

### `impl Deref for PathBuf`[src]

#### `type Target = Path`

#### `fn deref(&self) -> &Path`[src]

### `impl Deref for String`[src]

#### `type Target = str`

#### `fn deref(&self) -> &str`[src]

### `impl<'_, B> Deref for Cow<'_, B> where
B: ToOwned + ?Sized,` [src]

#### `type Target = B`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &B`[src]

### `impl<'_, T> Deref for &'_ T where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<'_, T> Deref for &'_ mut T where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<'_, T> Deref for Ref<'_, T> where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<'_, T> Deref for RefMut<'_, T> where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<'_, T> Deref for PeekMut<'_, T> where
T: Ord,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<'a> Deref for IoVec<'a>`[src]

#### `type Target = [u8]`

####
ⓘImportant traits for &'_ [u8]

### Important traits for &'_ [u8]

`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`
`fn deref(&self) -> &[u8]`[src]

### `impl<'a> Deref for IoVecMut<'a>`[src]

#### `type Target = [u8]`

####
ⓘImportant traits for &'_ [u8]

### Important traits for &'_ [u8]

`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`
`fn deref(&self) -> &[u8]`[src]

### `impl<P> Deref for Pin<P> where
P: Deref,` [src]

#### `type Target = <P as Deref>::Target`

#### `fn deref(&self) -> &<P as Deref>::Target`[src]

### `impl<T> Deref for Box<T> where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T> Deref for ManuallyDrop<T> where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T> Deref for AssertUnwindSafe<T>`[src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T> Deref for Rc<T> where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T> Deref for Arc<T> where
T: ?Sized,` [src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T> Deref for Vec<T>`[src]

#### `type Target = [T]`

####
ⓘImportant traits for &'_ [u8]

### Important traits for &'_ [u8]

`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`
`fn deref(&self) -> &[T]`[src]

### `impl<T: ?Sized, '_> Deref for MutexGuard<'_, T>`[src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T: ?Sized, '_> Deref for RwLockReadGuard<'_, T>`[src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

### `impl<T: ?Sized, '_> Deref for RwLockWriteGuard<'_, T>`[src]

#### `type Target = T`

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

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`fn deref(&self) -> &T`[src]

Loading content...

# 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
`+`
  Expand all sections
`-`
  Collapse 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`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)