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