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