src/libcollections/str.rs

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