Deprecate `str::from_utf16`

Use `String::from_utf16` instead

[breaking-change]

4 files changed, 40 insertions, 36 deletions

diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs
index 2d01d138271..8ed664e6c69 100644
--- a/src/libcollections/str.rs
+++ b/src/libcollections/str.rs
@@ -378,32 +378,10 @@ pub fn replace(s: &str, from: &str, to: &str) -> String {
 Section: Misc
 */
 
-/// Decode a UTF-16 encoded vector `v` into a string, returning `None`
-/// if `v` contains any invalid data.
-///
-/// # Example
-///
-/// ```rust
-/// use std::str;
-///
-/// // 𝄞music
-/// let mut v = [0xD834, 0xDD1E, 0x006d, 0x0075,
-///              0x0073, 0x0069, 0x0063];
-/// assert_eq!(str::from_utf16(v), Some("𝄞music".to_string()));
-///
-/// // 𝄞mu<invalid>ic
-/// v[4] = 0xD800;
-/// assert_eq!(str::from_utf16(v), None);
-/// ```
+/// Deprecated. Use `String::from_utf16`.
+#[deprecated = "Replaced by String::from_utf16"]
 pub fn from_utf16(v: &[u16]) -> Option<String> {
-    let mut s = String::with_capacity(v.len() / 2);
-    for c in utf16_items(v) {
-        match c {
-            ScalarValue(c) => s.push_char(c),
-            LoneSurrogate(_) => return None
-        }
-    }
-    Some(s)
+    String::from_utf16(v)
 }
 
 /// Decode a UTF-16 encoded vector `v` into a string, replacing
@@ -1722,7 +1700,7 @@ mod tests {
         for p in pairs.iter() {
             let (s, u) = (*p).clone();
             let s_as_utf16 = s.as_slice().utf16_units().collect::<Vec<u16>>();
-            let u_as_string = from_utf16(u.as_slice()).unwrap();
+            let u_as_string = String::from_utf16(u.as_slice()).unwrap();
 
             assert!(is_utf16(u.as_slice()));
             assert_eq!(s_as_utf16, u);
@@ -1730,7 +1708,7 @@ mod tests {
             assert_eq!(u_as_string, s);
             assert_eq!(from_utf16_lossy(u.as_slice()), s);
 
-            assert_eq!(from_utf16(s_as_utf16.as_slice()).unwrap(), s);
+            assert_eq!(String::from_utf16(s_as_utf16.as_slice()).unwrap(), s);
             assert_eq!(u_as_string.as_slice().utf16_units().collect::<Vec<u16>>(), u);
         }
     }
@@ -1739,15 +1717,15 @@ mod tests {
     fn test_utf16_invalid() {
         // completely positive cases tested above.
         // lead + eof
-        assert_eq!(from_utf16([0xD800]), None);
+        assert_eq!(String::from_utf16([0xD800]), None);
         // lead + lead
-        assert_eq!(from_utf16([0xD800, 0xD800]), None);
+        assert_eq!(String::from_utf16([0xD800, 0xD800]), None);
 
         // isolated trail
-        assert_eq!(from_utf16([0x0061, 0xDC00]), None);
+        assert_eq!(String::from_utf16([0x0061, 0xDC00]), None);
 
         // general
-        assert_eq!(from_utf16([0xD800, 0xd801, 0xdc8b, 0xD800]), None);
+        assert_eq!(String::from_utf16([0xD800, 0xd801, 0xdc8b, 0xD800]), None);
     }
 
     #[test]
diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs
index 555f2ee59fc..2928fd327ae 100644
--- a/src/libcollections/string.rs
+++ b/src/libcollections/string.rs
@@ -91,6 +91,32 @@ impl String {
             Err(vec)
         }
     }
+    
+    /// Decode a UTF-16 encoded vector `v` into a string, returning `None`
+    /// if `v` contains any invalid data.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// // 𝄞music
+    /// let mut v = [0xD834, 0xDD1E, 0x006d, 0x0075,
+    ///              0x0073, 0x0069, 0x0063];
+    /// assert_eq!(String::from_utf16(v), Some("𝄞music".to_string()));
+    ///
+    /// // 𝄞mu<invalid>ic
+    /// v[4] = 0xD800;
+    /// assert_eq!(String::from_utf16(v), None);
+    /// ```
+    pub fn from_utf16(v: &[u16]) -> Option<String> {
+        let mut s = String::with_capacity(v.len() / 2);
+        for c in str::utf16_items(v) {
+            match c {
+                str::ScalarValue(c) => s.push_char(c),
+                str::LoneSurrogate(_) => return None
+            }
+        }
+        Some(s)
+    }
 
     /// Convert a vector of chars to a string
     ///
diff --git a/src/libnative/io/file_win32.rs b/src/libnative/io/file_win32.rs
index dbca4ff7ff7..0f8fa261802 100644
--- a/src/libnative/io/file_win32.rs
+++ b/src/libnative/io/file_win32.rs
@@ -378,7 +378,7 @@ pub fn readdir(p: &CString) -> IoResult<Vec<CString>> {
                 } else {
                     let fp_vec = vec::raw::from_buf(fp_buf, libc::wcslen(fp_buf) as uint);
                     let fp_trimmed = str::truncate_utf16_at_nul(fp_vec.as_slice());
-                    let fp_str = str::from_utf16(fp_trimmed)
+                    let fp_str = String::from_utf16(fp_trimmed)
                             .expect("rust_list_dir_wfd_fp_buf returned invalid UTF-16");
                     paths.push(Path::new(fp_str));
                 }
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 86577a9840d..a221dd5b376 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -137,7 +137,7 @@ pub fn getcwd() -> Path {
             fail!();
         }
     }
-    Path::new(str::from_utf16(str::truncate_utf16_at_nul(buf))
+    Path::new(String::from_utf16(str::truncate_utf16_at_nul(buf))
               .expect("GetCurrentDirectoryW returned invalid UTF-16"))
 }
 
@@ -180,7 +180,7 @@ pub mod win32 {
                     // We want to explicitly catch the case when the
                     // closure returned invalid UTF-16, rather than
                     // set `res` to None and continue.
-                    let s = str::from_utf16(sub)
+                    let s = String::from_utf16(sub)
                         .expect("fill_utf16_buf_and_decode: closure created invalid UTF-16");
                     res = option::Some(s)
                 }
@@ -1050,7 +1050,7 @@ pub fn error_string(errnum: uint) -> String {
                 return format!("OS Error {} (FormatMessageW() returned error {})", errnum, fm_err);
             }
 
-            let msg = str::from_utf16(str::truncate_utf16_at_nul(buf));
+            let msg = String::from_utf16(str::truncate_utf16_at_nul(buf));
             match msg {
                 Some(msg) => format!("OS Error {}: {}", errnum, msg),
                 None => format!("OS Error {} (FormatMessageW() returned invalid UTF-16)", errnum),
@@ -1207,7 +1207,7 @@ fn real_args() -> Vec<String> {
 
         // Push it onto the list.
         let opt_s = slice::raw::buf_as_slice(ptr as *const _, len, |buf| {
-            str::from_utf16(str::truncate_utf16_at_nul(buf))
+            String::from_utf16(str::truncate_utf16_at_nul(buf))
         });
         opt_s.expect("CommandLineToArgvW returned invalid UTF-16")
     });