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.
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 //! Traits for conversions between types.
13 //! The traits in this module provide a general way to talk about conversions
14 //! from one type to another. They follow the standard Rust conventions of
15 //! `as`/`into`/`from`.
17 //! Like many traits, these are often used as bounds for generic functions, to
18 //! support arguments of multiple types.
20 //! See each trait for usage examples.
22 #![stable(feature = "rust1", since = "1.0.0")]
26 /// A cheap, reference-to-reference conversion.
28 /// `AsRef` is very similar to, but different than, `Borrow`. See
29 /// [the book][book] for more.
31 /// [book]: ../../book/borrow-and-asref.html
35 /// Both `String` and `&str` implement `AsRef<str>`:
38 /// fn is_hello<T: AsRef<str>>(s: T) {
39 /// assert_eq!("hello", s.as_ref());
45 /// let s = "hello".to_string();
48 #[stable(feature = "rust1", since = "1.0.0")]
49 pub trait AsRef<T: ?Sized> {
50 /// Performs the conversion.
51 #[stable(feature = "rust1", since = "1.0.0")]
52 fn as_ref(&self) -> &T;
55 /// A cheap, mutable reference-to-mutable reference conversion.
56 #[stable(feature = "rust1", since = "1.0.0")]
57 pub trait AsMut<T: ?Sized> {
58 /// Performs the conversion.
59 #[stable(feature = "rust1", since = "1.0.0")]
60 fn as_mut(&mut self) -> &mut T;
63 /// A conversion that consumes `self`, which may or may not be expensive.
67 /// `String` implements `Into<Vec<u8>>`:
70 /// fn is_hello<T: Into<Vec<u8>>>(s: T) {
71 /// let bytes = b"hello".to_vec();
72 /// assert_eq!(bytes, s.into());
75 /// let s = "hello".to_string();
78 #[stable(feature = "rust1", since = "1.0.0")]
79 pub trait Into<T>: Sized {
80 /// Performs the conversion.
81 #[stable(feature = "rust1", since = "1.0.0")]
85 /// Construct `Self` via a conversion.
89 /// `String` implements `From<&str>`:
92 /// let string = "hello".to_string();
93 /// let other_string = String::from("hello");
95 /// assert_eq!(string, other_string);
97 #[stable(feature = "rust1", since = "1.0.0")]
99 /// Performs the conversion.
100 #[stable(feature = "rust1", since = "1.0.0")]
104 ////////////////////////////////////////////////////////////////////////////////
106 ////////////////////////////////////////////////////////////////////////////////
109 #[stable(feature = "rust1", since = "1.0.0")]
110 impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a T where T: AsRef<U> {
111 fn as_ref(&self) -> &U {
112 <T as AsRef<U>>::as_ref(*self)
116 // As lifts over &mut
117 #[stable(feature = "rust1", since = "1.0.0")]
118 impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a mut T where T: AsRef<U> {
119 fn as_ref(&self) -> &U {
120 <T as AsRef<U>>::as_ref(*self)
124 // FIXME (#23442): replace the above impls for &/&mut with the following more general one:
125 // // As lifts over Deref
126 // impl<D: ?Sized + Deref, U: ?Sized> AsRef<U> for D where D::Target: AsRef<U> {
127 // fn as_ref(&self) -> &U {
128 // self.deref().as_ref()
132 // AsMut lifts over &mut
133 #[stable(feature = "rust1", since = "1.0.0")]
134 impl<'a, T: ?Sized, U: ?Sized> AsMut<U> for &'a mut T where T: AsMut<U> {
135 fn as_mut(&mut self) -> &mut U {
140 // FIXME (#23442): replace the above impl for &mut with the following more general one:
141 // // AsMut lifts over DerefMut
142 // impl<D: ?Sized + Deref, U: ?Sized> AsMut<U> for D where D::Target: AsMut<U> {
143 // fn as_mut(&mut self) -> &mut U {
144 // self.deref_mut().as_mut()
149 #[stable(feature = "rust1", since = "1.0.0")]
150 impl<T, U> Into<U> for T where U: From<T> {
156 // From (and thus Into) is reflexive
157 #[stable(feature = "rust1", since = "1.0.0")]
158 impl<T> From<T> for T {
159 fn from(t: T) -> T { t }
162 ////////////////////////////////////////////////////////////////////////////////
164 ////////////////////////////////////////////////////////////////////////////////
166 #[stable(feature = "rust1", since = "1.0.0")]
167 impl<T> AsRef<[T]> for [T] {
168 fn as_ref(&self) -> &[T] {
173 #[stable(feature = "rust1", since = "1.0.0")]
174 impl<T> AsMut<[T]> for [T] {
175 fn as_mut(&mut self) -> &mut [T] {
180 #[stable(feature = "rust1", since = "1.0.0")]
181 impl AsRef<str> for str {
183 fn as_ref(&self) -> &str {