src/liballoc/str.rs

   1 // Copyright 2012-2017 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 //! Unicode string slices.
  12 //!
  13 //! The `&str` type is one of the two main string types, the other being `String`.
  14 //! Unlike its `String` counterpart, its contents are borrowed.
  15 //!
  16 //! # Basic Usage
  17 //!
  18 //! A basic string declaration of `&str` type:
  19 //!
  20 //! ```
  21 //! let hello_world = "Hello, World!";
  22 //! ```
  23 //!
  24 //! Here we have declared a string literal, also known as a string slice.
  25 //! String literals have a static lifetime, which means the string `hello_world`
  26 //! is guaranteed to be valid for the duration of the entire program.
  27 //! We can explicitly specify `hello_world`'s lifetime as well:
  28 //!
  29 //! ```
  30 //! let hello_world: &'static str = "Hello, world!";
  31 //! ```
  32 //!
  33 //! *[See also the `str` primitive type](../../std/primitive.str.html).*
  34
  35 #![stable(feature = "rust1", since = "1.0.0")]
  36
  37 // Many of the usings in this module are only used in the test configuration.
  38 // It's cleaner to just turn off the unused_imports warning than to fix them.
  39 #![allow(unused_imports)]
  40
  41 use core::fmt;
  42 use core::str as core_str;
  43 use core::str::pattern::Pattern;
  44 use core::str::pattern::{Searcher, ReverseSearcher, DoubleEndedSearcher};
  45 use core::mem;
  46 use core::iter::FusedIterator;
  47 use std_unicode::str::{UnicodeStr, Utf16Encoder};
  48
  49 use vec_deque::VecDeque;
  50 use borrow::{Borrow, ToOwned};
  51 use string::String;
  52 use std_unicode;
  53 use vec::Vec;
  54 use slice::{SliceConcatExt, SliceIndex};
  55 use boxed::Box;
  56
  57 #[stable(feature = "rust1", since = "1.0.0")]
  58 pub use core::str::{FromStr, Utf8Error};
  59 #[allow(deprecated)]
  60 #[stable(feature = "rust1", since = "1.0.0")]
  61 pub use core::str::{Lines, LinesAny};
  62 #[stable(feature = "rust1", since = "1.0.0")]
  63 pub use core::str::{Split, RSplit};
  64 #[stable(feature = "rust1", since = "1.0.0")]
  65 pub use core::str::{SplitN, RSplitN};
  66 #[stable(feature = "rust1", since = "1.0.0")]
  67 pub use core::str::{SplitTerminator, RSplitTerminator};
  68 #[stable(feature = "rust1", since = "1.0.0")]
  69 pub use core::str::{Matches, RMatches};
  70 #[stable(feature = "rust1", since = "1.0.0")]
  71 pub use core::str::{MatchIndices, RMatchIndices};
  72 #[stable(feature = "rust1", since = "1.0.0")]
  73 pub use core::str::{from_utf8, from_utf8_mut, Chars, CharIndices, Bytes};
  74 #[stable(feature = "rust1", since = "1.0.0")]
  75 pub use core::str::{from_utf8_unchecked, from_utf8_unchecked_mut, ParseBoolError};
  76 #[stable(feature = "rust1", since = "1.0.0")]
  77 pub use std_unicode::str::SplitWhitespace;
  78 #[stable(feature = "rust1", since = "1.0.0")]
  79 pub use core::str::pattern;
  80
  81
  82 #[unstable(feature = "slice_concat_ext",
  83            reason = "trait should not have to exist",
  84            issue = "27747")]
  85 impl<S: Borrow<str>> SliceConcatExt<str> for [S] {
  86     type Output = String;
  87
  88     fn concat(&self) -> String {
  89         if self.is_empty() {
  90             return String::new();
  91         }
  92
  93         // `len` calculation may overflow but push_str will check boundaries
  94         let len = self.iter().map(|s| s.borrow().len()).sum();
  95         let mut result = String::with_capacity(len);
  96
  97         for s in self {
  98             result.push_str(s.borrow())
  99         }
 100
 101         result
 102     }
 103
 104     fn join(&self, sep: &str) -> String {
 105         if self.is_empty() {
 106             return String::new();
 107         }
 108
 109         // concat is faster
 110         if sep.is_empty() {
 111             return self.concat();
 112         }
 113
 114         // this is wrong without the guarantee that `self` is non-empty
 115         // `len` calculation may overflow but push_str but will check boundaries
 116         let len = sep.len() * (self.len() - 1) +
 117                   self.iter().map(|s| s.borrow().len()).sum::<usize>();
 118         let mut result = String::with_capacity(len);
 119         let mut first = true;
 120
 121         for s in self {
 122             if first {
 123                 first = false;
 124             } else {
 125                 result.push_str(sep);
 126             }
 127             result.push_str(s.borrow());
 128         }
 129         result
 130     }
 131
 132     fn connect(&self, sep: &str) -> String {
 133         self.join(sep)
 134     }
 135 }
 136
 137 /// An iterator of [`u16`] over the string encoded as UTF-16.
 138 ///
 139 /// [`u16`]: ../../std/primitive.u16.html
 140 ///
 141 /// This struct is created by the [`encode_utf16`] method on [`str`].
 142 /// See its documentation for more.
 143 ///
 144 /// [`encode_utf16`]: ../../std/primitive.str.html#method.encode_utf16
 145 /// [`str`]: ../../std/primitive.str.html
 146 #[derive(Clone)]
 147 #[stable(feature = "encode_utf16", since = "1.8.0")]
 148 pub struct EncodeUtf16<'a> {
 149     encoder: Utf16Encoder<Chars<'a>>,
 150 }
 151
 152 #[stable(feature = "collection_debug", since = "1.17.0")]
 153 impl<'a> fmt::Debug for EncodeUtf16<'a> {
 154     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 155         f.pad("EncodeUtf16 { .. }")
 156     }
 157 }
 158
 159 #[stable(feature = "encode_utf16", since = "1.8.0")]
 160 impl<'a> Iterator for EncodeUtf16<'a> {
 161     type Item = u16;
 162
 163     #[inline]
 164     fn next(&mut self) -> Option<u16> {
 165         self.encoder.next()
 166     }
 167
 168     #[inline]
 169     fn size_hint(&self) -> (usize, Option<usize>) {
 170         self.encoder.size_hint()
 171     }
 172 }
 173
 174 #[unstable(feature = "fused", issue = "35602")]
 175 impl<'a> FusedIterator for EncodeUtf16<'a> {}
 176
 177 #[stable(feature = "rust1", since = "1.0.0")]
 178 impl Borrow<str> for String {
 179     #[inline]
 180     fn borrow(&self) -> &str {
 181         &self[..]
 182     }
 183 }
 184
 185 #[stable(feature = "rust1", since = "1.0.0")]
 186 impl ToOwned for str {
 187     type Owned = String;
 188     fn to_owned(&self) -> String {
 189         unsafe { String::from_utf8_unchecked(self.as_bytes().to_owned()) }
 190     }
 191
 192     fn clone_into(&self, target: &mut String) {
 193         let mut b = mem::replace(target, String::new()).into_bytes();
 194         self.as_bytes().clone_into(&mut b);
 195         *target = unsafe { String::from_utf8_unchecked(b) }
 196     }
 197 }
 198
 199 /// Methods for string slices.
 200 #[lang = "str"]
 201 #[cfg(not(test))]
 202 impl str {
 203     /// Returns the length of `self`.
 204     ///
 205     /// This length is in bytes, not [`char`]s or graphemes. In other words,
 206     /// it may not be what a human considers the length of the string.
 207     ///
 208     /// [`char`]: primitive.char.html
 209     ///
 210     /// # Examples
 211     ///
 212     /// Basic usage:
 213     ///
 214     /// ```
 215     /// let len = "foo".len();
 216     /// assert_eq!(3, len);
 217     ///
 218     /// let len = "ƒoo".len(); // fancy f!
 219     /// assert_eq!(4, len);
 220     /// ```
 221     #[stable(feature = "rust1", since = "1.0.0")]
 222     #[inline]
 223     pub fn len(&self) -> usize {
 224         core_str::StrExt::len(self)
 225     }
 226
 227     /// Returns `true` if `self` has a length of zero bytes.
 228     ///
 229     /// # Examples
 230     ///
 231     /// Basic usage:
 232     ///
 233     /// ```
 234     /// let s = "";
 235     /// assert!(s.is_empty());
 236     ///
 237     /// let s = "not empty";
 238     /// assert!(!s.is_empty());
 239     /// ```
 240     #[inline]
 241     #[stable(feature = "rust1", since = "1.0.0")]
 242     pub fn is_empty(&self) -> bool {
 243         core_str::StrExt::is_empty(self)
 244     }
 245
 246     /// Checks that `index`-th byte lies at the start and/or end of a
 247     /// UTF-8 code point sequence.
 248     ///
 249     /// The start and end of the string (when `index == self.len()`) are
 250     /// considered to be
 251     /// boundaries.
 252     ///
 253     /// Returns `false` if `index` is greater than `self.len()`.
 254     ///
 255     /// # Examples
 256     ///
 257     /// ```
 258     /// let s = "Löwe 老虎 Léopard";
 259     /// assert!(s.is_char_boundary(0));
 260     /// // start of `老`
 261     /// assert!(s.is_char_boundary(6));
 262     /// assert!(s.is_char_boundary(s.len()));
 263     ///
 264     /// // second byte of `ö`
 265     /// assert!(!s.is_char_boundary(2));
 266     ///
 267     /// // third byte of `老`
 268     /// assert!(!s.is_char_boundary(8));
 269     /// ```
 270     #[stable(feature = "is_char_boundary", since = "1.9.0")]
 271     #[inline]
 272     pub fn is_char_boundary(&self, index: usize) -> bool {
 273         core_str::StrExt::is_char_boundary(self, index)
 274     }
 275
 276     /// Converts a string slice to a byte slice.
 277     ///
 278     /// # Examples
 279     ///
 280     /// Basic usage:
 281     ///
 282     /// ```
 283     /// let bytes = "bors".as_bytes();
 284     /// assert_eq!(b"bors", bytes);
 285     /// ```
 286     #[stable(feature = "rust1", since = "1.0.0")]
 287     #[inline(always)]
 288     pub fn as_bytes(&self) -> &[u8] {
 289         core_str::StrExt::as_bytes(self)
 290     }
 291
 292     /// Converts a mutable string slice to a mutable byte slice.
 293     #[stable(feature = "str_mut_extras", since = "1.20.0")]
 294     #[inline(always)]
 295     pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
 296         core_str::StrExt::as_bytes_mut(self)
 297     }
 298
 299     /// Converts a string slice to a raw pointer.
 300     ///
 301     /// As string slices are a slice of bytes, the raw pointer points to a
 302     /// [`u8`]. This pointer will be pointing to the first byte of the string
 303     /// slice.
 304     ///
 305     /// [`u8`]: primitive.u8.html
 306     ///
 307     /// # Examples
 308     ///
 309     /// Basic usage:
 310     ///
 311     /// ```
 312     /// let s = "Hello";
 313     /// let ptr = s.as_ptr();
 314     /// ```
 315     #[stable(feature = "rust1", since = "1.0.0")]
 316     #[inline]
 317     pub fn as_ptr(&self) -> *const u8 {
 318         core_str::StrExt::as_ptr(self)
 319     }
 320
 321     /// Returns a subslice of `str`.
 322     ///
 323     /// This is the non-panicking alternative to indexing the `str`. Returns
 324     /// [`None`] whenever equivalent indexing operation would panic.
 325     ///
 326     /// [`None`]: option/enum.Option.html#variant.None
 327     ///
 328     /// # Examples
 329     ///
 330     /// ```
 331     /// let v = "🗻∈🌏";
 332     /// assert_eq!(Some("🗻"), v.get(0..4));
 333     /// assert!(v.get(1..).is_none());
 334     /// assert!(v.get(..8).is_none());
 335     /// assert!(v.get(..42).is_none());
 336     /// ```
 337     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
 338     #[inline]
 339     pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
 340         core_str::StrExt::get(self, i)
 341     }
 342
 343     /// Returns a mutable subslice of `str`.
 344     ///
 345     /// This is the non-panicking alternative to indexing the `str`. Returns
 346     /// [`None`] whenever equivalent indexing operation would panic.
 347     ///
 348     /// [`None`]: option/enum.Option.html#variant.None
 349     ///
 350     /// # Examples
 351     ///
 352     /// ```
 353     /// let mut v = String::from("🗻∈🌏");
 354     /// assert_eq!(Some("🗻"), v.get_mut(0..4).map(|v| &*v));
 355     /// assert!(v.get_mut(1..).is_none());
 356     /// assert!(v.get_mut(..8).is_none());
 357     /// assert!(v.get_mut(..42).is_none());
 358     /// ```
 359     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
 360     #[inline]
 361     pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
 362         core_str::StrExt::get_mut(self, i)
 363     }
 364
 365     /// Returns a unchecked subslice of `str`.
 366     ///
 367     /// This is the unchecked alternative to indexing the `str`.
 368     ///
 369     /// # Safety
 370     ///
 371     /// Callers of this function are responsible that these preconditions are
 372     /// satisfied:
 373     ///
 374     /// * The starting index must come before the ending index;
 375     /// * Indexes must be within bounds of the original slice;
 376     /// * Indexes must lie on UTF-8 sequence boundaries.
 377     ///
 378     /// Failing that, the returned string slice may reference invalid memory or
 379     /// violate the invariants communicated by the `str` type.
 380     ///
 381     /// # Examples
 382     ///
 383     /// ```
 384     /// let v = "🗻∈🌏";
 385     /// unsafe {
 386     ///     assert_eq!("🗻", v.get_unchecked(0..4));
 387     ///     assert_eq!("∈", v.get_unchecked(4..7));
 388     ///     assert_eq!("🌏", v.get_unchecked(7..11));
 389     /// }
 390     /// ```
 391     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
 392     #[inline]
 393     pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
 394         core_str::StrExt::get_unchecked(self, i)
 395     }
 396
 397     /// Returns a mutable, unchecked subslice of `str`.
 398     ///
 399     /// This is the unchecked alternative to indexing the `str`.
 400     ///
 401     /// # Safety
 402     ///
 403     /// Callers of this function are responsible that these preconditions are
 404     /// satisfied:
 405     ///
 406     /// * The starting index must come before the ending index;
 407     /// * Indexes must be within bounds of the original slice;
 408     /// * Indexes must lie on UTF-8 sequence boundaries.
 409     ///
 410     /// Failing that, the returned string slice may reference invalid memory or
 411     /// violate the invariants communicated by the `str` type.
 412     ///
 413     /// # Examples
 414     ///
 415     /// ```
 416     /// let mut v = String::from("🗻∈🌏");
 417     /// unsafe {
 418     ///     assert_eq!("🗻", v.get_unchecked_mut(0..4));
 419     ///     assert_eq!("∈", v.get_unchecked_mut(4..7));
 420     ///     assert_eq!("🌏", v.get_unchecked_mut(7..11));
 421     /// }
 422     /// ```
 423     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
 424     #[inline]
 425     pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
 426         core_str::StrExt::get_unchecked_mut(self, i)
 427     }
 428
 429     /// Creates a string slice from another string slice, bypassing safety
 430     /// checks.
 431     ///
 432     /// This is generally not recommended, use with caution! For a safe
 433     /// alternative see [`str`] and [`Index`].
 434     ///
 435     /// [`str`]: primitive.str.html
 436     /// [`Index`]: ops/trait.Index.html
 437     ///
 438     /// This new slice goes from `begin` to `end`, including `begin` but
 439     /// excluding `end`.
 440     ///
 441     /// To get a mutable string slice instead, see the
 442     /// [`slice_mut_unchecked`] method.
 443     ///
 444     /// [`slice_mut_unchecked`]: #method.slice_mut_unchecked
 445     ///
 446     /// # Safety
 447     ///
 448     /// Callers of this function are responsible that three preconditions are
 449     /// satisfied:
 450     ///
 451     /// * `begin` must come before `end`.
 452     /// * `begin` and `end` must be byte positions within the string slice.
 453     /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
 454     ///
 455     /// # Examples
 456     ///
 457     /// Basic usage:
 458     ///
 459     /// ```
 460     /// let s = "Löwe 老虎 Léopard";
 461     ///
 462     /// unsafe {
 463     ///     assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
 464     /// }
 465     ///
 466     /// let s = "Hello, world!";
 467     ///
 468     /// unsafe {
 469     ///     assert_eq!("world", s.slice_unchecked(7, 12));
 470     /// }
 471     /// ```
 472     #[stable(feature = "rust1", since = "1.0.0")]
 473     #[inline]
 474     pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
 475         core_str::StrExt::slice_unchecked(self, begin, end)
 476     }
 477
 478     /// Creates a string slice from another string slice, bypassing safety
 479     /// checks.
 480     /// This is generally not recommended, use with caution! For a safe
 481     /// alternative see [`str`] and [`IndexMut`].
 482     ///
 483     /// [`str`]: primitive.str.html
 484     /// [`IndexMut`]: ops/trait.IndexMut.html
 485     ///
 486     /// This new slice goes from `begin` to `end`, including `begin` but
 487     /// excluding `end`.
 488     ///
 489     /// To get an immutable string slice instead, see the
 490     /// [`slice_unchecked`] method.
 491     ///
 492     /// [`slice_unchecked`]: #method.slice_unchecked
 493     ///
 494     /// # Safety
 495     ///
 496     /// Callers of this function are responsible that three preconditions are
 497     /// satisfied:
 498     ///
 499     /// * `begin` must come before `end`.
 500     /// * `begin` and `end` must be byte positions within the string slice.
 501     /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
 502     #[stable(feature = "str_slice_mut", since = "1.5.0")]
 503     #[inline]
 504     pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
 505         core_str::StrExt::slice_mut_unchecked(self, begin, end)
 506     }
 507
 508     /// Divide one string slice into two at an index.
 509     ///
 510     /// The argument, `mid`, should be a byte offset from the start of the
 511     /// string. It must also be on the boundary of a UTF-8 code point.
 512     ///
 513     /// The two slices returned go from the start of the string slice to `mid`,
 514     /// and from `mid` to the end of the string slice.
 515     ///
 516     /// To get mutable string slices instead, see the [`split_at_mut`]
 517     /// method.
 518     ///
 519     /// [`split_at_mut`]: #method.split_at_mut
 520     ///
 521     /// # Panics
 522     ///
 523     /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
 524     /// beyond the last code point of the string slice.
 525     ///
 526     /// # Examples
 527     ///
 528     /// Basic usage:
 529     ///
 530     /// ```
 531     /// let s = "Per Martin-Löf";
 532     ///
 533     /// let (first, last) = s.split_at(3);
 534     ///
 535     /// assert_eq!("Per", first);
 536     /// assert_eq!(" Martin-Löf", last);
 537     /// ```
 538     #[inline]
 539     #[stable(feature = "str_split_at", since = "1.4.0")]
 540     pub fn split_at(&self, mid: usize) -> (&str, &str) {
 541         core_str::StrExt::split_at(self, mid)
 542     }
 543
 544     /// Divide one mutable string slice into two at an index.
 545     ///
 546     /// The argument, `mid`, should be a byte offset from the start of the
 547     /// string. It must also be on the boundary of a UTF-8 code point.
 548     ///
 549     /// The two slices returned go from the start of the string slice to `mid`,
 550     /// and from `mid` to the end of the string slice.
 551     ///
 552     /// To get immutable string slices instead, see the [`split_at`] method.
 553     ///
 554     /// [`split_at`]: #method.split_at
 555     ///
 556     /// # Panics
 557     ///
 558     /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
 559     /// beyond the last code point of the string slice.
 560     ///
 561     /// # Examples
 562     ///
 563     /// Basic usage:
 564     ///
 565     /// ```
 566     /// let mut s = "Per Martin-Löf".to_string();
 567     ///
 568     /// let (first, last) = s.split_at_mut(3);
 569     ///
 570     /// assert_eq!("Per", first);
 571     /// assert_eq!(" Martin-Löf", last);
 572     /// ```
 573     #[inline]
 574     #[stable(feature = "str_split_at", since = "1.4.0")]
 575     pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
 576         core_str::StrExt::split_at_mut(self, mid)
 577     }
 578
 579     /// Returns an iterator over the [`char`]s of a string slice.
 580     ///
 581     /// As a string slice consists of valid UTF-8, we can iterate through a
 582     /// string slice by [`char`]. This method returns such an iterator.
 583     ///
 584     /// It's important to remember that [`char`] represents a Unicode Scalar
 585     /// Value, and may not match your idea of what a 'character' is. Iteration
 586     /// over grapheme clusters may be what you actually want.
 587     ///
 588     /// [`char`]: primitive.char.html
 589     ///
 590     /// # Examples
 591     ///
 592     /// Basic usage:
 593     ///
 594     /// ```
 595     /// let word = "goodbye";
 596     ///
 597     /// let count = word.chars().count();
 598     /// assert_eq!(7, count);
 599     ///
 600     /// let mut chars = word.chars();
 601     ///
 602     /// assert_eq!(Some('g'), chars.next());
 603     /// assert_eq!(Some('o'), chars.next());
 604     /// assert_eq!(Some('o'), chars.next());
 605     /// assert_eq!(Some('d'), chars.next());
 606     /// assert_eq!(Some('b'), chars.next());
 607     /// assert_eq!(Some('y'), chars.next());
 608     /// assert_eq!(Some('e'), chars.next());
 609     ///
 610     /// assert_eq!(None, chars.next());
 611     /// ```
 612     ///
 613     /// Remember, [`char`]s may not match your human intuition about characters:
 614     ///
 615     /// ```
 616     /// let y = "y̆";
 617     ///
 618     /// let mut chars = y.chars();
 619     ///
 620     /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
 621     /// assert_eq!(Some('\u{0306}'), chars.next());
 622     ///
 623     /// assert_eq!(None, chars.next());
 624     /// ```
 625     #[stable(feature = "rust1", since = "1.0.0")]
 626     #[inline]
 627     pub fn chars(&self) -> Chars {
 628         core_str::StrExt::chars(self)
 629     }
 630     /// Returns an iterator over the [`char`]s of a string slice, and their
 631     /// positions.
 632     ///
 633     /// As a string slice consists of valid UTF-8, we can iterate through a
 634     /// string slice by [`char`]. This method returns an iterator of both
 635     /// these [`char`]s, as well as their byte positions.
 636     ///
 637     /// The iterator yields tuples. The position is first, the [`char`] is
 638     /// second.
 639     ///
 640     /// [`char`]: primitive.char.html
 641     ///
 642     /// # Examples
 643     ///
 644     /// Basic usage:
 645     ///
 646     /// ```
 647     /// let word = "goodbye";
 648     ///
 649     /// let count = word.char_indices().count();
 650     /// assert_eq!(7, count);
 651     ///
 652     /// let mut char_indices = word.char_indices();
 653     ///
 654     /// assert_eq!(Some((0, 'g')), char_indices.next());
 655     /// assert_eq!(Some((1, 'o')), char_indices.next());
 656     /// assert_eq!(Some((2, 'o')), char_indices.next());
 657     /// assert_eq!(Some((3, 'd')), char_indices.next());
 658     /// assert_eq!(Some((4, 'b')), char_indices.next());
 659     /// assert_eq!(Some((5, 'y')), char_indices.next());
 660     /// assert_eq!(Some((6, 'e')), char_indices.next());
 661     ///
 662     /// assert_eq!(None, char_indices.next());
 663     /// ```
 664     ///
 665     /// Remember, [`char`]s may not match your human intuition about characters:
 666     ///
 667     /// ```
 668     /// let y = "y̆";
 669     ///
 670     /// let mut char_indices = y.char_indices();
 671     ///
 672     /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
 673     /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
 674     ///
 675     /// assert_eq!(None, char_indices.next());
 676     /// ```
 677     #[stable(feature = "rust1", since = "1.0.0")]
 678     #[inline]
 679     pub fn char_indices(&self) -> CharIndices {
 680         core_str::StrExt::char_indices(self)
 681     }
 682
 683     /// An iterator over the bytes of a string slice.
 684     ///
 685     /// As a string slice consists of a sequence of bytes, we can iterate
 686     /// through a string slice by byte. This method returns such an iterator.
 687     ///
 688     /// # Examples
 689     ///
 690     /// Basic usage:
 691     ///
 692     /// ```
 693     /// let mut bytes = "bors".bytes();
 694     ///
 695     /// assert_eq!(Some(b'b'), bytes.next());
 696     /// assert_eq!(Some(b'o'), bytes.next());
 697     /// assert_eq!(Some(b'r'), bytes.next());
 698     /// assert_eq!(Some(b's'), bytes.next());
 699     ///
 700     /// assert_eq!(None, bytes.next());
 701     /// ```
 702     #[stable(feature = "rust1", since = "1.0.0")]
 703     #[inline]
 704     pub fn bytes(&self) -> Bytes {
 705         core_str::StrExt::bytes(self)
 706     }
 707
 708     /// Split a string slice by whitespace.
 709     ///
 710     /// The iterator returned will return string slices that are sub-slices of
 711     /// the original string slice, separated by any amount of whitespace.
 712     ///
 713     /// 'Whitespace' is defined according to the terms of the Unicode Derived
 714     /// Core Property `White_Space`.
 715     ///
 716     /// # Examples
 717     ///
 718     /// Basic usage:
 719     ///
 720     /// ```
 721     /// let mut iter = "A few words".split_whitespace();
 722     ///
 723     /// assert_eq!(Some("A"), iter.next());
 724     /// assert_eq!(Some("few"), iter.next());
 725     /// assert_eq!(Some("words"), iter.next());
 726     ///
 727     /// assert_eq!(None, iter.next());
 728     /// ```
 729     ///
 730     /// All kinds of whitespace are considered:
 731     ///
 732     /// ```
 733     /// let mut iter = " Mary   had\ta\u{2009}little  \n\t lamb".split_whitespace();
 734     /// assert_eq!(Some("Mary"), iter.next());
 735     /// assert_eq!(Some("had"), iter.next());
 736     /// assert_eq!(Some("a"), iter.next());
 737     /// assert_eq!(Some("little"), iter.next());
 738     /// assert_eq!(Some("lamb"), iter.next());
 739     ///
 740     /// assert_eq!(None, iter.next());
 741     /// ```
 742     #[stable(feature = "split_whitespace", since = "1.1.0")]
 743     #[inline]
 744     pub fn split_whitespace(&self) -> SplitWhitespace {
 745         UnicodeStr::split_whitespace(self)
 746     }
 747
 748     /// An iterator over the lines of a string, as string slices.
 749     ///
 750     /// Lines are ended with either a newline (`\n`) or a carriage return with
 751     /// a line feed (`\r\n`).
 752     ///
 753     /// The final line ending is optional.
 754     ///
 755     /// # Examples
 756     ///
 757     /// Basic usage:
 758     ///
 759     /// ```
 760     /// let text = "foo\r\nbar\n\nbaz\n";
 761     /// let mut lines = text.lines();
 762     ///
 763     /// assert_eq!(Some("foo"), lines.next());
 764     /// assert_eq!(Some("bar"), lines.next());
 765     /// assert_eq!(Some(""), lines.next());
 766     /// assert_eq!(Some("baz"), lines.next());
 767     ///
 768     /// assert_eq!(None, lines.next());
 769     /// ```
 770     ///
 771     /// The final line ending isn't required:
 772     ///
 773     /// ```
 774     /// let text = "foo\nbar\n\r\nbaz";
 775     /// let mut lines = text.lines();
 776     ///
 777     /// assert_eq!(Some("foo"), lines.next());
 778     /// assert_eq!(Some("bar"), lines.next());
 779     /// assert_eq!(Some(""), lines.next());
 780     /// assert_eq!(Some("baz"), lines.next());
 781     ///
 782     /// assert_eq!(None, lines.next());
 783     /// ```
 784     #[stable(feature = "rust1", since = "1.0.0")]
 785     #[inline]
 786     pub fn lines(&self) -> Lines {
 787         core_str::StrExt::lines(self)
 788     }
 789
 790     /// An iterator over the lines of a string.
 791     #[stable(feature = "rust1", since = "1.0.0")]
 792     #[rustc_deprecated(since = "1.4.0", reason = "use lines() instead now")]
 793     #[inline]
 794     #[allow(deprecated)]
 795     pub fn lines_any(&self) -> LinesAny {
 796         core_str::StrExt::lines_any(self)
 797     }
 798
 799     /// Returns an iterator of `u16` over the string encoded as UTF-16.
 800     #[stable(feature = "encode_utf16", since = "1.8.0")]
 801     pub fn encode_utf16(&self) -> EncodeUtf16 {
 802         EncodeUtf16 { encoder: Utf16Encoder::new(self[..].chars()) }
 803     }
 804
 805     /// Returns `true` if the given pattern matches a sub-slice of
 806     /// this string slice.
 807     ///
 808     /// Returns `false` if it does not.
 809     ///
 810     /// # Examples
 811     ///
 812     /// Basic usage:
 813     ///
 814     /// ```
 815     /// let bananas = "bananas";
 816     ///
 817     /// assert!(bananas.contains("nana"));
 818     /// assert!(!bananas.contains("apples"));
 819     /// ```
 820     #[stable(feature = "rust1", since = "1.0.0")]
 821     #[inline]
 822     pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
 823         core_str::StrExt::contains(self, pat)
 824     }
 825
 826     /// Returns `true` if the given pattern matches a prefix of this
 827     /// string slice.
 828     ///
 829     /// Returns `false` if it does not.
 830     ///
 831     /// # Examples
 832     ///
 833     /// Basic usage:
 834     ///
 835     /// ```
 836     /// let bananas = "bananas";
 837     ///
 838     /// assert!(bananas.starts_with("bana"));
 839     /// assert!(!bananas.starts_with("nana"));
 840     /// ```
 841     #[stable(feature = "rust1", since = "1.0.0")]
 842     pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
 843         core_str::StrExt::starts_with(self, pat)
 844     }
 845
 846     /// Returns `true` if the given pattern matches a suffix of this
 847     /// string slice.
 848     ///
 849     /// Returns `false` if it does not.
 850     ///
 851     /// # Examples
 852     ///
 853     /// Basic usage:
 854     ///
 855     /// ```
 856     /// let bananas = "bananas";
 857     ///
 858     /// assert!(bananas.ends_with("anas"));
 859     /// assert!(!bananas.ends_with("nana"));
 860     /// ```
 861     #[stable(feature = "rust1", since = "1.0.0")]
 862     pub fn ends_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool
 863         where P::Searcher: ReverseSearcher<'a>
 864     {
 865         core_str::StrExt::ends_with(self, pat)
 866     }
 867
 868     /// Returns the byte index of the first character of this string slice that
 869     /// matches the pattern.
 870     ///
 871     /// Returns [`None`] if the pattern doesn't match.
 872     ///
 873     /// The pattern can be a `&str`, [`char`], or a closure that determines if
 874     /// a character matches.
 875     ///
 876     /// [`char`]: primitive.char.html
 877     /// [`None`]: option/enum.Option.html#variant.None
 878     ///
 879     /// # Examples
 880     ///
 881     /// Simple patterns:
 882     ///
 883     /// ```
 884     /// let s = "Löwe 老虎 Léopard";
 885     ///
 886     /// assert_eq!(s.find('L'), Some(0));
 887     /// assert_eq!(s.find('é'), Some(14));
 888     /// assert_eq!(s.find("Léopard"), Some(13));
 889     /// ```
 890     ///
 891     /// More complex patterns with closures:
 892     ///
 893     /// ```
 894     /// let s = "Löwe 老虎 Léopard";
 895     ///
 896     /// assert_eq!(s.find(char::is_whitespace), Some(5));
 897     /// assert_eq!(s.find(char::is_lowercase), Some(1));
 898     /// ```
 899     ///
 900     /// Not finding the pattern:
 901     ///
 902     /// ```
 903     /// let s = "Löwe 老虎 Léopard";
 904     /// let x: &[_] = &['1', '2'];
 905     ///
 906     /// assert_eq!(s.find(x), None);
 907     /// ```
 908     #[stable(feature = "rust1", since = "1.0.0")]
 909     #[inline]
 910     pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize> {
 911         core_str::StrExt::find(self, pat)
 912     }
 913
 914     /// Returns the byte index of the last character of this string slice that
 915     /// matches the pattern.
 916     ///
 917     /// Returns [`None`] if the pattern doesn't match.
 918     ///
 919     /// The pattern can be a `&str`, [`char`], or a closure that determines if
 920     /// a character matches.
 921     ///
 922     /// [`char`]: primitive.char.html
 923     /// [`None`]: option/enum.Option.html#variant.None
 924     ///
 925     /// # Examples
 926     ///
 927     /// Simple patterns:
 928     ///
 929     /// ```
 930     /// let s = "Löwe 老虎 Léopard";
 931     ///
 932     /// assert_eq!(s.rfind('L'), Some(13));
 933     /// assert_eq!(s.rfind('é'), Some(14));
 934     /// ```
 935     ///
 936     /// More complex patterns with closures:
 937     ///
 938     /// ```
 939     /// let s = "Löwe 老虎 Léopard";
 940     ///
 941     /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
 942     /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
 943     /// ```
 944     ///
 945     /// Not finding the pattern:
 946     ///
 947     /// ```
 948     /// let s = "Löwe 老虎 Léopard";
 949     /// let x: &[_] = &['1', '2'];
 950     ///
 951     /// assert_eq!(s.rfind(x), None);
 952     /// ```
 953     #[stable(feature = "rust1", since = "1.0.0")]
 954     #[inline]
 955     pub fn rfind<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize>
 956         where P::Searcher: ReverseSearcher<'a>
 957     {
 958         core_str::StrExt::rfind(self, pat)
 959     }
 960
 961     /// An iterator over substrings of this string slice, separated by
 962     /// characters matched by a pattern.
 963     ///
 964     /// The pattern can be a `&str`, [`char`], or a closure that determines the
 965     /// split.
 966     ///
 967     /// # Iterator behavior
 968     ///
 969     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
 970     /// allows a reverse search and forward/reverse search yields the same
 971     /// elements. This is true for, eg, [`char`] but not for `&str`.
 972     ///
 973     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
 974     ///
 975     /// If the pattern allows a reverse search but its results might differ
 976     /// from a forward search, the [`rsplit`] method can be used.
 977     ///
 978     /// [`char`]: primitive.char.html
 979     /// [`rsplit`]: #method.rsplit
 980     ///
 981     /// # Examples
 982     ///
 983     /// Simple patterns:
 984     ///
 985     /// ```
 986     /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
 987     /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
 988     ///
 989     /// let v: Vec<&str> = "".split('X').collect();
 990     /// assert_eq!(v, [""]);
 991     ///
 992     /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
 993     /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
 994     ///
 995     /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
 996     /// assert_eq!(v, ["lion", "tiger", "leopard"]);
 997     ///
 998     /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
 999     /// assert_eq!(v, ["abc", "def", "ghi"]);
1000     ///
1001     /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
1002     /// assert_eq!(v, ["lion", "tiger", "leopard"]);
1003     /// ```
1004     ///
1005     /// A more complex pattern, using a closure:
1006     ///
1007     /// ```
1008     /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
1009     /// assert_eq!(v, ["abc", "def", "ghi"]);
1010     /// ```
1011     ///
1012     /// If a string contains multiple contiguous separators, you will end up
1013     /// with empty strings in the output:
1014     ///
1015     /// ```
1016     /// let x = "||||a||b|c".to_string();
1017     /// let d: Vec<_> = x.split('|').collect();
1018     ///
1019     /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
1020     /// ```
1021     ///
1022     /// Contiguous separators are separated by the empty string.
1023     ///
1024     /// ```
1025     /// let x = "(///)".to_string();
1026     /// let d: Vec<_> = x.split('/').collect();
1027     ///
1028     /// assert_eq!(d, &["(", "", "", ")"]);
1029     /// ```
1030     ///
1031     /// Separators at the start or end of a string are neighbored
1032     /// by empty strings.
1033     ///
1034     /// ```
1035     /// let d: Vec<_> = "010".split("0").collect();
1036     /// assert_eq!(d, &["", "1", ""]);
1037     /// ```
1038     ///
1039     /// When the empty string is used as a separator, it separates
1040     /// every character in the string, along with the beginning
1041     /// and end of the string.
1042     ///
1043     /// ```
1044     /// let f: Vec<_> = "rust".split("").collect();
1045     /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
1046     /// ```
1047     ///
1048     /// Contiguous separators can lead to possibly surprising behavior
1049     /// when whitespace is used as the separator. This code is correct:
1050     ///
1051     /// ```
1052     /// let x = "    a  b c".to_string();
1053     /// let d: Vec<_> = x.split(' ').collect();
1054     ///
1055     /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
1056     /// ```
1057     ///
1058     /// It does _not_ give you:
1059     ///
1060     /// ```,ignore
1061     /// assert_eq!(d, &["a", "b", "c"]);
1062     /// ```
1063     ///
1064     /// Use [`split_whitespace`] for this behavior.
1065     ///
1066     /// [`split_whitespace`]: #method.split_whitespace
1067     #[stable(feature = "rust1", since = "1.0.0")]
1068     #[inline]
1069     pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> {
1070         core_str::StrExt::split(self, pat)
1071     }
1072
1073     /// An iterator over substrings of the given string slice, separated by
1074     /// characters matched by a pattern and yielded in reverse order.
1075     ///
1076     /// The pattern can be a `&str`, [`char`], or a closure that determines the
1077     /// split.
1078     ///
1079     /// [`char`]: primitive.char.html
1080     ///
1081     /// # Iterator behavior
1082     ///
1083     /// The returned iterator requires that the pattern supports a reverse
1084     /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1085     /// search yields the same elements.
1086     ///
1087     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
1088     ///
1089     /// For iterating from the front, the [`split`] method can be used.
1090     ///
1091     /// [`split`]: #method.split
1092     ///
1093     /// # Examples
1094     ///
1095     /// Simple patterns:
1096     ///
1097     /// ```
1098     /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
1099     /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
1100     ///
1101     /// let v: Vec<&str> = "".rsplit('X').collect();
1102     /// assert_eq!(v, [""]);
1103     ///
1104     /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
1105     /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
1106     ///
1107     /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
1108     /// assert_eq!(v, ["leopard", "tiger", "lion"]);
1109     /// ```
1110     ///
1111     /// A more complex pattern, using a closure:
1112     ///
1113     /// ```
1114     /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
1115     /// assert_eq!(v, ["ghi", "def", "abc"]);
1116     /// ```
1117     #[stable(feature = "rust1", since = "1.0.0")]
1118     #[inline]
1119     pub fn rsplit<'a, P: Pattern<'a>>(&'a self, pat: P) -> RSplit<'a, P>
1120         where P::Searcher: ReverseSearcher<'a>
1121     {
1122         core_str::StrExt::rsplit(self, pat)
1123     }
1124
1125     /// An iterator over substrings of the given string slice, separated by
1126     /// characters matched by a pattern.
1127     ///
1128     /// The pattern can be a `&str`, [`char`], or a closure that determines the
1129     /// split.
1130     ///
1131     /// Equivalent to [`split`], except that the trailing substring
1132     /// is skipped if empty.
1133     ///
1134     /// [`split`]: #method.split
1135     ///
1136     /// This method can be used for string data that is _terminated_,
1137     /// rather than _separated_ by a pattern.
1138     ///
1139     /// # Iterator behavior
1140     ///
1141     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1142     /// allows a reverse search and forward/reverse search yields the same
1143     /// elements. This is true for, eg, [`char`] but not for `&str`.
1144     ///
1145     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
1146     /// [`char`]: primitive.char.html
1147     ///
1148     /// If the pattern allows a reverse search but its results might differ
1149     /// from a forward search, the [`rsplit_terminator`] method can be used.
1150     ///
1151     /// [`rsplit_terminator`]: #method.rsplit_terminator
1152     ///
1153     /// # Examples
1154     ///
1155     /// Basic usage:
1156     ///
1157     /// ```
1158     /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
1159     /// assert_eq!(v, ["A", "B"]);
1160     ///
1161     /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
1162     /// assert_eq!(v, ["A", "", "B", ""]);
1163     /// ```
1164     #[stable(feature = "rust1", since = "1.0.0")]
1165     #[inline]
1166     pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
1167         core_str::StrExt::split_terminator(self, pat)
1168     }
1169
1170     /// An iterator over substrings of `self`, separated by characters
1171     /// matched by a pattern and yielded in reverse order.
1172     ///
1173     /// The pattern can be a simple `&str`, [`char`], or a closure that
1174     /// determines the split.
1175     /// Additional libraries might provide more complex patterns like
1176     /// regular expressions.
1177     ///
1178     /// [`char`]: primitive.char.html
1179     ///
1180     /// Equivalent to [`split`], except that the trailing substring is
1181     /// skipped if empty.
1182     ///
1183     /// [`split`]: #method.split
1184     ///
1185     /// This method can be used for string data that is _terminated_,
1186     /// rather than _separated_ by a pattern.
1187     ///
1188     /// # Iterator behavior
1189     ///
1190     /// The returned iterator requires that the pattern supports a
1191     /// reverse search, and it will be double ended if a forward/reverse
1192     /// search yields the same elements.
1193     ///
1194     /// For iterating from the front, the [`split_terminator`] method can be
1195     /// used.
1196     ///
1197     /// [`split_terminator`]: #method.split_terminator
1198     ///
1199     /// # Examples
1200     ///
1201     /// ```
1202     /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
1203     /// assert_eq!(v, ["B", "A"]);
1204     ///
1205     /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
1206     /// assert_eq!(v, ["", "B", "", "A"]);
1207     /// ```
1208     #[stable(feature = "rust1", since = "1.0.0")]
1209     #[inline]
1210     pub fn rsplit_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> RSplitTerminator<'a, P>
1211         where P::Searcher: ReverseSearcher<'a>
1212     {
1213         core_str::StrExt::rsplit_terminator(self, pat)
1214     }
1215
1216     /// An iterator over substrings of the given string slice, separated by a
1217     /// pattern, restricted to returning at most `n` items.
1218     ///
1219     /// If `n` substrings are returned, the last substring (the `n`th substring)
1220     /// will contain the remainder of the string.
1221     ///
1222     /// The pattern can be a `&str`, [`char`], or a closure that determines the
1223     /// split.
1224     ///
1225     /// [`char`]: primitive.char.html
1226     ///
1227     /// # Iterator behavior
1228     ///
1229     /// The returned iterator will not be double ended, because it is
1230     /// not efficient to support.
1231     ///
1232     /// If the pattern allows a reverse search, the [`rsplitn`] method can be
1233     /// used.
1234     ///
1235     /// [`rsplitn`]: #method.rsplitn
1236     ///
1237     /// # Examples
1238     ///
1239     /// Simple patterns:
1240     ///
1241     /// ```
1242     /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
1243     /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
1244     ///
1245     /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
1246     /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
1247     ///
1248     /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
1249     /// assert_eq!(v, ["abcXdef"]);
1250     ///
1251     /// let v: Vec<&str> = "".splitn(1, 'X').collect();
1252     /// assert_eq!(v, [""]);
1253     /// ```
1254     ///
1255     /// A more complex pattern, using a closure:
1256     ///
1257     /// ```
1258     /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
1259     /// assert_eq!(v, ["abc", "defXghi"]);
1260     /// ```
1261     #[stable(feature = "rust1", since = "1.0.0")]
1262     #[inline]
1263     pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> {
1264         core_str::StrExt::splitn(self, n, pat)
1265     }
1266
1267     /// An iterator over substrings of this string slice, separated by a
1268     /// pattern, starting from the end of the string, restricted to returning
1269     /// at most `n` items.
1270     ///
1271     /// If `n` substrings are returned, the last substring (the `n`th substring)
1272     /// will contain the remainder of the string.
1273     ///
1274     /// The pattern can be a `&str`, [`char`], or a closure that
1275     /// determines the split.
1276     ///
1277     /// [`char`]: primitive.char.html
1278     ///
1279     /// # Iterator behavior
1280     ///
1281     /// The returned iterator will not be double ended, because it is not
1282     /// efficient to support.
1283     ///
1284     /// For splitting from the front, the [`splitn`] method can be used.
1285     ///
1286     /// [`splitn`]: #method.splitn
1287     ///
1288     /// # Examples
1289     ///
1290     /// Simple patterns:
1291     ///
1292     /// ```
1293     /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
1294     /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
1295     ///
1296     /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
1297     /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
1298     ///
1299     /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
1300     /// assert_eq!(v, ["leopard", "lion::tiger"]);
1301     /// ```
1302     ///
1303     /// A more complex pattern, using a closure:
1304     ///
1305     /// ```
1306     /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
1307     /// assert_eq!(v, ["ghi", "abc1def"]);
1308     /// ```
1309     #[stable(feature = "rust1", since = "1.0.0")]
1310     #[inline]
1311     pub fn rsplitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> RSplitN<'a, P>
1312         where P::Searcher: ReverseSearcher<'a>
1313     {
1314         core_str::StrExt::rsplitn(self, n, pat)
1315     }
1316
1317     /// An iterator over the disjoint matches of a pattern within the given string
1318     /// slice.
1319     ///
1320     /// The pattern can be a `&str`, [`char`], or a closure that
1321     /// determines if a character matches.
1322     ///
1323     /// [`char`]: primitive.char.html
1324     ///
1325     /// # Iterator behavior
1326     ///
1327     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1328     /// allows a reverse search and forward/reverse search yields the same
1329     /// elements. This is true for, eg, [`char`] but not for `&str`.
1330     ///
1331     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
1332     /// [`char`]: primitive.char.html
1333     ///
1334     /// If the pattern allows a reverse search but its results might differ
1335     /// from a forward search, the [`rmatches`] method can be used.
1336     ///
1337     /// [`rmatches`]: #method.rmatches
1338     ///
1339     /// # Examples
1340     ///
1341     /// Basic usage:
1342     ///
1343     /// ```
1344     /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
1345     /// assert_eq!(v, ["abc", "abc", "abc"]);
1346     ///
1347     /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
1348     /// assert_eq!(v, ["1", "2", "3"]);
1349     /// ```
1350     #[stable(feature = "str_matches", since = "1.2.0")]
1351     #[inline]
1352     pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> {
1353         core_str::StrExt::matches(self, pat)
1354     }
1355
1356     /// An iterator over the disjoint matches of a pattern within this string slice,
1357     /// yielded in reverse order.
1358     ///
1359     /// The pattern can be a `&str`, [`char`], or a closure that determines if
1360     /// a character matches.
1361     ///
1362     /// [`char`]: primitive.char.html
1363     ///
1364     /// # Iterator behavior
1365     ///
1366     /// The returned iterator requires that the pattern supports a reverse
1367     /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1368     /// search yields the same elements.
1369     ///
1370     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
1371     ///
1372     /// For iterating from the front, the [`matches`] method can be used.
1373     ///
1374     /// [`matches`]: #method.matches
1375     ///
1376     /// # Examples
1377     ///
1378     /// Basic usage:
1379     ///
1380     /// ```
1381     /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
1382     /// assert_eq!(v, ["abc", "abc", "abc"]);
1383     ///
1384     /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
1385     /// assert_eq!(v, ["3", "2", "1"]);
1386     /// ```
1387     #[stable(feature = "str_matches", since = "1.2.0")]
1388     #[inline]
1389     pub fn rmatches<'a, P: Pattern<'a>>(&'a self, pat: P) -> RMatches<'a, P>
1390         where P::Searcher: ReverseSearcher<'a>
1391     {
1392         core_str::StrExt::rmatches(self, pat)
1393     }
1394
1395     /// An iterator over the disjoint matches of a pattern within this string
1396     /// slice as well as the index that the match starts at.
1397     ///
1398     /// For matches of `pat` within `self` that overlap, only the indices
1399     /// corresponding to the first match are returned.
1400     ///
1401     /// The pattern can be a `&str`, [`char`], or a closure that determines
1402     /// if a character matches.
1403     ///
1404     /// [`char`]: primitive.char.html
1405     ///
1406     /// # Iterator behavior
1407     ///
1408     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1409     /// allows a reverse search and forward/reverse search yields the same
1410     /// elements. This is true for, eg, [`char`] but not for `&str`.
1411     ///
1412     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
1413     ///
1414     /// If the pattern allows a reverse search but its results might differ
1415     /// from a forward search, the [`rmatch_indices`] method can be used.
1416     ///
1417     /// [`rmatch_indices`]: #method.rmatch_indices
1418     ///
1419     /// # Examples
1420     ///
1421     /// Basic usage:
1422     ///
1423     /// ```
1424     /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
1425     /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
1426     ///
1427     /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
1428     /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
1429     ///
1430     /// let v: Vec<_> = "ababa".match_indices("aba").collect();
1431     /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
1432     /// ```
1433     #[stable(feature = "str_match_indices", since = "1.5.0")]
1434     #[inline]
1435     pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> {
1436         core_str::StrExt::match_indices(self, pat)
1437     }
1438
1439     /// An iterator over the disjoint matches of a pattern within `self`,
1440     /// yielded in reverse order along with the index of the match.
1441     ///
1442     /// For matches of `pat` within `self` that overlap, only the indices
1443     /// corresponding to the last match are returned.
1444     ///
1445     /// The pattern can be a `&str`, [`char`], or a closure that determines if a
1446     /// character matches.
1447     ///
1448     /// [`char`]: primitive.char.html
1449     ///
1450     /// # Iterator behavior
1451     ///
1452     /// The returned iterator requires that the pattern supports a reverse
1453     /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1454     /// search yields the same elements.
1455     ///
1456     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
1457     ///
1458     /// For iterating from the front, the [`match_indices`] method can be used.
1459     ///
1460     /// [`match_indices`]: #method.match_indices
1461     ///
1462     /// # Examples
1463     ///
1464     /// Basic usage:
1465     ///
1466     /// ```
1467     /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
1468     /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
1469     ///
1470     /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
1471     /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
1472     ///
1473     /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
1474     /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
1475     /// ```
1476     #[stable(feature = "str_match_indices", since = "1.5.0")]
1477     #[inline]
1478     pub fn rmatch_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> RMatchIndices<'a, P>
1479         where P::Searcher: ReverseSearcher<'a>
1480     {
1481         core_str::StrExt::rmatch_indices(self, pat)
1482     }
1483
1484     /// Returns a string slice with leading and trailing whitespace removed.
1485     ///
1486     /// 'Whitespace' is defined according to the terms of the Unicode Derived
1487     /// Core Property `White_Space`.
1488     ///
1489     /// # Examples
1490     ///
1491     /// Basic usage:
1492     ///
1493     /// ```
1494     /// let s = " Hello\tworld\t";
1495     ///
1496     /// assert_eq!("Hello\tworld", s.trim());
1497     /// ```
1498     #[stable(feature = "rust1", since = "1.0.0")]
1499     pub fn trim(&self) -> &str {
1500         UnicodeStr::trim(self)
1501     }
1502
1503     /// Returns a string slice with leading whitespace removed.
1504     ///
1505     /// 'Whitespace' is defined according to the terms of the Unicode Derived
1506     /// Core Property `White_Space`.
1507     ///
1508     /// # Text directionality
1509     ///
1510     /// A string is a sequence of bytes. 'Left' in this context means the first
1511     /// position of that byte string; for a language like Arabic or Hebrew
1512     /// which are 'right to left' rather than 'left to right', this will be
1513     /// the _right_ side, not the left.
1514     ///
1515     /// # Examples
1516     ///
1517     /// Basic usage:
1518     ///
1519     /// ```
1520     /// let s = " Hello\tworld\t";
1521     ///
1522     /// assert_eq!("Hello\tworld\t", s.trim_left());
1523     /// ```
1524     ///
1525     /// Directionality:
1526     ///
1527     /// ```
1528     /// let s = "  English";
1529     /// assert!(Some('E') == s.trim_left().chars().next());
1530     ///
1531     /// let s = "  עברית";
1532     /// assert!(Some('ע') == s.trim_left().chars().next());
1533     /// ```
1534     #[stable(feature = "rust1", since = "1.0.0")]
1535     pub fn trim_left(&self) -> &str {
1536         UnicodeStr::trim_left(self)
1537     }
1538
1539     /// Returns a string slice with trailing whitespace removed.
1540     ///
1541     /// 'Whitespace' is defined according to the terms of the Unicode Derived
1542     /// Core Property `White_Space`.
1543     ///
1544     /// # Text directionality
1545     ///
1546     /// A string is a sequence of bytes. 'Right' in this context means the last
1547     /// position of that byte string; for a language like Arabic or Hebrew
1548     /// which are 'right to left' rather than 'left to right', this will be
1549     /// the _left_ side, not the right.
1550     ///
1551     /// # Examples
1552     ///
1553     /// Basic usage:
1554     ///
1555     /// ```
1556     /// let s = " Hello\tworld\t";
1557     ///
1558     /// assert_eq!(" Hello\tworld", s.trim_right());
1559     /// ```
1560     ///
1561     /// Directionality:
1562     ///
1563     /// ```
1564     /// let s = "English  ";
1565     /// assert!(Some('h') == s.trim_right().chars().rev().next());
1566     ///
1567     /// let s = "עברית  ";
1568     /// assert!(Some('ת') == s.trim_right().chars().rev().next());
1569     /// ```
1570     #[stable(feature = "rust1", since = "1.0.0")]
1571     pub fn trim_right(&self) -> &str {
1572         UnicodeStr::trim_right(self)
1573     }
1574
1575     /// Returns a string slice with all prefixes and suffixes that match a
1576     /// pattern repeatedly removed.
1577     ///
1578     /// The pattern can be a [`char`] or a closure that determines if a
1579     /// character matches.
1580     ///
1581     /// [`char`]: primitive.char.html
1582     ///
1583     /// # Examples
1584     ///
1585     /// Simple patterns:
1586     ///
1587     /// ```
1588     /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
1589     /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
1590     ///
1591     /// let x: &[_] = &['1', '2'];
1592     /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
1593     /// ```
1594     ///
1595     /// A more complex pattern, using a closure:
1596     ///
1597     /// ```
1598     /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
1599     /// ```
1600     #[stable(feature = "rust1", since = "1.0.0")]
1601     pub fn trim_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str
1602         where P::Searcher: DoubleEndedSearcher<'a>
1603     {
1604         core_str::StrExt::trim_matches(self, pat)
1605     }
1606
1607     /// Returns a string slice with all prefixes that match a pattern
1608     /// repeatedly removed.
1609     ///
1610     /// The pattern can be a `&str`, [`char`], or a closure that determines if
1611     /// a character matches.
1612     ///
1613     /// [`char`]: primitive.char.html
1614     ///
1615     /// # Text directionality
1616     ///
1617     /// A string is a sequence of bytes. 'Left' in this context means the first
1618     /// position of that byte string; for a language like Arabic or Hebrew
1619     /// which are 'right to left' rather than 'left to right', this will be
1620     /// the _right_ side, not the left.
1621     ///
1622     /// # Examples
1623     ///
1624     /// Basic usage:
1625     ///
1626     /// ```
1627     /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
1628     /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
1629     ///
1630     /// let x: &[_] = &['1', '2'];
1631     /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
1632     /// ```
1633     #[stable(feature = "rust1", since = "1.0.0")]
1634     pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
1635         core_str::StrExt::trim_left_matches(self, pat)
1636     }
1637
1638     /// Returns a string slice with all suffixes that match a pattern
1639     /// repeatedly removed.
1640     ///
1641     /// The pattern can be a `&str`, [`char`], or a closure that
1642     /// determines if a character matches.
1643     ///
1644     /// [`char`]: primitive.char.html
1645     ///
1646     /// # Text directionality
1647     ///
1648     /// A string is a sequence of bytes. 'Right' in this context means the last
1649     /// position of that byte string; for a language like Arabic or Hebrew
1650     /// which are 'right to left' rather than 'left to right', this will be
1651     /// the _left_ side, not the right.
1652     ///
1653     /// # Examples
1654     ///
1655     /// Simple patterns:
1656     ///
1657     /// ```
1658     /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
1659     /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
1660     ///
1661     /// let x: &[_] = &['1', '2'];
1662     /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
1663     /// ```
1664     ///
1665     /// A more complex pattern, using a closure:
1666     ///
1667     /// ```
1668     /// assert_eq!("1fooX".trim_left_matches(|c| c == '1' || c == 'X'), "fooX");
1669     /// ```
1670     #[stable(feature = "rust1", since = "1.0.0")]
1671     pub fn trim_right_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str
1672         where P::Searcher: ReverseSearcher<'a>
1673     {
1674         core_str::StrExt::trim_right_matches(self, pat)
1675     }
1676
1677     /// Parses this string slice into another type.
1678     ///
1679     /// Because `parse` is so general, it can cause problems with type
1680     /// inference. As such, `parse` is one of the few times you'll see
1681     /// the syntax affectionately known as the 'turbofish': `::<>`. This
1682     /// helps the inference algorithm understand specifically which type
1683     /// you're trying to parse into.
1684     ///
1685     /// `parse` can parse any type that implements the [`FromStr`] trait.
1686     ///
1687     /// [`FromStr`]: str/trait.FromStr.html
1688     ///
1689     /// # Errors
1690     ///
1691     /// Will return [`Err`] if it's not possible to parse this string slice into
1692     /// the desired type.
1693     ///
1694     /// [`Err`]: str/trait.FromStr.html#associatedtype.Err
1695     ///
1696     /// # Example
1697     ///
1698     /// Basic usage
1699     ///
1700     /// ```
1701     /// let four: u32 = "4".parse().unwrap();
1702     ///
1703     /// assert_eq!(4, four);
1704     /// ```
1705     ///
1706     /// Using the 'turbofish' instead of annotating `four`:
1707     ///
1708     /// ```
1709     /// let four = "4".parse::<u32>();
1710     ///
1711     /// assert_eq!(Ok(4), four);
1712     /// ```
1713     ///
1714     /// Failing to parse:
1715     ///
1716     /// ```
1717     /// let nope = "j".parse::<u32>();
1718     ///
1719     /// assert!(nope.is_err());
1720     /// ```
1721     #[inline]
1722     #[stable(feature = "rust1", since = "1.0.0")]
1723     pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
1724         core_str::StrExt::parse(self)
1725     }
1726
1727     /// Converts a `Box<str>` into a `Box<[u8]>` without copying or allocating.
1728     #[stable(feature = "str_box_extras", since = "1.20.0")]
1729     pub fn into_boxed_bytes(self: Box<str>) -> Box<[u8]> {
1730         self.into()
1731     }
1732
1733     /// Replaces all matches of a pattern with another string.
1734     ///
1735     /// `replace` creates a new [`String`], and copies the data from this string slice into it.
1736     /// While doing so, it attempts to find matches of a pattern. If it finds any, it
1737     /// replaces them with the replacement string slice.
1738     ///
1739     /// [`String`]: string/struct.String.html
1740     ///
1741     /// # Examples
1742     ///
1743     /// Basic usage:
1744     ///
1745     /// ```
1746     /// let s = "this is old";
1747     ///
1748     /// assert_eq!("this is new", s.replace("old", "new"));
1749     /// ```
1750     ///
1751     /// When the pattern doesn't match:
1752     ///
1753     /// ```
1754     /// let s = "this is old";
1755     /// assert_eq!(s, s.replace("cookie monster", "little lamb"));
1756     /// ```
1757     #[stable(feature = "rust1", since = "1.0.0")]
1758     #[inline]
1759     pub fn replace<'a, P: Pattern<'a>>(&'a self, from: P, to: &str) -> String {
1760         let mut result = String::new();
1761         let mut last_end = 0;
1762         for (start, part) in self.match_indices(from) {
1763             result.push_str(unsafe { self.slice_unchecked(last_end, start) });
1764             result.push_str(to);
1765             last_end = start + part.len();
1766         }
1767         result.push_str(unsafe { self.slice_unchecked(last_end, self.len()) });
1768         result
1769     }
1770
1771     /// Replaces first N matches of a pattern with another string.
1772     ///
1773     /// `replacen` creates a new [`String`], and copies the data from this string slice into it.
1774     /// While doing so, it attempts to find matches of a pattern. If it finds any, it
1775     /// replaces them with the replacement string slice at most `count` times.
1776     ///
1777     /// [`String`]: string/struct.String.html
1778     ///
1779     /// # Examples
1780     ///
1781     /// Basic usage:
1782     ///
1783     /// ```
1784     /// let s = "foo foo 123 foo";
1785     /// assert_eq!("new new 123 foo", s.replacen("foo", "new", 2));
1786     /// assert_eq!("faa fao 123 foo", s.replacen('o', "a", 3));
1787     /// assert_eq!("foo foo new23 foo", s.replacen(char::is_numeric, "new", 1));
1788     /// ```
1789     ///
1790     /// When the pattern doesn't match:
1791     ///
1792     /// ```
1793     /// let s = "this is old";
1794     /// assert_eq!(s, s.replacen("cookie monster", "little lamb", 10));
1795     /// ```
1796     #[stable(feature = "str_replacen", since = "1.16.0")]
1797     pub fn replacen<'a, P: Pattern<'a>>(&'a self, pat: P, to: &str, count: usize) -> String {
1798         // Hope to reduce the times of re-allocation
1799         let mut result = String::with_capacity(32);
1800         let mut last_end = 0;
1801         for (start, part) in self.match_indices(pat).take(count) {
1802             result.push_str(unsafe { self.slice_unchecked(last_end, start) });
1803             result.push_str(to);
1804             last_end = start + part.len();
1805         }
1806         result.push_str(unsafe { self.slice_unchecked(last_end, self.len()) });
1807         result
1808     }
1809
1810     /// Returns the lowercase equivalent of this string slice, as a new [`String`].
1811     ///
1812     /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property
1813     /// `Lowercase`.
1814     ///
1815     /// Since some characters can expand into multiple characters when changing
1816     /// the case, this function returns a [`String`] instead of modifying the
1817     /// parameter in-place.
1818     ///
1819     /// [`String`]: string/struct.String.html
1820     ///
1821     /// # Examples
1822     ///
1823     /// Basic usage:
1824     ///
1825     /// ```
1826     /// let s = "HELLO";
1827     ///
1828     /// assert_eq!("hello", s.to_lowercase());
1829     /// ```
1830     ///
1831     /// A tricky example, with sigma:
1832     ///
1833     /// ```
1834     /// let sigma = "Σ";
1835     ///
1836     /// assert_eq!("σ", sigma.to_lowercase());
1837     ///
1838     /// // but at the end of a word, it's ς, not σ:
1839     /// let odysseus = "ὈΔΥΣΣΕΎΣ";
1840     ///
1841     /// assert_eq!("ὀδυσσεύς", odysseus.to_lowercase());
1842     /// ```
1843     ///
1844     /// Languages without case are not changed:
1845     ///
1846     /// ```
1847     /// let new_year = "农历新年";
1848     ///
1849     /// assert_eq!(new_year, new_year.to_lowercase());
1850     /// ```
1851     #[stable(feature = "unicode_case_mapping", since = "1.2.0")]
1852     pub fn to_lowercase(&self) -> String {
1853         let mut s = String::with_capacity(self.len());
1854         for (i, c) in self[..].char_indices() {
1855             if c == 'Σ' {
1856                 // Σ maps to σ, except at the end of a word where it maps to ς.
1857                 // This is the only conditional (contextual) but language-independent mapping
1858                 // in `SpecialCasing.txt`,
1859                 // so hard-code it rather than have a generic "condition" mechanism.
1860                 // See https://github.com/rust-lang/rust/issues/26035
1861                 map_uppercase_sigma(self, i, &mut s)
1862             } else {
1863                 s.extend(c.to_lowercase());
1864             }
1865         }
1866         return s;
1867
1868         fn map_uppercase_sigma(from: &str, i: usize, to: &mut String) {
1869             // See http://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992
1870             // for the definition of `Final_Sigma`.
1871             debug_assert!('Σ'.len_utf8() == 2);
1872             let is_word_final = case_ignoreable_then_cased(from[..i].chars().rev()) &&
1873                                 !case_ignoreable_then_cased(from[i + 2..].chars());
1874             to.push_str(if is_word_final { "ς" } else { "σ" });
1875         }
1876
1877         fn case_ignoreable_then_cased<I: Iterator<Item = char>>(iter: I) -> bool {
1878             use std_unicode::derived_property::{Cased, Case_Ignorable};
1879             match iter.skip_while(|&c| Case_Ignorable(c)).next() {
1880                 Some(c) => Cased(c),
1881                 None => false,
1882             }
1883         }
1884     }
1885
1886     /// Returns the uppercase equivalent of this string slice, as a new [`String`].
1887     ///
1888     /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property
1889     /// `Uppercase`.
1890     ///
1891     /// Since some characters can expand into multiple characters when changing
1892     /// the case, this function returns a [`String`] instead of modifying the
1893     /// parameter in-place.
1894     ///
1895     /// [`String`]: string/struct.String.html
1896     ///
1897     /// # Examples
1898     ///
1899     /// Basic usage:
1900     ///
1901     /// ```
1902     /// let s = "hello";
1903     ///
1904     /// assert_eq!("HELLO", s.to_uppercase());
1905     /// ```
1906     ///
1907     /// Scripts without case are not changed:
1908     ///
1909     /// ```
1910     /// let new_year = "农历新年";
1911     ///
1912     /// assert_eq!(new_year, new_year.to_uppercase());
1913     /// ```
1914     #[stable(feature = "unicode_case_mapping", since = "1.2.0")]
1915     pub fn to_uppercase(&self) -> String {
1916         let mut s = String::with_capacity(self.len());
1917         s.extend(self.chars().flat_map(|c| c.to_uppercase()));
1918         return s;
1919     }
1920
1921     /// Escapes each char in `s` with [`char::escape_debug`].
1922     ///
1923     /// [`char::escape_debug`]: primitive.char.html#method.escape_debug
1924     #[unstable(feature = "str_escape",
1925                reason = "return type may change to be an iterator",
1926                issue = "27791")]
1927     pub fn escape_debug(&self) -> String {
1928         self.chars().flat_map(|c| c.escape_debug()).collect()
1929     }
1930
1931     /// Escapes each char in `s` with [`char::escape_default`].
1932     ///
1933     /// [`char::escape_default`]: primitive.char.html#method.escape_default
1934     #[unstable(feature = "str_escape",
1935                reason = "return type may change to be an iterator",
1936                issue = "27791")]
1937     pub fn escape_default(&self) -> String {
1938         self.chars().flat_map(|c| c.escape_default()).collect()
1939     }
1940
1941     /// Escapes each char in `s` with [`char::escape_unicode`].
1942     ///
1943     /// [`char::escape_unicode`]: primitive.char.html#method.escape_unicode
1944     #[unstable(feature = "str_escape",
1945                reason = "return type may change to be an iterator",
1946                issue = "27791")]
1947     pub fn escape_unicode(&self) -> String {
1948         self.chars().flat_map(|c| c.escape_unicode()).collect()
1949     }
1950
1951     /// Converts a [`Box<str>`] into a [`String`] without copying or allocating.
1952     ///
1953     /// [`String`]: string/struct.String.html
1954     /// [`Box<str>`]: boxed/struct.Box.html
1955     ///
1956     /// # Examples
1957     ///
1958     /// Basic usage:
1959     ///
1960     /// ```
1961     /// let string = String::from("birthday gift");
1962     /// let boxed_str = string.clone().into_boxed_str();
1963     ///
1964     /// assert_eq!(boxed_str.into_string(), string);
1965     /// ```
1966     #[stable(feature = "box_str", since = "1.4.0")]
1967     pub fn into_string(self: Box<str>) -> String {
1968         unsafe {
1969             let slice = mem::transmute::<Box<str>, Box<[u8]>>(self);
1970             String::from_utf8_unchecked(slice.into_vec())
1971         }
1972     }
1973
1974     /// Create a [`String`] by repeating a string `n` times.
1975     ///
1976     /// [`String`]: string/struct.String.html
1977     ///
1978     /// # Examples
1979     ///
1980     /// Basic usage:
1981     ///
1982     /// ```
1983     /// assert_eq!("abc".repeat(4), String::from("abcabcabcabc"));
1984     /// ```
1985     #[stable(feature = "repeat_str", since = "1.16.0")]
1986     pub fn repeat(&self, n: usize) -> String {
1987         let mut s = String::with_capacity(self.len() * n);
1988         s.extend((0..n).map(|_| self));
1989         s
1990     }
1991 }
1992
1993 /// Converts a boxed slice of bytes to a boxed string slice without checking
1994 /// that the string contains valid UTF-8.
1995 #[stable(feature = "str_box_extras", since = "1.20.0")]
1996 pub unsafe fn from_boxed_utf8_unchecked(v: Box<[u8]>) -> Box<str> {
1997     mem::transmute(v)
1998 }