libs: stabilize ascii module

This is an initial API stabilization pass for `std::ascii`. Aside from
some renaming to match conversion conventions, and deprecations in favor
of using iterators directly, almost nothing is changed here. However,
the static case conversion tables that were previously public are now private.

The stabilization of the (rather large!) set of extension traits is left
to a follow-up pass, because we hope to land some more general machinery
that will provide the same functionality without custom traits.

[breaking-change]

Author: aturon

src/compiletest/errors.rs

@@ -8,6 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+use std::ascii::AsciiExt;
 use std::io::{BufferedReader, File};
 use regex::Regex;
 
@@ -31,7 +32,7 @@ pub fn load_errors(re: &Regex, testfile: &Path) -> Vec<ExpectedError> {
 fn parse_expected(line_num: uint, line: &str, re: &Regex) -> Option<ExpectedError> {
     re.captures(line).and_then(|caps| {
         let adjusts = caps.name("adjusts").len();
-        let kind = caps.name("kind").to_ascii().to_lowercase().into_string();
+        let kind = caps.name("kind").to_ascii_lower();
         let msg = caps.name("msg").trim().to_string();
 
         debug!("line={} kind={} msg={}", line_num, kind, msg);

src/librustdoc/html/markdown.rs

@@ -28,6 +28,7 @@
 #![allow(non_camel_case_types)]
 
 use libc;
+use std::ascii::AsciiExt;
 use std::cell::{RefCell, Cell};
 use std::fmt;
 use std::slice;
@@ -226,12 +227,8 @@ pub fn render(w: &mut fmt::Formatter, s: &str, print_toc: bool) -> fmt::Result {
         };
 
         // Transform the contents of the header into a hyphenated string
-        let id = s.as_slice().words().map(|s| {
-            match s.to_ascii_opt() {
-                Some(s) => s.to_lowercase().into_string(),
-                None => s.to_string()
-            }
-        }).collect::<Vec<String>>().connect("-");
+        let id = s.as_slice().words().map(|s| s.to_ascii_lower())
+            .collect::<Vec<String>>().connect("-");
 
         // This is a terrible hack working around how hoedown gives us rendered
         // html for text rather than the raw text.

src/libstd/ascii.rs

@@ -12,7 +12,7 @@
 
 //! Operations on ASCII strings and characters
 
-#![experimental]
+#![unstable = "unsure about placement and naming"]
 
 use core::kinds::Sized;
 use fmt;
@@ -31,30 +31,40 @@ pub struct Ascii { chr: u8 }
 impl Ascii {
     /// Converts an ascii character into a `u8`.
     #[inline]
-    pub fn to_byte(self) -> u8 {
+    #[unstable = "recently renamed"]
+    pub fn as_byte(&self) -> u8 {
         self.chr
     }
 
+    #[deprecated = "use as_byte"]
+    pub fn to_byte(self) -> u8 {
+        self.as_byte()
+    }
+
     /// Converts an ascii character into a `char`.
     #[inline]
-    pub fn to_char(self) -> char {
+    #[unstable = "recently renamed"]
+    pub fn as_char(&self) -> char {
         self.chr as char
     }
 
     /// Convert to lowercase.
     #[inline]
-    pub fn to_lowercase(self) -> Ascii {
+    #[stable]
+    pub fn to_lowercase(&self) -> Ascii {
         Ascii{chr: ASCII_LOWER_MAP[self.chr as uint]}
     }
 
     /// Convert to uppercase.
     #[inline]
-    pub fn to_uppercase(self) -> Ascii {
+    #[stable]
+    pub fn to_uppercase(&self) -> Ascii {
         Ascii{chr: ASCII_UPPER_MAP[self.chr as uint]}
     }
 
     /// Compares two ascii characters of equality, ignoring case.
     #[inline]
+    #[deprecated = "normalize with to_lowercase"]
     pub fn eq_ignore_case(self, other: Ascii) -> bool {
         ASCII_LOWER_MAP[self.chr as uint] == ASCII_LOWER_MAP[other.chr as uint]
     }
@@ -63,66 +73,77 @@ impl Ascii {
 
     /// Check if the character is a letter (a-z, A-Z)
     #[inline]
+    #[stable]
     pub fn is_alphabetic(&self) -> bool {
         (self.chr >= 0x41 && self.chr <= 0x5A) || (self.chr >= 0x61 && self.chr <= 0x7A)
     }
 
     /// Check if the character is a number (0-9)
     #[inline]
+    #[unstable = "may be renamed"]
     pub fn is_digit(&self) -> bool {
         self.chr >= 0x30 && self.chr <= 0x39
     }
 
     /// Check if the character is a letter or number
     #[inline]
+    #[stable]
     pub fn is_alphanumeric(&self) -> bool {
         self.is_alphabetic() || self.is_digit()
     }
 
     /// Check if the character is a space or horizontal tab
     #[inline]
+    #[experimental = "likely to be removed"]
     pub fn is_blank(&self) -> bool {
         self.chr == b' ' || self.chr == b'\t'
     }
 
     /// Check if the character is a control character
     #[inline]
+    #[stable]
     pub fn is_control(&self) -> bool {
         self.chr < 0x20 || self.chr == 0x7F
     }
 
     /// Checks if the character is printable (except space)
     #[inline]
+    #[experimental = "unsure about naming, or whether this is needed"]
     pub fn is_graph(&self) -> bool {
         (self.chr - 0x21) < 0x5E
     }
 
     /// Checks if the character is printable (including space)
     #[inline]
+    #[unstable = "unsure about naming"]
     pub fn is_print(&self) -> bool {
         (self.chr - 0x20) < 0x5F
     }
 
-    /// Checks if the character is lowercase
+    /// Checks if the character is alphabetic and lowercase
     #[inline]
+    #[stable]
     pub fn is_lowercase(&self) -> bool {
         (self.chr - b'a') < 26
     }
 
-    /// Checks if the character is uppercase
+    /// Checks if the character is alphabetic and uppercase
     #[inline]
+    #[stable]
     pub fn is_uppercase(&self) -> bool {
         (self.chr - b'A') < 26
     }
 
     /// Checks if the character is punctuation
     #[inline]
+    #[stable]
     pub fn is_punctuation(&self) -> bool {
         self.is_graph() && !self.is_alphanumeric()
     }
 
     /// Checks if the character is a valid hex digit
     #[inline]
+    #[stable]
     pub fn is_hex(&self) -> bool {
         self.is_digit() || ((self.chr | 32u8) - b'a') < 6
     }
@@ -135,6 +156,7 @@ impl<'a> fmt::Show for Ascii {
 }
 
 /// Trait for converting into an ascii type.
+#[experimental = "may be replaced by generic conversion traits"]
 pub trait AsciiCast<T> {
     /// Convert to an ascii type, panic on non-ASCII input.
     #[inline]
@@ -160,6 +182,7 @@ pub trait AsciiCast<T> {
     fn is_ascii(&self) -> bool;
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl<'a> AsciiCast<&'a[Ascii]> for &'a [u8] {
     #[inline]
     unsafe fn to_ascii_nocheck(&self) -> &'a[Ascii] {
@@ -175,6 +198,7 @@ impl<'a> AsciiCast<&'a[Ascii]> for &'a [u8] {
     }
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl<'a> AsciiCast<&'a [Ascii]> for &'a str {
     #[inline]
     unsafe fn to_ascii_nocheck(&self) -> &'a [Ascii] {
@@ -187,6 +211,7 @@ impl<'a> AsciiCast<&'a [Ascii]> for &'a str {
     }
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl AsciiCast<Ascii> for u8 {
     #[inline]
     unsafe fn to_ascii_nocheck(&self) -> Ascii {
@@ -199,6 +224,7 @@ impl AsciiCast<Ascii> for u8 {
     }
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl AsciiCast<Ascii> for char {
     #[inline]
     unsafe fn to_ascii_nocheck(&self) -> Ascii {
@@ -212,6 +238,7 @@ impl AsciiCast<Ascii> for char {
 }
 
 /// Trait for copyless casting to an ascii vector.
+#[experimental = "may be replaced by generic conversion traits"]
 pub trait OwnedAsciiCast {
     /// Check if convertible to ascii
     fn is_ascii(&self) -> bool;
@@ -241,6 +268,7 @@ pub trait OwnedAsciiCast {
     unsafe fn into_ascii_nocheck(self) -> Vec<Ascii>;
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl OwnedAsciiCast for String {
     #[inline]
     fn is_ascii(&self) -> bool {
@@ -253,6 +281,7 @@ impl OwnedAsciiCast for String {
     }
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl OwnedAsciiCast for Vec<u8> {
     #[inline]
     fn is_ascii(&self) -> bool {
@@ -274,6 +303,7 @@ impl OwnedAsciiCast for Vec<u8> {
 
 /// Trait for converting an ascii type to a string. Needed to convert
 /// `&[Ascii]` to `&str`.
+#[experimental = "may be replaced by generic conversion traits"]
 pub trait AsciiStr for Sized? {
     /// Convert to a string.
     fn as_str_ascii<'a>(&'a self) -> &'a str;
@@ -283,19 +313,23 @@ pub trait AsciiStr for Sized? {
     fn to_lower(&self) -> Vec<Ascii>;
 
     /// Convert to vector representing a lower cased ascii string.
+    #[deprecated = "use iterators instead"]
     fn to_lowercase(&self) -> Vec<Ascii>;
 
     /// Deprecated: use `to_uppercase`
     #[deprecated="renamed `to_uppercase`"]
     fn to_upper(&self) -> Vec<Ascii>;
 
     /// Convert to vector representing a upper cased ascii string.
+    #[deprecated = "use iterators instead"]
     fn to_uppercase(&self) -> Vec<Ascii>;
 
     /// Compares two Ascii strings ignoring case.
+    #[deprecated = "use iterators instead"]
     fn eq_ignore_case(&self, other: &[Ascii]) -> bool;
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl AsciiStr for [Ascii] {
     #[inline]
     fn as_str_ascii<'a>(&'a self) -> &'a str {
@@ -338,11 +372,13 @@ impl IntoString for Vec<Ascii> {
 }
 
 /// Trait to convert to an owned byte vector by consuming self
+#[experimental = "may be replaced by generic conversion traits"]
 pub trait IntoBytes {
     /// Converts to an owned byte vector by consuming self
     fn into_bytes(self) -> Vec<u8>;
 }
 
+#[experimental = "may be replaced by generic conversion traits"]
 impl IntoBytes for Vec<Ascii> {
     fn into_bytes(self) -> Vec<u8> {
         unsafe {
@@ -360,6 +396,7 @@ impl IntoBytes for Vec<Ascii> {
 
 
 /// Extension methods for ASCII-subset only operations on owned strings
+#[experimental = "would prefer to do this in a more general way"]
 pub trait OwnedAsciiExt {
     /// Convert the string to ASCII upper case:
     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
@@ -373,6 +410,7 @@ pub trait OwnedAsciiExt {
 }
 
 /// Extension methods for ASCII-subset only operations on string slices
+#[experimental = "would prefer to do this in a more general way"]
 pub trait AsciiExt<T> for Sized? {
     /// Makes a copy of the string in ASCII upper case:
     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
@@ -390,6 +428,7 @@ pub trait AsciiExt<T> for Sized? {
     fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
 }
 
+#[experimental = "would prefer to do this in a more general way"]
 impl AsciiExt<String> for str {
     #[inline]
     fn to_ascii_upper(&self) -> String {
@@ -409,6 +448,7 @@ impl AsciiExt<String> for str {
     }
 }
 
+#[experimental = "would prefer to do this in a more general way"]
 impl OwnedAsciiExt for String {
     #[inline]
     fn into_ascii_upper(self) -> String {
@@ -423,6 +463,7 @@ impl OwnedAsciiExt for String {
     }
 }
 
+#[experimental = "would prefer to do this in a more general way"]
 impl AsciiExt<Vec<u8>> for [u8] {
     #[inline]
     fn to_ascii_upper(&self) -> Vec<u8> {
@@ -445,6 +486,7 @@ impl AsciiExt<Vec<u8>> for [u8] {
     }
 }
 
+#[experimental = "would prefer to do this in a more general way"]
 impl OwnedAsciiExt for Vec<u8> {
     #[inline]
     fn into_ascii_upper(mut self) -> Vec<u8> {
@@ -474,6 +516,7 @@ impl OwnedAsciiExt for Vec<u8> {
 /// - Any other chars in the range [0x20,0x7e] are not escaped.
 /// - Any other chars are given hex escapes.
 /// - Unicode escapes are never generated by this function.
+#[unstable = "needs to be updated to use an iterator"]
 pub fn escape_default(c: u8, f: |u8|) {
     match c {
         b'\t' => { f(b'\\'); f(b't'); }
@@ -496,7 +539,7 @@ pub fn escape_default(c: u8, f: |u8|) {
     }
 }
 
-pub static ASCII_LOWER_MAP: [u8, ..256] = [
+static ASCII_LOWER_MAP: [u8, ..256] = [
     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
     0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
     0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
@@ -535,7 +578,7 @@ pub static ASCII_LOWER_MAP: [u8, ..256] = [
     0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff,
 ];
 
-pub static ASCII_UPPER_MAP: [u8, ..256] = [
+static ASCII_UPPER_MAP: [u8, ..256] = [
     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
     0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
     0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,