Trait tor_hsservice::internal_prelude::Deref
1.0.0 · source · pub(crate) trait Deref {
type Target: ?Sized;
// Required method
fn deref(&self) -> &Self::Target;
}
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 behaviour 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
(whereT
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 typeU
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:
- a value of the type transparently behaves like a value of the target type;
- the implementation of the deref function is cheap; and
- users of the type will not be surprised by any deref coercion behaviour.
In general, deref traits should not be implemented if:
- the deref implementations could fail unexpectedly; or
- the type has methods that are likely to collide with methods on the target type; or
- 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§
Required Methods§
Implementors§
source§impl Deref for Asn1BitString
impl Deref for Asn1BitString
type Target = Asn1BitStringRef
source§impl Deref for Asn1Enumerated
impl Deref for Asn1Enumerated
type Target = Asn1EnumeratedRef
source§impl Deref for Asn1GeneralizedTime
impl Deref for Asn1GeneralizedTime
type Target = Asn1GeneralizedTimeRef
source§impl Deref for Asn1Integer
impl Deref for Asn1Integer
type Target = Asn1IntegerRef
source§impl Deref for Asn1Object
impl Deref for Asn1Object
type Target = Asn1ObjectRef
source§impl Deref for Asn1OctetString
impl Deref for Asn1OctetString
type Target = Asn1OctetStringRef
source§impl Deref for Asn1String
impl Deref for Asn1String
type Target = Asn1StringRef
source§impl Deref for BigNumContext
impl Deref for BigNumContext
type Target = BigNumContextRef
source§impl Deref for CmsContentInfo
impl Deref for CmsContentInfo
type Target = CmsContentInfoRef
source§impl Deref for OcspBasicResponse
impl Deref for OcspBasicResponse
type Target = OcspBasicResponseRef
source§impl Deref for OcspCertId
impl Deref for OcspCertId
type Target = OcspCertIdRef
source§impl Deref for OcspOneReq
impl Deref for OcspOneReq
type Target = OcspOneReqRef
source§impl Deref for OcspRequest
impl Deref for OcspRequest
type Target = OcspRequestRef
source§impl Deref for OcspResponse
impl Deref for OcspResponse
type Target = OcspResponseRef
source§impl Deref for Pkcs7Signed
impl Deref for Pkcs7Signed
type Target = Pkcs7SignedRef
source§impl Deref for Pkcs7SignerInfo
impl Deref for Pkcs7SignerInfo
type Target = Pkcs7SignerInfoRef
source§impl Deref for SrtpProtectionProfile
impl Deref for SrtpProtectionProfile
type Target = SrtpProtectionProfileRef
source§impl Deref for SslAcceptorBuilder
impl Deref for SslAcceptorBuilder
type Target = SslContextBuilder
source§impl Deref for SslConnectorBuilder
impl Deref for SslConnectorBuilder
type Target = SslContextBuilder
source§impl Deref for SslContext
impl Deref for SslContext
type Target = SslContextRef
source§impl Deref for SslSession
impl Deref for SslSession
type Target = SslSessionRef
source§impl Deref for OpensslString
impl Deref for OpensslString
type Target = OpensslStringRef
source§impl Deref for X509StoreBuilder
impl Deref for X509StoreBuilder
type Target = X509StoreBuilderRef
source§impl Deref for AccessDescription
impl Deref for AccessDescription
type Target = AccessDescriptionRef
source§impl Deref for DistPointName
impl Deref for DistPointName
type Target = DistPointNameRef
source§impl Deref for GeneralName
impl Deref for GeneralName
type Target = GeneralNameRef
source§impl Deref for X509Algorithm
impl Deref for X509Algorithm
type Target = X509AlgorithmRef
source§impl Deref for X509Extension
impl Deref for X509Extension
type Target = X509ExtensionRef
source§impl Deref for X509NameEntry
impl Deref for X509NameEntry
type Target = X509NameEntryRef
source§impl Deref for X509Object
impl Deref for X509Object
type Target = X509ObjectRef
source§impl Deref for X509Revoked
impl Deref for X509Revoked
type Target = X509RevokedRef
source§impl Deref for X509StoreContext
impl Deref for X509StoreContext
type Target = X509StoreContextRef
source§impl Deref for X509VerifyParam
impl Deref for X509VerifyParam
type Target = X509VerifyParamRef
§impl Deref for HsBlindIdKey
impl Deref for HsBlindIdKey
type Target = VerifyingKey
§impl Deref for HsIntroPtSessionIdKey
impl Deref for HsIntroPtSessionIdKey
type Target = VerifyingKey
source§impl Deref for InstanceRawSubdir
impl Deref for InstanceRawSubdir
type Target = CheckedDir
§impl Deref for HsClientIntroAuthKey
impl Deref for HsClientIntroAuthKey
type Target = VerifyingKey
§impl Deref for HsDescSigningKey
impl Deref for HsDescSigningKey
type Target = VerifyingKey
§impl Deref for Timestamp
impl Deref for Timestamp
type Target = SystemTime
source§impl<'a> Deref for socket2::MaybeUninitSlice<'a>
impl<'a> Deref for socket2::MaybeUninitSlice<'a>
type Target = [MaybeUninit<u8>]
§impl<'a, R, G, T> Deref for MappedReentrantMutexGuard<'a, R, G, T>where
R: RawMutex + 'a,
G: GetThreadId + 'a,
T: 'a + ?Sized,
impl<'a, R, G, T> Deref for MappedReentrantMutexGuard<'a, R, G, T>where
R: RawMutex + 'a,
G: GetThreadId + 'a,
T: 'a + ?Sized,
§impl<'a, R, G, T> Deref for ReentrantMutexGuard<'a, R, G, T>where
R: RawMutex + 'a,
G: GetThreadId + 'a,
T: 'a + ?Sized,
impl<'a, R, G, T> Deref for ReentrantMutexGuard<'a, R, G, T>where
R: RawMutex + 'a,
G: GetThreadId + 'a,
T: 'a + ?Sized,
§impl<'a, R, T> Deref for RwLockUpgradableReadGuard<'a, R, T>where
R: RawRwLockUpgrade + 'a,
T: 'a + ?Sized,
impl<'a, R, T> Deref for RwLockUpgradableReadGuard<'a, R, T>where
R: RawRwLockUpgrade + 'a,
T: 'a + ?Sized,
source§impl<'v, R: SleepProvider> Deref for NotifyingBorrow<'v, R>
impl<'v, R: SleepProvider> Deref for NotifyingBorrow<'v, R>
type Target = <MutexGuard<'v, PublishIptSet> as Deref>::Target
source§impl<T> Deref for std::sync::rwlock::MappedRwLockReadGuard<'_, T>where
T: ?Sized,
impl<T> Deref for std::sync::rwlock::MappedRwLockReadGuard<'_, T>where
T: ?Sized,
source§impl<T> Deref for std::sync::rwlock::MappedRwLockWriteGuard<'_, T>where
T: ?Sized,
impl<T> Deref for std::sync::rwlock::MappedRwLockWriteGuard<'_, T>where
T: ?Sized,
1.0.0 · source§impl<T> Deref for std::sync::rwlock::RwLockReadGuard<'_, T>where
T: ?Sized,
impl<T> Deref for std::sync::rwlock::RwLockReadGuard<'_, T>where
T: ?Sized,
1.0.0 · source§impl<T> Deref for std::sync::rwlock::RwLockWriteGuard<'_, T>where
T: ?Sized,
impl<T> Deref for std::sync::rwlock::RwLockWriteGuard<'_, T>where
T: ?Sized,
source§impl<T> Deref for X509Lookup<T>
impl<T> Deref for X509Lookup<T>
type Target = X509LookupRef<T>
source§impl<T> Deref for X509LookupMethod<T>
impl<T> Deref for X509LookupMethod<T>
type Target = X509LookupMethodRef<T>
source§impl<T> Deref for DropNotifyWatchSender<T>where
T: DropNotifyEofSignallable,
impl<T> Deref for DropNotifyWatchSender<T>where
T: DropNotifyEofSignallable,
1.0.0 · source§impl<T> Deref for tor_hsservice::internal_prelude::MutexGuard<'_, T>where
T: ?Sized,
impl<T> Deref for tor_hsservice::internal_prelude::MutexGuard<'_, T>where
T: ?Sized,
§impl<T> Deref for FmtList<T>where
&'a T: for<'a> IntoIterator,
Available on non-tarpaulin_include
only.
impl<T> Deref for FmtList<T>where
&'a T: for<'a> IntoIterator,
tarpaulin_include
only.§impl<T> Deref for Metadata<'_, T>where
T: SmartDisplay + ?Sized,
impl<T> Deref for Metadata<'_, T>where
T: SmartDisplay + ?Sized,
Permit using Metadata
as a smart pointer to the user-provided metadata.