rollup merge of #21718: alexcrichton/stabilize-from-str

This commits adds an associated type to the `FromStr` trait representing an
error payload for parses which do not succeed. The previous return value,
`Option<Self>` did not allow for this form of payload. After the associated type
was added, the following attributes were applied:

* `FromStr` is now stable
* `FromStr::Err` is now stable
* `FromStr::from_str` is now stable
* `StrExt::parse` is now stable
* `FromStr for bool` is now stable
* `FromStr for $float` is now stable
* `FromStr for $integral` is now stable
* Errors returned from stable `FromStr` implementations are stable
* Errors implement `Display` and `Error` (both impl blocks being `#[stable]`)

Closes #15138

src/libcore/str/mod.rs

@@ -109,37 +109,62 @@ macro_rules! delegate_iter {
 
 /// A trait to abstract the idea of creating a new instance of a type from a
 /// string.
-// FIXME(#17307): there should be an `E` associated type for a `Result` return
-#[unstable(feature = "core",
-           reason = "will return a Result once associated types are working")]
+#[stable(feature = "rust1", since = "1.0.0")]
 pub trait FromStr {
+    /// The associated error which can be returned from parsing.
+    #[stable(feature = "rust1", since = "1.0.0")]
+    type Err;
+
     /// Parses a string `s` to return an optional value of this type. If the
     /// string is ill-formatted, the None is returned.
-    fn from_str(s: &str) -> Option<Self>;
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn from_str(s: &str) -> Result<Self, Self::Err>;
 }
 
+#[stable(feature = "rust1", since = "1.0.0")]
 impl FromStr for bool {
+    type Err = ParseBoolError;
+
     /// Parse a `bool` from a string.
     ///
-    /// Yields an `Option<bool>`, because `s` may or may not actually be parseable.
+    /// Yields an `Option<bool>`, because `s` may or may not actually be
+    /// parseable.
     ///
     /// # Examples
     ///
     /// ```rust
-    /// assert_eq!("true".parse(), Some(true));
-    /// assert_eq!("false".parse(), Some(false));
-    /// assert_eq!("not even a boolean".parse::<bool>(), None);
+    /// assert_eq!("true".parse(), Ok(true));
+    /// assert_eq!("false".parse(), Ok(false));
+    /// assert!("not even a boolean".parse::<bool>().is_err());
     /// ```
     #[inline]
-    fn from_str(s: &str) -> Option<bool> {
+    fn from_str(s: &str) -> Result<bool, ParseBoolError> {
         match s {
-            "true"  => Some(true),
-            "false" => Some(false),
-            _       => None,
+            "true"  => Ok(true),
+            "false" => Ok(false),
+            _       => Err(ParseBoolError { _priv: () }),
         }
     }
 }
 
+/// An error returned when parsing a `bool` from a string fails.
+#[derive(Show, Clone, PartialEq)]
+#[allow(missing_copy_implementations)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub struct ParseBoolError { _priv: () }
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl fmt::Display for ParseBoolError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        "provided string was not `true` or `false`".fmt(f)
+    }
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl Error for ParseBoolError {
+    fn description(&self) -> &str { "failed to parse bool" }
+}
+
 /*
 Section: Creating a string
 */
@@ -1356,7 +1381,7 @@ pub trait StrExt {
     fn as_ptr(&self) -> *const u8;
     fn len(&self) -> uint;
     fn is_empty(&self) -> bool;
-    fn parse<T: FromStr>(&self) -> Option<T>;
+    fn parse<T: FromStr>(&self) -> Result<T, T::Err>;
 }
 
 #[inline(never)]
@@ -1671,7 +1696,7 @@ impl StrExt for str {
     fn is_empty(&self) -> bool { self.len() == 0 }
 
     #[inline]
-    fn parse<T: FromStr>(&self) -> Option<T> { FromStr::from_str(self) }
+    fn parse<T: FromStr>(&self) -> Result<T, T::Err> { FromStr::from_str(self) }
 }
 
 /// Pluck a code point out of a UTF-8-like byte slice and return the