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