]>
git.proxmox.com Git - rustc.git/blob - library/core/src/ops/deref.rs
d68932402a411f235721583af450ae0543506cd2
1 /// Used for immutable dereferencing operations, like `*v`.
3 /// In addition to being used for explicit dereferencing operations with the
4 /// (unary) `*` operator in immutable contexts, `Deref` is also used implicitly
5 /// by the compiler in many circumstances. This mechanism is called
6 /// ['`Deref` coercion'][more]. In mutable contexts, [`DerefMut`] is used.
8 /// Implementing `Deref` for smart pointers makes accessing the data behind them
9 /// convenient, which is why they implement `Deref`. On the other hand, the
10 /// rules regarding `Deref` and [`DerefMut`] were designed specifically to
11 /// accommodate smart pointers. Because of this, **`Deref` should only be
12 /// implemented for smart pointers** to avoid confusion.
14 /// For similar reasons, **this trait should never fail**. Failure during
15 /// dereferencing can be extremely confusing when `Deref` is invoked implicitly.
17 /// # More on `Deref` coercion
19 /// If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:
21 /// * In immutable contexts, `*x` (where `T` is neither a reference nor a raw pointer)
22 /// is equivalent to `*Deref::deref(&x)`.
23 /// * Values of type `&T` are coerced to values of type `&U`
24 /// * `T` implicitly implements all the (immutable) methods of the type `U`.
26 /// For more details, visit [the chapter in *The Rust Programming Language*][book]
27 /// as well as the reference sections on [the dereference operator][ref-deref-op],
28 /// [method resolution] and [type coercions].
30 /// [book]: ../../book/ch15-02-deref.html
31 /// [more]: #more-on-deref-coercion
32 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
33 /// [method resolution]: ../../reference/expressions/method-call-expr.html
34 /// [type coercions]: ../../reference/type-coercions.html
38 /// A struct with a single field which is accessible by dereferencing the
42 /// use std::ops::Deref;
44 /// struct DerefExample<T> {
48 /// impl<T> Deref for DerefExample<T> {
51 /// fn deref(&self) -> &Self::Target {
56 /// let x = DerefExample { value: 'a' };
57 /// assert_eq!('a', *x);
62 #[stable(feature = "rust1", since = "1.0.0")]
63 #[rustc_diagnostic_item = "Deref"]
65 /// The resulting type after dereferencing.
66 #[stable(feature = "rust1", since = "1.0.0")]
67 #[rustc_diagnostic_item = "deref_target"]
68 #[lang = "deref_target"]
71 /// Dereferences the value.
73 #[stable(feature = "rust1", since = "1.0.0")]
74 #[rustc_diagnostic_item = "deref_method"]
75 fn deref(&self) -> &Self::Target
;
78 #[stable(feature = "rust1", since = "1.0.0")]
79 #[rustc_const_unstable(feature = "const_deref", issue = "88955")]
80 impl<T
: ?Sized
> const Deref
for &T
{
83 #[rustc_diagnostic_item = "noop_method_deref"]
84 fn deref(&self) -> &T
{
89 #[stable(feature = "rust1", since = "1.0.0")]
90 impl<T
: ?Sized
> !DerefMut
for &T {}
92 #[stable(feature = "rust1", since = "1.0.0")]
93 #[rustc_const_unstable(feature = "const_deref", issue = "88955")]
94 impl<T
: ?Sized
> const Deref
for &mut T
{
97 fn deref(&self) -> &T
{
102 /// Used for mutable dereferencing operations, like in `*v = 1;`.
104 /// In addition to being used for explicit dereferencing operations with the
105 /// (unary) `*` operator in mutable contexts, `DerefMut` is also used implicitly
106 /// by the compiler in many circumstances. This mechanism is called
107 /// ['`Deref` coercion'][more]. In immutable contexts, [`Deref`] is used.
109 /// Implementing `DerefMut` for smart pointers makes mutating the data behind
110 /// them convenient, which is why they implement `DerefMut`. On the other hand,
111 /// the rules regarding [`Deref`] and `DerefMut` were designed specifically to
112 /// accommodate smart pointers. Because of this, **`DerefMut` should only be
113 /// implemented for smart pointers** to avoid confusion.
115 /// For similar reasons, **this trait should never fail**. Failure during
116 /// dereferencing can be extremely confusing when `DerefMut` is invoked
119 /// # More on `Deref` coercion
121 /// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
124 /// * In mutable contexts, `*x` (where `T` is neither a reference nor a raw pointer)
125 /// is equivalent to `*DerefMut::deref_mut(&mut x)`.
126 /// * Values of type `&mut T` are coerced to values of type `&mut U`
127 /// * `T` implicitly implements all the (mutable) methods of the type `U`.
129 /// For more details, visit [the chapter in *The Rust Programming Language*][book]
130 /// as well as the reference sections on [the dereference operator][ref-deref-op],
131 /// [method resolution] and [type coercions].
133 /// [book]: ../../book/ch15-02-deref.html
134 /// [more]: #more-on-deref-coercion
135 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
136 /// [method resolution]: ../../reference/expressions/method-call-expr.html
137 /// [type coercions]: ../../reference/type-coercions.html
141 /// A struct with a single field which is modifiable by dereferencing the
145 /// use std::ops::{Deref, DerefMut};
147 /// struct DerefMutExample<T> {
151 /// impl<T> Deref for DerefMutExample<T> {
154 /// fn deref(&self) -> &Self::Target {
159 /// impl<T> DerefMut for DerefMutExample<T> {
160 /// fn deref_mut(&mut self) -> &mut Self::Target {
165 /// let mut x = DerefMutExample { value: 'a' };
167 /// assert_eq!('b', x.value);
169 #[lang = "deref_mut"]
171 #[stable(feature = "rust1", since = "1.0.0")]
172 pub trait DerefMut
: Deref
{
173 /// Mutably dereferences the value.
174 #[stable(feature = "rust1", since = "1.0.0")]
175 fn deref_mut(&mut self) -> &mut Self::Target
;
178 #[stable(feature = "rust1", since = "1.0.0")]
179 impl<T
: ?Sized
> DerefMut
for &mut T
{
180 fn deref_mut(&mut self) -> &mut T
{
185 /// Indicates that a struct can be used as a method receiver, without the
186 /// `arbitrary_self_types` feature. This is implemented by stdlib pointer types like `Box<T>`,
187 /// `Rc<T>`, `&T`, and `Pin<P>`.
189 #[unstable(feature = "receiver_trait", issue = "none")]
195 #[unstable(feature = "receiver_trait", issue = "none")]
196 impl<T
: ?Sized
> Receiver
for &T {}
198 #[unstable(feature = "receiver_trait", issue = "none")]
199 impl<T
: ?Sized
> Receiver
for &mut T {}