src/libcollections/string.rs

   1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10 //
  11 // ignore-lexer-test FIXME #15679
  12
  13 //! An owned, growable string that enforces that its contents are valid UTF-8.
  14
  15 #![stable]
  16
  17 use core::prelude::*;
  18
  19 use core::borrow::{Cow, IntoCow};
  20 use core::cmp::Equiv;
  21 use core::default::Default;
  22 use core::fmt;
  23 use core::hash;
  24 use core::iter::FromIterator;
  25 use core::mem;
  26 use core::ops::{mod, Deref, Add};
  27 use core::ptr;
  28 use core::raw::Slice as RawSlice;
  29 use unicode::str as unicode_str;
  30 use unicode::str::Utf16Item;
  31
  32 use str::{mod, CharRange, FromStr, Utf8Error};
  33 use vec::{DerefVec, Vec, as_vec};
  34
  35 /// A growable string stored as a UTF-8 encoded buffer.
  36 #[deriving(Clone, PartialOrd, Eq, Ord)]
  37 #[stable]
  38 pub struct String {
  39     vec: Vec<u8>,
  40 }
  41
  42 /// A possible error value from the `String::from_utf8` function.
  43 #[stable]
  44 pub struct FromUtf8Error {
  45     bytes: Vec<u8>,
  46     error: Utf8Error,
  47 }
  48
  49 /// A possible error value from the `String::from_utf16` function.
  50 #[stable]
  51 #[allow(missing_copy_implementations)]
  52 pub struct FromUtf16Error(());
  53
  54 impl String {
  55     /// Creates a new string buffer initialized with the empty string.
  56     ///
  57     /// # Examples
  58     ///
  59     /// ```
  60     /// let mut s = String::new();
  61     /// ```
  62     #[inline]
  63     #[stable]
  64     pub fn new() -> String {
  65         String {
  66             vec: Vec::new(),
  67         }
  68     }
  69
  70     /// Creates a new string buffer with the given capacity.
  71     /// The string will be able to hold exactly `capacity` bytes without
  72     /// reallocating. If `capacity` is 0, the string will not allocate.
  73     ///
  74     /// # Examples
  75     ///
  76     /// ```
  77     /// let mut s = String::with_capacity(10);
  78     /// ```
  79     #[inline]
  80     #[stable]
  81     pub fn with_capacity(capacity: uint) -> String {
  82         String {
  83             vec: Vec::with_capacity(capacity),
  84         }
  85     }
  86
  87     /// Creates a new string buffer from the given string.
  88     ///
  89     /// # Examples
  90     ///
  91     /// ```
  92     /// let s = String::from_str("hello");
  93     /// assert_eq!(s.as_slice(), "hello");
  94     /// ```
  95     #[inline]
  96     #[experimental = "needs investigation to see if to_string() can match perf"]
  97     pub fn from_str(string: &str) -> String {
  98         String { vec: ::slice::SliceExt::to_vec(string.as_bytes()) }
  99     }
 100
 101     /// Returns the vector as a string buffer, if possible, taking care not to
 102     /// copy it.
 103     ///
 104     /// # Failure
 105     ///
 106     /// If the given vector is not valid UTF-8, then the original vector and the
 107     /// corresponding error is returned.
 108     ///
 109     /// # Examples
 110     ///
 111     /// ```rust
 112     /// # #![allow(deprecated)]
 113     /// use std::str::Utf8Error;
 114     ///
 115     /// let hello_vec = vec![104, 101, 108, 108, 111];
 116     /// let s = String::from_utf8(hello_vec).unwrap();
 117     /// assert_eq!(s, "hello");
 118     ///
 119     /// let invalid_vec = vec![240, 144, 128];
 120     /// let s = String::from_utf8(invalid_vec).err().unwrap();
 121     /// assert_eq!(s.utf8_error(), Utf8Error::TooShort);
 122     /// assert_eq!(s.into_bytes(), vec![240, 144, 128]);
 123     /// ```
 124     #[inline]
 125     #[stable]
 126     pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error> {
 127         match str::from_utf8(vec.as_slice()) {
 128             Ok(..) => Ok(String { vec: vec }),
 129             Err(e) => Err(FromUtf8Error { bytes: vec, error: e })
 130         }
 131     }
 132
 133     /// Converts a vector of bytes to a new UTF-8 string.
 134     /// Any invalid UTF-8 sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
 135     ///
 136     /// # Examples
 137     ///
 138     /// ```rust
 139     /// let input = b"Hello \xF0\x90\x80World";
 140     /// let output = String::from_utf8_lossy(input);
 141     /// assert_eq!(output.as_slice(), "Hello \u{FFFD}World");
 142     /// ```
 143     #[stable]
 144     pub fn from_utf8_lossy<'a>(v: &'a [u8]) -> CowString<'a> {
 145         let mut i = 0;
 146         match str::from_utf8(v) {
 147             Ok(s) => return Cow::Borrowed(s),
 148             Err(e) => {
 149                 if let Utf8Error::InvalidByte(firstbad) = e {
 150                     i = firstbad;
 151                 }
 152             }
 153         }
 154
 155         static TAG_CONT_U8: u8 = 128u8;
 156         static REPLACEMENT: &'static [u8] = b"\xEF\xBF\xBD"; // U+FFFD in UTF-8
 157         let total = v.len();
 158         fn unsafe_get(xs: &[u8], i: uint) -> u8 {
 159             unsafe { *xs.get_unchecked(i) }
 160         }
 161         fn safe_get(xs: &[u8], i: uint, total: uint) -> u8 {
 162             if i >= total {
 163                 0
 164             } else {
 165                 unsafe_get(xs, i)
 166             }
 167         }
 168
 169         let mut res = String::with_capacity(total);
 170
 171         if i > 0 {
 172             unsafe {
 173                 res.as_mut_vec().push_all(v[..i])
 174             };
 175         }
 176
 177         // subseqidx is the index of the first byte of the subsequence we're looking at.
 178         // It's used to copy a bunch of contiguous good codepoints at once instead of copying
 179         // them one by one.
 180         let mut subseqidx = i;
 181
 182         while i < total {
 183             let i_ = i;
 184             let byte = unsafe_get(v, i);
 185             i += 1;
 186
 187             macro_rules! error(() => ({
 188                 unsafe {
 189                     if subseqidx != i_ {
 190                         res.as_mut_vec().push_all(v[subseqidx..i_]);
 191                     }
 192                     subseqidx = i;
 193                     res.as_mut_vec().push_all(REPLACEMENT);
 194                 }
 195             }));
 196
 197             if byte < 128u8 {
 198                 // subseqidx handles this
 199             } else {
 200                 let w = unicode_str::utf8_char_width(byte);
 201
 202                 match w {
 203                     2 => {
 204                         if safe_get(v, i, total) & 192u8 != TAG_CONT_U8 {
 205                             error!();
 206                             continue;
 207                         }
 208                         i += 1;
 209                     }
 210                     3 => {
 211                         match (byte, safe_get(v, i, total)) {
 212                             (0xE0         , 0xA0 ... 0xBF) => (),
 213                             (0xE1 ... 0xEC, 0x80 ... 0xBF) => (),
 214                             (0xED         , 0x80 ... 0x9F) => (),
 215                             (0xEE ... 0xEF, 0x80 ... 0xBF) => (),
 216                             _ => {
 217                                 error!();
 218                                 continue;
 219                             }
 220                         }
 221                         i += 1;
 222                         if safe_get(v, i, total) & 192u8 != TAG_CONT_U8 {
 223                             error!();
 224                             continue;
 225                         }
 226                         i += 1;
 227                     }
 228                     4 => {
 229                         match (byte, safe_get(v, i, total)) {
 230                             (0xF0         , 0x90 ... 0xBF) => (),
 231                             (0xF1 ... 0xF3, 0x80 ... 0xBF) => (),
 232                             (0xF4         , 0x80 ... 0x8F) => (),
 233                             _ => {
 234                                 error!();
 235                                 continue;
 236                             }
 237                         }
 238                         i += 1;
 239                         if safe_get(v, i, total) & 192u8 != TAG_CONT_U8 {
 240                             error!();
 241                             continue;
 242                         }
 243                         i += 1;
 244                         if safe_get(v, i, total) & 192u8 != TAG_CONT_U8 {
 245                             error!();
 246                             continue;
 247                         }
 248                         i += 1;
 249                     }
 250                     _ => {
 251                         error!();
 252                         continue;
 253                     }
 254                 }
 255             }
 256         }
 257         if subseqidx < total {
 258             unsafe {
 259                 res.as_mut_vec().push_all(v[subseqidx..total])
 260             };
 261         }
 262         Cow::Owned(res)
 263     }
 264
 265     /// Decode a UTF-16 encoded vector `v` into a `String`, returning `None`
 266     /// if `v` contains any invalid data.
 267     ///
 268     /// # Examples
 269     ///
 270     /// ```rust
 271     /// // 𝄞music
 272     /// let mut v = &mut [0xD834, 0xDD1E, 0x006d, 0x0075,
 273     ///                   0x0073, 0x0069, 0x0063];
 274     /// assert_eq!(String::from_utf16(v).unwrap(),
 275     ///            "𝄞music".to_string());
 276     ///
 277     /// // 𝄞mu<invalid>ic
 278     /// v[4] = 0xD800;
 279     /// assert!(String::from_utf16(v).is_err());
 280     /// ```
 281     #[stable]
 282     pub fn from_utf16(v: &[u16]) -> Result<String, FromUtf16Error> {
 283         let mut s = String::with_capacity(v.len());
 284         for c in unicode_str::utf16_items(v) {
 285             match c {
 286                 Utf16Item::ScalarValue(c) => s.push(c),
 287                 Utf16Item::LoneSurrogate(_) => return Err(FromUtf16Error(())),
 288             }
 289         }
 290         Ok(s)
 291     }
 292
 293     /// Decode a UTF-16 encoded vector `v` into a string, replacing
 294     /// invalid data with the replacement character (U+FFFD).
 295     ///
 296     /// # Examples
 297     ///
 298     /// ```rust
 299     /// // 𝄞mus<invalid>ic<invalid>
 300     /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
 301     ///           0x0073, 0xDD1E, 0x0069, 0x0063,
 302     ///           0xD834];
 303     ///
 304     /// assert_eq!(String::from_utf16_lossy(v),
 305     ///            "𝄞mus\u{FFFD}ic\u{FFFD}".to_string());
 306     /// ```
 307     #[stable]
 308     pub fn from_utf16_lossy(v: &[u16]) -> String {
 309         unicode_str::utf16_items(v).map(|c| c.to_char_lossy()).collect()
 310     }
 311
 312     /// Convert a vector of `char`s to a `String`.
 313     ///
 314     /// # Examples
 315     ///
 316     /// ```rust
 317     /// # #![allow(deprecated)]
 318     /// let chars = &['h', 'e', 'l', 'l', 'o'];
 319     /// let s = String::from_chars(chars);
 320     /// assert_eq!(s.as_slice(), "hello");
 321     /// ```
 322     #[inline]
 323     #[deprecated = "use .collect() instead"]
 324     pub fn from_chars(chs: &[char]) -> String {
 325         chs.iter().map(|c| *c).collect()
 326     }
 327
 328     /// Creates a new `String` from a length, capacity, and pointer.
 329     ///
 330     /// This is unsafe because:
 331     /// * We call `Vec::from_raw_parts` to get a `Vec<u8>`;
 332     /// * We assume that the `Vec` contains valid UTF-8.
 333     #[inline]
 334     #[stable]
 335     pub unsafe fn from_raw_parts(buf: *mut u8, length: uint, capacity: uint) -> String {
 336         String {
 337             vec: Vec::from_raw_parts(buf, length, capacity),
 338         }
 339     }
 340
 341     /// Creates a `String` from a null-terminated `*const u8` buffer.
 342     ///
 343     /// This function is unsafe because we dereference memory until we find the
 344     /// NUL character, which is not guaranteed to be present. Additionally, the
 345     /// slice is not checked to see whether it contains valid UTF-8
 346     #[unstable = "just renamed from `mod raw`"]
 347     pub unsafe fn from_raw_buf(buf: *const u8) -> String {
 348         String::from_str(str::from_c_str(buf as *const i8))
 349     }
 350
 351     /// Creates a `String` from a `*const u8` buffer of the given length.
 352     ///
 353     /// This function is unsafe because it blindly assumes the validity of the
 354     /// pointer `buf` for `len` bytes of memory. This function will copy the
 355     /// memory from `buf` into a new allocation (owned by the returned
 356     /// `String`).
 357     ///
 358     /// This function is also unsafe because it does not validate that the
 359     /// buffer is valid UTF-8 encoded data.
 360     #[unstable = "just renamed from `mod raw`"]
 361     pub unsafe fn from_raw_buf_len(buf: *const u8, len: uint) -> String {
 362         String::from_utf8_unchecked(Vec::from_raw_buf(buf, len))
 363     }
 364
 365     /// Converts a vector of bytes to a new `String` without checking if
 366     /// it contains valid UTF-8. This is unsafe because it assumes that
 367     /// the UTF-8-ness of the vector has already been validated.
 368     #[inline]
 369     #[stable]
 370     pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> String {
 371         String { vec: bytes }
 372     }
 373
 374     /// Return the underlying byte buffer, encoded as UTF-8.
 375     ///
 376     /// # Examples
 377     ///
 378     /// ```
 379     /// let s = String::from_str("hello");
 380     /// let bytes = s.into_bytes();
 381     /// assert_eq!(bytes, vec![104, 101, 108, 108, 111]);
 382     /// ```
 383     #[inline]
 384     #[stable]
 385     pub fn into_bytes(self) -> Vec<u8> {
 386         self.vec
 387     }
 388
 389     /// Creates a string buffer by repeating a character `length` times.
 390     ///
 391     /// # Examples
 392     ///
 393     /// ```
 394     /// # #![allow(deprecated)]
 395     /// let s = String::from_char(5, 'a');
 396     /// assert_eq!(s.as_slice(), "aaaaa");
 397     /// ```
 398     #[inline]
 399     #[deprecated = "use repeat(ch).take(length).collect() instead"]
 400     pub fn from_char(length: uint, ch: char) -> String {
 401         if length == 0 {
 402             return String::new()
 403         }
 404
 405         let mut buf = String::new();
 406         buf.push(ch);
 407         let size = buf.len() * (length - 1);
 408         buf.reserve_exact(size);
 409         for _ in range(1, length) {
 410             buf.push(ch)
 411         }
 412         buf
 413     }
 414
 415     /// Pushes the given string onto this string buffer.
 416     ///
 417     /// # Examples
 418     ///
 419     /// ```
 420     /// let mut s = String::from_str("foo");
 421     /// s.push_str("bar");
 422     /// assert_eq!(s.as_slice(), "foobar");
 423     /// ```
 424     #[inline]
 425     #[stable]
 426     pub fn push_str(&mut self, string: &str) {
 427         self.vec.push_all(string.as_bytes())
 428     }
 429
 430     /// Pushes `ch` onto the given string `count` times.
 431     ///
 432     /// # Examples
 433     ///
 434     /// ```
 435     /// # #![allow(deprecated)]
 436     /// let mut s = String::from_str("foo");
 437     /// s.grow(5, 'Z');
 438     /// assert_eq!(s.as_slice(), "fooZZZZZ");
 439     /// ```
 440     #[inline]
 441     #[deprecated = "deprecated in favor of .extend(repeat(ch).take(count))"]
 442     pub fn grow(&mut self, count: uint, ch: char) {
 443         for _ in range(0, count) {
 444             self.push(ch)
 445         }
 446     }
 447
 448     /// Returns the number of bytes that this string buffer can hold without
 449     /// reallocating.
 450     ///
 451     /// # Examples
 452     ///
 453     /// ```
 454     /// let s = String::with_capacity(10);
 455     /// assert!(s.capacity() >= 10);
 456     /// ```
 457     #[inline]
 458     #[stable]
 459     pub fn capacity(&self) -> uint {
 460         self.vec.capacity()
 461     }
 462
 463     /// Deprecated: Renamed to `reserve`.
 464     #[deprecated = "Renamed to `reserve`"]
 465     pub fn reserve_additional(&mut self, extra: uint) {
 466         self.vec.reserve(extra)
 467     }
 468
 469     /// Reserves capacity for at least `additional` more bytes to be inserted
 470     /// in the given `String`. The collection may reserve more space to avoid
 471     /// frequent reallocations.
 472     ///
 473     /// # Panics
 474     ///
 475     /// Panics if the new capacity overflows `uint`.
 476     ///
 477     /// # Examples
 478     ///
 479     /// ```
 480     /// let mut s = String::new();
 481     /// s.reserve(10);
 482     /// assert!(s.capacity() >= 10);
 483     /// ```
 484     #[inline]
 485     #[stable]
 486     pub fn reserve(&mut self, additional: uint) {
 487         self.vec.reserve(additional)
 488     }
 489
 490     /// Reserves the minimum capacity for exactly `additional` more bytes to be
 491     /// inserted in the given `String`. Does nothing if the capacity is already
 492     /// sufficient.
 493     ///
 494     /// Note that the allocator may give the collection more space than it
 495     /// requests. Therefore capacity can not be relied upon to be precisely
 496     /// minimal. Prefer `reserve` if future insertions are expected.
 497     ///
 498     /// # Panics
 499     ///
 500     /// Panics if the new capacity overflows `uint`.
 501     ///
 502     /// # Examples
 503     ///
 504     /// ```
 505     /// let mut s = String::new();
 506     /// s.reserve(10);
 507     /// assert!(s.capacity() >= 10);
 508     /// ```
 509     #[inline]
 510     #[stable]
 511     pub fn reserve_exact(&mut self, additional: uint) {
 512         self.vec.reserve_exact(additional)
 513     }
 514
 515     /// Shrinks the capacity of this string buffer to match its length.
 516     ///
 517     /// # Examples
 518     ///
 519     /// ```
 520     /// let mut s = String::from_str("foo");
 521     /// s.reserve(100);
 522     /// assert!(s.capacity() >= 100);
 523     /// s.shrink_to_fit();
 524     /// assert_eq!(s.capacity(), 3);
 525     /// ```
 526     #[inline]
 527     #[stable]
 528     pub fn shrink_to_fit(&mut self) {
 529         self.vec.shrink_to_fit()
 530     }
 531
 532     /// Adds the given character to the end of the string.
 533     ///
 534     /// # Examples
 535     ///
 536     /// ```
 537     /// let mut s = String::from_str("abc");
 538     /// s.push('1');
 539     /// s.push('2');
 540     /// s.push('3');
 541     /// assert_eq!(s.as_slice(), "abc123");
 542     /// ```
 543     #[inline]
 544     #[stable]
 545     pub fn push(&mut self, ch: char) {
 546         if (ch as u32) < 0x80 {
 547             self.vec.push(ch as u8);
 548             return;
 549         }
 550
 551         let cur_len = self.len();
 552         // This may use up to 4 bytes.
 553         self.vec.reserve(4);
 554
 555         unsafe {
 556             // Attempt to not use an intermediate buffer by just pushing bytes
 557             // directly onto this string.
 558             let slice = RawSlice {
 559                 data: self.vec.as_ptr().offset(cur_len as int),
 560                 len: 4,
 561             };
 562             let used = ch.encode_utf8(mem::transmute(slice)).unwrap_or(0);
 563             self.vec.set_len(cur_len + used);
 564         }
 565     }
 566
 567     /// Works with the underlying buffer as a byte slice.
 568     ///
 569     /// # Examples
 570     ///
 571     /// ```
 572     /// let s = String::from_str("hello");
 573     /// let b: &[_] = &[104, 101, 108, 108, 111];
 574     /// assert_eq!(s.as_bytes(), b);
 575     /// ```
 576     #[inline]
 577     #[stable]
 578     pub fn as_bytes<'a>(&'a self) -> &'a [u8] {
 579         self.vec.as_slice()
 580     }
 581
 582     /// Shortens a string to the specified length.
 583     ///
 584     /// # Panics
 585     ///
 586     /// Panics if `new_len` > current length,
 587     /// or if `new_len` is not a character boundary.
 588     ///
 589     /// # Examples
 590     ///
 591     /// ```
 592     /// let mut s = String::from_str("hello");
 593     /// s.truncate(2);
 594     /// assert_eq!(s.as_slice(), "he");
 595     /// ```
 596     #[inline]
 597     #[stable]
 598     pub fn truncate(&mut self, new_len: uint) {
 599         assert!(self.is_char_boundary(new_len));
 600         self.vec.truncate(new_len)
 601     }
 602
 603     /// Removes the last character from the string buffer and returns it.
 604     /// Returns `None` if this string buffer is empty.
 605     ///
 606     /// # Examples
 607     ///
 608     /// ```
 609     /// let mut s = String::from_str("foo");
 610     /// assert_eq!(s.pop(), Some('o'));
 611     /// assert_eq!(s.pop(), Some('o'));
 612     /// assert_eq!(s.pop(), Some('f'));
 613     /// assert_eq!(s.pop(), None);
 614     /// ```
 615     #[inline]
 616     #[stable]
 617     pub fn pop(&mut self) -> Option<char> {
 618         let len = self.len();
 619         if len == 0 {
 620             return None
 621         }
 622
 623         let CharRange {ch, next} = self.char_range_at_reverse(len);
 624         unsafe {
 625             self.vec.set_len(next);
 626         }
 627         Some(ch)
 628     }
 629
 630     /// Removes the character from the string buffer at byte position `idx` and
 631     /// returns it.
 632     ///
 633     /// # Warning
 634     ///
 635     /// This is an O(n) operation as it requires copying every element in the
 636     /// buffer.
 637     ///
 638     /// # Panics
 639     ///
 640     /// If `idx` does not lie on a character boundary, or if it is out of
 641     /// bounds, then this function will panic.
 642     ///
 643     /// # Examples
 644     ///
 645     /// ```
 646     /// let mut s = String::from_str("foo");
 647     /// assert_eq!(s.remove(0), 'f');
 648     /// assert_eq!(s.remove(1), 'o');
 649     /// assert_eq!(s.remove(0), 'o');
 650     /// ```
 651     #[stable]
 652     pub fn remove(&mut self, idx: uint) -> char {
 653         let len = self.len();
 654         assert!(idx <= len);
 655
 656         let CharRange { ch, next } = self.char_range_at(idx);
 657         unsafe {
 658             ptr::copy_memory(self.vec.as_mut_ptr().offset(idx as int),
 659                              self.vec.as_ptr().offset(next as int),
 660                              len - next);
 661             self.vec.set_len(len - (next - idx));
 662         }
 663         ch
 664     }
 665
 666     /// Insert a character into the string buffer at byte position `idx`.
 667     ///
 668     /// # Warning
 669     ///
 670     /// This is an O(n) operation as it requires copying every element in the
 671     /// buffer.
 672     ///
 673     /// # Panics
 674     ///
 675     /// If `idx` does not lie on a character boundary or is out of bounds, then
 676     /// this function will panic.
 677     #[stable]
 678     pub fn insert(&mut self, idx: uint, ch: char) {
 679         let len = self.len();
 680         assert!(idx <= len);
 681         assert!(self.is_char_boundary(idx));
 682         self.vec.reserve(4);
 683         let mut bits = [0; 4];
 684         let amt = ch.encode_utf8(&mut bits).unwrap();
 685
 686         unsafe {
 687             ptr::copy_memory(self.vec.as_mut_ptr().offset((idx + amt) as int),
 688                              self.vec.as_ptr().offset(idx as int),
 689                              len - idx);
 690             ptr::copy_memory(self.vec.as_mut_ptr().offset(idx as int),
 691                              bits.as_ptr(),
 692                              amt);
 693             self.vec.set_len(len + amt);
 694         }
 695     }
 696
 697     /// Views the string buffer as a mutable sequence of bytes.
 698     ///
 699     /// This is unsafe because it does not check
 700     /// to ensure that the resulting string will be valid UTF-8.
 701     ///
 702     /// # Examples
 703     ///
 704     /// ```
 705     /// let mut s = String::from_str("hello");
 706     /// unsafe {
 707     ///     let vec = s.as_mut_vec();
 708     ///     assert!(vec == &mut vec![104, 101, 108, 108, 111]);
 709     ///     vec.reverse();
 710     /// }
 711     /// assert_eq!(s.as_slice(), "olleh");
 712     /// ```
 713     #[stable]
 714     pub unsafe fn as_mut_vec<'a>(&'a mut self) -> &'a mut Vec<u8> {
 715         &mut self.vec
 716     }
 717
 718     /// Return the number of bytes in this string.
 719     ///
 720     /// # Examples
 721     ///
 722     /// ```
 723     /// let a = "foo".to_string();
 724     /// assert_eq!(a.len(), 3);
 725     /// ```
 726     #[inline]
 727     #[stable]
 728     pub fn len(&self) -> uint { self.vec.len() }
 729
 730     /// Returns true if the string contains no bytes
 731     ///
 732     /// # Examples
 733     ///
 734     /// ```
 735     /// let mut v = String::new();
 736     /// assert!(v.is_empty());
 737     /// v.push('a');
 738     /// assert!(!v.is_empty());
 739     /// ```
 740     #[stable]
 741     pub fn is_empty(&self) -> bool { self.len() == 0 }
 742
 743     /// Truncates the string, returning it to 0 length.
 744     ///
 745     /// # Examples
 746     ///
 747     /// ```
 748     /// let mut s = "foo".to_string();
 749     /// s.clear();
 750     /// assert!(s.is_empty());
 751     /// ```
 752     #[inline]
 753     #[stable]
 754     pub fn clear(&mut self) {
 755         self.vec.clear()
 756     }
 757 }
 758
 759 impl FromUtf8Error {
 760     /// Consume this error, returning the bytes that were attempted to make a
 761     /// `String` with.
 762     #[stable]
 763     pub fn into_bytes(self) -> Vec<u8> { self.bytes }
 764
 765     /// Access the underlying UTF8-error that was the cause of this error.
 766     #[stable]
 767     pub fn utf8_error(&self) -> Utf8Error { self.error }
 768 }
 769
 770 impl fmt::Show for FromUtf8Error {
 771     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 772         self.error.fmt(f)
 773     }
 774 }
 775
 776 impl fmt::Show for FromUtf16Error {
 777     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 778         "invalid utf-16: lone surrogate found".fmt(f)
 779     }
 780 }
 781
 782 #[experimental = "waiting on FromIterator stabilization"]
 783 impl FromIterator<char> for String {
 784     fn from_iter<I:Iterator<Item=char>>(iterator: I) -> String {
 785         let mut buf = String::new();
 786         buf.extend(iterator);
 787         buf
 788     }
 789 }
 790
 791 #[experimental = "waiting on FromIterator stabilization"]
 792 impl<'a> FromIterator<&'a str> for String {
 793     fn from_iter<I:Iterator<Item=&'a str>>(iterator: I) -> String {
 794         let mut buf = String::new();
 795         buf.extend(iterator);
 796         buf
 797     }
 798 }
 799
 800 #[experimental = "waiting on Extend stabilization"]
 801 impl Extend<char> for String {
 802     fn extend<I:Iterator<Item=char>>(&mut self, mut iterator: I) {
 803         let (lower_bound, _) = iterator.size_hint();
 804         self.reserve(lower_bound);
 805         for ch in iterator {
 806             self.push(ch)
 807         }
 808     }
 809 }
 810
 811 #[experimental = "waiting on Extend stabilization"]
 812 impl<'a> Extend<&'a str> for String {
 813     fn extend<I: Iterator<Item=&'a str>>(&mut self, mut iterator: I) {
 814         // A guess that at least one byte per iterator element will be needed.
 815         let (lower_bound, _) = iterator.size_hint();
 816         self.reserve(lower_bound);
 817         for s in iterator {
 818             self.push_str(s)
 819         }
 820     }
 821 }
 822
 823 #[stable]
 824 impl PartialEq for String {
 825     #[inline]
 826     fn eq(&self, other: &String) -> bool { PartialEq::eq(&**self, &**other) }
 827     #[inline]
 828     fn ne(&self, other: &String) -> bool { PartialEq::ne(&**self, &**other) }
 829 }
 830
 831 macro_rules! impl_eq {
 832     ($lhs:ty, $rhs: ty) => {
 833         #[stable]
 834         impl<'a> PartialEq<$rhs> for $lhs {
 835             #[inline]
 836             fn eq(&self, other: &$rhs) -> bool { PartialEq::eq(&**self, &**other) }
 837             #[inline]
 838             fn ne(&self, other: &$rhs) -> bool { PartialEq::ne(&**self, &**other) }
 839         }
 840
 841         #[stable]
 842         impl<'a> PartialEq<$lhs> for $rhs {
 843             #[inline]
 844             fn eq(&self, other: &$lhs) -> bool { PartialEq::eq(&**self, &**other) }
 845             #[inline]
 846             fn ne(&self, other: &$lhs) -> bool { PartialEq::ne(&**self, &**other) }
 847         }
 848
 849     }
 850 }
 851
 852 impl_eq! { String, &'a str }
 853 impl_eq! { CowString<'a>, String }
 854
 855 #[stable]
 856 impl<'a, 'b> PartialEq<&'b str> for CowString<'a> {
 857     #[inline]
 858     fn eq(&self, other: &&'b str) -> bool { PartialEq::eq(&**self, &**other) }
 859     #[inline]
 860     fn ne(&self, other: &&'b str) -> bool { PartialEq::ne(&**self, &**other) }
 861 }
 862
 863 #[stable]
 864 impl<'a, 'b> PartialEq<CowString<'a>> for &'b str {
 865     #[inline]
 866     fn eq(&self, other: &CowString<'a>) -> bool { PartialEq::eq(&**self, &**other) }
 867     #[inline]
 868     fn ne(&self, other: &CowString<'a>) -> bool { PartialEq::ne(&**self, &**other) }
 869 }
 870
 871 #[experimental = "waiting on Str stabilization"]
 872 #[allow(deprecated)]
 873 impl Str for String {
 874     #[inline]
 875     #[stable]
 876     fn as_slice<'a>(&'a self) -> &'a str {
 877         unsafe { mem::transmute(self.vec.as_slice()) }
 878     }
 879 }
 880
 881 #[stable]
 882 impl Default for String {
 883     #[stable]
 884     fn default() -> String {
 885         String::new()
 886     }
 887 }
 888
 889 #[experimental = "waiting on Show stabilization"]
 890 impl fmt::Show for String {
 891     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 892         (**self).fmt(f)
 893     }
 894 }
 895
 896 #[experimental = "waiting on Hash stabilization"]
 897 impl<H: hash::Writer> hash::Hash<H> for String {
 898     #[inline]
 899     fn hash(&self, hasher: &mut H) {
 900         (**self).hash(hasher)
 901     }
 902 }
 903
 904 #[allow(deprecated)]
 905 #[deprecated = "Use overloaded `core::cmp::PartialEq`"]
 906 impl<'a, S: Str> Equiv<S> for String {
 907     #[inline]
 908     fn equiv(&self, other: &S) -> bool {
 909         self.as_slice() == other.as_slice()
 910     }
 911 }
 912
 913 #[experimental = "waiting on Add stabilization"]
 914 impl<'a> Add<&'a str> for String {
 915     type Output = String;
 916
 917     fn add(mut self, other: &str) -> String {
 918         self.push_str(other);
 919         self
 920     }
 921 }
 922
 923 impl ops::Slice<uint, str> for String {
 924     #[inline]
 925     fn as_slice_<'a>(&'a self) -> &'a str {
 926         unsafe { mem::transmute(self.vec.as_slice()) }
 927     }
 928
 929     #[inline]
 930     fn slice_from_or_fail<'a>(&'a self, from: &uint) -> &'a str {
 931         self[][*from..]
 932     }
 933
 934     #[inline]
 935     fn slice_to_or_fail<'a>(&'a self, to: &uint) -> &'a str {
 936         self[][..*to]
 937     }
 938
 939     #[inline]
 940     fn slice_or_fail<'a>(&'a self, from: &uint, to: &uint) -> &'a str {
 941         self[][*from..*to]
 942     }
 943 }
 944
 945 #[experimental = "waiting on Deref stabilization"]
 946 impl ops::Deref for String {
 947     type Target = str;
 948
 949     fn deref<'a>(&'a self) -> &'a str {
 950         unsafe { mem::transmute(self.vec[]) }
 951     }
 952 }
 953
 954 /// Wrapper type providing a `&String` reference via `Deref`.
 955 #[experimental]
 956 pub struct DerefString<'a> {
 957     x: DerefVec<'a, u8>
 958 }
 959
 960 impl<'a> Deref for DerefString<'a> {
 961     type Target = String;
 962
 963     fn deref<'b>(&'b self) -> &'b String {
 964         unsafe { mem::transmute(&*self.x) }
 965     }
 966 }
 967
 968 /// Convert a string slice to a wrapper type providing a `&String` reference.
 969 ///
 970 /// # Examples
 971 ///
 972 /// ```
 973 /// use std::string::as_string;
 974 ///
 975 /// fn string_consumer(s: String) {
 976 ///     assert_eq!(s, "foo".to_string());
 977 /// }
 978 ///
 979 /// let string = as_string("foo").clone();
 980 /// string_consumer(string);
 981 /// ```
 982 #[experimental]
 983 pub fn as_string<'a>(x: &'a str) -> DerefString<'a> {
 984     DerefString { x: as_vec(x.as_bytes()) }
 985 }
 986
 987 impl FromStr for String {
 988     #[inline]
 989     fn from_str(s: &str) -> Option<String> {
 990         Some(String::from_str(s))
 991     }
 992 }
 993
 994 /// Trait for converting a type to a string, consuming it in the process.
 995 #[deprecated = "trait will be removed"]
 996 pub trait IntoString {
 997     /// Consume and convert to a string.
 998     fn into_string(self) -> String;
 999 }
1000
1001 /// A generic trait for converting a value to a string
1002 pub trait ToString {
1003     /// Converts the value of `self` to an owned string
1004     fn to_string(&self) -> String;
1005 }
1006
1007 impl<T: fmt::Show> ToString for T {
1008     fn to_string(&self) -> String {
1009         use core::fmt::Writer;
1010         let mut buf = String::new();
1011         let _ = buf.write_fmt(format_args!("{}", self));
1012         buf.shrink_to_fit();
1013         buf
1014     }
1015 }
1016
1017 impl IntoCow<'static, String, str> for String {
1018     fn into_cow(self) -> CowString<'static> {
1019         Cow::Owned(self)
1020     }
1021 }
1022
1023 impl<'a> IntoCow<'a, String, str> for &'a str {
1024     fn into_cow(self) -> CowString<'a> {
1025         Cow::Borrowed(self)
1026     }
1027 }
1028
1029 /// Unsafe operations
1030 #[deprecated]
1031 pub mod raw {
1032     use super::String;
1033     use vec::Vec;
1034
1035     /// Creates a new `String` from a length, capacity, and pointer.
1036     ///
1037     /// This is unsafe because:
1038     /// * We call `Vec::from_raw_parts` to get a `Vec<u8>`;
1039     /// * We assume that the `Vec` contains valid UTF-8.
1040     #[inline]
1041     #[deprecated = "renamed to String::from_raw_parts"]
1042     pub unsafe fn from_parts(buf: *mut u8, length: uint, capacity: uint) -> String {
1043         String::from_raw_parts(buf, length, capacity)
1044     }
1045
1046     /// Creates a `String` from a `*const u8` buffer of the given length.
1047     ///
1048     /// This function is unsafe because of two reasons:
1049     ///
1050     /// * A raw pointer is dereferenced and transmuted to `&[u8]`;
1051     /// * The slice is not checked to see whether it contains valid UTF-8.
1052     #[deprecated = "renamed to String::from_raw_buf_len"]
1053     pub unsafe fn from_buf_len(buf: *const u8, len: uint) -> String {
1054         String::from_raw_buf_len(buf, len)
1055     }
1056
1057     /// Creates a `String` from a null-terminated `*const u8` buffer.
1058     ///
1059     /// This function is unsafe because we dereference memory until we find the NUL character,
1060     /// which is not guaranteed to be present. Additionally, the slice is not checked to see
1061     /// whether it contains valid UTF-8
1062     #[deprecated = "renamed to String::from_raw_buf"]
1063     pub unsafe fn from_buf(buf: *const u8) -> String {
1064         String::from_raw_buf(buf)
1065     }
1066
1067     /// Converts a vector of bytes to a new `String` without checking if
1068     /// it contains valid UTF-8. This is unsafe because it assumes that
1069     /// the UTF-8-ness of the vector has already been validated.
1070     #[inline]
1071     #[deprecated = "renamed to String::from_utf8_unchecked"]
1072     pub unsafe fn from_utf8(bytes: Vec<u8>) -> String {
1073         String::from_utf8_unchecked(bytes)
1074     }
1075 }
1076
1077 /// A clone-on-write string
1078 #[stable]
1079 pub type CowString<'a> = Cow<'a, String, str>;
1080
1081 #[allow(deprecated)]
1082 impl<'a> Str for CowString<'a> {
1083     #[inline]
1084     fn as_slice<'b>(&'b self) -> &'b str {
1085         (**self).as_slice()
1086     }
1087 }
1088
1089 impl fmt::Writer for String {
1090     fn write_str(&mut self, s: &str) -> fmt::Result {
1091         self.push_str(s);
1092         Ok(())
1093     }
1094 }
1095
1096 #[cfg(test)]
1097 mod tests {
1098     use prelude::*;
1099     use test::Bencher;
1100
1101     use str::Utf8Error;
1102     use str;
1103     use super::as_string;
1104
1105     #[test]
1106     fn test_as_string() {
1107         let x = "foo";
1108         assert_eq!(x, as_string(x).as_slice());
1109     }
1110
1111     #[test]
1112     fn test_from_str() {
1113       let owned: Option<::std::string::String> = from_str("string");
1114       assert_eq!(owned.as_ref().map(|s| s.as_slice()), Some("string"));
1115     }
1116
1117     #[test]
1118     fn test_from_utf8() {
1119         let xs = b"hello".to_vec();
1120         assert_eq!(String::from_utf8(xs).unwrap(),
1121                    String::from_str("hello"));
1122
1123         let xs = "ศไทย中华Việt Nam".as_bytes().to_vec();
1124         assert_eq!(String::from_utf8(xs).unwrap(),
1125                    String::from_str("ศไทย中华Việt Nam"));
1126
1127         let xs = b"hello\xFF".to_vec();
1128         let err = String::from_utf8(xs).err().unwrap();
1129         assert_eq!(err.utf8_error(), Utf8Error::TooShort);
1130         assert_eq!(err.into_bytes(), b"hello\xff".to_vec());
1131     }
1132
1133     #[test]
1134     fn test_from_utf8_lossy() {
1135         let xs = b"hello";
1136         let ys: str::CowString = "hello".into_cow();
1137         assert_eq!(String::from_utf8_lossy(xs), ys);
1138
1139         let xs = "ศไทย中华Việt Nam".as_bytes();
1140         let ys: str::CowString = "ศไทย中华Việt Nam".into_cow();
1141         assert_eq!(String::from_utf8_lossy(xs), ys);
1142
1143         let xs = b"Hello\xC2 There\xFF Goodbye";
1144         assert_eq!(String::from_utf8_lossy(xs),
1145                    String::from_str("Hello\u{FFFD} There\u{FFFD} Goodbye").into_cow());
1146
1147         let xs = b"Hello\xC0\x80 There\xE6\x83 Goodbye";
1148         assert_eq!(String::from_utf8_lossy(xs),
1149                    String::from_str("Hello\u{FFFD}\u{FFFD} There\u{FFFD} Goodbye").into_cow());
1150
1151         let xs = b"\xF5foo\xF5\x80bar";
1152         assert_eq!(String::from_utf8_lossy(xs),
1153                    String::from_str("\u{FFFD}foo\u{FFFD}\u{FFFD}bar").into_cow());
1154
1155         let xs = b"\xF1foo\xF1\x80bar\xF1\x80\x80baz";
1156         assert_eq!(String::from_utf8_lossy(xs),
1157                    String::from_str("\u{FFFD}foo\u{FFFD}bar\u{FFFD}baz").into_cow());
1158
1159         let xs = b"\xF4foo\xF4\x80bar\xF4\xBFbaz";
1160         assert_eq!(String::from_utf8_lossy(xs),
1161                    String::from_str("\u{FFFD}foo\u{FFFD}bar\u{FFFD}\u{FFFD}baz").into_cow());
1162
1163         let xs = b"\xF0\x80\x80\x80foo\xF0\x90\x80\x80bar";
1164         assert_eq!(String::from_utf8_lossy(xs), String::from_str("\u{FFFD}\u{FFFD}\u{FFFD}\u{FFFD}\
1165                                                foo\u{10000}bar").into_cow());
1166
1167         // surrogates
1168         let xs = b"\xED\xA0\x80foo\xED\xBF\xBFbar";
1169         assert_eq!(String::from_utf8_lossy(xs), String::from_str("\u{FFFD}\u{FFFD}\u{FFFD}foo\
1170                                                \u{FFFD}\u{FFFD}\u{FFFD}bar").into_cow());
1171     }
1172
1173     #[test]
1174     fn test_from_utf16() {
1175         let pairs =
1176             [(String::from_str("𐍅𐌿𐌻𐍆𐌹𐌻𐌰\n"),
1177               vec![0xd800_u16, 0xdf45_u16, 0xd800_u16, 0xdf3f_u16,
1178                 0xd800_u16, 0xdf3b_u16, 0xd800_u16, 0xdf46_u16,
1179                 0xd800_u16, 0xdf39_u16, 0xd800_u16, 0xdf3b_u16,
1180                 0xd800_u16, 0xdf30_u16, 0x000a_u16]),
1181
1182              (String::from_str("𐐒𐑉𐐮𐑀𐐲𐑋 𐐏𐐲𐑍\n"),
1183               vec![0xd801_u16, 0xdc12_u16, 0xd801_u16,
1184                 0xdc49_u16, 0xd801_u16, 0xdc2e_u16, 0xd801_u16,
1185                 0xdc40_u16, 0xd801_u16, 0xdc32_u16, 0xd801_u16,
1186                 0xdc4b_u16, 0x0020_u16, 0xd801_u16, 0xdc0f_u16,
1187                 0xd801_u16, 0xdc32_u16, 0xd801_u16, 0xdc4d_u16,
1188                 0x000a_u16]),
1189
1190              (String::from_str("𐌀𐌖𐌋𐌄𐌑𐌉·𐌌𐌄𐌕𐌄𐌋𐌉𐌑\n"),
1191               vec![0xd800_u16, 0xdf00_u16, 0xd800_u16, 0xdf16_u16,
1192                 0xd800_u16, 0xdf0b_u16, 0xd800_u16, 0xdf04_u16,
1193                 0xd800_u16, 0xdf11_u16, 0xd800_u16, 0xdf09_u16,
1194                 0x00b7_u16, 0xd800_u16, 0xdf0c_u16, 0xd800_u16,
1195                 0xdf04_u16, 0xd800_u16, 0xdf15_u16, 0xd800_u16,
1196                 0xdf04_u16, 0xd800_u16, 0xdf0b_u16, 0xd800_u16,
1197                 0xdf09_u16, 0xd800_u16, 0xdf11_u16, 0x000a_u16 ]),
1198
1199              (String::from_str("𐒋𐒘𐒈𐒑𐒛𐒒 𐒕𐒓 𐒈𐒚𐒍 𐒏𐒜𐒒𐒖𐒆 𐒕𐒆\n"),
1200               vec![0xd801_u16, 0xdc8b_u16, 0xd801_u16, 0xdc98_u16,
1201                 0xd801_u16, 0xdc88_u16, 0xd801_u16, 0xdc91_u16,
1202                 0xd801_u16, 0xdc9b_u16, 0xd801_u16, 0xdc92_u16,
1203                 0x0020_u16, 0xd801_u16, 0xdc95_u16, 0xd801_u16,
1204                 0xdc93_u16, 0x0020_u16, 0xd801_u16, 0xdc88_u16,
1205                 0xd801_u16, 0xdc9a_u16, 0xd801_u16, 0xdc8d_u16,
1206                 0x0020_u16, 0xd801_u16, 0xdc8f_u16, 0xd801_u16,
1207                 0xdc9c_u16, 0xd801_u16, 0xdc92_u16, 0xd801_u16,
1208                 0xdc96_u16, 0xd801_u16, 0xdc86_u16, 0x0020_u16,
1209                 0xd801_u16, 0xdc95_u16, 0xd801_u16, 0xdc86_u16,
1210                 0x000a_u16 ]),
1211              // Issue #12318, even-numbered non-BMP planes
1212              (String::from_str("\u{20000}"),
1213               vec![0xD840, 0xDC00])];
1214
1215         for p in pairs.iter() {
1216             let (s, u) = (*p).clone();
1217             let s_as_utf16 = s.utf16_units().collect::<Vec<u16>>();
1218             let u_as_string = String::from_utf16(u.as_slice()).unwrap();
1219
1220             assert!(::unicode::str::is_utf16(u.as_slice()));
1221             assert_eq!(s_as_utf16, u);
1222
1223             assert_eq!(u_as_string, s);
1224             assert_eq!(String::from_utf16_lossy(u.as_slice()), s);
1225
1226             assert_eq!(String::from_utf16(s_as_utf16.as_slice()).unwrap(), s);
1227             assert_eq!(u_as_string.utf16_units().collect::<Vec<u16>>(), u);
1228         }
1229     }
1230
1231     #[test]
1232     fn test_utf16_invalid() {
1233         // completely positive cases tested above.
1234         // lead + eof
1235         assert!(String::from_utf16(&[0xD800]).is_err());
1236         // lead + lead
1237         assert!(String::from_utf16(&[0xD800, 0xD800]).is_err());
1238
1239         // isolated trail
1240         assert!(String::from_utf16(&[0x0061, 0xDC00]).is_err());
1241
1242         // general
1243         assert!(String::from_utf16(&[0xD800, 0xd801, 0xdc8b, 0xD800]).is_err());
1244     }
1245
1246     #[test]
1247     fn test_from_utf16_lossy() {
1248         // completely positive cases tested above.
1249         // lead + eof
1250         assert_eq!(String::from_utf16_lossy(&[0xD800]), String::from_str("\u{FFFD}"));
1251         // lead + lead
1252         assert_eq!(String::from_utf16_lossy(&[0xD800, 0xD800]),
1253                    String::from_str("\u{FFFD}\u{FFFD}"));
1254
1255         // isolated trail
1256         assert_eq!(String::from_utf16_lossy(&[0x0061, 0xDC00]), String::from_str("a\u{FFFD}"));
1257
1258         // general
1259         assert_eq!(String::from_utf16_lossy(&[0xD800, 0xd801, 0xdc8b, 0xD800]),
1260                    String::from_str("\u{FFFD}𐒋\u{FFFD}"));
1261     }
1262
1263     #[test]
1264     fn test_from_buf_len() {
1265         unsafe {
1266             let a = vec![65u8, 65, 65, 65, 65, 65, 65, 0];
1267             assert_eq!(super::raw::from_buf_len(a.as_ptr(), 3), String::from_str("AAA"));
1268         }
1269     }
1270
1271     #[test]
1272     fn test_from_buf() {
1273         unsafe {
1274             let a = vec![65, 65, 65, 65, 65, 65, 65, 0];
1275             let b = a.as_ptr();
1276             let c = super::raw::from_buf(b);
1277             assert_eq!(c, String::from_str("AAAAAAA"));
1278         }
1279     }
1280
1281     #[test]
1282     fn test_push_bytes() {
1283         let mut s = String::from_str("ABC");
1284         unsafe {
1285             let mv = s.as_mut_vec();
1286             mv.push_all(&[b'D']);
1287         }
1288         assert_eq!(s, "ABCD");
1289     }
1290
1291     #[test]
1292     fn test_push_str() {
1293         let mut s = String::new();
1294         s.push_str("");
1295         assert_eq!(s.slice_from(0), "");
1296         s.push_str("abc");
1297         assert_eq!(s.slice_from(0), "abc");
1298         s.push_str("ประเทศไทย中华Việt Nam");
1299         assert_eq!(s.slice_from(0), "abcประเทศไทย中华Việt Nam");
1300     }
1301
1302     #[test]
1303     fn test_push() {
1304         let mut data = String::from_str("ประเทศไทย中");
1305         data.push('华');
1306         data.push('b'); // 1 byte
1307         data.push('¢'); // 2 byte
1308         data.push('€'); // 3 byte
1309         data.push('𤭢'); // 4 byte
1310         assert_eq!(data, "ประเทศไทย中华b¢€𤭢");
1311     }
1312
1313     #[test]
1314     fn test_pop() {
1315         let mut data = String::from_str("ประเทศไทย中华b¢€𤭢");
1316         assert_eq!(data.pop().unwrap(), '𤭢'); // 4 bytes
1317         assert_eq!(data.pop().unwrap(), '€'); // 3 bytes
1318         assert_eq!(data.pop().unwrap(), '¢'); // 2 bytes
1319         assert_eq!(data.pop().unwrap(), 'b'); // 1 bytes
1320         assert_eq!(data.pop().unwrap(), '华');
1321         assert_eq!(data, "ประเทศไทย中");
1322     }
1323
1324     #[test]
1325     fn test_str_truncate() {
1326         let mut s = String::from_str("12345");
1327         s.truncate(5);
1328         assert_eq!(s, "12345");
1329         s.truncate(3);
1330         assert_eq!(s, "123");
1331         s.truncate(0);
1332         assert_eq!(s, "");
1333
1334         let mut s = String::from_str("12345");
1335         let p = s.as_ptr();
1336         s.truncate(3);
1337         s.push_str("6");
1338         let p_ = s.as_ptr();
1339         assert_eq!(p_, p);
1340     }
1341
1342     #[test]
1343     #[should_fail]
1344     fn test_str_truncate_invalid_len() {
1345         let mut s = String::from_str("12345");
1346         s.truncate(6);
1347     }
1348
1349     #[test]
1350     #[should_fail]
1351     fn test_str_truncate_split_codepoint() {
1352         let mut s = String::from_str("\u{FC}"); // ü
1353         s.truncate(1);
1354     }
1355
1356     #[test]
1357     fn test_str_clear() {
1358         let mut s = String::from_str("12345");
1359         s.clear();
1360         assert_eq!(s.len(), 0);
1361         assert_eq!(s, "");
1362     }
1363
1364     #[test]
1365     fn test_str_add() {
1366         let a = String::from_str("12345");
1367         let b = a + "2";
1368         let b = b + "2";
1369         assert_eq!(b.len(), 7);
1370         assert_eq!(b, "1234522");
1371     }
1372
1373     #[test]
1374     fn remove() {
1375         let mut s = "ศไทย中华Việt Nam; foobar".to_string();;
1376         assert_eq!(s.remove(0), 'ศ');
1377         assert_eq!(s.len(), 33);
1378         assert_eq!(s, "ไทย中华Việt Nam; foobar");
1379         assert_eq!(s.remove(17), 'ệ');
1380         assert_eq!(s, "ไทย中华Vit Nam; foobar");
1381     }
1382
1383     #[test] #[should_fail]
1384     fn remove_bad() {
1385         "ศ".to_string().remove(1);
1386     }
1387
1388     #[test]
1389     fn insert() {
1390         let mut s = "foobar".to_string();
1391         s.insert(0, 'ệ');
1392         assert_eq!(s, "ệfoobar");
1393         s.insert(6, 'ย');
1394         assert_eq!(s, "ệfooยbar");
1395     }
1396
1397     #[test] #[should_fail] fn insert_bad1() { "".to_string().insert(1, 't'); }
1398     #[test] #[should_fail] fn insert_bad2() { "ệ".to_string().insert(1, 't'); }
1399
1400     #[test]
1401     fn test_slicing() {
1402         let s = "foobar".to_string();
1403         assert_eq!("foobar", s[]);
1404         assert_eq!("foo", s[..3]);
1405         assert_eq!("bar", s[3..]);
1406         assert_eq!("oob", s[1..4]);
1407     }
1408
1409     #[test]
1410     fn test_simple_types() {
1411         assert_eq!(1i.to_string(), "1");
1412         assert_eq!((-1i).to_string(), "-1");
1413         assert_eq!(200u.to_string(), "200");
1414         assert_eq!(2u8.to_string(), "2");
1415         assert_eq!(true.to_string(), "true");
1416         assert_eq!(false.to_string(), "false");
1417         assert_eq!(().to_string(), "()");
1418         assert_eq!(("hi".to_string()).to_string(), "hi");
1419     }
1420
1421     #[test]
1422     fn test_vectors() {
1423         let x: Vec<int> = vec![];
1424         assert_eq!(x.to_string(), "[]");
1425         assert_eq!((vec![1i]).to_string(), "[1]");
1426         assert_eq!((vec![1i, 2, 3]).to_string(), "[1, 2, 3]");
1427         assert!((vec![vec![], vec![1i], vec![1i, 1]]).to_string() ==
1428                "[[], [1], [1, 1]]");
1429     }
1430
1431     #[test]
1432     fn test_from_iterator() {
1433         let s = "ศไทย中华Việt Nam".to_string();
1434         let t = "ศไทย中华";
1435         let u = "Việt Nam";
1436
1437         let a: String = s.chars().collect();
1438         assert_eq!(s, a);
1439
1440         let mut b = t.to_string();
1441         b.extend(u.chars());
1442         assert_eq!(s, b);
1443
1444         let c: String = vec![t, u].into_iter().collect();
1445         assert_eq!(s, c);
1446
1447         let mut d = t.to_string();
1448         d.extend(vec![u].into_iter());
1449         assert_eq!(s, d);
1450     }
1451
1452     #[bench]
1453     fn bench_with_capacity(b: &mut Bencher) {
1454         b.iter(|| {
1455             String::with_capacity(100)
1456         });
1457     }
1458
1459     #[bench]
1460     fn bench_push_str(b: &mut Bencher) {
1461         let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb";
1462         b.iter(|| {
1463             let mut r = String::new();
1464             r.push_str(s);
1465         });
1466     }
1467
1468     const REPETITIONS: u64 = 10_000;
1469
1470     #[bench]
1471     fn bench_push_str_one_byte(b: &mut Bencher) {
1472         b.bytes = REPETITIONS;
1473         b.iter(|| {
1474             let mut r = String::new();
1475             for _ in range(0, REPETITIONS) {
1476                 r.push_str("a")
1477             }
1478         });
1479     }
1480
1481     #[bench]
1482     fn bench_push_char_one_byte(b: &mut Bencher) {
1483         b.bytes = REPETITIONS;
1484         b.iter(|| {
1485             let mut r = String::new();
1486             for _ in range(0, REPETITIONS) {
1487                 r.push('a')
1488             }
1489         });
1490     }
1491
1492     #[bench]
1493     fn bench_push_char_two_bytes(b: &mut Bencher) {
1494         b.bytes = REPETITIONS * 2;
1495         b.iter(|| {
1496             let mut r = String::new();
1497             for _ in range(0, REPETITIONS) {
1498                 r.push('â')
1499             }
1500         });
1501     }
1502
1503     #[bench]
1504     fn from_utf8_lossy_100_ascii(b: &mut Bencher) {
1505         let s = b"Hello there, the quick brown fox jumped over the lazy dog! \
1506                   Lorem ipsum dolor sit amet, consectetur. ";
1507
1508         assert_eq!(100, s.len());
1509         b.iter(|| {
1510             let _ = String::from_utf8_lossy(s);
1511         });
1512     }
1513
1514     #[bench]
1515     fn from_utf8_lossy_100_multibyte(b: &mut Bencher) {
1516         let s = "𐌀𐌖𐌋𐌄𐌑𐌉ปรدولة الكويتทศไทย中华𐍅𐌿𐌻𐍆𐌹𐌻𐌰".as_bytes();
1517         assert_eq!(100, s.len());
1518         b.iter(|| {
1519             let _ = String::from_utf8_lossy(s);
1520         });
1521     }
1522
1523     #[bench]
1524     fn from_utf8_lossy_invalid(b: &mut Bencher) {
1525         let s = b"Hello\xC0\x80 There\xE6\x83 Goodbye";
1526         b.iter(|| {
1527             let _ = String::from_utf8_lossy(s);
1528         });
1529     }
1530
1531     #[bench]
1532     fn from_utf8_lossy_100_invalid(b: &mut Bencher) {
1533         let s = Vec::from_elem(100, 0xF5u8);
1534         b.iter(|| {
1535             let _ = String::from_utf8_lossy(s.as_slice());
1536         });
1537     }
1538 }