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.
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.
11 /// Used for immutable dereferencing operations, like `*v`.
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.
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.
24 /// For similar reasons, **this trait should never fail**. Failure during
25 /// dereferencing can be extremely confusing when `Deref` is invoked implicitly.
27 /// # More on `Deref` coercion
29 /// If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:
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`.
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].
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
49 /// A struct with a single field which is accessible by dereferencing the
53 /// use std::ops::Deref;
55 /// struct DerefExample<T> {
59 /// impl<T> Deref for DerefExample<T> {
62 /// fn deref(&self) -> &T {
67 /// let x = DerefExample { value: 'a' };
68 /// assert_eq!('a', *x);
71 #[stable(feature = "rust1", since = "1.0.0")]
73 /// The resulting type after dereferencing.
74 #[stable(feature = "rust1", since = "1.0.0")]
77 /// Dereferences the value.
78 #[stable(feature = "rust1", since = "1.0.0")]
79 fn deref(&self) -> &Self::Target;
82 #[stable(feature = "rust1", since = "1.0.0")]
83 impl<'a, T: ?Sized> Deref for &'a T {
86 fn deref(&self) -> &T { *self }
89 #[stable(feature = "rust1", since = "1.0.0")]
90 impl<'a, T: ?Sized> Deref for &'a mut T {
93 fn deref(&self) -> &T { *self }
96 /// Used for mutable dereferencing operations, like in `*v = 1;`.
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.
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.
109 /// For similar reasons, **this trait should never fail**. Failure during
110 /// dereferencing can be extremely confusing when `DerefMut` is invoked
113 /// # More on `Deref` coercion
115 /// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
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`.
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].
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
136 /// A struct with a single field which is modifiable by dereferencing the
140 /// use std::ops::{Deref, DerefMut};
142 /// struct DerefMutExample<T> {
146 /// impl<T> Deref for DerefMutExample<T> {
149 /// fn deref(&self) -> &T {
154 /// impl<T> DerefMut for DerefMutExample<T> {
155 /// fn deref_mut(&mut self) -> &mut T {
160 /// let mut x = DerefMutExample { value: 'a' };
162 /// assert_eq!('b', *x);
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;
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 }