src/libcore/ops/deref.rs

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 /// Used for immutable dereferencing operations, like `*v`.
  12 ///
  13 /// In addition to being used for explicit dereferencing operations with the
  14 /// (unary) `*` operator in immutable contexts, `Deref` is also used implicitly
  15 /// by the compiler in many circumstances. This mechanism is called
  16 /// ['`Deref` coercion'][more]. In mutable contexts, [`DerefMut`] is used.
  17 ///
  18 /// Implementing `Deref` for smart pointers makes accessing the data behind them
  19 /// convenient, which is why they implement `Deref`. On the other hand, the
  20 /// rules regarding `Deref` and [`DerefMut`] were designed specifically to
  21 /// accommodate smart pointers. Because of this, **`Deref` should only be
  22 /// implemented for smart pointers** to avoid confusion.
  23 ///
  24 /// For similar reasons, **this trait should never fail**. Failure during
  25 /// dereferencing can be extremely confusing when `Deref` is invoked implicitly.
  26 ///
  27 /// # More on `Deref` coercion
  28 ///
  29 /// If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:
  30 ///
  31 /// * In immutable contexts, `*x` on non-pointer types is equivalent to
  32 ///   `*Deref::deref(&x)`.
  33 /// * Values of type `&T` are coerced to values of type `&U`
  34 /// * `T` implicitly implements all the (immutable) methods of the type `U`.
  35 ///
  36 /// For more details, visit [the chapter in *The Rust Programming Language*]
  37 /// [book] as well as the reference sections on [the dereference operator]
  38 /// [ref-deref-op], [method resolution] and [type coercions].
  39 ///
  40 /// [book]: ../../book/second-edition/ch15-02-deref.html
  41 /// [`DerefMut`]: trait.DerefMut.html
  42 /// [more]: #more-on-deref-coercion
  43 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
  44 /// [method resolution]: ../../reference/expressions/method-call-expr.html
  45 /// [type coercions]: ../../reference/type-coercions.html
  46 ///
  47 /// # Examples
  48 ///
  49 /// A struct with a single field which is accessible by dereferencing the
  50 /// struct.
  51 ///
  52 /// ```
  53 /// use std::ops::Deref;
  54 ///
  55 /// struct DerefExample<T> {
  56 ///     value: T
  57 /// }
  58 ///
  59 /// impl<T> Deref for DerefExample<T> {
  60 ///     type Target = T;
  61 ///
  62 ///     fn deref(&self) -> &T {
  63 ///         &self.value
  64 ///     }
  65 /// }
  66 ///
  67 /// let x = DerefExample { value: 'a' };
  68 /// assert_eq!('a', *x);
  69 /// ```
  70 #[lang = "deref"]
  71 #[doc(alias = "*")]
  72 #[doc(alias = "&*")]
  73 #[stable(feature = "rust1", since = "1.0.0")]
  74 pub trait Deref {
  75     /// The resulting type after dereferencing.
  76     #[stable(feature = "rust1", since = "1.0.0")]
  77     type Target: ?Sized;
  78
  79     /// Dereferences the value.
  80     #[must_use]
  81     #[stable(feature = "rust1", since = "1.0.0")]
  82     fn deref(&self) -> &Self::Target;
  83 }
  84
  85 #[stable(feature = "rust1", since = "1.0.0")]
  86 impl<T: ?Sized> Deref for &T {
  87     type Target = T;
  88
  89     fn deref(&self) -> &T { *self }
  90 }
  91
  92 #[stable(feature = "rust1", since = "1.0.0")]
  93 impl<T: ?Sized> Deref for &mut T {
  94     type Target = T;
  95
  96     fn deref(&self) -> &T { *self }
  97 }
  98
  99 /// Used for mutable dereferencing operations, like in `*v = 1;`.
 100 ///
 101 /// In addition to being used for explicit dereferencing operations with the
 102 /// (unary) `*` operator in mutable contexts, `DerefMut` is also used implicitly
 103 /// by the compiler in many circumstances. This mechanism is called
 104 /// ['`Deref` coercion'][more]. In immutable contexts, [`Deref`] is used.
 105 ///
 106 /// Implementing `DerefMut` for smart pointers makes mutating the data behind
 107 /// them convenient, which is why they implement `DerefMut`. On the other hand,
 108 /// the rules regarding [`Deref`] and `DerefMut` were designed specifically to
 109 /// accommodate smart pointers. Because of this, **`DerefMut` should only be
 110 /// implemented for smart pointers** to avoid confusion.
 111 ///
 112 /// For similar reasons, **this trait should never fail**. Failure during
 113 /// dereferencing can be extremely confusing when `DerefMut` is invoked
 114 /// implicitly.
 115 ///
 116 /// # More on `Deref` coercion
 117 ///
 118 /// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
 119 /// then:
 120 ///
 121 /// * In mutable contexts, `*x` on non-pointer types is equivalent to
 122 ///   `*Deref::deref(&x)`.
 123 /// * Values of type `&mut T` are coerced to values of type `&mut U`
 124 /// * `T` implicitly implements all the (mutable) methods of the type `U`.
 125 ///
 126 /// For more details, visit [the chapter in *The Rust Programming Language*]
 127 /// [book] as well as the reference sections on [the dereference operator]
 128 /// [ref-deref-op], [method resolution] and [type coercions].
 129 ///
 130 /// [book]: ../../book/second-edition/ch15-02-deref.html
 131 /// [`Deref`]: trait.Deref.html
 132 /// [more]: #more-on-deref-coercion
 133 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
 134 /// [method resolution]: ../../reference/expressions/method-call-expr.html
 135 /// [type coercions]: ../../reference/type-coercions.html
 136 ///
 137 /// # Examples
 138 ///
 139 /// A struct with a single field which is modifiable by dereferencing the
 140 /// struct.
 141 ///
 142 /// ```
 143 /// use std::ops::{Deref, DerefMut};
 144 ///
 145 /// struct DerefMutExample<T> {
 146 ///     value: T
 147 /// }
 148 ///
 149 /// impl<T> Deref for DerefMutExample<T> {
 150 ///     type Target = T;
 151 ///
 152 ///     fn deref(&self) -> &T {
 153 ///         &self.value
 154 ///     }
 155 /// }
 156 ///
 157 /// impl<T> DerefMut for DerefMutExample<T> {
 158 ///     fn deref_mut(&mut self) -> &mut T {
 159 ///         &mut self.value
 160 ///     }
 161 /// }
 162 ///
 163 /// let mut x = DerefMutExample { value: 'a' };
 164 /// *x = 'b';
 165 /// assert_eq!('b', *x);
 166 /// ```
 167 #[lang = "deref_mut"]
 168 #[doc(alias = "*")]
 169 #[stable(feature = "rust1", since = "1.0.0")]
 170 pub trait DerefMut: Deref {
 171     /// Mutably dereferences the value.
 172     #[stable(feature = "rust1", since = "1.0.0")]
 173     fn deref_mut(&mut self) -> &mut Self::Target;
 174 }
 175
 176 #[stable(feature = "rust1", since = "1.0.0")]
 177 impl<T: ?Sized> DerefMut for &mut T {
 178     fn deref_mut(&mut self) -> &mut T { *self }
 179 }