175 lines
6 KiB
Rust
175 lines
6 KiB
Rust
// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
|
|
// file at the top-level directory of this distribution and at
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
/// Used for immutable dereferencing operations, like `*v`.
|
|
///
|
|
/// In addition to being used for explicit dereferencing operations with the
|
|
/// (unary) `*` operator in immutable contexts, `Deref` is also used implicitly
|
|
/// by the compiler in many circumstances. This mechanism is called
|
|
/// ['`Deref` coercion'][more]. In mutable contexts, [`DerefMut`] is used.
|
|
///
|
|
/// Implementing `Deref` for smart pointers makes accessing the data behind them
|
|
/// convenient, which is why they implement `Deref`. On the other hand, the
|
|
/// rules regarding `Deref` and [`DerefMut`] were designed specifically to
|
|
/// accomodate smart pointers. Because of this, **`Deref` should only be
|
|
/// implemented for smart pointers** to avoid confusion.
|
|
///
|
|
/// For similar reasons, **this trait should never fail**. Failure during
|
|
/// dereferencing can be extremely confusing when `Deref` is invoked implicitly.
|
|
///
|
|
/// # More on `Deref` coercion
|
|
///
|
|
/// If `T` implements `Deref<Target = U>`, and `x` is a value of type `T`, then:
|
|
///
|
|
/// * In immutable contexts, `*x` on non-pointer types is equivalent to
|
|
/// `*Deref::deref(&x)`.
|
|
/// * Values of type `&T` are coerced to values of type `&U`
|
|
/// * `T` implicitly implements all the (immutable) methods of the type `U`.
|
|
///
|
|
/// For more details, visit [the chapter in *The Rust Programming Language*]
|
|
/// [book] as well as the reference sections on [the dereference operator]
|
|
/// [ref-deref-op], [the `Deref` trait][ref-deref-trait], and [type coercions].
|
|
///
|
|
/// [book]: ../../book/second-edition/ch15-02-deref.html
|
|
/// [`DerefMut`]: trait.DerefMut.html
|
|
/// [more]: #more-on-deref-coercion
|
|
/// [ref-deref-op]: ../../reference/expressions.html#the-dereference-operator
|
|
/// [ref-deref-trait]: ../../reference/the-deref-trait.html
|
|
/// [type coercions]: ../../reference/type-coercions.html
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// A struct with a single field which is accessible by dereferencing the
|
|
/// struct.
|
|
///
|
|
/// ```
|
|
/// use std::ops::Deref;
|
|
///
|
|
/// struct DerefExample<T> {
|
|
/// value: T
|
|
/// }
|
|
///
|
|
/// impl<T> Deref for DerefExample<T> {
|
|
/// type Target = T;
|
|
///
|
|
/// fn deref(&self) -> &T {
|
|
/// &self.value
|
|
/// }
|
|
/// }
|
|
///
|
|
/// let x = DerefExample { value: 'a' };
|
|
/// assert_eq!('a', *x);
|
|
/// ```
|
|
#[lang = "deref"]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
pub trait Deref {
|
|
/// The resulting type after dereferencing.
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
type Target: ?Sized;
|
|
|
|
/// Dereferences the value.
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
fn deref(&self) -> &Self::Target;
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<'a, T: ?Sized> Deref for &'a T {
|
|
type Target = T;
|
|
|
|
fn deref(&self) -> &T { *self }
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<'a, T: ?Sized> Deref for &'a mut T {
|
|
type Target = T;
|
|
|
|
fn deref(&self) -> &T { *self }
|
|
}
|
|
|
|
/// Used for mutable dereferencing operations, like in `*v = 1;`.
|
|
///
|
|
/// In addition to being used for explicit dereferencing operations with the
|
|
/// (unary) `*` operator in mutable contexts, `DerefMut` is also used implicitly
|
|
/// by the compiler in many circumstances. This mechanism is called
|
|
/// ['`Deref` coercion'][more]. In immutable contexts, [`Deref`] is used.
|
|
///
|
|
/// Implementing `DerefMut` for smart pointers makes mutating the data behind
|
|
/// them convenient, which is why they implement `DerefMut`. On the other hand,
|
|
/// the rules regarding [`Deref`] and `DerefMut` were designed specifically to
|
|
/// accomodate smart pointers. Because of this, **`DerefMut` should only be
|
|
/// implemented for smart pointers** to avoid confusion.
|
|
///
|
|
/// For similar reasons, **this trait should never fail**. Failure during
|
|
/// dereferencing can be extremely confusing when `DerefMut` is invoked
|
|
/// implicitly.
|
|
///
|
|
/// # More on `Deref` coercion
|
|
///
|
|
/// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
|
|
/// then:
|
|
///
|
|
/// * In mutable contexts, `*x` on non-pointer types is equivalent to
|
|
/// `*Deref::deref(&x)`.
|
|
/// * Values of type `&mut T` are coerced to values of type `&mut U`
|
|
/// * `T` implicitly implements all the (mutable) methods of the type `U`.
|
|
///
|
|
/// For more details, visit [the chapter in *The Rust Programming Language*]
|
|
/// [book] as well as the reference sections on [the dereference operator]
|
|
/// [ref-deref-op], [the `Deref` trait][ref-deref-trait], and [type coercions].
|
|
///
|
|
/// [book]: ../../book/second-edition/ch15-02-deref.html
|
|
/// [`Deref`]: trait.Deref.html
|
|
/// [more]: #more-on-deref-coercion
|
|
/// [ref-deref-op]: ../../reference/expressions.html#the-dereference-operator
|
|
/// [ref-deref-trait]: ../../reference/the-deref-trait.html
|
|
/// [type coercions]: ../../reference/type-coercions.html
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// A struct with a single field which is modifiable by dereferencing the
|
|
/// struct.
|
|
///
|
|
/// ```
|
|
/// use std::ops::{Deref, DerefMut};
|
|
///
|
|
/// struct DerefMutExample<T> {
|
|
/// value: T
|
|
/// }
|
|
///
|
|
/// impl<T> Deref for DerefMutExample<T> {
|
|
/// type Target = T;
|
|
///
|
|
/// fn deref(&self) -> &T {
|
|
/// &self.value
|
|
/// }
|
|
/// }
|
|
///
|
|
/// impl<T> DerefMut for DerefMutExample<T> {
|
|
/// fn deref_mut(&mut self) -> &mut T {
|
|
/// &mut self.value
|
|
/// }
|
|
/// }
|
|
///
|
|
/// let mut x = DerefMutExample { value: 'a' };
|
|
/// *x = 'b';
|
|
/// assert_eq!('b', *x);
|
|
/// ```
|
|
#[lang = "deref_mut"]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
pub trait DerefMut: Deref {
|
|
/// Mutably dereferences the value.
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
fn deref_mut(&mut self) -> &mut Self::Target;
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<'a, T: ?Sized> DerefMut for &'a mut T {
|
|
fn deref_mut(&mut self) -> &mut T { *self }
|
|
}
|