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 #[stable(feature = "rust1", since = "1.0.0")]
  72 pub trait Deref {
  73     /// The resulting type after dereferencing.
  74     #[stable(feature = "rust1", since = "1.0.0")]
  75     type Target: ?Sized;
  76
  77     /// Dereferences the value.
  78     #[stable(feature = "rust1", since = "1.0.0")]
  79     fn deref(&self) -> &Self::Target;
  80 }
  81
  82 #[stable(feature = "rust1", since = "1.0.0")]
  83 impl<'a, T: ?Sized> Deref for &'a T {
  84     type Target = T;
  85
  86     fn deref(&self) -> &T { *self }
  87 }
  88
  89 #[stable(feature = "rust1", since = "1.0.0")]
  90 impl<'a, T: ?Sized> Deref for &'a mut T {
  91     type Target = T;
  92
  93     fn deref(&self) -> &T { *self }
  94 }
  95
  96 /// Used for mutable dereferencing operations, like in `*v = 1;`.
  97 ///
  98 /// In addition to being used for explicit dereferencing operations with the
  99 /// (unary) `*` operator in mutable contexts, `DerefMut` is also used implicitly
 100 /// by the compiler in many circumstances. This mechanism is called
 101 /// ['`Deref` coercion'][more]. In immutable contexts, [`Deref`] is used.
 102 ///
 103 /// Implementing `DerefMut` for smart pointers makes mutating the data behind
 104 /// them convenient, which is why they implement `DerefMut`. On the other hand,
 105 /// the rules regarding [`Deref`] and `DerefMut` were designed specifically to
 106 /// accommodate smart pointers. Because of this, **`DerefMut` should only be
 107 /// implemented for smart pointers** to avoid confusion.
 108 ///
 109 /// For similar reasons, **this trait should never fail**. Failure during
 110 /// dereferencing can be extremely confusing when `DerefMut` is invoked
 111 /// implicitly.
 112 ///
 113 /// # More on `Deref` coercion
 114 ///
 115 /// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
 116 /// then:
 117 ///
 118 /// * In mutable contexts, `*x` on non-pointer types is equivalent to
 119 ///   `*Deref::deref(&x)`.
 120 /// * Values of type `&mut T` are coerced to values of type `&mut U`
 121 /// * `T` implicitly implements all the (mutable) methods of the type `U`.
 122 ///
 123 /// For more details, visit [the chapter in *The Rust Programming Language*]
 124 /// [book] as well as the reference sections on [the dereference operator]
 125 /// [ref-deref-op], [method resolution] and [type coercions].
 126 ///
 127 /// [book]: ../../book/second-edition/ch15-02-deref.html
 128 /// [`Deref`]: trait.Deref.html
 129 /// [more]: #more-on-deref-coercion
 130 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
 131 /// [method resolution]: ../../reference/expressions/method-call-expr.html
 132 /// [type coercions]: ../../reference/type-coercions.html
 133 ///
 134 /// # Examples
 135 ///
 136 /// A struct with a single field which is modifiable by dereferencing the
 137 /// struct.
 138 ///
 139 /// ```
 140 /// use std::ops::{Deref, DerefMut};
 141 ///
 142 /// struct DerefMutExample<T> {
 143 ///     value: T
 144 /// }
 145 ///
 146 /// impl<T> Deref for DerefMutExample<T> {
 147 ///     type Target = T;
 148 ///
 149 ///     fn deref(&self) -> &T {
 150 ///         &self.value
 151 ///     }
 152 /// }
 153 ///
 154 /// impl<T> DerefMut for DerefMutExample<T> {
 155 ///     fn deref_mut(&mut self) -> &mut T {
 156 ///         &mut self.value
 157 ///     }
 158 /// }
 159 ///
 160 /// let mut x = DerefMutExample { value: 'a' };
 161 /// *x = 'b';
 162 /// assert_eq!('b', *x);
 163 /// ```
 164 #[lang = "deref_mut"]
 165 #[stable(feature = "rust1", since = "1.0.0")]
 166 pub trait DerefMut: Deref {
 167     /// Mutably dereferences the value.
 168     #[stable(feature = "rust1", since = "1.0.0")]
 169     fn deref_mut(&mut self) -> &mut Self::Target;
 170 }
 171
 172 #[stable(feature = "rust1", since = "1.0.0")]
 173 impl<'a, T: ?Sized> DerefMut for &'a mut T {
 174     fn deref_mut(&mut self) -> &mut T { *self }
 175 }