library/core/src/ops/deref.rs

   1 /// Used for immutable dereferencing operations, like `*v`.
   2 ///
   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.
   7 ///
   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.
  13 ///
  14 /// For similar reasons, **this trait should never fail**. Failure during
  15 /// dereferencing can be extremely confusing when `Deref` is invoked implicitly.
  16 ///
  17 /// # More on `Deref` coercion
  18 ///
  19 /// If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:
  20 ///
  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`.
  25 ///
  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].
  29 ///
  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
  35 ///
  36 /// # Examples
  37 ///
  38 /// A struct with a single field which is accessible by dereferencing the
  39 /// struct.
  40 ///
  41 /// ```
  42 /// use std::ops::Deref;
  43 ///
  44 /// struct DerefExample<T> {
  45 ///     value: T
  46 /// }
  47 ///
  48 /// impl<T> Deref for DerefExample<T> {
  49 ///     type Target = T;
  50 ///
  51 ///     fn deref(&self) -> &Self::Target {
  52 ///         &self.value
  53 ///     }
  54 /// }
  55 ///
  56 /// let x = DerefExample { value: 'a' };
  57 /// assert_eq!('a', *x);
  58 /// ```
  59 #[lang = "deref"]
  60 #[doc(alias = "*")]
  61 #[doc(alias = "&*")]
  62 #[stable(feature = "rust1", since = "1.0.0")]
  63 #[rustc_diagnostic_item = "Deref"]
  64 #[const_trait]
  65 pub trait Deref {
  66     /// The resulting type after dereferencing.
  67     #[stable(feature = "rust1", since = "1.0.0")]
  68     #[rustc_diagnostic_item = "deref_target"]
  69     #[lang = "deref_target"]
  70     type Target: ?Sized;
  71
  72     /// Dereferences the value.
  73     #[must_use]
  74     #[stable(feature = "rust1", since = "1.0.0")]
  75     #[rustc_diagnostic_item = "deref_method"]
  76     fn deref(&self) -> &Self::Target;
  77 }
  78
  79 #[stable(feature = "rust1", since = "1.0.0")]
  80 #[rustc_const_unstable(feature = "const_deref", issue = "88955")]
  81 impl<T: ?Sized> const Deref for &T {
  82     type Target = T;
  83
  84     #[rustc_diagnostic_item = "noop_method_deref"]
  85     fn deref(&self) -> &T {
  86         *self
  87     }
  88 }
  89
  90 #[stable(feature = "rust1", since = "1.0.0")]
  91 impl<T: ?Sized> !DerefMut for &T {}
  92
  93 #[stable(feature = "rust1", since = "1.0.0")]
  94 #[rustc_const_unstable(feature = "const_deref", issue = "88955")]
  95 impl<T: ?Sized> const Deref for &mut T {
  96     type Target = T;
  97
  98     fn deref(&self) -> &T {
  99         *self
 100     }
 101 }
 102
 103 /// Used for mutable dereferencing operations, like in `*v = 1;`.
 104 ///
 105 /// In addition to being used for explicit dereferencing operations with the
 106 /// (unary) `*` operator in mutable contexts, `DerefMut` is also used implicitly
 107 /// by the compiler in many circumstances. This mechanism is called
 108 /// ['`Deref` coercion'][more]. In immutable contexts, [`Deref`] is used.
 109 ///
 110 /// Implementing `DerefMut` for smart pointers makes mutating the data behind
 111 /// them convenient, which is why they implement `DerefMut`. On the other hand,
 112 /// the rules regarding [`Deref`] and `DerefMut` were designed specifically to
 113 /// accommodate smart pointers. Because of this, **`DerefMut` should only be
 114 /// implemented for smart pointers** to avoid confusion.
 115 ///
 116 /// For similar reasons, **this trait should never fail**. Failure during
 117 /// dereferencing can be extremely confusing when `DerefMut` is invoked
 118 /// implicitly.
 119 ///
 120 /// # More on `Deref` coercion
 121 ///
 122 /// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
 123 /// then:
 124 ///
 125 /// * In mutable contexts, `*x` (where `T` is neither a reference nor a raw pointer)
 126 ///   is equivalent to `*DerefMut::deref_mut(&mut x)`.
 127 /// * Values of type `&mut T` are coerced to values of type `&mut U`
 128 /// * `T` implicitly implements all the (mutable) methods of the type `U`.
 129 ///
 130 /// For more details, visit [the chapter in *The Rust Programming Language*][book]
 131 /// as well as the reference sections on [the dereference operator][ref-deref-op],
 132 /// [method resolution] and [type coercions].
 133 ///
 134 /// [book]: ../../book/ch15-02-deref.html
 135 /// [more]: #more-on-deref-coercion
 136 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
 137 /// [method resolution]: ../../reference/expressions/method-call-expr.html
 138 /// [type coercions]: ../../reference/type-coercions.html
 139 ///
 140 /// # Examples
 141 ///
 142 /// A struct with a single field which is modifiable by dereferencing the
 143 /// struct.
 144 ///
 145 /// ```
 146 /// use std::ops::{Deref, DerefMut};
 147 ///
 148 /// struct DerefMutExample<T> {
 149 ///     value: T
 150 /// }
 151 ///
 152 /// impl<T> Deref for DerefMutExample<T> {
 153 ///     type Target = T;
 154 ///
 155 ///     fn deref(&self) -> &Self::Target {
 156 ///         &self.value
 157 ///     }
 158 /// }
 159 ///
 160 /// impl<T> DerefMut for DerefMutExample<T> {
 161 ///     fn deref_mut(&mut self) -> &mut Self::Target {
 162 ///         &mut self.value
 163 ///     }
 164 /// }
 165 ///
 166 /// let mut x = DerefMutExample { value: 'a' };
 167 /// *x = 'b';
 168 /// assert_eq!('b', x.value);
 169 /// ```
 170 #[lang = "deref_mut"]
 171 #[doc(alias = "*")]
 172 #[stable(feature = "rust1", since = "1.0.0")]
 173 #[const_trait]
 174 pub trait DerefMut: Deref {
 175     /// Mutably dereferences the value.
 176     #[stable(feature = "rust1", since = "1.0.0")]
 177     fn deref_mut(&mut self) -> &mut Self::Target;
 178 }
 179
 180 #[stable(feature = "rust1", since = "1.0.0")]
 181 impl<T: ?Sized> DerefMut for &mut T {
 182     fn deref_mut(&mut self) -> &mut T {
 183         *self
 184     }
 185 }
 186
 187 /// Indicates that a struct can be used as a method receiver, without the
 188 /// `arbitrary_self_types` feature. This is implemented by stdlib pointer types like `Box<T>`,
 189 /// `Rc<T>`, `&T`, and `Pin<P>`.
 190 #[lang = "receiver"]
 191 #[unstable(feature = "receiver_trait", issue = "none")]
 192 #[doc(hidden)]
 193 pub trait Receiver {
 194     // Empty.
 195 }
 196
 197 #[unstable(feature = "receiver_trait", issue = "none")]
 198 impl<T: ?Sized> Receiver for &T {}
 199
 200 #[unstable(feature = "receiver_trait", issue = "none")]
 201 impl<T: ?Sized> Receiver for &mut T {}