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 conversions from one type to
  14 //! another. They follow the standard Rust conventions of `as`/`into`/`from`.
  15 //!
  16 //! Like many traits, these are often used as bounds for generic functions, to support arguments of
  17 //! multiple types.
  18 //!
  19 //! See each trait for usage examples.
  20
  21 #![stable(feature = "rust1", since = "1.0.0")]
  22
  23 use marker::Sized;
  24
  25 /// A cheap, reference-to-reference conversion.
  26 ///
  27 /// `AsRef` is very similar to, but different than, `Borrow`. See
  28 /// [the book][book] for more.
  29 ///
  30 /// [book]: ../../book/borrow-and-asref.html
  31 ///
  32 /// # Examples
  33 ///
  34 /// Both `String` and `&str` implement `AsRef<str>`:
  35 ///
  36 /// ```
  37 /// fn is_hello<T: AsRef<str>>(s: T) {
  38 ///    assert_eq!("hello", s.as_ref());
  39 /// }
  40 ///
  41 /// let s = "hello";
  42 /// is_hello(s);
  43 ///
  44 /// let s = "hello".to_string();
  45 /// is_hello(s);
  46 /// ```
  47 #[stable(feature = "rust1", since = "1.0.0")]
  48 pub trait AsRef<T: ?Sized> {
  49     /// Performs the conversion.
  50     #[stable(feature = "rust1", since = "1.0.0")]
  51     fn as_ref(&self) -> &T;
  52 }
  53
  54 /// A cheap, mutable reference-to-mutable reference conversion.
  55 #[stable(feature = "rust1", since = "1.0.0")]
  56 pub trait AsMut<T: ?Sized> {
  57     /// Performs the conversion.
  58     #[stable(feature = "rust1", since = "1.0.0")]
  59     fn as_mut(&mut self) -> &mut T;
  60 }
  61
  62 /// A conversion that consumes `self`, which may or may not be expensive.
  63 ///
  64 /// # Examples
  65 ///
  66 /// `String` implements `Into<Vec<u8>>`:
  67 ///
  68 /// ```
  69 /// fn is_hello<T: Into<Vec<u8>>>(s: T) {
  70 ///    let bytes = b"hello".to_vec();
  71 ///    assert_eq!(bytes, s.into());
  72 /// }
  73 ///
  74 /// let s = "hello".to_string();
  75 /// is_hello(s);
  76 /// ```
  77 #[stable(feature = "rust1", since = "1.0.0")]
  78 pub trait Into<T>: Sized {
  79     /// Performs the conversion.
  80     #[stable(feature = "rust1", since = "1.0.0")]
  81     fn into(self) -> T;
  82 }
  83
  84 /// Construct `Self` via a conversion.
  85 ///
  86 /// # Examples
  87 ///
  88 /// `String` implements `From<&str>`:
  89 ///
  90 /// ```
  91 /// let string = "hello".to_string();
  92 /// let other_string = String::from("hello");
  93 ///
  94 /// assert_eq!(string, other_string);
  95 /// ```
  96 #[stable(feature = "rust1", since = "1.0.0")]
  97 pub trait From<T> {
  98     /// Performs the conversion.
  99     #[stable(feature = "rust1", since = "1.0.0")]
 100     fn from(T) -> Self;
 101 }
 102
 103 ////////////////////////////////////////////////////////////////////////////////
 104 // GENERIC IMPLS
 105 ////////////////////////////////////////////////////////////////////////////////
 106
 107 // As lifts over &
 108 #[stable(feature = "rust1", since = "1.0.0")]
 109 impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a T where T: AsRef<U> {
 110     fn as_ref(&self) -> &U {
 111         <T as AsRef<U>>::as_ref(*self)
 112     }
 113 }
 114
 115 // As lifts over &mut
 116 #[stable(feature = "rust1", since = "1.0.0")]
 117 impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a mut T where T: AsRef<U> {
 118     fn as_ref(&self) -> &U {
 119         <T as AsRef<U>>::as_ref(*self)
 120     }
 121 }
 122
 123 // FIXME (#23442): replace the above impls for &/&mut with the following more general one:
 124 // // As lifts over Deref
 125 // impl<D: ?Sized + Deref, U: ?Sized> AsRef<U> for D where D::Target: AsRef<U> {
 126 //     fn as_ref(&self) -> &U {
 127 //         self.deref().as_ref()
 128 //     }
 129 // }
 130
 131 // AsMut lifts over &mut
 132 #[stable(feature = "rust1", since = "1.0.0")]
 133 impl<'a, T: ?Sized, U: ?Sized> AsMut<U> for &'a mut T where T: AsMut<U> {
 134     fn as_mut(&mut self) -> &mut U {
 135         (*self).as_mut()
 136     }
 137 }
 138
 139 // FIXME (#23442): replace the above impl for &mut with the following more general one:
 140 // // AsMut lifts over DerefMut
 141 // impl<D: ?Sized + Deref, U: ?Sized> AsMut<U> for D where D::Target: AsMut<U> {
 142 //     fn as_mut(&mut self) -> &mut U {
 143 //         self.deref_mut().as_mut()
 144 //     }
 145 // }
 146
 147 // From implies Into
 148 #[stable(feature = "rust1", since = "1.0.0")]
 149 impl<T, U> Into<U> for T where U: From<T> {
 150     fn into(self) -> U {
 151         U::from(self)
 152     }
 153 }
 154
 155 // From (and thus Into) is reflexive
 156 #[stable(feature = "rust1", since = "1.0.0")]
 157 impl<T> From<T> for T {
 158     fn from(t: T) -> T { t }
 159 }
 160
 161 ////////////////////////////////////////////////////////////////////////////////
 162 // CONCRETE IMPLS
 163 ////////////////////////////////////////////////////////////////////////////////
 164
 165 #[stable(feature = "rust1", since = "1.0.0")]
 166 impl<T> AsRef<[T]> for [T] {
 167     fn as_ref(&self) -> &[T] {
 168         self
 169     }
 170 }
 171
 172 #[stable(feature = "rust1", since = "1.0.0")]
 173 impl<T> AsMut<[T]> for [T] {
 174     fn as_mut(&mut self) -> &mut [T] {
 175         self
 176     }
 177 }
 178
 179 #[stable(feature = "rust1", since = "1.0.0")]
 180 impl AsRef<str> for str {
 181     #[inline]
 182     fn as_ref(&self) -> &str {
 183         self
 184     }
 185 }