Implement RFC 1542

cc #33417

1 files changed, 47 insertions, 10 deletions

diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs
index 2d999868f71..48421abc7bb 100644
--- a/src/libcore/convert.rs
+++ b/src/libcore/convert.rs
@@ -20,18 +20,19 @@
 //! - Impl the `As*` traits for reference-to-reference conversions
 //! - Impl the `Into` trait when you want to consume the value in the conversion
 //! - The `From` trait is the most flexible, useful for value _and_ reference conversions
+//! - The `TryFrom` and `TryInto` traits behave like `From` and `Into`, but allow for the
+//!   conversion to fail
 //!
-//! As a library author, you should prefer implementing `From<T>` rather than
-//! `Into<U>`, as `From` provides greater flexibility and offers an equivalent `Into`
-//! implementation for free, thanks to a blanket implementation in the standard library.
-//!
-//! **Note: these traits must not fail**. If the conversion can fail, you must use a dedicated
-//! method which returns an `Option<T>` or a `Result<T, E>`.
+//! As a library author, you should prefer implementing `From<T>` or `TryFrom<T>` rather than
+//! `Into<U>` or `TryInto<U>`, as `From` and `TryFrom` provide greater flexibility and offer
+//! equivalent `Into` or `TryInto` implementations for free, thanks to a blanket implementation
+//! in the standard library.
 //!
 //! # Generic impl
 //!
 //! - `AsRef` and `AsMut` auto-dereference if the inner type is a reference
 //! - `From<U> for T` implies `Into<T> for U`
+//! - `TryFrom<U> for T` implies `TryInto<T> for U`
 //! - `From` and `Into` are reflexive, which means that all types can `into()`
 //!   themselves and `from()` themselves
 //!
@@ -40,6 +41,7 @@
 #![stable(feature = "rust1", since = "1.0.0")]
 
 use marker::Sized;
+use result::Result;
 
 /// A cheap, reference-to-reference conversion.
 ///
@@ -98,8 +100,8 @@ pub trait AsMut<T: ?Sized> {
 
 /// A conversion that consumes `self`, which may or may not be expensive.
 ///
-/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which
-/// returns an `Option<T>` or a `Result<T, E>`.
+/// **Note: this trait must not fail**. If the conversion can fail, use `TryInto` or a dedicated
+/// method which returns an `Option<T>` or a `Result<T, E>`.
 ///
 /// Library authors should not directly implement this trait, but should prefer implementing
 /// the `From` trait, which offers greater flexibility and provides an equivalent `Into`
@@ -133,8 +135,8 @@ pub trait Into<T>: Sized {
 
 /// Construct `Self` via a conversion.
 ///
-/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which
-/// returns an `Option<T>` or a `Result<T, E>`.
+/// **Note: this trait must not fail**. If the conversion can fail, use `TryFrom` or a dedicated
+/// method which returns an `Option<T>` or a `Result<T, E>`.
 ///
 /// # Examples
 ///
@@ -158,6 +160,30 @@ pub trait From<T>: Sized {
     fn from(T) -> Self;
 }
 
+/// An attempted conversion that consumes `self`, which may or may not be expensive.
+///
+/// Library authors should not directly implement this trait, but should prefer implementing
+/// the `TryFrom` trait, which offers greater flexibility and provides an equivalent `TryInto`
+/// implementation for free, thanks to a blanket implementation in the standard library.
+#[unstable(feature = "try_from", issue = "33417")]
+pub trait TryInto<T>: Sized {
+    /// The type returned in the event of a conversion error.
+    type Err;
+
+    /// Performs the conversion.
+    fn try_into(self) -> Result<T, Self::Err>;
+}
+
+/// Attempt to construct `Self` via a conversion.
+#[unstable(feature = "try_from", issue = "33417")]
+pub trait TryFrom<T>: Sized {
+    /// The type returned in the event of a conversion error.
+    type Err;
+
+    /// Performs the conversion.
+    fn try_from(T) -> Result<Self, Self::Err>;
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 // GENERIC IMPLS
 ////////////////////////////////////////////////////////////////////////////////
@@ -216,6 +242,17 @@ impl<T> From<T> for T {
     fn from(t: T) -> T { t }
 }
 
+
+// TryFrom implies TryInto
+#[unstable(feature = "try_from", issue = "33417")]
+impl<T, U> TryInto<U> for T where U: TryFrom<T> {
+    type Err = U::Err;
+
+    fn try_into(self) -> Result<U, U::Err> {
+        U::try_from(self)
+    }
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 // CONCRETE IMPLS
 ////////////////////////////////////////////////////////////////////////////////