Skip to main content

Deref

Trait Deref 

1.0.0 (const: unstable) · Source
pub trait Deref {
    type Target: ?Sized;

    // Required method
    fn deref(&self) -> &Self::Target;
}
Available on crate features mtls and std only.
Expand description

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 and mutable deref coercion similarly occurs.

Warning: Deref coercion is a powerful language feature which has far-reaching implications for every type that implements Deref. The compiler will silently insert calls to Deref::deref. For this reason, one should be careful about implementing Deref and only do so when deref coercion is desirable. See below for advice on when this is typically desirable or undesirable.

Types that implement Deref or DerefMut are often called “smart pointers” and the mechanism of deref coercion has been specifically designed to facilitate the pointer-like behavior that name suggests. Often, the purpose of a “smart pointer” type is to change the ownership semantics of a contained value (for example, Rc or Cow) or the storage semantics of a contained value (for example, Box).

§Deref coercion

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

  • In immutable contexts, *v (where T is neither a reference nor a raw pointer) is equivalent to *Deref::deref(&v).
  • Values of type &T are coerced to values of type &U
  • T implicitly implements all the methods of the type U which take the &self receiver.

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.

§When to implement Deref or DerefMut

The same advice applies to both deref traits. In general, deref traits should be implemented if:

  1. a value of the type transparently behaves like a value of the target type;
  2. the implementation of the deref function is cheap; and
  3. users of the type will not be surprised by any deref coercion behavior.

In general, deref traits should not be implemented if:

  1. the deref implementations could fail unexpectedly; or
  2. the type has methods that are likely to collide with methods on the target type; or
  3. committing to deref coercion as part of the public API is not desirable.

Note that there’s a large difference between implementing deref traits generically over many target types, and doing so only for specific target types.

Generic implementations, such as for Box<T> (which is generic over every type and dereferences to T) should be careful to provide few or no methods, since the target type is unknown and therefore every method could collide with one on the target type, causing confusion for users. impl<T> Box<T> has no methods (though several associated functions), partly for this reason.

Specific implementations, such as for String (whose Deref implementation has Target = str) can have many methods, since avoiding collision is much easier. String and str both have many methods, and String additionally behaves as if it has every method of str because of deref coercion. The implementing type may also be generic while the implementation is still specific in this sense; for example, Vec<T> dereferences to [T], so methods of T are not applicable.

Consider also that deref coercion means that deref traits are a much larger part of a type’s public API than any other trait as it is implicitly called by the compiler. Therefore, it is advisable to consider whether this is something you are comfortable supporting as a public API.

The AsRef and Borrow traits have very similar signatures to Deref. It may be desirable to implement either or both of these, whether in addition to or rather than deref traits. See their documentation for details.

§Fallibility

This trait’s method should never unexpectedly fail. Deref coercion means the compiler will often insert calls to Deref::deref implicitly. Failure during dereferencing can be extremely confusing when Deref is invoked implicitly. In the majority of uses it should be infallible, though it may be acceptable to panic if the type is misused through programmer error, for example.

However, infallibility is not enforced and therefore not guaranteed. As such, unsafe code should not rely on infallibility in general for soundness.

§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);

Required Associated Types§

1.0.0 (const: unstable) · Source

type Target: ?Sized

The resulting type after dereferencing.

Required Methods§

1.0.0 (const: unstable) · Source

fn deref(&self) -> &Self::Target

Dereferences the value.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§

Source§

impl Deref for AlgorithmIdentifier

Source§

impl Deref for BStr

Source§

impl Deref for BorrowedPayload<'_>

Source§

impl Deref for ByteStr

Source§

impl Deref for ByteString

Source§

impl Deref for bytes::bytes::Bytes

Source§

impl Deref for winnow::stream::bytes::Bytes

Source§

impl Deref for BytesMut

1.0.0 · Source§

impl Deref for CString

Source§

impl Deref for CertificateDer<'_>

Source§

impl Deref for CertificateRevocationListDer<'_>

Source§

impl Deref for CertificateSigningRequestDer<'_>

Source§

impl Deref for rustls::client::client_conn::connection::ClientConnection

Source§

impl Deref for rustls::quic::connection::ClientConnection

Source§

impl Deref for Condition

Source§

type Target = fn() -> bool

Source§

impl Deref for rustls::conn::connection::Connection

Source§

impl Deref for rustls::quic::connection::Connection

Source§

impl Deref for ConnectionId

§

impl Deref for ContentType

Source§

impl Deref for Der<'_>

Source§

impl Deref for DocumentMut

Source§

impl Deref for EchConfigListBytes<'_>

Source§

impl Deref for EnteredSpan

Source§

impl Deref for InlinableString

Source§

impl Deref for InlineString

Source§

impl Deref for InternalString

Source§

impl Deref for toml_edit::key::Key

Source§

impl Deref for rocket::form::name::Key

Source§

impl Deref for KeyMut<'_>

Source§

impl Deref for N

Source§

impl Deref for rocket::form::name::Name

Source§

impl Deref for NamedFile

1.0.0 · Source§

impl Deref for OsString

§

impl Deref for Path<'_>

1.0.0 · Source§

impl Deref for PathBuf

Source§

impl Deref for Profile

§

impl Deref for QMediaType

§

impl Deref for Query<'_>

§

impl Deref for RawStrBuf

Source§

impl Deref for rustls::server::server_conn::connection::ServerConnection

Source§

impl Deref for rustls::quic::connection::ServerConnection

1.0.0 · Source§

impl Deref for String

Source§

impl Deref for SubjectPublicKeyInfoDer<'_>

Source§

impl Deref for TempPath

Source§

impl Deref for Tls12ClientSessionValue

Available on crate feature tls12 only.
Source§

type Target = ClientSessionCommon

Source§

impl Deref for Tls13ClientSessionValue

Source§

type Target = ClientSessionCommon

Source§

impl Deref for UnbufferedClientConnection

Source§

impl Deref for UnbufferedServerConnection

Source§

impl Deref for Uncased<'_>

Source§

impl Deref for WakerRef<'_>

Source§

impl<'a, 'b> Deref for TransformBuf<'a, 'b>

Source§

impl<'a, R, G, T> Deref for lock_api::remutex::MappedReentrantMutexGuard<'a, R, G, T>
where R: RawMutex + 'a, G: GetThreadId + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, G, T> Deref for lock_api::remutex::MappedReentrantMutexGuard<'a, R, G, T>
where R: RawMutex + 'a, G: GetThreadId + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, G, T> Deref for lock_api::remutex::ReentrantMutexGuard<'a, R, G, T>
where R: RawMutex + 'a, G: GetThreadId + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, G, T> Deref for lock_api::remutex::ReentrantMutexGuard<'a, R, G, T>
where R: RawMutex + 'a, G: GetThreadId + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::mutex::MappedMutexGuard<'a, R, T>
where R: RawMutex + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::mutex::MappedMutexGuard<'a, R, T>
where R: RawMutex + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::MappedRwLockReadGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::MappedRwLockReadGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::MappedRwLockWriteGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::MappedRwLockWriteGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::mutex::MutexGuard<'a, R, T>
where R: RawMutex + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::mutex::MutexGuard<'a, R, T>
where R: RawMutex + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::RwLockReadGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::RwLockReadGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::RwLockUpgradableReadGuard<'a, R, T>
where R: RawRwLockUpgrade + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::RwLockUpgradableReadGuard<'a, R, T>
where R: RawRwLockUpgrade + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::RwLockWriteGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, R, T> Deref for lock_api::rwlock::RwLockWriteGuard<'a, R, T>
where R: RawRwLock + 'a, T: 'a + ?Sized,

Source§

impl<'a, T, A> Deref for rocket::mtls::oid::asn1_rs::nom::lib::std::vec::PeekMut<'a, T, A>
where A: Allocator,

Source§

impl<'a, T, C> Deref for Entry<'a, T, C>
where C: Config,

Source§

impl<'a, T, C> Deref for sharded_slab::pool::Ref<'a, T, C>
where T: Clear + Default, C: Config,

Source§

impl<'a, T, C> Deref for sharded_slab::pool::RefMut<'a, T, C>
where C: Config, T: Clear + Default,

Source§

impl<'a, T> Deref for tokio::sync::mutex::MappedMutexGuard<'a, T>
where T: ?Sized,

Source§

impl<'a, T> Deref for spin::mutex::MutexGuard<'a, T>
where T: ?Sized,

Source§

impl<'a, T> Deref for SpinMutexGuard<'a, T>
where T: ?Sized,

Source§

impl<'a> Deref for CRLDistributionPoints<'a>

Source§

impl<'a> Deref for Certificate<'a>

Source§

impl<'a> Deref for EndEntityCert<'a>

Source§

type Target = Cert<'a>

1.36.0 · Source§

impl<'a> Deref for IoSlice<'a>

1.36.0 · Source§

impl<'a> Deref for IoSliceMut<'a>

Source§

impl<'a> Deref for MaybeUninitSlice<'a>

Source§

impl<'a> Deref for rocket::mtls::Name<'a>

Source§

impl<'a> Deref for RouteUri<'a>

Source§

impl<'a> Deref for Text<'a>

Source§

impl<'a> Deref for X509Certificate<'a>

Source§

impl<'c> Deref for rocket::local::asynchronous::LocalRequest<'c>

Source§

impl<'c> Deref for rocket::local::blocking::LocalRequest<'c>

Source§

impl<'i> Deref for BytesCData<'i>

Source§

impl<'i> Deref for BytesDecl<'i>

Source§

impl<'i> Deref for BytesEnd<'i>

Source§

impl<'i> Deref for BytesPI<'i>

Source§

impl<'i> Deref for BytesRef<'i>

Source§

impl<'i> Deref for BytesStart<'i>

Source§

impl<'i> Deref for BytesText<'i>

Source§

impl<'i> Deref for Event<'i>

Source§

impl<'rwlock, T, R> Deref for RwLockUpgradableGuard<'rwlock, T, R>
where T: ?Sized,

Source§

impl<'rwlock, T, R> Deref for spin::rwlock::RwLockWriteGuard<'rwlock, T, R>
where T: ?Sized,

Source§

impl<'rwlock, T> Deref for spin::rwlock::RwLockReadGuard<'rwlock, T>
where T: ?Sized,

Source§

impl<'s, T> Deref for SliceVec<'s, T>

Source§

impl<'s> Deref for SockRef<'s>

Source§

impl<'v> Deref for Error<'v>

Source§

impl<'v> Deref for Errors<'v>

Source§

impl<A> Deref for ArrayVec<A>
where A: Array,

Source§

type Target = [<A as Array>::Item]

Source§

impl<A> Deref for SmallVec<A>
where A: Array,

Source§

type Target = [<A as Array>::Item]

Source§

impl<A> Deref for TinyVec<A>
where A: Array,

Source§

type Target = [<A as Array>::Item]

Source§

impl<B, T> Deref for zerocopy::ref::def::Ref<B, T>

1.0.0 · Source§

impl<B> Deref for Cow<'_, B>
where B: ToOwned + ?Sized,

Source§

impl<Data> Deref for rustls::quic::connection::ConnectionCommon<Data>

Source§

impl<E> Deref for FormattedFields<E>
where E: ?Sized,

Source§

impl<I, S> Deref for Stateful<I, S>

Source§

impl<I> Deref for LocatingSlice<I>

Source§

impl<I> Deref for Partial<I>

Source§

impl<I> Deref for pear::input::pear::Pear<I>
where I: Input,

Source§

impl<I> Deref for pear::input::pear::Pear<I>
where I: Input,

Source§

impl<L, R> Deref for Either<L, R>
where L: Deref, R: Deref<Target = <L as Deref>::Target>,

Source§

type Target = <L as Deref>::Target

1.33.0 (const: unstable) · Source§

impl<Ptr> Deref for Pin<Ptr>
where Ptr: Deref,

Source§

type Target = <Ptr as Deref>::Target

Source§

impl<R> Deref for NsReader<R>

Source§

impl<S> Deref for BlockingStream<S>
where S: Stream + Unpin,

Source§

impl<S> Deref for ImDocument<S>

1.0.0 · Source§

impl<T, A> Deref for Arc<T, A>
where A: Allocator, T: ?Sized,

1.0.0 · Source§

impl<T, A> Deref for Box<T, A>
where A: Allocator, T: ?Sized,

1.12.0 · Source§

impl<T, A> Deref for rocket::mtls::oid::asn1_rs::nom::lib::std::collections::binary_heap::PeekMut<'_, T, A>
where T: Ord, A: Allocator,

1.0.0 · Source§

impl<T, A> Deref for Rc<T, A>
where A: Allocator, T: ?Sized,

Source§

impl<T, A> Deref for UniqueArc<T, A>
where A: Allocator, T: ?Sized,

Source§

impl<T, A> Deref for UniqueRc<T, A>
where A: Allocator, T: ?Sized,

1.0.0 (const: unstable) · Source§

impl<T, A> Deref for Vec<T, A>
where A: Allocator,

Source§

impl<T, C> Deref for OwnedEntry<T, C>
where C: Config,

Source§

impl<T, C> Deref for OwnedRef<T, C>
where T: Clear + Default, C: Config,

Source§

impl<T, C> Deref for OwnedRefMut<T, C>
where T: Clear + Default, C: Config,

Source§

impl<T, F, R> Deref for spin::lazy::Lazy<T, F, R>
where F: FnOnce() -> T, R: RelaxStrategy,

Source§

impl<T, F, S> Deref for ScopeGuard<T, F, S>
where F: FnOnce(T), S: Strategy,

1.100.0 (const: unstable) · Source§

impl<T, F> Deref for DropGuard<T, F>
where F: FnOnce(T),

Source§

impl<T, F> Deref for once_cell::unsync::Lazy<T, F>
where F: FnOnce() -> T,

Source§

impl<T, F> Deref for once_cell::sync::Lazy<T, F>
where F: FnOnce() -> T,

1.80.0 · Source§

impl<T, F> Deref for LazyCell<T, F>
where F: FnOnce() -> T,

1.80.0 · Source§

impl<T, F> Deref for LazyLock<T, F>
where F: FnOnce() -> T,

Source§

impl<T, N> Deref for GenericArray<T, N>
where N: ArrayLength<T>,

Source§

impl<T, U> Deref for futures_util::lock::mutex::MappedMutexGuard<'_, T, U>
where T: ?Sized, U: ?Sized,

Source§

impl<T, U> Deref for OwnedMappedMutexGuard<T, U>
where T: ?Sized, U: ?Sized,

Source§

impl<T, U> Deref for OwnedRwLockMappedWriteGuard<T, U>
where T: ?Sized, U: ?Sized,

Source§

impl<T, U> Deref for OwnedRwLockReadGuard<T, U>
where T: ?Sized, U: ?Sized,

Source§

impl<T, const COMPACT: bool> Deref for MsgPack<T, COMPACT>

Available on crate feature msgpack only.
Source§

impl<T: Send + Sync + 'static> Deref for State<T>

1.0.0 (const: unstable) · Source§

impl<T> Deref for &T
where T: ?Sized,

1.0.0 (const: unstable) · Source§

impl<T> Deref for &mut T
where T: ?Sized,

1.9.0 (const: unstable) · Source§

impl<T> Deref for AssertUnwindSafe<T>

Source§

impl<T> Deref for Capped<T>

Source§

impl<T> Deref for rustls::conn::ConnectionCommon<T>

Source§

impl<T> Deref for pear::input::cursor::Extent<T>

Source§

impl<T> Deref for pear::input::cursor::Extent<T>

Source§

impl<T> Deref for Form<T>

Source§

impl<T> Deref for Json<T>

Available on crate feature json only.
Source§

impl<T> Deref for Lenient<T>

1.20.0 (const: unstable) · Source§

impl<T> Deref for ManuallyDrop<T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::nonpoison::mutex::MappedMutexGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::poison::mutex::MappedMutexGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::nonpoison::rwlock::MappedRwLockReadGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::poison::rwlock::MappedRwLockReadGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::nonpoison::rwlock::MappedRwLockWriteGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::poison::rwlock::MappedRwLockWriteGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for Metadata<'_, T>
where T: SmartDisplay + ?Sized,

Permit using Metadata as a smart pointer to the user-provided metadata.

Source§

impl<T> Deref for std::sync::nonpoison::mutex::MutexGuard<'_, T>
where T: ?Sized,

1.0.0 · Source§

impl<T> Deref for std::sync::poison::mutex::MutexGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for futures_util::lock::mutex::MutexGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for tokio::sync::mutex::MutexGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for futures_util::lock::mutex::OwnedMutexGuard<T>
where T: ?Sized,

Source§

impl<T> Deref for tokio::sync::mutex::OwnedMutexGuard<T>
where T: ?Sized,

Source§

impl<T> Deref for OwnedRwLockWriteGuard<T>
where T: ?Sized,

Source§

impl<T> Deref for ReadOnly<T>
where T: Immutable + ?Sized,

Source§

impl<T> Deref for ReentrantLockGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for tokio::sync::watch::Ref<'_, T>

1.0.0 (const: unstable) · Source§

impl<T> Deref for core::cell::Ref<'_, T>
where T: ?Sized,

1.0.0 (const: unstable) · Source§

impl<T> Deref for core::cell::RefMut<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for RwLockMappedWriteGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::nonpoison::rwlock::RwLockReadGuard<'_, T>
where T: ?Sized,

1.0.0 · Source§

impl<T> Deref for std::sync::poison::rwlock::RwLockReadGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for tokio::sync::rwlock::read_guard::RwLockReadGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for std::sync::nonpoison::rwlock::RwLockWriteGuard<'_, T>
where T: ?Sized,

1.0.0 · Source§

impl<T> Deref for std::sync::poison::rwlock::RwLockWriteGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for tokio::sync::rwlock::write_guard::RwLockWriteGuard<'_, T>
where T: ?Sized,

Source§

impl<T> Deref for SequenceOf<T>

Source§

impl<T> Deref for SetOf<T>

Source§

impl<T> Deref for Strict<T>

Source§

impl<T> Deref for Tagged<T>

Source§

impl<T> Deref for ThinBox<T>
where T: ?Sized,

Source§

impl<T> Deref for TokenSlice<'_, T>

Source§

impl<T> Deref for Unalign<T>
where T: Unaligned,

Source§

impl<T> Deref for UnbufferedConnectionCommon<T>

Source§

impl<T> Deref for Xml<T>

Available on crate feature xml only.
Source§

impl<Z> Deref for Zeroizing<Z>
where Z: Zeroize + ?Sized,

Source§

impl<const N: usize> Deref for CcidEndpoints<N>

Available on Linux and crate feature all only.
Source§

impl<const SIZE: usize> Deref for WriteBuffer<SIZE>