src/libcore/convert.rs

   1 // Copyright 2014 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 //! Traits for conversions between types.
  12 //!
  13 //! The traits in this module provide a general way to talk about
  14 //! conversions from one type to another. They follow the standard
  15 //! Rust conventions of `as`/`to`/`into`/`from`.
  16
  17 #![stable(feature = "rust1", since = "1.0.0")]
  18
  19 use marker::Sized;
  20
  21 /// A cheap, reference-to-reference conversion.
  22 #[stable(feature = "rust1", since = "1.0.0")]
  23 pub trait AsRef<T: ?Sized> {
  24     /// Perform the conversion.
  25     #[stable(feature = "rust1", since = "1.0.0")]
  26     fn as_ref(&self) -> &T;
  27 }
  28
  29 /// A cheap, mutable reference-to-mutable reference conversion.
  30 #[stable(feature = "rust1", since = "1.0.0")]
  31 pub trait AsMut<T: ?Sized> {
  32     /// Perform the conversion.
  33     #[stable(feature = "rust1", since = "1.0.0")]
  34     fn as_mut(&mut self) -> &mut T;
  35 }
  36
  37 /// A conversion that consumes `self`, which may or may not be
  38 /// expensive.
  39 #[stable(feature = "rust1", since = "1.0.0")]
  40 pub trait Into<T>: Sized {
  41     /// Perform the conversion.
  42     #[stable(feature = "rust1", since = "1.0.0")]
  43     fn into(self) -> T;
  44 }
  45
  46 /// Construct `Self` via a conversion.
  47 #[stable(feature = "rust1", since = "1.0.0")]
  48 pub trait From<T> {
  49     /// Perform the conversion.
  50     #[stable(feature = "rust1", since = "1.0.0")]
  51     fn from(T) -> Self;
  52 }
  53
  54 ////////////////////////////////////////////////////////////////////////////////
  55 // GENERIC IMPLS
  56 ////////////////////////////////////////////////////////////////////////////////
  57
  58 // As lifts over &
  59 #[stable(feature = "rust1", since = "1.0.0")]
  60 impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a T where T: AsRef<U> {
  61     fn as_ref(&self) -> &U {
  62         <T as AsRef<U>>::as_ref(*self)
  63     }
  64 }
  65
  66 // As lifts over &mut
  67 #[stable(feature = "rust1", since = "1.0.0")]
  68 impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a mut T where T: AsRef<U> {
  69     fn as_ref(&self) -> &U {
  70         <T as AsRef<U>>::as_ref(*self)
  71     }
  72 }
  73
  74 // FIXME (#23442): replace the above impls for &/&mut with the following more general one:
  75 // // As lifts over Deref
  76 // impl<D: ?Sized + Deref, U: ?Sized> AsRef<U> for D where D::Target: AsRef<U> {
  77 //     fn as_ref(&self) -> &U {
  78 //         self.deref().as_ref()
  79 //     }
  80 // }
  81
  82 // AsMut lifts over &mut
  83 #[stable(feature = "rust1", since = "1.0.0")]
  84 impl<'a, T: ?Sized, U: ?Sized> AsMut<U> for &'a mut T where T: AsMut<U> {
  85     fn as_mut(&mut self) -> &mut U {
  86         (*self).as_mut()
  87     }
  88 }
  89
  90 // FIXME (#23442): replace the above impl for &mut with the following more general one:
  91 // // AsMut lifts over DerefMut
  92 // impl<D: ?Sized + Deref, U: ?Sized> AsMut<U> for D where D::Target: AsMut<U> {
  93 //     fn as_mut(&mut self) -> &mut U {
  94 //         self.deref_mut().as_mut()
  95 //     }
  96 // }
  97
  98 // From implies Into
  99 #[stable(feature = "rust1", since = "1.0.0")]
 100 impl<T, U> Into<U> for T where U: From<T> {
 101     fn into(self) -> U {
 102         U::from(self)
 103     }
 104 }
 105
 106 // From (and thus Into) is reflexive
 107 #[stable(feature = "rust1", since = "1.0.0")]
 108 impl<T> From<T> for T {
 109     fn from(t: T) -> T { t }
 110 }
 111
 112 ////////////////////////////////////////////////////////////////////////////////
 113 // CONCRETE IMPLS
 114 ////////////////////////////////////////////////////////////////////////////////
 115
 116 #[stable(feature = "rust1", since = "1.0.0")]
 117 impl<T> AsRef<[T]> for [T] {
 118     fn as_ref(&self) -> &[T] {
 119         self
 120     }
 121 }
 122
 123 #[stable(feature = "rust1", since = "1.0.0")]
 124 impl<T> AsMut<[T]> for [T] {
 125     fn as_mut(&mut self) -> &mut [T] {
 126         self
 127     }
 128 }
 129
 130 #[stable(feature = "rust1", since = "1.0.0")]
 131 impl AsRef<str> for str {
 132     fn as_ref(&self) -> &str {
 133         self
 134     }
 135 }