std: Stabilize APIs for the 1.7 release

This commit stabilizes and deprecates the FCP (final comment period) APIs for
the upcoming 1.7 beta release. The specific APIs which changed were:

Stabilized

* `Path::strip_prefix` (renamed from `relative_from`)
* `path::StripPrefixError` (new error type returned from `strip_prefix`)
* `Ipv4Addr::is_loopback`
* `Ipv4Addr::is_private`
* `Ipv4Addr::is_link_local`
* `Ipv4Addr::is_multicast`
* `Ipv4Addr::is_broadcast`
* `Ipv4Addr::is_documentation`
* `Ipv6Addr::is_unspecified`
* `Ipv6Addr::is_loopback`
* `Ipv6Addr::is_unique_local`
* `Ipv6Addr::is_multicast`
* `Vec::as_slice`
* `Vec::as_mut_slice`
* `String::as_str`
* `String::as_mut_str`
* `<[T]>::clone_from_slice` - the `usize` return value is removed
* `<[T]>::sort_by_key`
* `i32::checked_rem` (and other signed types)
* `i32::checked_neg` (and other signed types)
* `i32::checked_shl` (and other signed types)
* `i32::checked_shr` (and other signed types)
* `i32::saturating_mul` (and other signed types)
* `i32::overflowing_add` (and other signed types)
* `i32::overflowing_sub` (and other signed types)
* `i32::overflowing_mul` (and other signed types)
* `i32::overflowing_div` (and other signed types)
* `i32::overflowing_rem` (and other signed types)
* `i32::overflowing_neg` (and other signed types)
* `i32::overflowing_shl` (and other signed types)
* `i32::overflowing_shr` (and other signed types)
* `u32::checked_rem` (and other unsigned types)
* `u32::checked_neg` (and other unsigned types)
* `u32::checked_shl` (and other unsigned types)
* `u32::saturating_mul` (and other unsigned types)
* `u32::overflowing_add` (and other unsigned types)
* `u32::overflowing_sub` (and other unsigned types)
* `u32::overflowing_mul` (and other unsigned types)
* `u32::overflowing_div` (and other unsigned types)
* `u32::overflowing_rem` (and other unsigned types)
* `u32::overflowing_neg` (and other unsigned types)
* `u32::overflowing_shl` (and other unsigned types)
* `u32::overflowing_shr` (and other unsigned types)
* `ffi::IntoStringError`
* `CString::into_string`
* `CString::into_bytes`
* `CString::into_bytes_with_nul`
* `From<CString> for Vec<u8>`
* `From<CString> for Vec<u8>`
* `IntoStringError::into_cstring`
* `IntoStringError::utf8_error`
* `Error for IntoStringError`

Deprecated

* `Path::relative_from` - renamed to `strip_prefix`
* `Path::prefix` - use `components().next()` instead
* `os::unix::fs` constants - moved to the `libc` crate
* `fmt::{radix, Radix, RadixFmt}` - not used enough to stabilize
* `IntoCow` - conflicts with `Into` and may come back later
* `i32::{BITS, BYTES}` (and other integers) - not pulling their weight
* `DebugTuple::formatter` - will be removed
* `sync::Semaphore` - not used enough and confused with system semaphores

Closes #23284
cc #27709 (still lots more methods though)
Closes #27712
Closes #27722
Closes #27728
Closes #27735
Closes #27729
Closes #27755
Closes #27782
Closes #27798

src/libstd/path.rs

@@ -100,8 +100,10 @@
 #![stable(feature = "rust1", since = "1.0.0")]
 
 use ascii::*;
+#[allow(deprecated)]
 use borrow::{Borrow, IntoCow, ToOwned, Cow};
 use cmp;
+use error::Error;
 use fmt;
 use fs;
 use hash::{Hash, Hasher};
@@ -1043,6 +1045,7 @@ impl PathBuf {
         self._push(path.as_ref())
     }
 
+    #[allow(deprecated)]
     fn _push(&mut self, path: &Path) {
         // in general, a separator is needed if the rightmost byte is not a separator
         let mut need_sep = self.as_mut_vec().last().map(|c| !is_sep_byte(*c)).unwrap_or(false);
@@ -1219,6 +1222,7 @@ impl Borrow<Path> for PathBuf {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[allow(deprecated)]
 impl IntoCow<'static, Path> for PathBuf {
     fn into_cow(self) -> Cow<'static, Path> {
         Cow::Owned(self)
@@ -1226,6 +1230,7 @@ impl IntoCow<'static, Path> for PathBuf {
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
+#[allow(deprecated)]
 impl<'a> IntoCow<'a, Path> for &'a Path {
     fn into_cow(self) -> Cow<'a, Path> {
         Cow::Borrowed(self)
@@ -1328,6 +1333,12 @@ pub struct Path {
     inner: OsStr,
 }
 
+/// An error returned from the `Path::strip_prefix` method indicating that the
+/// prefix was not found in `self`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[stable(since = "1.7.0", feature = "strip_prefix")]
+pub struct StripPrefixError(());
+
 impl Path {
     // The following (private!) function allows construction of a path from a u8
     // slice, which is only safe when it is known to follow the OsStr encoding.
@@ -1447,6 +1458,7 @@ impl Path {
     /// assert!(!Path::new("foo.txt").is_absolute());
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[allow(deprecated)]
     pub fn is_absolute(&self) -> bool {
         self.has_root() && (cfg!(unix) || self.prefix().is_some())
     }
@@ -1473,6 +1485,8 @@ impl Path {
     #[unstable(feature = "path_prefix",
                reason = "uncertain whether to expose this convenience",
                issue = "27722")]
+    #[rustc_deprecated(since = "1.7.0",
+                       reason = "inspect components().next() instead")]
     pub fn prefix(&self) -> Option<Prefix> {
         self.components().prefix
     }
@@ -1561,12 +1575,28 @@ impl Path {
     /// returns false), then `relative_from` returns `None`.
     #[unstable(feature = "path_relative_from", reason = "see #23284",
                issue = "23284")]
+    #[rustc_deprecated(since = "1.7.0", reason = "renamed to strip_prefix")]
     pub fn relative_from<'a, P: ?Sized + AsRef<Path>>(&'a self, base: &'a P) -> Option<&Path> {
-        self._relative_from(base.as_ref())
+        self._strip_prefix(base.as_ref()).ok()
     }
 
-    fn _relative_from<'a>(&'a self, base: &'a Path) -> Option<&'a Path> {
-        iter_after(self.components(), base.components()).map(|c| c.as_path())
+    /// Returns a path that, when joined onto `base`, yields `self`.
+    ///
+    /// If `base` is not a prefix of `self` (i.e. `starts_with`
+    /// returns false), then `relative_from` returns `None`.
+    #[stable(since = "1.7.0", feature = "path_strip_prefix")]
+    pub fn strip_prefix<'a, P: ?Sized>(&'a self, base: &'a P)
+                                       -> Result<&'a Path, StripPrefixError>
+        where P: AsRef<Path>
+    {
+        self._strip_prefix(base.as_ref())
+    }
+
+    fn _strip_prefix<'a>(&'a self, base: &'a Path)
+                         -> Result<&'a Path, StripPrefixError> {
+        iter_after(self.components(), base.components())
+            .map(|c| c.as_path())
+            .ok_or(StripPrefixError(()))
     }
 
     /// Determines whether `base` is a prefix of `self`.
@@ -2015,6 +2045,18 @@ impl_eq!(Cow<'a, Path>, Path);
 impl_eq!(Cow<'a, Path>, &'b Path);
 impl_eq!(Cow<'a, Path>, PathBuf);
 
+#[stable(since = "1.7.0", feature = "strip_prefix")]
+impl fmt::Display for StripPrefixError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        self.description().fmt(f)
+    }
+}
+
+#[stable(since = "1.7.0", feature = "strip_prefix")]
+impl Error for StripPrefixError {
+    fn description(&self) -> &str { "prefix not found" }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2105,6 +2147,7 @@ mod tests {
     );
 
     #[test]
+    #[allow(deprecated)]
     fn into_cow() {
         use borrow::{Cow, IntoCow};