]>
Commit | Line | Data |
---|---|---|
041b39d2 XL |
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 | ||
3b2f2976 | 11 | /// Used for immutable dereferencing operations, like `*v`. |
041b39d2 | 12 | /// |
3b2f2976 XL |
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. | |
041b39d2 | 17 | /// |
3b2f2976 XL |
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 | /// accomodate 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], [the `Deref` trait][ref-deref-trait], and [type coercions]. | |
39 | /// | |
40 | /// [book]: ../../book/second-edition/ch15-02-deref.html | |
41 | /// [`DerefMut`]: trait.DerefMut.html | |
42 | /// [more]: #more-on-deref-coercion | |
ea8adc8c | 43 | /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator |
3b2f2976 XL |
44 | /// [ref-deref-trait]: ../../reference/the-deref-trait.html |
45 | /// [type coercions]: ../../reference/type-coercions.html | |
041b39d2 XL |
46 | /// |
47 | /// # Examples | |
48 | /// | |
3b2f2976 | 49 | /// A struct with a single field which is accessible by dereferencing the |
041b39d2 XL |
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 | /// | |
3b2f2976 XL |
67 | /// let x = DerefExample { value: 'a' }; |
68 | /// assert_eq!('a', *x); | |
041b39d2 XL |
69 | /// ``` |
70 | #[lang = "deref"] | |
71 | #[stable(feature = "rust1", since = "1.0.0")] | |
72 | pub trait Deref { | |
3b2f2976 | 73 | /// The resulting type after dereferencing. |
041b39d2 XL |
74 | #[stable(feature = "rust1", since = "1.0.0")] |
75 | type Target: ?Sized; | |
76 | ||
3b2f2976 | 77 | /// Dereferences the value. |
041b39d2 XL |
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 | ||
3b2f2976 | 96 | /// Used for mutable dereferencing operations, like in `*v = 1;`. |
041b39d2 | 97 | /// |
3b2f2976 XL |
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. | |
041b39d2 | 102 | /// |
3b2f2976 XL |
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 | /// accomodate 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], [the `Deref` trait][ref-deref-trait], and [type coercions]. | |
126 | /// | |
127 | /// [book]: ../../book/second-edition/ch15-02-deref.html | |
128 | /// [`Deref`]: trait.Deref.html | |
129 | /// [more]: #more-on-deref-coercion | |
ea8adc8c | 130 | /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator |
3b2f2976 XL |
131 | /// [ref-deref-trait]: ../../reference/the-deref-trait.html |
132 | /// [type coercions]: ../../reference/type-coercions.html | |
041b39d2 XL |
133 | /// |
134 | /// # Examples | |
135 | /// | |
3b2f2976 | 136 | /// A struct with a single field which is modifiable by dereferencing the |
041b39d2 XL |
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 | /// | |
3b2f2976 XL |
160 | /// let mut x = DerefMutExample { value: 'a' }; |
161 | /// *x = 'b'; | |
162 | /// assert_eq!('b', *x); | |
041b39d2 XL |
163 | /// ``` |
164 | #[lang = "deref_mut"] | |
165 | #[stable(feature = "rust1", since = "1.0.0")] | |
166 | pub trait DerefMut: Deref { | |
3b2f2976 | 167 | /// Mutably dereferences the value. |
041b39d2 XL |
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 | } |