std: Stabilize the ascii module

This commit performs a stabilization pass over the `std::ascii` module taking
the following actions:

* the module name is now stable
* `AsciiExt` is now stable after moving its type parameter to an `Owned`
  associated type
* `AsciiExt::is_ascii` is now stable
* `AsciiExt::to_ascii_uppercase` is now stable
* `AsciiExt::to_ascii_lowercase` is now stable
* `AsciiExt::eq_ignore_ascii_case` is now stable
* `AsciiExt::make_ascii_uppercase` is added to possibly replace
  `OwnedAsciiExt::into_ascii_uppercase` (similarly for lowercase variants).
* `escape_default` now returns an iterator and is stable
* `EscapeDefault` is now stable

Trait implementations are now also marked stable.

Primarily it is still unstable to *implement* the `AsciiExt` trait due to it
containing some unstable methods.

[breaking-change]

Author: alexcrichton

src/libstd/ascii.rs

@@ -12,15 +12,12 @@
 
 //! Operations on ASCII strings and characters
 
-#![unstable(feature = "std_misc",
-            reason = "unsure about placement and naming")]
+#![stable(feature = "rust1", since = "1.0.0")]
 
-use iter::IteratorExt;
-use ops::FnMut;
-use slice::SliceExt;
-use str::StrExt;
-use string::String;
-use vec::Vec;
+use prelude::v1::*;
+
+use mem;
+use iter::Range;
 
 /// Extension methods for ASCII-subset only operations on owned strings
 #[unstable(feature = "std_misc",
@@ -38,52 +35,79 @@ pub trait OwnedAsciiExt {
 }
 
 /// Extension methods for ASCII-subset only operations on string slices
-#[unstable(feature = "std_misc",
-           reason = "would prefer to do this in a more general way")]
-pub trait AsciiExt<T = Self> {
+#[stable(feature = "rust1", since = "1.0.0")]
+pub trait AsciiExt {
+    #[stable(feature = "rust1", since = "1.0.0")]
+    type Owned;
+
     /// Check if within the ASCII range.
+    #[stable(feature = "rust1", since = "1.0.0")]
     fn is_ascii(&self) -> bool;
 
     /// Makes a copy of the string in ASCII upper case:
     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
     /// but non-ASCII letters are unchanged.
-    fn to_ascii_uppercase(&self) -> T;
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn to_ascii_uppercase(&self) -> Self::Owned;
 
     /// Makes a copy of the string in ASCII lower case:
     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
     /// but non-ASCII letters are unchanged.
-    fn to_ascii_lowercase(&self) -> T;
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn to_ascii_lowercase(&self) -> Self::Owned;
 
     /// Check that two strings are an ASCII case-insensitive match.
     /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
     /// but without allocating and copying temporary strings.
+    #[stable(feature = "rust1", since = "1.0.0")]
     fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
+
+    /// Convert this type to its ASCII upper case equivalent in-place.
+    ///
+    /// See `to_ascii_uppercase` for more information.
+    #[unstable(feature = "ascii")]
+    fn make_ascii_uppercase(&mut self);
+
+    /// Convert this type to its ASCII lower case equivalent in-place.
+    ///
+    /// See `to_ascii_lowercase` for more information.
+    #[unstable(feature = "ascii")]
+    fn make_ascii_lowercase(&mut self);
 }
 
-#[unstable(feature = "std_misc",
-           reason = "would prefer to do this in a more general way")]
-impl AsciiExt<String> for str {
+#[stable(feature = "rust1", since = "1.0.0")]
+impl AsciiExt for str {
+    type Owned = String;
+
     #[inline]
     fn is_ascii(&self) -> bool {
         self.bytes().all(|b| b.is_ascii())
     }
 
     #[inline]
     fn to_ascii_uppercase(&self) -> String {
-        // Vec<u8>::to_ascii_uppercase() preserves the UTF-8 invariant.
-        unsafe { String::from_utf8_unchecked(self.as_bytes().to_ascii_uppercase()) }
+        self.to_string().into_ascii_uppercase()
     }
 
     #[inline]
     fn to_ascii_lowercase(&self) -> String {
-        // Vec<u8>::to_ascii_lowercase() preserves the UTF-8 invariant.
-        unsafe { String::from_utf8_unchecked(self.as_bytes().to_ascii_lowercase()) }
+        self.to_string().into_ascii_lowercase()
     }
 
     #[inline]
     fn eq_ignore_ascii_case(&self, other: &str) -> bool {
         self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
     }
+
+    fn make_ascii_uppercase(&mut self) {
+        let me: &mut [u8] = unsafe { mem::transmute(self) };
+        me.make_ascii_uppercase()
+    }
+
+    fn make_ascii_lowercase(&mut self) {
+        let me: &mut [u8] = unsafe { mem::transmute(self) };
+        me.make_ascii_lowercase()
+    }
 }
 
 #[unstable(feature = "std_misc",
@@ -102,22 +126,22 @@ impl OwnedAsciiExt for String {
     }
 }
 
-#[unstable(feature = "std_misc",
-           reason = "would prefer to do this in a more general way")]
-impl AsciiExt<Vec<u8>> for [u8] {
+#[stable(feature = "rust1", since = "1.0.0")]
+impl AsciiExt for [u8] {
+    type Owned = Vec<u8>;
     #[inline]
     fn is_ascii(&self) -> bool {
         self.iter().all(|b| b.is_ascii())
     }
 
     #[inline]
     fn to_ascii_uppercase(&self) -> Vec<u8> {
-        self.iter().map(|b| b.to_ascii_uppercase()).collect()
+        self.to_vec().into_ascii_uppercase()
     }
 
     #[inline]
     fn to_ascii_lowercase(&self) -> Vec<u8> {
-        self.iter().map(|b| b.to_ascii_lowercase()).collect()
+        self.to_vec().into_ascii_lowercase()
     }
 
     #[inline]
@@ -127,55 +151,58 @@ impl AsciiExt<Vec<u8>> for [u8] {
             a.eq_ignore_ascii_case(b)
         })
     }
+
+    fn make_ascii_uppercase(&mut self) {
+        for byte in self {
+            byte.make_ascii_uppercase();
+        }
+    }
+
+    fn make_ascii_lowercase(&mut self) {
+        for byte in self {
+            byte.make_ascii_lowercase();
+        }
+    }
 }
 
 #[unstable(feature = "std_misc",
            reason = "would prefer to do this in a more general way")]
 impl OwnedAsciiExt for Vec<u8> {
     #[inline]
     fn into_ascii_uppercase(mut self) -> Vec<u8> {
-        for byte in &mut self {
-            *byte = byte.to_ascii_uppercase();
-        }
+        self.make_ascii_uppercase();
         self
     }
 
     #[inline]
     fn into_ascii_lowercase(mut self) -> Vec<u8> {
-        for byte in &mut self {
-            *byte = byte.to_ascii_lowercase();
-        }
+        self.make_ascii_lowercase();
         self
     }
 }
 
-#[unstable(feature = "std_misc",
-           reason = "would prefer to do this in a more general way")]
+#[stable(feature = "rust1", since = "1.0.0")]
 impl AsciiExt for u8 {
+    type Owned = u8;
     #[inline]
-    fn is_ascii(&self) -> bool {
-        *self & 128 == 0u8
-    }
-
+    fn is_ascii(&self) -> bool { *self & 128 == 0u8 }
     #[inline]
-    fn to_ascii_uppercase(&self) -> u8 {
-        ASCII_UPPERCASE_MAP[*self as usize]
-    }
-
+    fn to_ascii_uppercase(&self) -> u8 { ASCII_UPPERCASE_MAP[*self as usize] }
     #[inline]
-    fn to_ascii_lowercase(&self) -> u8 {
-        ASCII_LOWERCASE_MAP[*self as usize]
-    }
-
+    fn to_ascii_lowercase(&self) -> u8 { ASCII_LOWERCASE_MAP[*self as usize] }
     #[inline]
     fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
         self.to_ascii_lowercase() == other.to_ascii_lowercase()
     }
+    #[inline]
+    fn make_ascii_uppercase(&mut self) { *self = self.to_ascii_uppercase(); }
+    #[inline]
+    fn make_ascii_lowercase(&mut self) { *self = self.to_ascii_lowercase(); }
 }
 
-#[unstable(feature = "std_misc",
-           reason = "would prefer to do this in a more general way")]
+#[stable(feature = "rust1", since = "1.0.0")]
 impl AsciiExt for char {
+    type Owned = char;
     #[inline]
     fn is_ascii(&self) -> bool {
         *self as u32 <= 0x7F
@@ -203,6 +230,19 @@ impl AsciiExt for char {
     fn eq_ignore_ascii_case(&self, other: &char) -> bool {
         self.to_ascii_lowercase() == other.to_ascii_lowercase()
     }
+
+    #[inline]
+    fn make_ascii_uppercase(&mut self) { *self = self.to_ascii_uppercase(); }
+    #[inline]
+    fn make_ascii_lowercase(&mut self) { *self = self.to_ascii_lowercase(); }
+}
+
+/// An iterator over the escaped version of a byte, constructed via
+/// `std::ascii::escape_default`.
+#[stable(feature = "rust1", since = "1.0.0")]
+pub struct EscapeDefault {
+    range: Range<usize>,
+    data: [u8; 4],
 }
 
 /// Returns a 'default' ASCII and C++11-like literal escape of a `u8`
@@ -214,34 +254,46 @@ impl AsciiExt for char {
 /// - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
 /// - Single-quote, double-quote and backslash chars are backslash-escaped.
 /// - Any other chars in the range [0x20,0x7e] are not escaped.
-/// - Any other chars are given hex escapes.
+/// - Any other chars are given hex escapes of the form '\xNN'.
 /// - Unicode escapes are never generated by this function.
-#[unstable(feature = "std_misc",
-           reason = "needs to be updated to use an iterator")]
-pub fn escape_default<F>(c: u8, mut f: F) where
-    F: FnMut(u8),
-{
-    match c {
-        b'\t' => { f(b'\\'); f(b't'); }
-        b'\r' => { f(b'\\'); f(b'r'); }
-        b'\n' => { f(b'\\'); f(b'n'); }
-        b'\\' => { f(b'\\'); f(b'\\'); }
-        b'\'' => { f(b'\\'); f(b'\''); }
-        b'"'  => { f(b'\\'); f(b'"'); }
-        b'\x20' ... b'\x7e' => { f(c); }
-        _ => {
-            f(b'\\');
-            f(b'x');
-            for &offset in &[4u, 0u] {
-                match ((c as i32) >> offset) & 0xf {
-                    i @ 0 ... 9 => f(b'0' + (i as u8)),
-                    i => f(b'a' + (i as u8 - 10)),
-                }
-            }
+#[stable(feature = "rust1", since = "1.0.0")]
+pub fn escape_default(c: u8) -> EscapeDefault {
+    let (data, len) = match c {
+        b'\t' => ([b'\\', b't', 0, 0], 2),
+        b'\r' => ([b'\\', b'r', 0, 0], 2),
+        b'\n' => ([b'\\', b'n', 0, 0], 2),
+        b'\\' => ([b'\\', b'\\', 0, 0], 2),
+        b'\'' => ([b'\\', b'\'', 0, 0], 2),
+        b'"' => ([b'\\', b'"', 0, 0], 2),
+        b'\x20' ... b'\x7e' => ([c, 0, 0, 0], 1),
+        _ => ([b'\\', b'x', hexify(c >> 4), hexify(c & 0xf)], 4),
+    };
+
+    return EscapeDefault { range: range(0, len), data: data };
+
+    fn hexify(b: u8) -> u8 {
+        match b {
+            0 ... 9 => b'0' + b,
+            _ => b'a' + b - 10,
         }
     }
 }
 
+#[stable(feature = "rust1", since = "1.0.0")]
+impl Iterator for EscapeDefault {
+    type Item = u8;
+    fn next(&mut self) -> Option<u8> { self.range.next().map(|i| self.data[i]) }
+    fn size_hint(&self) -> (usize, Option<usize>) { self.range.size_hint() }
+}
+#[stable(feature = "rust1", since = "1.0.0")]
+impl DoubleEndedIterator for EscapeDefault {
+    fn next_back(&mut self) -> Option<u8> {
+        self.range.next_back().map(|i| self.data[i])
+    }
+}
+#[stable(feature = "rust1", since = "1.0.0")]
+impl ExactSizeIterator for EscapeDefault {}
+
 static ASCII_LOWERCASE_MAP: [u8; 256] = [
     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
     0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,

src/libstd/sys/common/wtf8.rs

@@ -817,7 +817,9 @@ impl<'a, S: Writer + Hasher> Hash<S> for Wtf8 {
     }
 }
 
-impl AsciiExt<Wtf8Buf> for Wtf8 {
+impl AsciiExt for Wtf8 {
+    type Owned = Wtf8Buf;
+
     fn is_ascii(&self) -> bool {
         self.bytes.is_ascii()
     }
@@ -830,6 +832,9 @@ impl AsciiExt<Wtf8Buf> for Wtf8 {
     fn eq_ignore_ascii_case(&self, other: &Wtf8) -> bool {
         self.bytes.eq_ignore_ascii_case(&other.bytes)
     }
+
+    fn make_ascii_uppercase(&mut self) { self.bytes.make_ascii_uppercase() }
+    fn make_ascii_lowercase(&mut self) { self.bytes.make_ascii_lowercase() }
 }
 
 #[cfg(test)]

src/libsyntax/print/pprust.rs

@@ -2761,15 +2761,13 @@ impl<'a> State<'a> {
             ast::LitStr(ref st, style) => self.print_string(&st, style),
             ast::LitByte(byte) => {
                 let mut res = String::from_str("b'");
-                ascii::escape_default(byte, |c| res.push(c as char));
+                res.extend(ascii::escape_default(byte).map(|c| c as char));
                 res.push('\'');
                 word(&mut self.s, &res[])
             }
             ast::LitChar(ch) => {
                 let mut res = String::from_str("'");
-                for c in ch.escape_default() {
-                    res.push(c);
-                }
+                res.extend(ch.escape_default());
                 res.push('\'');
                 word(&mut self.s, &res[])
             }
@@ -2809,8 +2807,8 @@ impl<'a> State<'a> {
             ast::LitBinary(ref v) => {
                 let mut escaped: String = String::new();
                 for &ch in &**v {
-                    ascii::escape_default(ch as u8,
-                                          |ch| escaped.push(ch as char));
+                    escaped.extend(ascii::escape_default(ch as u8)
+                                         .map(|c| c as char));
                 }
                 word(&mut self.s, &format!("b\"{}\"", escaped)[])
             }

src/libterm/lib.rs

@@ -58,7 +58,6 @@
 #![feature(path)]
 #![feature(rustc_private)]
 #![feature(staged_api)]
-#![feature(std_misc)]
 #![feature(unicode)]
 #![feature(env)]
 #![cfg_attr(windows, feature(libc))]