src/libcore/str/mod.rs

   1 // ignore-tidy-filelength
   2 // ignore-tidy-undocumented-unsafe
   3
   4 //! String manipulation.
   5 //!
   6 //! For more details, see the `std::str` module.
   7
   8 #![stable(feature = "rust1", since = "1.0.0")]
   9
  10 use self::pattern::Pattern;
  11 use self::pattern::{DoubleEndedSearcher, ReverseSearcher, SearchStep, Searcher};
  12
  13 use crate::char;
  14 use crate::fmt::{self, Write};
  15 use crate::iter::{Chain, FlatMap, Flatten};
  16 use crate::iter::{Cloned, Filter, FusedIterator, Map, TrustedLen, TrustedRandomAccess};
  17 use crate::mem;
  18 use crate::ops::Try;
  19 use crate::option;
  20 use crate::slice::{self, SliceIndex, Split as SliceSplit};
  21
  22 pub mod pattern;
  23
  24 #[unstable(feature = "str_internals", issue = "none")]
  25 #[allow(missing_docs)]
  26 pub mod lossy;
  27
  28 /// Parse a value from a string
  29 ///
  30 /// `FromStr`'s [`from_str`] method is often used implicitly, through
  31 /// [`str`]'s [`parse`] method. See [`parse`]'s documentation for examples.
  32 ///
  33 /// [`from_str`]: #tymethod.from_str
  34 /// [`str`]: ../../std/primitive.str.html
  35 /// [`parse`]: ../../std/primitive.str.html#method.parse
  36 ///
  37 /// `FromStr` does not have a lifetime parameter, and so you can only parse types
  38 /// that do not contain a lifetime parameter themselves. In other words, you can
  39 /// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that
  40 /// contains an `i32`, but not one that contains an `&i32`.
  41 ///
  42 /// # Examples
  43 ///
  44 /// Basic implementation of `FromStr` on an example `Point` type:
  45 ///
  46 /// ```
  47 /// use std::str::FromStr;
  48 /// use std::num::ParseIntError;
  49 ///
  50 /// #[derive(Debug, PartialEq)]
  51 /// struct Point {
  52 ///     x: i32,
  53 ///     y: i32
  54 /// }
  55 ///
  56 /// impl FromStr for Point {
  57 ///     type Err = ParseIntError;
  58 ///
  59 ///     fn from_str(s: &str) -> Result<Self, Self::Err> {
  60 ///         let coords: Vec<&str> = s.trim_matches(|p| p == '(' || p == ')' )
  61 ///                                  .split(',')
  62 ///                                  .collect();
  63 ///
  64 ///         let x_fromstr = coords[0].parse::<i32>()?;
  65 ///         let y_fromstr = coords[1].parse::<i32>()?;
  66 ///
  67 ///         Ok(Point { x: x_fromstr, y: y_fromstr })
  68 ///     }
  69 /// }
  70 ///
  71 /// let p = Point::from_str("(1,2)");
  72 /// assert_eq!(p.unwrap(), Point{ x: 1, y: 2} )
  73 /// ```
  74 #[stable(feature = "rust1", since = "1.0.0")]
  75 pub trait FromStr: Sized {
  76     /// The associated error which can be returned from parsing.
  77     #[stable(feature = "rust1", since = "1.0.0")]
  78     type Err;
  79
  80     /// Parses a string `s` to return a value of this type.
  81     ///
  82     /// If parsing succeeds, return the value inside [`Ok`], otherwise
  83     /// when the string is ill-formatted return an error specific to the
  84     /// inside [`Err`]. The error type is specific to implementation of the trait.
  85     ///
  86     /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
  87     /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
  88     ///
  89     /// # Examples
  90     ///
  91     /// Basic usage with [`i32`][ithirtytwo], a type that implements `FromStr`:
  92     ///
  93     /// [ithirtytwo]: ../../std/primitive.i32.html
  94     ///
  95     /// ```
  96     /// use std::str::FromStr;
  97     ///
  98     /// let s = "5";
  99     /// let x = i32::from_str(s).unwrap();
 100     ///
 101     /// assert_eq!(5, x);
 102     /// ```
 103     #[stable(feature = "rust1", since = "1.0.0")]
 104     fn from_str(s: &str) -> Result<Self, Self::Err>;
 105 }
 106
 107 #[stable(feature = "rust1", since = "1.0.0")]
 108 impl FromStr for bool {
 109     type Err = ParseBoolError;
 110
 111     /// Parse a `bool` from a string.
 112     ///
 113     /// Yields a `Result<bool, ParseBoolError>`, because `s` may or may not
 114     /// actually be parseable.
 115     ///
 116     /// # Examples
 117     ///
 118     /// ```
 119     /// use std::str::FromStr;
 120     ///
 121     /// assert_eq!(FromStr::from_str("true"), Ok(true));
 122     /// assert_eq!(FromStr::from_str("false"), Ok(false));
 123     /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
 124     /// ```
 125     ///
 126     /// Note, in many cases, the `.parse()` method on `str` is more proper.
 127     ///
 128     /// ```
 129     /// assert_eq!("true".parse(), Ok(true));
 130     /// assert_eq!("false".parse(), Ok(false));
 131     /// assert!("not even a boolean".parse::<bool>().is_err());
 132     /// ```
 133     #[inline]
 134     fn from_str(s: &str) -> Result<bool, ParseBoolError> {
 135         match s {
 136             "true" => Ok(true),
 137             "false" => Ok(false),
 138             _ => Err(ParseBoolError { _priv: () }),
 139         }
 140     }
 141 }
 142
 143 /// An error returned when parsing a `bool` using [`from_str`] fails
 144 ///
 145 /// [`from_str`]: ../../std/primitive.bool.html#method.from_str
 146 #[derive(Debug, Clone, PartialEq, Eq)]
 147 #[stable(feature = "rust1", since = "1.0.0")]
 148 pub struct ParseBoolError {
 149     _priv: (),
 150 }
 151
 152 #[stable(feature = "rust1", since = "1.0.0")]
 153 impl fmt::Display for ParseBoolError {
 154     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 155         "provided string was not `true` or `false`".fmt(f)
 156     }
 157 }
 158
 159 /*
 160 Section: Creating a string
 161 */
 162
 163 /// Errors which can occur when attempting to interpret a sequence of [`u8`]
 164 /// as a string.
 165 ///
 166 /// [`u8`]: ../../std/primitive.u8.html
 167 ///
 168 /// As such, the `from_utf8` family of functions and methods for both [`String`]s
 169 /// and [`&str`]s make use of this error, for example.
 170 ///
 171 /// [`String`]: ../../std/string/struct.String.html#method.from_utf8
 172 /// [`&str`]: ../../std/str/fn.from_utf8.html
 173 ///
 174 /// # Examples
 175 ///
 176 /// This error type’s methods can be used to create functionality
 177 /// similar to `String::from_utf8_lossy` without allocating heap memory:
 178 ///
 179 /// ```
 180 /// fn from_utf8_lossy<F>(mut input: &[u8], mut push: F) where F: FnMut(&str) {
 181 ///     loop {
 182 ///         match std::str::from_utf8(input) {
 183 ///             Ok(valid) => {
 184 ///                 push(valid);
 185 ///                 break
 186 ///             }
 187 ///             Err(error) => {
 188 ///                 let (valid, after_valid) = input.split_at(error.valid_up_to());
 189 ///                 unsafe {
 190 ///                     push(std::str::from_utf8_unchecked(valid))
 191 ///                 }
 192 ///                 push("\u{FFFD}");
 193 ///
 194 ///                 if let Some(invalid_sequence_length) = error.error_len() {
 195 ///                     input = &after_valid[invalid_sequence_length..]
 196 ///                 } else {
 197 ///                     break
 198 ///                 }
 199 ///             }
 200 ///         }
 201 ///     }
 202 /// }
 203 /// ```
 204 #[derive(Copy, Eq, PartialEq, Clone, Debug)]
 205 #[stable(feature = "rust1", since = "1.0.0")]
 206 pub struct Utf8Error {
 207     valid_up_to: usize,
 208     error_len: Option<u8>,
 209 }
 210
 211 impl Utf8Error {
 212     /// Returns the index in the given string up to which valid UTF-8 was
 213     /// verified.
 214     ///
 215     /// It is the maximum index such that `from_utf8(&input[..index])`
 216     /// would return `Ok(_)`.
 217     ///
 218     /// # Examples
 219     ///
 220     /// Basic usage:
 221     ///
 222     /// ```
 223     /// use std::str;
 224     ///
 225     /// // some invalid bytes, in a vector
 226     /// let sparkle_heart = vec![0, 159, 146, 150];
 227     ///
 228     /// // std::str::from_utf8 returns a Utf8Error
 229     /// let error = str::from_utf8(&sparkle_heart).unwrap_err();
 230     ///
 231     /// // the second byte is invalid here
 232     /// assert_eq!(1, error.valid_up_to());
 233     /// ```
 234     #[stable(feature = "utf8_error", since = "1.5.0")]
 235     pub fn valid_up_to(&self) -> usize {
 236         self.valid_up_to
 237     }
 238
 239     /// Provides more information about the failure:
 240     ///
 241     /// * `None`: the end of the input was reached unexpectedly.
 242     ///   `self.valid_up_to()` is 1 to 3 bytes from the end of the input.
 243     ///   If a byte stream (such as a file or a network socket) is being decoded incrementally,
 244     ///   this could be a valid `char` whose UTF-8 byte sequence is spanning multiple chunks.
 245     ///
 246     /// * `Some(len)`: an unexpected byte was encountered.
 247     ///   The length provided is that of the invalid byte sequence
 248     ///   that starts at the index given by `valid_up_to()`.
 249     ///   Decoding should resume after that sequence
 250     ///   (after inserting a [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]) in case of
 251     ///   lossy decoding.
 252     ///
 253     /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html
 254     #[stable(feature = "utf8_error_error_len", since = "1.20.0")]
 255     pub fn error_len(&self) -> Option<usize> {
 256         self.error_len.map(|len| len as usize)
 257     }
 258 }
 259
 260 /// Converts a slice of bytes to a string slice.
 261 ///
 262 /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
 263 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
 264 /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
 265 /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
 266 /// UTF-8, and then does the conversion.
 267 ///
 268 /// [`&str`]: ../../std/primitive.str.html
 269 /// [`u8`]: ../../std/primitive.u8.html
 270 /// [byteslice]: ../../std/primitive.slice.html
 271 ///
 272 /// If you are sure that the byte slice is valid UTF-8, and you don't want to
 273 /// incur the overhead of the validity check, there is an unsafe version of
 274 /// this function, [`from_utf8_unchecked`][fromutf8u], which has the same
 275 /// behavior but skips the check.
 276 ///
 277 /// [fromutf8u]: fn.from_utf8_unchecked.html
 278 ///
 279 /// If you need a `String` instead of a `&str`, consider
 280 /// [`String::from_utf8`][string].
 281 ///
 282 /// [string]: ../../std/string/struct.String.html#method.from_utf8
 283 ///
 284 /// Because you can stack-allocate a `[u8; N]`, and you can take a
 285 /// [`&[u8]`][byteslice] of it, this function is one way to have a
 286 /// stack-allocated string. There is an example of this in the
 287 /// examples section below.
 288 ///
 289 /// [byteslice]: ../../std/primitive.slice.html
 290 ///
 291 /// # Errors
 292 ///
 293 /// Returns `Err` if the slice is not UTF-8 with a description as to why the
 294 /// provided slice is not UTF-8.
 295 ///
 296 /// # Examples
 297 ///
 298 /// Basic usage:
 299 ///
 300 /// ```
 301 /// use std::str;
 302 ///
 303 /// // some bytes, in a vector
 304 /// let sparkle_heart = vec![240, 159, 146, 150];
 305 ///
 306 /// // We know these bytes are valid, so just use `unwrap()`.
 307 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
 308 ///
 309 /// assert_eq!("💖", sparkle_heart);
 310 /// ```
 311 ///
 312 /// Incorrect bytes:
 313 ///
 314 /// ```
 315 /// use std::str;
 316 ///
 317 /// // some invalid bytes, in a vector
 318 /// let sparkle_heart = vec![0, 159, 146, 150];
 319 ///
 320 /// assert!(str::from_utf8(&sparkle_heart).is_err());
 321 /// ```
 322 ///
 323 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
 324 /// errors that can be returned.
 325 ///
 326 /// [error]: struct.Utf8Error.html
 327 ///
 328 /// A "stack allocated string":
 329 ///
 330 /// ```
 331 /// use std::str;
 332 ///
 333 /// // some bytes, in a stack-allocated array
 334 /// let sparkle_heart = [240, 159, 146, 150];
 335 ///
 336 /// // We know these bytes are valid, so just use `unwrap()`.
 337 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
 338 ///
 339 /// assert_eq!("💖", sparkle_heart);
 340 /// ```
 341 #[stable(feature = "rust1", since = "1.0.0")]
 342 pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
 343     run_utf8_validation(v)?;
 344     Ok(unsafe { from_utf8_unchecked(v) })
 345 }
 346
 347 /// Converts a mutable slice of bytes to a mutable string slice.
 348 ///
 349 /// # Examples
 350 ///
 351 /// Basic usage:
 352 ///
 353 /// ```
 354 /// use std::str;
 355 ///
 356 /// // "Hello, Rust!" as a mutable vector
 357 /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
 358 ///
 359 /// // As we know these bytes are valid, we can use `unwrap()`
 360 /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
 361 ///
 362 /// assert_eq!("Hello, Rust!", outstr);
 363 /// ```
 364 ///
 365 /// Incorrect bytes:
 366 ///
 367 /// ```
 368 /// use std::str;
 369 ///
 370 /// // Some invalid bytes in a mutable vector
 371 /// let mut invalid = vec![128, 223];
 372 ///
 373 /// assert!(str::from_utf8_mut(&mut invalid).is_err());
 374 /// ```
 375 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
 376 /// errors that can be returned.
 377 ///
 378 /// [error]: struct.Utf8Error.html
 379 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 380 pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
 381     run_utf8_validation(v)?;
 382     Ok(unsafe { from_utf8_unchecked_mut(v) })
 383 }
 384
 385 /// Converts a slice of bytes to a string slice without checking
 386 /// that the string contains valid UTF-8.
 387 ///
 388 /// See the safe version, [`from_utf8`][fromutf8], for more information.
 389 ///
 390 /// [fromutf8]: fn.from_utf8.html
 391 ///
 392 /// # Safety
 393 ///
 394 /// This function is unsafe because it does not check that the bytes passed to
 395 /// it are valid UTF-8. If this constraint is violated, undefined behavior
 396 /// results, as the rest of Rust assumes that [`&str`]s are valid UTF-8.
 397 ///
 398 /// [`&str`]: ../../std/primitive.str.html
 399 ///
 400 /// # Examples
 401 ///
 402 /// Basic usage:
 403 ///
 404 /// ```
 405 /// use std::str;
 406 ///
 407 /// // some bytes, in a vector
 408 /// let sparkle_heart = vec![240, 159, 146, 150];
 409 ///
 410 /// let sparkle_heart = unsafe {
 411 ///     str::from_utf8_unchecked(&sparkle_heart)
 412 /// };
 413 ///
 414 /// assert_eq!("💖", sparkle_heart);
 415 /// ```
 416 #[inline]
 417 #[stable(feature = "rust1", since = "1.0.0")]
 418 pub unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
 419     &*(v as *const [u8] as *const str)
 420 }
 421
 422 /// Converts a slice of bytes to a string slice without checking
 423 /// that the string contains valid UTF-8; mutable version.
 424 ///
 425 /// See the immutable version, [`from_utf8_unchecked()`][fromutf8], for more information.
 426 ///
 427 /// [fromutf8]: fn.from_utf8_unchecked.html
 428 ///
 429 /// # Examples
 430 ///
 431 /// Basic usage:
 432 ///
 433 /// ```
 434 /// use std::str;
 435 ///
 436 /// let mut heart = vec![240, 159, 146, 150];
 437 /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
 438 ///
 439 /// assert_eq!("💖", heart);
 440 /// ```
 441 #[inline]
 442 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 443 pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
 444     &mut *(v as *mut [u8] as *mut str)
 445 }
 446
 447 #[stable(feature = "rust1", since = "1.0.0")]
 448 impl fmt::Display for Utf8Error {
 449     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 450         if let Some(error_len) = self.error_len {
 451             write!(
 452                 f,
 453                 "invalid utf-8 sequence of {} bytes from index {}",
 454                 error_len, self.valid_up_to
 455             )
 456         } else {
 457             write!(f, "incomplete utf-8 byte sequence from index {}", self.valid_up_to)
 458         }
 459     }
 460 }
 461
 462 /*
 463 Section: Iterators
 464 */
 465
 466 /// An iterator over the [`char`]s of a string slice.
 467 ///
 468 /// [`char`]: ../../std/primitive.char.html
 469 ///
 470 /// This struct is created by the [`chars`] method on [`str`].
 471 /// See its documentation for more.
 472 ///
 473 /// [`chars`]: ../../std/primitive.str.html#method.chars
 474 /// [`str`]: ../../std/primitive.str.html
 475 #[derive(Clone)]
 476 #[stable(feature = "rust1", since = "1.0.0")]
 477 pub struct Chars<'a> {
 478     iter: slice::Iter<'a, u8>,
 479 }
 480
 481 /// Returns the initial codepoint accumulator for the first byte.
 482 /// The first byte is special, only want bottom 5 bits for width 2, 4 bits
 483 /// for width 3, and 3 bits for width 4.
 484 #[inline]
 485 fn utf8_first_byte(byte: u8, width: u32) -> u32 {
 486     (byte & (0x7F >> width)) as u32
 487 }
 488
 489 /// Returns the value of `ch` updated with continuation byte `byte`.
 490 #[inline]
 491 fn utf8_acc_cont_byte(ch: u32, byte: u8) -> u32 {
 492     (ch << 6) | (byte & CONT_MASK) as u32
 493 }
 494
 495 /// Checks whether the byte is a UTF-8 continuation byte (i.e., starts with the
 496 /// bits `10`).
 497 #[inline]
 498 fn utf8_is_cont_byte(byte: u8) -> bool {
 499     (byte & !CONT_MASK) == TAG_CONT_U8
 500 }
 501
 502 #[inline]
 503 fn unwrap_or_0(opt: Option<&u8>) -> u8 {
 504     match opt {
 505         Some(&byte) => byte,
 506         None => 0,
 507     }
 508 }
 509
 510 /// Reads the next code point out of a byte iterator (assuming a
 511 /// UTF-8-like encoding).
 512 #[unstable(feature = "str_internals", issue = "none")]
 513 #[inline]
 514 pub fn next_code_point<'a, I: Iterator<Item = &'a u8>>(bytes: &mut I) -> Option<u32> {
 515     // Decode UTF-8
 516     let x = *bytes.next()?;
 517     if x < 128 {
 518         return Some(x as u32);
 519     }
 520
 521     // Multibyte case follows
 522     // Decode from a byte combination out of: [[[x y] z] w]
 523     // NOTE: Performance is sensitive to the exact formulation here
 524     let init = utf8_first_byte(x, 2);
 525     let y = unwrap_or_0(bytes.next());
 526     let mut ch = utf8_acc_cont_byte(init, y);
 527     if x >= 0xE0 {
 528         // [[x y z] w] case
 529         // 5th bit in 0xE0 .. 0xEF is always clear, so `init` is still valid
 530         let z = unwrap_or_0(bytes.next());
 531         let y_z = utf8_acc_cont_byte((y & CONT_MASK) as u32, z);
 532         ch = init << 12 | y_z;
 533         if x >= 0xF0 {
 534             // [x y z w] case
 535             // use only the lower 3 bits of `init`
 536             let w = unwrap_or_0(bytes.next());
 537             ch = (init & 7) << 18 | utf8_acc_cont_byte(y_z, w);
 538         }
 539     }
 540
 541     Some(ch)
 542 }
 543
 544 /// Reads the last code point out of a byte iterator (assuming a
 545 /// UTF-8-like encoding).
 546 #[inline]
 547 fn next_code_point_reverse<'a, I>(bytes: &mut I) -> Option<u32>
 548 where
 549     I: DoubleEndedIterator<Item = &'a u8>,
 550 {
 551     // Decode UTF-8
 552     let w = match *bytes.next_back()? {
 553         next_byte if next_byte < 128 => return Some(next_byte as u32),
 554         back_byte => back_byte,
 555     };
 556
 557     // Multibyte case follows
 558     // Decode from a byte combination out of: [x [y [z w]]]
 559     let mut ch;
 560     let z = unwrap_or_0(bytes.next_back());
 561     ch = utf8_first_byte(z, 2);
 562     if utf8_is_cont_byte(z) {
 563         let y = unwrap_or_0(bytes.next_back());
 564         ch = utf8_first_byte(y, 3);
 565         if utf8_is_cont_byte(y) {
 566             let x = unwrap_or_0(bytes.next_back());
 567             ch = utf8_first_byte(x, 4);
 568             ch = utf8_acc_cont_byte(ch, y);
 569         }
 570         ch = utf8_acc_cont_byte(ch, z);
 571     }
 572     ch = utf8_acc_cont_byte(ch, w);
 573
 574     Some(ch)
 575 }
 576
 577 #[stable(feature = "rust1", since = "1.0.0")]
 578 impl<'a> Iterator for Chars<'a> {
 579     type Item = char;
 580
 581     #[inline]
 582     fn next(&mut self) -> Option<char> {
 583         next_code_point(&mut self.iter).map(|ch| {
 584             // str invariant says `ch` is a valid Unicode Scalar Value
 585             unsafe { char::from_u32_unchecked(ch) }
 586         })
 587     }
 588
 589     #[inline]
 590     fn count(self) -> usize {
 591         // length in `char` is equal to the number of non-continuation bytes
 592         let bytes_len = self.iter.len();
 593         let mut cont_bytes = 0;
 594         for &byte in self.iter {
 595             cont_bytes += utf8_is_cont_byte(byte) as usize;
 596         }
 597         bytes_len - cont_bytes
 598     }
 599
 600     #[inline]
 601     fn size_hint(&self) -> (usize, Option<usize>) {
 602         let len = self.iter.len();
 603         // `(len + 3)` can't overflow, because we know that the `slice::Iter`
 604         // belongs to a slice in memory which has a maximum length of
 605         // `isize::MAX` (that's well below `usize::MAX`).
 606         ((len + 3) / 4, Some(len))
 607     }
 608
 609     #[inline]
 610     fn last(mut self) -> Option<char> {
 611         // No need to go through the entire string.
 612         self.next_back()
 613     }
 614 }
 615
 616 #[stable(feature = "chars_debug_impl", since = "1.38.0")]
 617 impl fmt::Debug for Chars<'_> {
 618     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 619         write!(f, "Chars(")?;
 620         f.debug_list().entries(self.clone()).finish()?;
 621         write!(f, ")")?;
 622         Ok(())
 623     }
 624 }
 625
 626 #[stable(feature = "rust1", since = "1.0.0")]
 627 impl<'a> DoubleEndedIterator for Chars<'a> {
 628     #[inline]
 629     fn next_back(&mut self) -> Option<char> {
 630         next_code_point_reverse(&mut self.iter).map(|ch| {
 631             // str invariant says `ch` is a valid Unicode Scalar Value
 632             unsafe { char::from_u32_unchecked(ch) }
 633         })
 634     }
 635 }
 636
 637 #[stable(feature = "fused", since = "1.26.0")]
 638 impl FusedIterator for Chars<'_> {}
 639
 640 impl<'a> Chars<'a> {
 641     /// Views the underlying data as a subslice of the original data.
 642     ///
 643     /// This has the same lifetime as the original slice, and so the
 644     /// iterator can continue to be used while this exists.
 645     ///
 646     /// # Examples
 647     ///
 648     /// ```
 649     /// let mut chars = "abc".chars();
 650     ///
 651     /// assert_eq!(chars.as_str(), "abc");
 652     /// chars.next();
 653     /// assert_eq!(chars.as_str(), "bc");
 654     /// chars.next();
 655     /// chars.next();
 656     /// assert_eq!(chars.as_str(), "");
 657     /// ```
 658     #[stable(feature = "iter_to_slice", since = "1.4.0")]
 659     #[inline]
 660     pub fn as_str(&self) -> &'a str {
 661         unsafe { from_utf8_unchecked(self.iter.as_slice()) }
 662     }
 663 }
 664
 665 /// An iterator over the [`char`]s of a string slice, and their positions.
 666 ///
 667 /// [`char`]: ../../std/primitive.char.html
 668 ///
 669 /// This struct is created by the [`char_indices`] method on [`str`].
 670 /// See its documentation for more.
 671 ///
 672 /// [`char_indices`]: ../../std/primitive.str.html#method.char_indices
 673 /// [`str`]: ../../std/primitive.str.html
 674 #[derive(Clone, Debug)]
 675 #[stable(feature = "rust1", since = "1.0.0")]
 676 pub struct CharIndices<'a> {
 677     front_offset: usize,
 678     iter: Chars<'a>,
 679 }
 680
 681 #[stable(feature = "rust1", since = "1.0.0")]
 682 impl<'a> Iterator for CharIndices<'a> {
 683     type Item = (usize, char);
 684
 685     #[inline]
 686     fn next(&mut self) -> Option<(usize, char)> {
 687         let pre_len = self.iter.iter.len();
 688         match self.iter.next() {
 689             None => None,
 690             Some(ch) => {
 691                 let index = self.front_offset;
 692                 let len = self.iter.iter.len();
 693                 self.front_offset += pre_len - len;
 694                 Some((index, ch))
 695             }
 696         }
 697     }
 698
 699     #[inline]
 700     fn count(self) -> usize {
 701         self.iter.count()
 702     }
 703
 704     #[inline]
 705     fn size_hint(&self) -> (usize, Option<usize>) {
 706         self.iter.size_hint()
 707     }
 708
 709     #[inline]
 710     fn last(mut self) -> Option<(usize, char)> {
 711         // No need to go through the entire string.
 712         self.next_back()
 713     }
 714 }
 715
 716 #[stable(feature = "rust1", since = "1.0.0")]
 717 impl<'a> DoubleEndedIterator for CharIndices<'a> {
 718     #[inline]
 719     fn next_back(&mut self) -> Option<(usize, char)> {
 720         self.iter.next_back().map(|ch| {
 721             let index = self.front_offset + self.iter.iter.len();
 722             (index, ch)
 723         })
 724     }
 725 }
 726
 727 #[stable(feature = "fused", since = "1.26.0")]
 728 impl FusedIterator for CharIndices<'_> {}
 729
 730 impl<'a> CharIndices<'a> {
 731     /// Views the underlying data as a subslice of the original data.
 732     ///
 733     /// This has the same lifetime as the original slice, and so the
 734     /// iterator can continue to be used while this exists.
 735     #[stable(feature = "iter_to_slice", since = "1.4.0")]
 736     #[inline]
 737     pub fn as_str(&self) -> &'a str {
 738         self.iter.as_str()
 739     }
 740 }
 741
 742 /// An iterator over the bytes of a string slice.
 743 ///
 744 /// This struct is created by the [`bytes`] method on [`str`].
 745 /// See its documentation for more.
 746 ///
 747 /// [`bytes`]: ../../std/primitive.str.html#method.bytes
 748 /// [`str`]: ../../std/primitive.str.html
 749 #[stable(feature = "rust1", since = "1.0.0")]
 750 #[derive(Clone, Debug)]
 751 pub struct Bytes<'a>(Cloned<slice::Iter<'a, u8>>);
 752
 753 #[stable(feature = "rust1", since = "1.0.0")]
 754 impl Iterator for Bytes<'_> {
 755     type Item = u8;
 756
 757     #[inline]
 758     fn next(&mut self) -> Option<u8> {
 759         self.0.next()
 760     }
 761
 762     #[inline]
 763     fn size_hint(&self) -> (usize, Option<usize>) {
 764         self.0.size_hint()
 765     }
 766
 767     #[inline]
 768     fn count(self) -> usize {
 769         self.0.count()
 770     }
 771
 772     #[inline]
 773     fn last(self) -> Option<Self::Item> {
 774         self.0.last()
 775     }
 776
 777     #[inline]
 778     fn nth(&mut self, n: usize) -> Option<Self::Item> {
 779         self.0.nth(n)
 780     }
 781
 782     #[inline]
 783     fn all<F>(&mut self, f: F) -> bool
 784     where
 785         F: FnMut(Self::Item) -> bool,
 786     {
 787         self.0.all(f)
 788     }
 789
 790     #[inline]
 791     fn any<F>(&mut self, f: F) -> bool
 792     where
 793         F: FnMut(Self::Item) -> bool,
 794     {
 795         self.0.any(f)
 796     }
 797
 798     #[inline]
 799     fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
 800     where
 801         P: FnMut(&Self::Item) -> bool,
 802     {
 803         self.0.find(predicate)
 804     }
 805
 806     #[inline]
 807     fn position<P>(&mut self, predicate: P) -> Option<usize>
 808     where
 809         P: FnMut(Self::Item) -> bool,
 810     {
 811         self.0.position(predicate)
 812     }
 813
 814     #[inline]
 815     fn rposition<P>(&mut self, predicate: P) -> Option<usize>
 816     where
 817         P: FnMut(Self::Item) -> bool,
 818     {
 819         self.0.rposition(predicate)
 820     }
 821 }
 822
 823 #[stable(feature = "rust1", since = "1.0.0")]
 824 impl DoubleEndedIterator for Bytes<'_> {
 825     #[inline]
 826     fn next_back(&mut self) -> Option<u8> {
 827         self.0.next_back()
 828     }
 829
 830     #[inline]
 831     fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
 832         self.0.nth_back(n)
 833     }
 834
 835     #[inline]
 836     fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
 837     where
 838         P: FnMut(&Self::Item) -> bool,
 839     {
 840         self.0.rfind(predicate)
 841     }
 842 }
 843
 844 #[stable(feature = "rust1", since = "1.0.0")]
 845 impl ExactSizeIterator for Bytes<'_> {
 846     #[inline]
 847     fn len(&self) -> usize {
 848         self.0.len()
 849     }
 850
 851     #[inline]
 852     fn is_empty(&self) -> bool {
 853         self.0.is_empty()
 854     }
 855 }
 856
 857 #[stable(feature = "fused", since = "1.26.0")]
 858 impl FusedIterator for Bytes<'_> {}
 859
 860 #[unstable(feature = "trusted_len", issue = "37572")]
 861 unsafe impl TrustedLen for Bytes<'_> {}
 862
 863 #[doc(hidden)]
 864 unsafe impl TrustedRandomAccess for Bytes<'_> {
 865     unsafe fn get_unchecked(&mut self, i: usize) -> u8 {
 866         self.0.get_unchecked(i)
 867     }
 868     fn may_have_side_effect() -> bool {
 869         false
 870     }
 871 }
 872
 873 /// This macro generates a Clone impl for string pattern API
 874 /// wrapper types of the form X<'a, P>
 875 macro_rules! derive_pattern_clone {
 876     (clone $t:ident with |$s:ident| $e:expr) => {
 877         impl<'a, P> Clone for $t<'a, P>
 878         where
 879             P: Pattern<'a, Searcher: Clone>,
 880         {
 881             fn clone(&self) -> Self {
 882                 let $s = self;
 883                 $e
 884             }
 885         }
 886     };
 887 }
 888
 889 /// This macro generates two public iterator structs
 890 /// wrapping a private internal one that makes use of the `Pattern` API.
 891 ///
 892 /// For all patterns `P: Pattern<'a>` the following items will be
 893 /// generated (generics omitted):
 894 ///
 895 /// struct $forward_iterator($internal_iterator);
 896 /// struct $reverse_iterator($internal_iterator);
 897 ///
 898 /// impl Iterator for $forward_iterator
 899 /// { /* internal ends up calling Searcher::next_match() */ }
 900 ///
 901 /// impl DoubleEndedIterator for $forward_iterator
 902 ///       where P::Searcher: DoubleEndedSearcher
 903 /// { /* internal ends up calling Searcher::next_match_back() */ }
 904 ///
 905 /// impl Iterator for $reverse_iterator
 906 ///       where P::Searcher: ReverseSearcher
 907 /// { /* internal ends up calling Searcher::next_match_back() */ }
 908 ///
 909 /// impl DoubleEndedIterator for $reverse_iterator
 910 ///       where P::Searcher: DoubleEndedSearcher
 911 /// { /* internal ends up calling Searcher::next_match() */ }
 912 ///
 913 /// The internal one is defined outside the macro, and has almost the same
 914 /// semantic as a DoubleEndedIterator by delegating to `pattern::Searcher` and
 915 /// `pattern::ReverseSearcher` for both forward and reverse iteration.
 916 ///
 917 /// "Almost", because a `Searcher` and a `ReverseSearcher` for a given
 918 /// `Pattern` might not return the same elements, so actually implementing
 919 /// `DoubleEndedIterator` for it would be incorrect.
 920 /// (See the docs in `str::pattern` for more details)
 921 ///
 922 /// However, the internal struct still represents a single ended iterator from
 923 /// either end, and depending on pattern is also a valid double ended iterator,
 924 /// so the two wrapper structs implement `Iterator`
 925 /// and `DoubleEndedIterator` depending on the concrete pattern type, leading
 926 /// to the complex impls seen above.
 927 macro_rules! generate_pattern_iterators {
 928     {
 929         // Forward iterator
 930         forward:
 931             $(#[$forward_iterator_attribute:meta])*
 932             struct $forward_iterator:ident;
 933
 934         // Reverse iterator
 935         reverse:
 936             $(#[$reverse_iterator_attribute:meta])*
 937             struct $reverse_iterator:ident;
 938
 939         // Stability of all generated items
 940         stability:
 941             $(#[$common_stability_attribute:meta])*
 942
 943         // Internal almost-iterator that is being delegated to
 944         internal:
 945             $internal_iterator:ident yielding ($iterty:ty);
 946
 947         // Kind of delegation - either single ended or double ended
 948         delegate $($t:tt)*
 949     } => {
 950         $(#[$forward_iterator_attribute])*
 951         $(#[$common_stability_attribute])*
 952         pub struct $forward_iterator<'a, P: Pattern<'a>>($internal_iterator<'a, P>);
 953
 954         $(#[$common_stability_attribute])*
 955         impl<'a, P> fmt::Debug for $forward_iterator<'a, P>
 956         where
 957             P: Pattern<'a, Searcher: fmt::Debug>,
 958         {
 959             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 960                 f.debug_tuple(stringify!($forward_iterator))
 961                     .field(&self.0)
 962                     .finish()
 963             }
 964         }
 965
 966         $(#[$common_stability_attribute])*
 967         impl<'a, P: Pattern<'a>> Iterator for $forward_iterator<'a, P> {
 968             type Item = $iterty;
 969
 970             #[inline]
 971             fn next(&mut self) -> Option<$iterty> {
 972                 self.0.next()
 973             }
 974         }
 975
 976         $(#[$common_stability_attribute])*
 977         impl<'a, P> Clone for $forward_iterator<'a, P>
 978         where
 979             P: Pattern<'a, Searcher: Clone>,
 980         {
 981             fn clone(&self) -> Self {
 982                 $forward_iterator(self.0.clone())
 983             }
 984         }
 985
 986         $(#[$reverse_iterator_attribute])*
 987         $(#[$common_stability_attribute])*
 988         pub struct $reverse_iterator<'a, P: Pattern<'a>>($internal_iterator<'a, P>);
 989
 990         $(#[$common_stability_attribute])*
 991         impl<'a, P> fmt::Debug for $reverse_iterator<'a, P>
 992         where
 993             P: Pattern<'a, Searcher: fmt::Debug>,
 994         {
 995             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 996                 f.debug_tuple(stringify!($reverse_iterator))
 997                     .field(&self.0)
 998                     .finish()
 999             }
1000         }
1001
1002         $(#[$common_stability_attribute])*
1003         impl<'a, P> Iterator for $reverse_iterator<'a, P>
1004         where
1005             P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1006         {
1007             type Item = $iterty;
1008
1009             #[inline]
1010             fn next(&mut self) -> Option<$iterty> {
1011                 self.0.next_back()
1012             }
1013         }
1014
1015         $(#[$common_stability_attribute])*
1016         impl<'a, P> Clone for $reverse_iterator<'a, P>
1017         where
1018             P: Pattern<'a, Searcher: Clone>,
1019         {
1020             fn clone(&self) -> Self {
1021                 $reverse_iterator(self.0.clone())
1022             }
1023         }
1024
1025         #[stable(feature = "fused", since = "1.26.0")]
1026         impl<'a, P: Pattern<'a>> FusedIterator for $forward_iterator<'a, P> {}
1027
1028         #[stable(feature = "fused", since = "1.26.0")]
1029         impl<'a, P> FusedIterator for $reverse_iterator<'a, P>
1030         where
1031             P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1032         {}
1033
1034         generate_pattern_iterators!($($t)* with $(#[$common_stability_attribute])*,
1035                                                 $forward_iterator,
1036                                                 $reverse_iterator, $iterty);
1037     };
1038     {
1039         double ended; with $(#[$common_stability_attribute:meta])*,
1040                            $forward_iterator:ident,
1041                            $reverse_iterator:ident, $iterty:ty
1042     } => {
1043         $(#[$common_stability_attribute])*
1044         impl<'a, P> DoubleEndedIterator for $forward_iterator<'a, P>
1045         where
1046             P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1047         {
1048             #[inline]
1049             fn next_back(&mut self) -> Option<$iterty> {
1050                 self.0.next_back()
1051             }
1052         }
1053
1054         $(#[$common_stability_attribute])*
1055         impl<'a, P> DoubleEndedIterator for $reverse_iterator<'a, P>
1056         where
1057             P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1058         {
1059             #[inline]
1060             fn next_back(&mut self) -> Option<$iterty> {
1061                 self.0.next()
1062             }
1063         }
1064     };
1065     {
1066         single ended; with $(#[$common_stability_attribute:meta])*,
1067                            $forward_iterator:ident,
1068                            $reverse_iterator:ident, $iterty:ty
1069     } => {}
1070 }
1071
1072 derive_pattern_clone! {
1073     clone SplitInternal
1074     with |s| SplitInternal { matcher: s.matcher.clone(), ..*s }
1075 }
1076
1077 struct SplitInternal<'a, P: Pattern<'a>> {
1078     start: usize,
1079     end: usize,
1080     matcher: P::Searcher,
1081     allow_trailing_empty: bool,
1082     finished: bool,
1083 }
1084
1085 impl<'a, P> fmt::Debug for SplitInternal<'a, P>
1086 where
1087     P: Pattern<'a, Searcher: fmt::Debug>,
1088 {
1089     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1090         f.debug_struct("SplitInternal")
1091             .field("start", &self.start)
1092             .field("end", &self.end)
1093             .field("matcher", &self.matcher)
1094             .field("allow_trailing_empty", &self.allow_trailing_empty)
1095             .field("finished", &self.finished)
1096             .finish()
1097     }
1098 }
1099
1100 impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
1101     #[inline]
1102     fn get_end(&mut self) -> Option<&'a str> {
1103         if !self.finished && (self.allow_trailing_empty || self.end - self.start > 0) {
1104             self.finished = true;
1105             unsafe {
1106                 let string = self.matcher.haystack().get_unchecked(self.start..self.end);
1107                 Some(string)
1108             }
1109         } else {
1110             None
1111         }
1112     }
1113
1114     #[inline]
1115     fn next(&mut self) -> Option<&'a str> {
1116         if self.finished {
1117             return None;
1118         }
1119
1120         let haystack = self.matcher.haystack();
1121         match self.matcher.next_match() {
1122             Some((a, b)) => unsafe {
1123                 let elt = haystack.get_unchecked(self.start..a);
1124                 self.start = b;
1125                 Some(elt)
1126             },
1127             None => self.get_end(),
1128         }
1129     }
1130
1131     #[inline]
1132     fn next_back(&mut self) -> Option<&'a str>
1133     where
1134         P::Searcher: ReverseSearcher<'a>,
1135     {
1136         if self.finished {
1137             return None;
1138         }
1139
1140         if !self.allow_trailing_empty {
1141             self.allow_trailing_empty = true;
1142             match self.next_back() {
1143                 Some(elt) if !elt.is_empty() => return Some(elt),
1144                 _ => {
1145                     if self.finished {
1146                         return None;
1147                     }
1148                 }
1149             }
1150         }
1151
1152         let haystack = self.matcher.haystack();
1153         match self.matcher.next_match_back() {
1154             Some((a, b)) => unsafe {
1155                 let elt = haystack.get_unchecked(b..self.end);
1156                 self.end = a;
1157                 Some(elt)
1158             },
1159             None => unsafe {
1160                 self.finished = true;
1161                 Some(haystack.get_unchecked(self.start..self.end))
1162             },
1163         }
1164     }
1165 }
1166
1167 generate_pattern_iterators! {
1168     forward:
1169         /// Created with the method [`split`].
1170         ///
1171         /// [`split`]: ../../std/primitive.str.html#method.split
1172         struct Split;
1173     reverse:
1174         /// Created with the method [`rsplit`].
1175         ///
1176         /// [`rsplit`]: ../../std/primitive.str.html#method.rsplit
1177         struct RSplit;
1178     stability:
1179         #[stable(feature = "rust1", since = "1.0.0")]
1180     internal:
1181         SplitInternal yielding (&'a str);
1182     delegate double ended;
1183 }
1184
1185 generate_pattern_iterators! {
1186     forward:
1187         /// Created with the method [`split_terminator`].
1188         ///
1189         /// [`split_terminator`]: ../../std/primitive.str.html#method.split_terminator
1190         struct SplitTerminator;
1191     reverse:
1192         /// Created with the method [`rsplit_terminator`].
1193         ///
1194         /// [`rsplit_terminator`]: ../../std/primitive.str.html#method.rsplit_terminator
1195         struct RSplitTerminator;
1196     stability:
1197         #[stable(feature = "rust1", since = "1.0.0")]
1198     internal:
1199         SplitInternal yielding (&'a str);
1200     delegate double ended;
1201 }
1202
1203 derive_pattern_clone! {
1204     clone SplitNInternal
1205     with |s| SplitNInternal { iter: s.iter.clone(), ..*s }
1206 }
1207
1208 struct SplitNInternal<'a, P: Pattern<'a>> {
1209     iter: SplitInternal<'a, P>,
1210     /// The number of splits remaining
1211     count: usize,
1212 }
1213
1214 impl<'a, P> fmt::Debug for SplitNInternal<'a, P>
1215 where
1216     P: Pattern<'a, Searcher: fmt::Debug>,
1217 {
1218     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1219         f.debug_struct("SplitNInternal")
1220             .field("iter", &self.iter)
1221             .field("count", &self.count)
1222             .finish()
1223     }
1224 }
1225
1226 impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> {
1227     #[inline]
1228     fn next(&mut self) -> Option<&'a str> {
1229         match self.count {
1230             0 => None,
1231             1 => {
1232                 self.count = 0;
1233                 self.iter.get_end()
1234             }
1235             _ => {
1236                 self.count -= 1;
1237                 self.iter.next()
1238             }
1239         }
1240     }
1241
1242     #[inline]
1243     fn next_back(&mut self) -> Option<&'a str>
1244     where
1245         P::Searcher: ReverseSearcher<'a>,
1246     {
1247         match self.count {
1248             0 => None,
1249             1 => {
1250                 self.count = 0;
1251                 self.iter.get_end()
1252             }
1253             _ => {
1254                 self.count -= 1;
1255                 self.iter.next_back()
1256             }
1257         }
1258     }
1259 }
1260
1261 generate_pattern_iterators! {
1262     forward:
1263         /// Created with the method [`splitn`].
1264         ///
1265         /// [`splitn`]: ../../std/primitive.str.html#method.splitn
1266         struct SplitN;
1267     reverse:
1268         /// Created with the method [`rsplitn`].
1269         ///
1270         /// [`rsplitn`]: ../../std/primitive.str.html#method.rsplitn
1271         struct RSplitN;
1272     stability:
1273         #[stable(feature = "rust1", since = "1.0.0")]
1274     internal:
1275         SplitNInternal yielding (&'a str);
1276     delegate single ended;
1277 }
1278
1279 derive_pattern_clone! {
1280     clone MatchIndicesInternal
1281     with |s| MatchIndicesInternal(s.0.clone())
1282 }
1283
1284 struct MatchIndicesInternal<'a, P: Pattern<'a>>(P::Searcher);
1285
1286 impl<'a, P> fmt::Debug for MatchIndicesInternal<'a, P>
1287 where
1288     P: Pattern<'a, Searcher: fmt::Debug>,
1289 {
1290     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1291         f.debug_tuple("MatchIndicesInternal").field(&self.0).finish()
1292     }
1293 }
1294
1295 impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
1296     #[inline]
1297     fn next(&mut self) -> Option<(usize, &'a str)> {
1298         self.0
1299             .next_match()
1300             .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1301     }
1302
1303     #[inline]
1304     fn next_back(&mut self) -> Option<(usize, &'a str)>
1305     where
1306         P::Searcher: ReverseSearcher<'a>,
1307     {
1308         self.0
1309             .next_match_back()
1310             .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1311     }
1312 }
1313
1314 generate_pattern_iterators! {
1315     forward:
1316         /// Created with the method [`match_indices`].
1317         ///
1318         /// [`match_indices`]: ../../std/primitive.str.html#method.match_indices
1319         struct MatchIndices;
1320     reverse:
1321         /// Created with the method [`rmatch_indices`].
1322         ///
1323         /// [`rmatch_indices`]: ../../std/primitive.str.html#method.rmatch_indices
1324         struct RMatchIndices;
1325     stability:
1326         #[stable(feature = "str_match_indices", since = "1.5.0")]
1327     internal:
1328         MatchIndicesInternal yielding ((usize, &'a str));
1329     delegate double ended;
1330 }
1331
1332 derive_pattern_clone! {
1333     clone MatchesInternal
1334     with |s| MatchesInternal(s.0.clone())
1335 }
1336
1337 struct MatchesInternal<'a, P: Pattern<'a>>(P::Searcher);
1338
1339 impl<'a, P> fmt::Debug for MatchesInternal<'a, P>
1340 where
1341     P: Pattern<'a, Searcher: fmt::Debug>,
1342 {
1343     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1344         f.debug_tuple("MatchesInternal").field(&self.0).finish()
1345     }
1346 }
1347
1348 impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
1349     #[inline]
1350     fn next(&mut self) -> Option<&'a str> {
1351         self.0.next_match().map(|(a, b)| unsafe {
1352             // Indices are known to be on utf8 boundaries
1353             self.0.haystack().get_unchecked(a..b)
1354         })
1355     }
1356
1357     #[inline]
1358     fn next_back(&mut self) -> Option<&'a str>
1359     where
1360         P::Searcher: ReverseSearcher<'a>,
1361     {
1362         self.0.next_match_back().map(|(a, b)| unsafe {
1363             // Indices are known to be on utf8 boundaries
1364             self.0.haystack().get_unchecked(a..b)
1365         })
1366     }
1367 }
1368
1369 generate_pattern_iterators! {
1370     forward:
1371         /// Created with the method [`matches`].
1372         ///
1373         /// [`matches`]: ../../std/primitive.str.html#method.matches
1374         struct Matches;
1375     reverse:
1376         /// Created with the method [`rmatches`].
1377         ///
1378         /// [`rmatches`]: ../../std/primitive.str.html#method.rmatches
1379         struct RMatches;
1380     stability:
1381         #[stable(feature = "str_matches", since = "1.2.0")]
1382     internal:
1383         MatchesInternal yielding (&'a str);
1384     delegate double ended;
1385 }
1386
1387 /// An iterator over the lines of a string, as string slices.
1388 ///
1389 /// This struct is created with the [`lines`] method on [`str`].
1390 /// See its documentation for more.
1391 ///
1392 /// [`lines`]: ../../std/primitive.str.html#method.lines
1393 /// [`str`]: ../../std/primitive.str.html
1394 #[stable(feature = "rust1", since = "1.0.0")]
1395 #[derive(Clone, Debug)]
1396 pub struct Lines<'a>(Map<SplitTerminator<'a, char>, LinesAnyMap>);
1397
1398 #[stable(feature = "rust1", since = "1.0.0")]
1399 impl<'a> Iterator for Lines<'a> {
1400     type Item = &'a str;
1401
1402     #[inline]
1403     fn next(&mut self) -> Option<&'a str> {
1404         self.0.next()
1405     }
1406
1407     #[inline]
1408     fn size_hint(&self) -> (usize, Option<usize>) {
1409         self.0.size_hint()
1410     }
1411
1412     #[inline]
1413     fn last(mut self) -> Option<&'a str> {
1414         self.next_back()
1415     }
1416 }
1417
1418 #[stable(feature = "rust1", since = "1.0.0")]
1419 impl<'a> DoubleEndedIterator for Lines<'a> {
1420     #[inline]
1421     fn next_back(&mut self) -> Option<&'a str> {
1422         self.0.next_back()
1423     }
1424 }
1425
1426 #[stable(feature = "fused", since = "1.26.0")]
1427 impl FusedIterator for Lines<'_> {}
1428
1429 /// Created with the method [`lines_any`].
1430 ///
1431 /// [`lines_any`]: ../../std/primitive.str.html#method.lines_any
1432 #[stable(feature = "rust1", since = "1.0.0")]
1433 #[rustc_deprecated(since = "1.4.0", reason = "use lines()/Lines instead now")]
1434 #[derive(Clone, Debug)]
1435 #[allow(deprecated)]
1436 pub struct LinesAny<'a>(Lines<'a>);
1437
1438 impl_fn_for_zst! {
1439     /// A nameable, cloneable fn type
1440     #[derive(Clone)]
1441     struct LinesAnyMap impl<'a> Fn = |line: &'a str| -> &'a str {
1442         let l = line.len();
1443         if l > 0 && line.as_bytes()[l - 1] == b'\r' { &line[0 .. l - 1] }
1444         else { line }
1445     };
1446 }
1447
1448 #[stable(feature = "rust1", since = "1.0.0")]
1449 #[allow(deprecated)]
1450 impl<'a> Iterator for LinesAny<'a> {
1451     type Item = &'a str;
1452
1453     #[inline]
1454     fn next(&mut self) -> Option<&'a str> {
1455         self.0.next()
1456     }
1457
1458     #[inline]
1459     fn size_hint(&self) -> (usize, Option<usize>) {
1460         self.0.size_hint()
1461     }
1462 }
1463
1464 #[stable(feature = "rust1", since = "1.0.0")]
1465 #[allow(deprecated)]
1466 impl<'a> DoubleEndedIterator for LinesAny<'a> {
1467     #[inline]
1468     fn next_back(&mut self) -> Option<&'a str> {
1469         self.0.next_back()
1470     }
1471 }
1472
1473 #[stable(feature = "fused", since = "1.26.0")]
1474 #[allow(deprecated)]
1475 impl FusedIterator for LinesAny<'_> {}
1476
1477 /*
1478 Section: UTF-8 validation
1479 */
1480
1481 // use truncation to fit u64 into usize
1482 const NONASCII_MASK: usize = 0x80808080_80808080u64 as usize;
1483
1484 /// Returns `true` if any byte in the word `x` is nonascii (>= 128).
1485 #[inline]
1486 fn contains_nonascii(x: usize) -> bool {
1487     (x & NONASCII_MASK) != 0
1488 }
1489
1490 /// Walks through `v` checking that it's a valid UTF-8 sequence,
1491 /// returning `Ok(())` in that case, or, if it is invalid, `Err(err)`.
1492 #[inline]
1493 fn run_utf8_validation(v: &[u8]) -> Result<(), Utf8Error> {
1494     let mut index = 0;
1495     let len = v.len();
1496
1497     let usize_bytes = mem::size_of::<usize>();
1498     let ascii_block_size = 2 * usize_bytes;
1499     let blocks_end = if len >= ascii_block_size { len - ascii_block_size + 1 } else { 0 };
1500     let align = v.as_ptr().align_offset(usize_bytes);
1501
1502     while index < len {
1503         let old_offset = index;
1504         macro_rules! err {
1505             ($error_len: expr) => {
1506                 return Err(Utf8Error { valid_up_to: old_offset, error_len: $error_len });
1507             };
1508         }
1509
1510         macro_rules! next {
1511             () => {{
1512                 index += 1;
1513                 // we needed data, but there was none: error!
1514                 if index >= len {
1515                     err!(None)
1516                 }
1517                 v[index]
1518             }};
1519         }
1520
1521         let first = v[index];
1522         if first >= 128 {
1523             let w = UTF8_CHAR_WIDTH[first as usize];
1524             // 2-byte encoding is for codepoints  \u{0080} to  \u{07ff}
1525             //        first  C2 80        last DF BF
1526             // 3-byte encoding is for codepoints  \u{0800} to  \u{ffff}
1527             //        first  E0 A0 80     last EF BF BF
1528             //   excluding surrogates codepoints  \u{d800} to  \u{dfff}
1529             //               ED A0 80 to       ED BF BF
1530             // 4-byte encoding is for codepoints \u{1000}0 to \u{10ff}ff
1531             //        first  F0 90 80 80  last F4 8F BF BF
1532             //
1533             // Use the UTF-8 syntax from the RFC
1534             //
1535             // https://tools.ietf.org/html/rfc3629
1536             // UTF8-1      = %x00-7F
1537             // UTF8-2      = %xC2-DF UTF8-tail
1538             // UTF8-3      = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
1539             //               %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
1540             // UTF8-4      = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
1541             //               %xF4 %x80-8F 2( UTF8-tail )
1542             match w {
1543                 2 => {
1544                     if next!() & !CONT_MASK != TAG_CONT_U8 {
1545                         err!(Some(1))
1546                     }
1547                 }
1548                 3 => {
1549                     match (first, next!()) {
1550                         (0xE0, 0xA0..=0xBF)
1551                         | (0xE1..=0xEC, 0x80..=0xBF)
1552                         | (0xED, 0x80..=0x9F)
1553                         | (0xEE..=0xEF, 0x80..=0xBF) => {}
1554                         _ => err!(Some(1)),
1555                     }
1556                     if next!() & !CONT_MASK != TAG_CONT_U8 {
1557                         err!(Some(2))
1558                     }
1559                 }
1560                 4 => {
1561                     match (first, next!()) {
1562                         (0xF0, 0x90..=0xBF) | (0xF1..=0xF3, 0x80..=0xBF) | (0xF4, 0x80..=0x8F) => {}
1563                         _ => err!(Some(1)),
1564                     }
1565                     if next!() & !CONT_MASK != TAG_CONT_U8 {
1566                         err!(Some(2))
1567                     }
1568                     if next!() & !CONT_MASK != TAG_CONT_U8 {
1569                         err!(Some(3))
1570                     }
1571                 }
1572                 _ => err!(Some(1)),
1573             }
1574             index += 1;
1575         } else {
1576             // Ascii case, try to skip forward quickly.
1577             // When the pointer is aligned, read 2 words of data per iteration
1578             // until we find a word containing a non-ascii byte.
1579             if align != usize::max_value() && align.wrapping_sub(index) % usize_bytes == 0 {
1580                 let ptr = v.as_ptr();
1581                 while index < blocks_end {
1582                     unsafe {
1583                         let block = ptr.add(index) as *const usize;
1584                         // break if there is a nonascii byte
1585                         let zu = contains_nonascii(*block);
1586                         let zv = contains_nonascii(*block.offset(1));
1587                         if zu | zv {
1588                             break;
1589                         }
1590                     }
1591                     index += ascii_block_size;
1592                 }
1593                 // step from the point where the wordwise loop stopped
1594                 while index < len && v[index] < 128 {
1595                     index += 1;
1596                 }
1597             } else {
1598                 index += 1;
1599             }
1600         }
1601     }
1602
1603     Ok(())
1604 }
1605
1606 // https://tools.ietf.org/html/rfc3629
1607 static UTF8_CHAR_WIDTH: [u8; 256] = [
1608     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1609     1, // 0x1F
1610     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1611     1, // 0x3F
1612     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1613     1, // 0x5F
1614     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1615     1, // 0x7F
1616     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
1617     0, // 0x9F
1618     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
1619     0, // 0xBF
1620     0, 0, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2,
1621     2, // 0xDF
1622     3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, // 0xEF
1623     4, 4, 4, 4, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xFF
1624 ];
1625
1626 /// Given a first byte, determines how many bytes are in this UTF-8 character.
1627 #[unstable(feature = "str_internals", issue = "none")]
1628 #[inline]
1629 pub fn utf8_char_width(b: u8) -> usize {
1630     UTF8_CHAR_WIDTH[b as usize] as usize
1631 }
1632
1633 /// Mask of the value bits of a continuation byte.
1634 const CONT_MASK: u8 = 0b0011_1111;
1635 /// Value of the tag bits (tag mask is !CONT_MASK) of a continuation byte.
1636 const TAG_CONT_U8: u8 = 0b1000_0000;
1637
1638 /*
1639 Section: Trait implementations
1640 */
1641
1642 mod traits {
1643     use crate::cmp::Ordering;
1644     use crate::ops;
1645     use crate::slice::{self, SliceIndex};
1646
1647     /// Implements ordering of strings.
1648     ///
1649     /// Strings are ordered  lexicographically by their byte values. This orders Unicode code
1650     /// points based on their positions in the code charts. This is not necessarily the same as
1651     /// "alphabetical" order, which varies by language and locale. Sorting strings according to
1652     /// culturally-accepted standards requires locale-specific data that is outside the scope of
1653     /// the `str` type.
1654     #[stable(feature = "rust1", since = "1.0.0")]
1655     impl Ord for str {
1656         #[inline]
1657         fn cmp(&self, other: &str) -> Ordering {
1658             self.as_bytes().cmp(other.as_bytes())
1659         }
1660     }
1661
1662     #[stable(feature = "rust1", since = "1.0.0")]
1663     impl PartialEq for str {
1664         #[inline]
1665         fn eq(&self, other: &str) -> bool {
1666             self.as_bytes() == other.as_bytes()
1667         }
1668         #[inline]
1669         fn ne(&self, other: &str) -> bool {
1670             !(*self).eq(other)
1671         }
1672     }
1673
1674     #[stable(feature = "rust1", since = "1.0.0")]
1675     impl Eq for str {}
1676
1677     /// Implements comparison operations on strings.
1678     ///
1679     /// Strings are compared lexicographically by their byte values. This compares Unicode code
1680     /// points based on their positions in the code charts. This is not necessarily the same as
1681     /// "alphabetical" order, which varies by language and locale. Comparing strings according to
1682     /// culturally-accepted standards requires locale-specific data that is outside the scope of
1683     /// the `str` type.
1684     #[stable(feature = "rust1", since = "1.0.0")]
1685     impl PartialOrd for str {
1686         #[inline]
1687         fn partial_cmp(&self, other: &str) -> Option<Ordering> {
1688             Some(self.cmp(other))
1689         }
1690     }
1691
1692     #[stable(feature = "rust1", since = "1.0.0")]
1693     impl<I> ops::Index<I> for str
1694     where
1695         I: SliceIndex<str>,
1696     {
1697         type Output = I::Output;
1698
1699         #[inline]
1700         fn index(&self, index: I) -> &I::Output {
1701             index.index(self)
1702         }
1703     }
1704
1705     #[stable(feature = "rust1", since = "1.0.0")]
1706     impl<I> ops::IndexMut<I> for str
1707     where
1708         I: SliceIndex<str>,
1709     {
1710         #[inline]
1711         fn index_mut(&mut self, index: I) -> &mut I::Output {
1712             index.index_mut(self)
1713         }
1714     }
1715
1716     #[inline(never)]
1717     #[cold]
1718     fn str_index_overflow_fail() -> ! {
1719         panic!("attempted to index str up to maximum usize");
1720     }
1721
1722     /// Implements substring slicing with syntax `&self[..]` or `&mut self[..]`.
1723     ///
1724     /// Returns a slice of the whole string, i.e., returns `&self` or `&mut
1725     /// self`. Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`. Unlike
1726     /// other indexing operations, this can never panic.
1727     ///
1728     /// This operation is `O(1)`.
1729     ///
1730     /// Prior to 1.20.0, these indexing operations were still supported by
1731     /// direct implementation of `Index` and `IndexMut`.
1732     ///
1733     /// Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`.
1734     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1735     impl SliceIndex<str> for ops::RangeFull {
1736         type Output = str;
1737         #[inline]
1738         fn get(self, slice: &str) -> Option<&Self::Output> {
1739             Some(slice)
1740         }
1741         #[inline]
1742         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1743             Some(slice)
1744         }
1745         #[inline]
1746         unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1747             slice
1748         }
1749         #[inline]
1750         unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1751             slice
1752         }
1753         #[inline]
1754         fn index(self, slice: &str) -> &Self::Output {
1755             slice
1756         }
1757         #[inline]
1758         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1759             slice
1760         }
1761     }
1762
1763     /// Implements substring slicing with syntax `&self[begin .. end]` or `&mut
1764     /// self[begin .. end]`.
1765     ///
1766     /// Returns a slice of the given string from the byte range
1767     /// [`begin`, `end`).
1768     ///
1769     /// This operation is `O(1)`.
1770     ///
1771     /// Prior to 1.20.0, these indexing operations were still supported by
1772     /// direct implementation of `Index` and `IndexMut`.
1773     ///
1774     /// # Panics
1775     ///
1776     /// Panics if `begin` or `end` does not point to the starting byte offset of
1777     /// a character (as defined by `is_char_boundary`), if `begin > end`, or if
1778     /// `end > len`.
1779     ///
1780     /// # Examples
1781     ///
1782     /// ```
1783     /// let s = "Löwe 老虎 Léopard";
1784     /// assert_eq!(&s[0 .. 1], "L");
1785     ///
1786     /// assert_eq!(&s[1 .. 9], "öwe 老");
1787     ///
1788     /// // these will panic:
1789     /// // byte 2 lies within `ö`:
1790     /// // &s[2 ..3];
1791     ///
1792     /// // byte 8 lies within `老`
1793     /// // &s[1 .. 8];
1794     ///
1795     /// // byte 100 is outside the string
1796     /// // &s[3 .. 100];
1797     /// ```
1798     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1799     impl SliceIndex<str> for ops::Range<usize> {
1800         type Output = str;
1801         #[inline]
1802         fn get(self, slice: &str) -> Option<&Self::Output> {
1803             if self.start <= self.end
1804                 && slice.is_char_boundary(self.start)
1805                 && slice.is_char_boundary(self.end)
1806             {
1807                 Some(unsafe { self.get_unchecked(slice) })
1808             } else {
1809                 None
1810             }
1811         }
1812         #[inline]
1813         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1814             if self.start <= self.end
1815                 && slice.is_char_boundary(self.start)
1816                 && slice.is_char_boundary(self.end)
1817             {
1818                 Some(unsafe { self.get_unchecked_mut(slice) })
1819             } else {
1820                 None
1821             }
1822         }
1823         #[inline]
1824         unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1825             let ptr = slice.as_ptr().add(self.start);
1826             let len = self.end - self.start;
1827             super::from_utf8_unchecked(slice::from_raw_parts(ptr, len))
1828         }
1829         #[inline]
1830         unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1831             let ptr = slice.as_mut_ptr().add(self.start);
1832             let len = self.end - self.start;
1833             super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len))
1834         }
1835         #[inline]
1836         fn index(self, slice: &str) -> &Self::Output {
1837             let (start, end) = (self.start, self.end);
1838             self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, start, end))
1839         }
1840         #[inline]
1841         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1842             // is_char_boundary checks that the index is in [0, .len()]
1843             // cannot reuse `get` as above, because of NLL trouble
1844             if self.start <= self.end
1845                 && slice.is_char_boundary(self.start)
1846                 && slice.is_char_boundary(self.end)
1847             {
1848                 unsafe { self.get_unchecked_mut(slice) }
1849             } else {
1850                 super::slice_error_fail(slice, self.start, self.end)
1851             }
1852         }
1853     }
1854
1855     /// Implements substring slicing with syntax `&self[.. end]` or `&mut
1856     /// self[.. end]`.
1857     ///
1858     /// Returns a slice of the given string from the byte range [`0`, `end`).
1859     /// Equivalent to `&self[0 .. end]` or `&mut self[0 .. end]`.
1860     ///
1861     /// This operation is `O(1)`.
1862     ///
1863     /// Prior to 1.20.0, these indexing operations were still supported by
1864     /// direct implementation of `Index` and `IndexMut`.
1865     ///
1866     /// # Panics
1867     ///
1868     /// Panics if `end` does not point to the starting byte offset of a
1869     /// character (as defined by `is_char_boundary`), or if `end > len`.
1870     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1871     impl SliceIndex<str> for ops::RangeTo<usize> {
1872         type Output = str;
1873         #[inline]
1874         fn get(self, slice: &str) -> Option<&Self::Output> {
1875             if slice.is_char_boundary(self.end) {
1876                 Some(unsafe { self.get_unchecked(slice) })
1877             } else {
1878                 None
1879             }
1880         }
1881         #[inline]
1882         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1883             if slice.is_char_boundary(self.end) {
1884                 Some(unsafe { self.get_unchecked_mut(slice) })
1885             } else {
1886                 None
1887             }
1888         }
1889         #[inline]
1890         unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1891             let ptr = slice.as_ptr();
1892             super::from_utf8_unchecked(slice::from_raw_parts(ptr, self.end))
1893         }
1894         #[inline]
1895         unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1896             let ptr = slice.as_mut_ptr();
1897             super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, self.end))
1898         }
1899         #[inline]
1900         fn index(self, slice: &str) -> &Self::Output {
1901             let end = self.end;
1902             self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, 0, end))
1903         }
1904         #[inline]
1905         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1906             // is_char_boundary checks that the index is in [0, .len()]
1907             if slice.is_char_boundary(self.end) {
1908                 unsafe { self.get_unchecked_mut(slice) }
1909             } else {
1910                 super::slice_error_fail(slice, 0, self.end)
1911             }
1912         }
1913     }
1914
1915     /// Implements substring slicing with syntax `&self[begin ..]` or `&mut
1916     /// self[begin ..]`.
1917     ///
1918     /// Returns a slice of the given string from the byte range [`begin`,
1919     /// `len`). Equivalent to `&self[begin .. len]` or `&mut self[begin ..
1920     /// len]`.
1921     ///
1922     /// This operation is `O(1)`.
1923     ///
1924     /// Prior to 1.20.0, these indexing operations were still supported by
1925     /// direct implementation of `Index` and `IndexMut`.
1926     ///
1927     /// # Panics
1928     ///
1929     /// Panics if `begin` does not point to the starting byte offset of
1930     /// a character (as defined by `is_char_boundary`), or if `begin >= len`.
1931     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1932     impl SliceIndex<str> for ops::RangeFrom<usize> {
1933         type Output = str;
1934         #[inline]
1935         fn get(self, slice: &str) -> Option<&Self::Output> {
1936             if slice.is_char_boundary(self.start) {
1937                 Some(unsafe { self.get_unchecked(slice) })
1938             } else {
1939                 None
1940             }
1941         }
1942         #[inline]
1943         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1944             if slice.is_char_boundary(self.start) {
1945                 Some(unsafe { self.get_unchecked_mut(slice) })
1946             } else {
1947                 None
1948             }
1949         }
1950         #[inline]
1951         unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1952             let ptr = slice.as_ptr().add(self.start);
1953             let len = slice.len() - self.start;
1954             super::from_utf8_unchecked(slice::from_raw_parts(ptr, len))
1955         }
1956         #[inline]
1957         unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1958             let ptr = slice.as_mut_ptr().add(self.start);
1959             let len = slice.len() - self.start;
1960             super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len))
1961         }
1962         #[inline]
1963         fn index(self, slice: &str) -> &Self::Output {
1964             let (start, end) = (self.start, slice.len());
1965             self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, start, end))
1966         }
1967         #[inline]
1968         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1969             // is_char_boundary checks that the index is in [0, .len()]
1970             if slice.is_char_boundary(self.start) {
1971                 unsafe { self.get_unchecked_mut(slice) }
1972             } else {
1973                 super::slice_error_fail(slice, self.start, slice.len())
1974             }
1975         }
1976     }
1977
1978     /// Implements substring slicing with syntax `&self[begin ..= end]` or `&mut
1979     /// self[begin ..= end]`.
1980     ///
1981     /// Returns a slice of the given string from the byte range
1982     /// [`begin`, `end`]. Equivalent to `&self [begin .. end + 1]` or `&mut
1983     /// self[begin .. end + 1]`, except if `end` has the maximum value for
1984     /// `usize`.
1985     ///
1986     /// This operation is `O(1)`.
1987     ///
1988     /// # Panics
1989     ///
1990     /// Panics if `begin` does not point to the starting byte offset of
1991     /// a character (as defined by `is_char_boundary`), if `end` does not point
1992     /// to the ending byte offset of a character (`end + 1` is either a starting
1993     /// byte offset or equal to `len`), if `begin > end`, or if `end >= len`.
1994     #[stable(feature = "inclusive_range", since = "1.26.0")]
1995     impl SliceIndex<str> for ops::RangeInclusive<usize> {
1996         type Output = str;
1997         #[inline]
1998         fn get(self, slice: &str) -> Option<&Self::Output> {
1999             if *self.end() == usize::max_value() {
2000                 None
2001             } else {
2002                 (*self.start()..self.end() + 1).get(slice)
2003             }
2004         }
2005         #[inline]
2006         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
2007             if *self.end() == usize::max_value() {
2008                 None
2009             } else {
2010                 (*self.start()..self.end() + 1).get_mut(slice)
2011             }
2012         }
2013         #[inline]
2014         unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
2015             (*self.start()..self.end() + 1).get_unchecked(slice)
2016         }
2017         #[inline]
2018         unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
2019             (*self.start()..self.end() + 1).get_unchecked_mut(slice)
2020         }
2021         #[inline]
2022         fn index(self, slice: &str) -> &Self::Output {
2023             if *self.end() == usize::max_value() {
2024                 str_index_overflow_fail();
2025             }
2026             (*self.start()..self.end() + 1).index(slice)
2027         }
2028         #[inline]
2029         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
2030             if *self.end() == usize::max_value() {
2031                 str_index_overflow_fail();
2032             }
2033             (*self.start()..self.end() + 1).index_mut(slice)
2034         }
2035     }
2036
2037     /// Implements substring slicing with syntax `&self[..= end]` or `&mut
2038     /// self[..= end]`.
2039     ///
2040     /// Returns a slice of the given string from the byte range [0, `end`].
2041     /// Equivalent to `&self [0 .. end + 1]`, except if `end` has the maximum
2042     /// value for `usize`.
2043     ///
2044     /// This operation is `O(1)`.
2045     ///
2046     /// # Panics
2047     ///
2048     /// Panics if `end` does not point to the ending byte offset of a character
2049     /// (`end + 1` is either a starting byte offset as defined by
2050     /// `is_char_boundary`, or equal to `len`), or if `end >= len`.
2051     #[stable(feature = "inclusive_range", since = "1.26.0")]
2052     impl SliceIndex<str> for ops::RangeToInclusive<usize> {
2053         type Output = str;
2054         #[inline]
2055         fn get(self, slice: &str) -> Option<&Self::Output> {
2056             if self.end == usize::max_value() { None } else { (..self.end + 1).get(slice) }
2057         }
2058         #[inline]
2059         fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
2060             if self.end == usize::max_value() { None } else { (..self.end + 1).get_mut(slice) }
2061         }
2062         #[inline]
2063         unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
2064             (..self.end + 1).get_unchecked(slice)
2065         }
2066         #[inline]
2067         unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
2068             (..self.end + 1).get_unchecked_mut(slice)
2069         }
2070         #[inline]
2071         fn index(self, slice: &str) -> &Self::Output {
2072             if self.end == usize::max_value() {
2073                 str_index_overflow_fail();
2074             }
2075             (..self.end + 1).index(slice)
2076         }
2077         #[inline]
2078         fn index_mut(self, slice: &mut str) -> &mut Self::Output {
2079             if self.end == usize::max_value() {
2080                 str_index_overflow_fail();
2081             }
2082             (..self.end + 1).index_mut(slice)
2083         }
2084     }
2085 }
2086
2087 // truncate `&str` to length at most equal to `max`
2088 // return `true` if it were truncated, and the new str.
2089 fn truncate_to_char_boundary(s: &str, mut max: usize) -> (bool, &str) {
2090     if max >= s.len() {
2091         (false, s)
2092     } else {
2093         while !s.is_char_boundary(max) {
2094             max -= 1;
2095         }
2096         (true, &s[..max])
2097     }
2098 }
2099
2100 #[inline(never)]
2101 #[cold]
2102 fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
2103     const MAX_DISPLAY_LENGTH: usize = 256;
2104     let (truncated, s_trunc) = truncate_to_char_boundary(s, MAX_DISPLAY_LENGTH);
2105     let ellipsis = if truncated { "[...]" } else { "" };
2106
2107     // 1. out of bounds
2108     if begin > s.len() || end > s.len() {
2109         let oob_index = if begin > s.len() { begin } else { end };
2110         panic!("byte index {} is out of bounds of `{}`{}", oob_index, s_trunc, ellipsis);
2111     }
2112
2113     // 2. begin <= end
2114     assert!(
2115         begin <= end,
2116         "begin <= end ({} <= {}) when slicing `{}`{}",
2117         begin,
2118         end,
2119         s_trunc,
2120         ellipsis
2121     );
2122
2123     // 3. character boundary
2124     let index = if !s.is_char_boundary(begin) { begin } else { end };
2125     // find the character
2126     let mut char_start = index;
2127     while !s.is_char_boundary(char_start) {
2128         char_start -= 1;
2129     }
2130     // `char_start` must be less than len and a char boundary
2131     let ch = s[char_start..].chars().next().unwrap();
2132     let char_range = char_start..char_start + ch.len_utf8();
2133     panic!(
2134         "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
2135         index, ch, char_range, s_trunc, ellipsis
2136     );
2137 }
2138
2139 #[lang = "str"]
2140 #[cfg(not(test))]
2141 impl str {
2142     /// Returns the length of `self`.
2143     ///
2144     /// This length is in bytes, not [`char`]s or graphemes. In other words,
2145     /// it may not be what a human considers the length of the string.
2146     ///
2147     /// # Examples
2148     ///
2149     /// Basic usage:
2150     ///
2151     /// ```
2152     /// let len = "foo".len();
2153     /// assert_eq!(3, len);
2154     ///
2155     /// assert_eq!("ƒoo".len(), 4); // fancy f!
2156     /// assert_eq!("ƒoo".chars().count(), 3);
2157     /// ```
2158     #[stable(feature = "rust1", since = "1.0.0")]
2159     #[rustc_const_stable(feature = "const_str_len", since = "1.32.0")]
2160     #[inline]
2161     pub const fn len(&self) -> usize {
2162         self.as_bytes().len()
2163     }
2164
2165     /// Returns `true` if `self` has a length of zero bytes.
2166     ///
2167     /// # Examples
2168     ///
2169     /// Basic usage:
2170     ///
2171     /// ```
2172     /// let s = "";
2173     /// assert!(s.is_empty());
2174     ///
2175     /// let s = "not empty";
2176     /// assert!(!s.is_empty());
2177     /// ```
2178     #[inline]
2179     #[stable(feature = "rust1", since = "1.0.0")]
2180     #[rustc_const_stable(feature = "const_str_is_empty", since = "1.32.0")]
2181     pub const fn is_empty(&self) -> bool {
2182         self.len() == 0
2183     }
2184
2185     /// Checks that `index`-th byte lies at the start and/or end of a
2186     /// UTF-8 code point sequence.
2187     ///
2188     /// The start and end of the string (when `index == self.len()`) are
2189     /// considered to be
2190     /// boundaries.
2191     ///
2192     /// Returns `false` if `index` is greater than `self.len()`.
2193     ///
2194     /// # Examples
2195     ///
2196     /// ```
2197     /// let s = "Löwe 老虎 Léopard";
2198     /// assert!(s.is_char_boundary(0));
2199     /// // start of `老`
2200     /// assert!(s.is_char_boundary(6));
2201     /// assert!(s.is_char_boundary(s.len()));
2202     ///
2203     /// // second byte of `ö`
2204     /// assert!(!s.is_char_boundary(2));
2205     ///
2206     /// // third byte of `老`
2207     /// assert!(!s.is_char_boundary(8));
2208     /// ```
2209     #[stable(feature = "is_char_boundary", since = "1.9.0")]
2210     #[inline]
2211     pub fn is_char_boundary(&self, index: usize) -> bool {
2212         // 0 and len are always ok.
2213         // Test for 0 explicitly so that it can optimize out the check
2214         // easily and skip reading string data for that case.
2215         if index == 0 || index == self.len() {
2216             return true;
2217         }
2218         match self.as_bytes().get(index) {
2219             None => false,
2220             // This is bit magic equivalent to: b < 128 || b >= 192
2221             Some(&b) => (b as i8) >= -0x40,
2222         }
2223     }
2224
2225     /// Converts a string slice to a byte slice. To convert the byte slice back
2226     /// into a string slice, use the [`str::from_utf8`] function.
2227     ///
2228     /// [`str::from_utf8`]: ./str/fn.from_utf8.html
2229     ///
2230     /// # Examples
2231     ///
2232     /// Basic usage:
2233     ///
2234     /// ```
2235     /// let bytes = "bors".as_bytes();
2236     /// assert_eq!(b"bors", bytes);
2237     /// ```
2238     #[stable(feature = "rust1", since = "1.0.0")]
2239     #[rustc_const_stable(feature = "str_as_bytes", since = "1.32.0")]
2240     #[inline(always)]
2241     // SAFETY: const sound because we transmute two types with the same layout
2242     #[allow(unused_attributes)]
2243     #[allow_internal_unstable(const_fn_union)]
2244     pub const fn as_bytes(&self) -> &[u8] {
2245         #[repr(C)]
2246         union Slices<'a> {
2247             str: &'a str,
2248             slice: &'a [u8],
2249         }
2250         unsafe { Slices { str: self }.slice }
2251     }
2252
2253     /// Converts a mutable string slice to a mutable byte slice. To convert the
2254     /// mutable byte slice back into a mutable string slice, use the
2255     /// [`str::from_utf8_mut`] function.
2256     ///
2257     /// [`str::from_utf8_mut`]: ./str/fn.from_utf8_mut.html
2258     ///
2259     /// # Examples
2260     ///
2261     /// Basic usage:
2262     ///
2263     /// ```
2264     /// let mut s = String::from("Hello");
2265     /// let bytes = unsafe { s.as_bytes_mut() };
2266     ///
2267     /// assert_eq!(b"Hello", bytes);
2268     /// ```
2269     ///
2270     /// Mutability:
2271     ///
2272     /// ```
2273     /// let mut s = String::from("🗻∈🌏");
2274     ///
2275     /// unsafe {
2276     ///     let bytes = s.as_bytes_mut();
2277     ///
2278     ///     bytes[0] = 0xF0;
2279     ///     bytes[1] = 0x9F;
2280     ///     bytes[2] = 0x8D;
2281     ///     bytes[3] = 0x94;
2282     /// }
2283     ///
2284     /// assert_eq!("🍔∈🌏", s);
2285     /// ```
2286     #[stable(feature = "str_mut_extras", since = "1.20.0")]
2287     #[inline(always)]
2288     pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
2289         &mut *(self as *mut str as *mut [u8])
2290     }
2291
2292     /// Converts a string slice to a raw pointer.
2293     ///
2294     /// As string slices are a slice of bytes, the raw pointer points to a
2295     /// [`u8`]. This pointer will be pointing to the first byte of the string
2296     /// slice.
2297     ///
2298     /// The caller must ensure that the returned pointer is never written to.
2299     /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
2300     ///
2301     /// [`u8`]: primitive.u8.html
2302     /// [`as_mut_ptr`]: #method.as_mut_ptr
2303     ///
2304     /// # Examples
2305     ///
2306     /// Basic usage:
2307     ///
2308     /// ```
2309     /// let s = "Hello";
2310     /// let ptr = s.as_ptr();
2311     /// ```
2312     #[stable(feature = "rust1", since = "1.0.0")]
2313     #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
2314     #[inline]
2315     pub const fn as_ptr(&self) -> *const u8 {
2316         self as *const str as *const u8
2317     }
2318
2319     /// Converts a mutable string slice to a raw pointer.
2320     ///
2321     /// As string slices are a slice of bytes, the raw pointer points to a
2322     /// [`u8`]. This pointer will be pointing to the first byte of the string
2323     /// slice.
2324     ///
2325     /// It is your responsibility to make sure that the string slice only gets
2326     /// modified in a way that it remains valid UTF-8.
2327     ///
2328     /// [`u8`]: primitive.u8.html
2329     #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
2330     #[inline]
2331     pub fn as_mut_ptr(&mut self) -> *mut u8 {
2332         self as *mut str as *mut u8
2333     }
2334
2335     /// Returns a subslice of `str`.
2336     ///
2337     /// This is the non-panicking alternative to indexing the `str`. Returns
2338     /// [`None`] whenever equivalent indexing operation would panic.
2339     ///
2340     /// [`None`]: option/enum.Option.html#variant.None
2341     ///
2342     /// # Examples
2343     ///
2344     /// ```
2345     /// let v = String::from("🗻∈🌏");
2346     ///
2347     /// assert_eq!(Some("🗻"), v.get(0..4));
2348     ///
2349     /// // indices not on UTF-8 sequence boundaries
2350     /// assert!(v.get(1..).is_none());
2351     /// assert!(v.get(..8).is_none());
2352     ///
2353     /// // out of bounds
2354     /// assert!(v.get(..42).is_none());
2355     /// ```
2356     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2357     #[inline]
2358     pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
2359         i.get(self)
2360     }
2361
2362     /// Returns a mutable subslice of `str`.
2363     ///
2364     /// This is the non-panicking alternative to indexing the `str`. Returns
2365     /// [`None`] whenever equivalent indexing operation would panic.
2366     ///
2367     /// [`None`]: option/enum.Option.html#variant.None
2368     ///
2369     /// # Examples
2370     ///
2371     /// ```
2372     /// let mut v = String::from("hello");
2373     /// // correct length
2374     /// assert!(v.get_mut(0..5).is_some());
2375     /// // out of bounds
2376     /// assert!(v.get_mut(..42).is_none());
2377     /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
2378     ///
2379     /// assert_eq!("hello", v);
2380     /// {
2381     ///     let s = v.get_mut(0..2);
2382     ///     let s = s.map(|s| {
2383     ///         s.make_ascii_uppercase();
2384     ///         &*s
2385     ///     });
2386     ///     assert_eq!(Some("HE"), s);
2387     /// }
2388     /// assert_eq!("HEllo", v);
2389     /// ```
2390     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2391     #[inline]
2392     pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
2393         i.get_mut(self)
2394     }
2395
2396     /// Returns an unchecked subslice of `str`.
2397     ///
2398     /// This is the unchecked alternative to indexing the `str`.
2399     ///
2400     /// # Safety
2401     ///
2402     /// Callers of this function are responsible that these preconditions are
2403     /// satisfied:
2404     ///
2405     /// * The starting index must come before the ending index;
2406     /// * Indexes must be within bounds of the original slice;
2407     /// * Indexes must lie on UTF-8 sequence boundaries.
2408     ///
2409     /// Failing that, the returned string slice may reference invalid memory or
2410     /// violate the invariants communicated by the `str` type.
2411     ///
2412     /// # Examples
2413     ///
2414     /// ```
2415     /// let v = "🗻∈🌏";
2416     /// unsafe {
2417     ///     assert_eq!("🗻", v.get_unchecked(0..4));
2418     ///     assert_eq!("∈", v.get_unchecked(4..7));
2419     ///     assert_eq!("🌏", v.get_unchecked(7..11));
2420     /// }
2421     /// ```
2422     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2423     #[inline]
2424     pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
2425         i.get_unchecked(self)
2426     }
2427
2428     /// Returns a mutable, unchecked subslice of `str`.
2429     ///
2430     /// This is the unchecked alternative to indexing the `str`.
2431     ///
2432     /// # Safety
2433     ///
2434     /// Callers of this function are responsible that these preconditions are
2435     /// satisfied:
2436     ///
2437     /// * The starting index must come before the ending index;
2438     /// * Indexes must be within bounds of the original slice;
2439     /// * Indexes must lie on UTF-8 sequence boundaries.
2440     ///
2441     /// Failing that, the returned string slice may reference invalid memory or
2442     /// violate the invariants communicated by the `str` type.
2443     ///
2444     /// # Examples
2445     ///
2446     /// ```
2447     /// let mut v = String::from("🗻∈🌏");
2448     /// unsafe {
2449     ///     assert_eq!("🗻", v.get_unchecked_mut(0..4));
2450     ///     assert_eq!("∈", v.get_unchecked_mut(4..7));
2451     ///     assert_eq!("🌏", v.get_unchecked_mut(7..11));
2452     /// }
2453     /// ```
2454     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2455     #[inline]
2456     pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
2457         i.get_unchecked_mut(self)
2458     }
2459
2460     /// Creates a string slice from another string slice, bypassing safety
2461     /// checks.
2462     ///
2463     /// This is generally not recommended, use with caution! For a safe
2464     /// alternative see [`str`] and [`Index`].
2465     ///
2466     /// [`str`]: primitive.str.html
2467     /// [`Index`]: ops/trait.Index.html
2468     ///
2469     /// This new slice goes from `begin` to `end`, including `begin` but
2470     /// excluding `end`.
2471     ///
2472     /// To get a mutable string slice instead, see the
2473     /// [`slice_mut_unchecked`] method.
2474     ///
2475     /// [`slice_mut_unchecked`]: #method.slice_mut_unchecked
2476     ///
2477     /// # Safety
2478     ///
2479     /// Callers of this function are responsible that three preconditions are
2480     /// satisfied:
2481     ///
2482     /// * `begin` must come before `end`.
2483     /// * `begin` and `end` must be byte positions within the string slice.
2484     /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2485     ///
2486     /// # Examples
2487     ///
2488     /// Basic usage:
2489     ///
2490     /// ```
2491     /// let s = "Löwe 老虎 Léopard";
2492     ///
2493     /// unsafe {
2494     ///     assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
2495     /// }
2496     ///
2497     /// let s = "Hello, world!";
2498     ///
2499     /// unsafe {
2500     ///     assert_eq!("world", s.slice_unchecked(7, 12));
2501     /// }
2502     /// ```
2503     #[stable(feature = "rust1", since = "1.0.0")]
2504     #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked(begin..end)` instead")]
2505     #[inline]
2506     pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
2507         (begin..end).get_unchecked(self)
2508     }
2509
2510     /// Creates a string slice from another string slice, bypassing safety
2511     /// checks.
2512     /// This is generally not recommended, use with caution! For a safe
2513     /// alternative see [`str`] and [`IndexMut`].
2514     ///
2515     /// [`str`]: primitive.str.html
2516     /// [`IndexMut`]: ops/trait.IndexMut.html
2517     ///
2518     /// This new slice goes from `begin` to `end`, including `begin` but
2519     /// excluding `end`.
2520     ///
2521     /// To get an immutable string slice instead, see the
2522     /// [`slice_unchecked`] method.
2523     ///
2524     /// [`slice_unchecked`]: #method.slice_unchecked
2525     ///
2526     /// # Safety
2527     ///
2528     /// Callers of this function are responsible that three preconditions are
2529     /// satisfied:
2530     ///
2531     /// * `begin` must come before `end`.
2532     /// * `begin` and `end` must be byte positions within the string slice.
2533     /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2534     #[stable(feature = "str_slice_mut", since = "1.5.0")]
2535     #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked_mut(begin..end)` instead")]
2536     #[inline]
2537     pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
2538         (begin..end).get_unchecked_mut(self)
2539     }
2540
2541     /// Divide one string slice into two at an index.
2542     ///
2543     /// The argument, `mid`, should be a byte offset from the start of the
2544     /// string. It must also be on the boundary of a UTF-8 code point.
2545     ///
2546     /// The two slices returned go from the start of the string slice to `mid`,
2547     /// and from `mid` to the end of the string slice.
2548     ///
2549     /// To get mutable string slices instead, see the [`split_at_mut`]
2550     /// method.
2551     ///
2552     /// [`split_at_mut`]: #method.split_at_mut
2553     ///
2554     /// # Panics
2555     ///
2556     /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2557     /// beyond the last code point of the string slice.
2558     ///
2559     /// # Examples
2560     ///
2561     /// Basic usage:
2562     ///
2563     /// ```
2564     /// let s = "Per Martin-Löf";
2565     ///
2566     /// let (first, last) = s.split_at(3);
2567     ///
2568     /// assert_eq!("Per", first);
2569     /// assert_eq!(" Martin-Löf", last);
2570     /// ```
2571     #[inline]
2572     #[stable(feature = "str_split_at", since = "1.4.0")]
2573     pub fn split_at(&self, mid: usize) -> (&str, &str) {
2574         // is_char_boundary checks that the index is in [0, .len()]
2575         if self.is_char_boundary(mid) {
2576             unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
2577         } else {
2578             slice_error_fail(self, 0, mid)
2579         }
2580     }
2581
2582     /// Divide one mutable string slice into two at an index.
2583     ///
2584     /// The argument, `mid`, should be a byte offset from the start of the
2585     /// string. It must also be on the boundary of a UTF-8 code point.
2586     ///
2587     /// The two slices returned go from the start of the string slice to `mid`,
2588     /// and from `mid` to the end of the string slice.
2589     ///
2590     /// To get immutable string slices instead, see the [`split_at`] method.
2591     ///
2592     /// [`split_at`]: #method.split_at
2593     ///
2594     /// # Panics
2595     ///
2596     /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2597     /// beyond the last code point of the string slice.
2598     ///
2599     /// # Examples
2600     ///
2601     /// Basic usage:
2602     ///
2603     /// ```
2604     /// let mut s = "Per Martin-Löf".to_string();
2605     /// {
2606     ///     let (first, last) = s.split_at_mut(3);
2607     ///     first.make_ascii_uppercase();
2608     ///     assert_eq!("PER", first);
2609     ///     assert_eq!(" Martin-Löf", last);
2610     /// }
2611     /// assert_eq!("PER Martin-Löf", s);
2612     /// ```
2613     #[inline]
2614     #[stable(feature = "str_split_at", since = "1.4.0")]
2615     pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
2616         // is_char_boundary checks that the index is in [0, .len()]
2617         if self.is_char_boundary(mid) {
2618             let len = self.len();
2619             let ptr = self.as_mut_ptr();
2620             unsafe {
2621                 (
2622                     from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
2623                     from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
2624                 )
2625             }
2626         } else {
2627             slice_error_fail(self, 0, mid)
2628         }
2629     }
2630
2631     /// Returns an iterator over the [`char`]s of a string slice.
2632     ///
2633     /// As a string slice consists of valid UTF-8, we can iterate through a
2634     /// string slice by [`char`]. This method returns such an iterator.
2635     ///
2636     /// It's important to remember that [`char`] represents a Unicode Scalar
2637     /// Value, and may not match your idea of what a 'character' is. Iteration
2638     /// over grapheme clusters may be what you actually want.
2639     ///
2640     /// # Examples
2641     ///
2642     /// Basic usage:
2643     ///
2644     /// ```
2645     /// let word = "goodbye";
2646     ///
2647     /// let count = word.chars().count();
2648     /// assert_eq!(7, count);
2649     ///
2650     /// let mut chars = word.chars();
2651     ///
2652     /// assert_eq!(Some('g'), chars.next());
2653     /// assert_eq!(Some('o'), chars.next());
2654     /// assert_eq!(Some('o'), chars.next());
2655     /// assert_eq!(Some('d'), chars.next());
2656     /// assert_eq!(Some('b'), chars.next());
2657     /// assert_eq!(Some('y'), chars.next());
2658     /// assert_eq!(Some('e'), chars.next());
2659     ///
2660     /// assert_eq!(None, chars.next());
2661     /// ```
2662     ///
2663     /// Remember, [`char`]s may not match your human intuition about characters:
2664     ///
2665     /// ```
2666     /// let y = "y̆";
2667     ///
2668     /// let mut chars = y.chars();
2669     ///
2670     /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
2671     /// assert_eq!(Some('\u{0306}'), chars.next());
2672     ///
2673     /// assert_eq!(None, chars.next());
2674     /// ```
2675     #[stable(feature = "rust1", since = "1.0.0")]
2676     #[inline]
2677     pub fn chars(&self) -> Chars<'_> {
2678         Chars { iter: self.as_bytes().iter() }
2679     }
2680
2681     /// Returns an iterator over the [`char`]s of a string slice, and their
2682     /// positions.
2683     ///
2684     /// As a string slice consists of valid UTF-8, we can iterate through a
2685     /// string slice by [`char`]. This method returns an iterator of both
2686     /// these [`char`]s, as well as their byte positions.
2687     ///
2688     /// The iterator yields tuples. The position is first, the [`char`] is
2689     /// second.
2690     ///
2691     /// # Examples
2692     ///
2693     /// Basic usage:
2694     ///
2695     /// ```
2696     /// let word = "goodbye";
2697     ///
2698     /// let count = word.char_indices().count();
2699     /// assert_eq!(7, count);
2700     ///
2701     /// let mut char_indices = word.char_indices();
2702     ///
2703     /// assert_eq!(Some((0, 'g')), char_indices.next());
2704     /// assert_eq!(Some((1, 'o')), char_indices.next());
2705     /// assert_eq!(Some((2, 'o')), char_indices.next());
2706     /// assert_eq!(Some((3, 'd')), char_indices.next());
2707     /// assert_eq!(Some((4, 'b')), char_indices.next());
2708     /// assert_eq!(Some((5, 'y')), char_indices.next());
2709     /// assert_eq!(Some((6, 'e')), char_indices.next());
2710     ///
2711     /// assert_eq!(None, char_indices.next());
2712     /// ```
2713     ///
2714     /// Remember, [`char`]s may not match your human intuition about characters:
2715     ///
2716     /// ```
2717     /// let yes = "y̆es";
2718     ///
2719     /// let mut char_indices = yes.char_indices();
2720     ///
2721     /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
2722     /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
2723     ///
2724     /// // note the 3 here - the last character took up two bytes
2725     /// assert_eq!(Some((3, 'e')), char_indices.next());
2726     /// assert_eq!(Some((4, 's')), char_indices.next());
2727     ///
2728     /// assert_eq!(None, char_indices.next());
2729     /// ```
2730     #[stable(feature = "rust1", since = "1.0.0")]
2731     #[inline]
2732     pub fn char_indices(&self) -> CharIndices<'_> {
2733         CharIndices { front_offset: 0, iter: self.chars() }
2734     }
2735
2736     /// An iterator over the bytes of a string slice.
2737     ///
2738     /// As a string slice consists of a sequence of bytes, we can iterate
2739     /// through a string slice by byte. This method returns such an iterator.
2740     ///
2741     /// # Examples
2742     ///
2743     /// Basic usage:
2744     ///
2745     /// ```
2746     /// let mut bytes = "bors".bytes();
2747     ///
2748     /// assert_eq!(Some(b'b'), bytes.next());
2749     /// assert_eq!(Some(b'o'), bytes.next());
2750     /// assert_eq!(Some(b'r'), bytes.next());
2751     /// assert_eq!(Some(b's'), bytes.next());
2752     ///
2753     /// assert_eq!(None, bytes.next());
2754     /// ```
2755     #[stable(feature = "rust1", since = "1.0.0")]
2756     #[inline]
2757     pub fn bytes(&self) -> Bytes<'_> {
2758         Bytes(self.as_bytes().iter().cloned())
2759     }
2760
2761     /// Splits a string slice by whitespace.
2762     ///
2763     /// The iterator returned will return string slices that are sub-slices of
2764     /// the original string slice, separated by any amount of whitespace.
2765     ///
2766     /// 'Whitespace' is defined according to the terms of the Unicode Derived
2767     /// Core Property `White_Space`. If you only want to split on ASCII whitespace
2768     /// instead, use [`split_ascii_whitespace`].
2769     ///
2770     /// [`split_ascii_whitespace`]: #method.split_ascii_whitespace
2771     ///
2772     /// # Examples
2773     ///
2774     /// Basic usage:
2775     ///
2776     /// ```
2777     /// let mut iter = "A few words".split_whitespace();
2778     ///
2779     /// assert_eq!(Some("A"), iter.next());
2780     /// assert_eq!(Some("few"), iter.next());
2781     /// assert_eq!(Some("words"), iter.next());
2782     ///
2783     /// assert_eq!(None, iter.next());
2784     /// ```
2785     ///
2786     /// All kinds of whitespace are considered:
2787     ///
2788     /// ```
2789     /// let mut iter = " Mary   had\ta\u{2009}little  \n\t lamb".split_whitespace();
2790     /// assert_eq!(Some("Mary"), iter.next());
2791     /// assert_eq!(Some("had"), iter.next());
2792     /// assert_eq!(Some("a"), iter.next());
2793     /// assert_eq!(Some("little"), iter.next());
2794     /// assert_eq!(Some("lamb"), iter.next());
2795     ///
2796     /// assert_eq!(None, iter.next());
2797     /// ```
2798     #[stable(feature = "split_whitespace", since = "1.1.0")]
2799     #[inline]
2800     pub fn split_whitespace(&self) -> SplitWhitespace<'_> {
2801         SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
2802     }
2803
2804     /// Splits a string slice by ASCII whitespace.
2805     ///
2806     /// The iterator returned will return string slices that are sub-slices of
2807     /// the original string slice, separated by any amount of ASCII whitespace.
2808     ///
2809     /// To split by Unicode `Whitespace` instead, use [`split_whitespace`].
2810     ///
2811     /// [`split_whitespace`]: #method.split_whitespace
2812     ///
2813     /// # Examples
2814     ///
2815     /// Basic usage:
2816     ///
2817     /// ```
2818     /// let mut iter = "A few words".split_ascii_whitespace();
2819     ///
2820     /// assert_eq!(Some("A"), iter.next());
2821     /// assert_eq!(Some("few"), iter.next());
2822     /// assert_eq!(Some("words"), iter.next());
2823     ///
2824     /// assert_eq!(None, iter.next());
2825     /// ```
2826     ///
2827     /// All kinds of ASCII whitespace are considered:
2828     ///
2829     /// ```
2830     /// let mut iter = " Mary   had\ta little  \n\t lamb".split_ascii_whitespace();
2831     /// assert_eq!(Some("Mary"), iter.next());
2832     /// assert_eq!(Some("had"), iter.next());
2833     /// assert_eq!(Some("a"), iter.next());
2834     /// assert_eq!(Some("little"), iter.next());
2835     /// assert_eq!(Some("lamb"), iter.next());
2836     ///
2837     /// assert_eq!(None, iter.next());
2838     /// ```
2839     #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
2840     #[inline]
2841     pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
2842         let inner =
2843             self.as_bytes().split(IsAsciiWhitespace).filter(BytesIsNotEmpty).map(UnsafeBytesToStr);
2844         SplitAsciiWhitespace { inner }
2845     }
2846
2847     /// An iterator over the lines of a string, as string slices.
2848     ///
2849     /// Lines are ended with either a newline (`\n`) or a carriage return with
2850     /// a line feed (`\r\n`).
2851     ///
2852     /// The final line ending is optional.
2853     ///
2854     /// # Examples
2855     ///
2856     /// Basic usage:
2857     ///
2858     /// ```
2859     /// let text = "foo\r\nbar\n\nbaz\n";
2860     /// let mut lines = text.lines();
2861     ///
2862     /// assert_eq!(Some("foo"), lines.next());
2863     /// assert_eq!(Some("bar"), lines.next());
2864     /// assert_eq!(Some(""), lines.next());
2865     /// assert_eq!(Some("baz"), lines.next());
2866     ///
2867     /// assert_eq!(None, lines.next());
2868     /// ```
2869     ///
2870     /// The final line ending isn't required:
2871     ///
2872     /// ```
2873     /// let text = "foo\nbar\n\r\nbaz";
2874     /// let mut lines = text.lines();
2875     ///
2876     /// assert_eq!(Some("foo"), lines.next());
2877     /// assert_eq!(Some("bar"), lines.next());
2878     /// assert_eq!(Some(""), lines.next());
2879     /// assert_eq!(Some("baz"), lines.next());
2880     ///
2881     /// assert_eq!(None, lines.next());
2882     /// ```
2883     #[stable(feature = "rust1", since = "1.0.0")]
2884     #[inline]
2885     pub fn lines(&self) -> Lines<'_> {
2886         Lines(self.split_terminator('\n').map(LinesAnyMap))
2887     }
2888
2889     /// An iterator over the lines of a string.
2890     #[stable(feature = "rust1", since = "1.0.0")]
2891     #[rustc_deprecated(since = "1.4.0", reason = "use lines() instead now")]
2892     #[inline]
2893     #[allow(deprecated)]
2894     pub fn lines_any(&self) -> LinesAny<'_> {
2895         LinesAny(self.lines())
2896     }
2897
2898     /// Returns an iterator of `u16` over the string encoded as UTF-16.
2899     ///
2900     /// # Examples
2901     ///
2902     /// Basic usage:
2903     ///
2904     /// ```
2905     /// let text = "Zażółć gęślą jaźń";
2906     ///
2907     /// let utf8_len = text.len();
2908     /// let utf16_len = text.encode_utf16().count();
2909     ///
2910     /// assert!(utf16_len <= utf8_len);
2911     /// ```
2912     #[stable(feature = "encode_utf16", since = "1.8.0")]
2913     pub fn encode_utf16(&self) -> EncodeUtf16<'_> {
2914         EncodeUtf16 { chars: self.chars(), extra: 0 }
2915     }
2916
2917     /// Returns `true` if the given pattern matches a sub-slice of
2918     /// this string slice.
2919     ///
2920     /// Returns `false` if it does not.
2921     ///
2922     /// # Examples
2923     ///
2924     /// Basic usage:
2925     ///
2926     /// ```
2927     /// let bananas = "bananas";
2928     ///
2929     /// assert!(bananas.contains("nana"));
2930     /// assert!(!bananas.contains("apples"));
2931     /// ```
2932     #[stable(feature = "rust1", since = "1.0.0")]
2933     #[inline]
2934     pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
2935         pat.is_contained_in(self)
2936     }
2937
2938     /// Returns `true` if the given pattern matches a prefix of this
2939     /// string slice.
2940     ///
2941     /// Returns `false` if it does not.
2942     ///
2943     /// # Examples
2944     ///
2945     /// Basic usage:
2946     ///
2947     /// ```
2948     /// let bananas = "bananas";
2949     ///
2950     /// assert!(bananas.starts_with("bana"));
2951     /// assert!(!bananas.starts_with("nana"));
2952     /// ```
2953     #[stable(feature = "rust1", since = "1.0.0")]
2954     pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
2955         pat.is_prefix_of(self)
2956     }
2957
2958     /// Returns `true` if the given pattern matches a suffix of this
2959     /// string slice.
2960     ///
2961     /// Returns `false` if it does not.
2962     ///
2963     /// # Examples
2964     ///
2965     /// Basic usage:
2966     ///
2967     /// ```
2968     /// let bananas = "bananas";
2969     ///
2970     /// assert!(bananas.ends_with("anas"));
2971     /// assert!(!bananas.ends_with("nana"));
2972     /// ```
2973     #[stable(feature = "rust1", since = "1.0.0")]
2974     pub fn ends_with<'a, P>(&'a self, pat: P) -> bool
2975     where
2976         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
2977     {
2978         pat.is_suffix_of(self)
2979     }
2980
2981     /// Returns the byte index of the first character of this string slice that
2982     /// matches the pattern.
2983     ///
2984     /// Returns [`None`] if the pattern doesn't match.
2985     ///
2986     /// The pattern can be a `&str`, [`char`], or a closure that determines if
2987     /// a character matches.
2988     ///
2989     /// [`None`]: option/enum.Option.html#variant.None
2990     ///
2991     /// # Examples
2992     ///
2993     /// Simple patterns:
2994     ///
2995     /// ```
2996     /// let s = "Löwe 老虎 Léopard";
2997     ///
2998     /// assert_eq!(s.find('L'), Some(0));
2999     /// assert_eq!(s.find('é'), Some(14));
3000     /// assert_eq!(s.find("Léopard"), Some(13));
3001     /// ```
3002     ///
3003     /// More complex patterns using point-free style and closures:
3004     ///
3005     /// ```
3006     /// let s = "Löwe 老虎 Léopard";
3007     ///
3008     /// assert_eq!(s.find(char::is_whitespace), Some(5));
3009     /// assert_eq!(s.find(char::is_lowercase), Some(1));
3010     /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
3011     /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
3012     /// ```
3013     ///
3014     /// Not finding the pattern:
3015     ///
3016     /// ```
3017     /// let s = "Löwe 老虎 Léopard";
3018     /// let x: &[_] = &['1', '2'];
3019     ///
3020     /// assert_eq!(s.find(x), None);
3021     /// ```
3022     #[stable(feature = "rust1", since = "1.0.0")]
3023     #[inline]
3024     pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize> {
3025         pat.into_searcher(self).next_match().map(|(i, _)| i)
3026     }
3027
3028     /// Returns the byte index of the last character of this string slice that
3029     /// matches the pattern.
3030     ///
3031     /// Returns [`None`] if the pattern doesn't match.
3032     ///
3033     /// The pattern can be a `&str`, [`char`], or a closure that determines if
3034     /// a character matches.
3035     ///
3036     /// [`None`]: option/enum.Option.html#variant.None
3037     ///
3038     /// # Examples
3039     ///
3040     /// Simple patterns:
3041     ///
3042     /// ```
3043     /// let s = "Löwe 老虎 Léopard";
3044     ///
3045     /// assert_eq!(s.rfind('L'), Some(13));
3046     /// assert_eq!(s.rfind('é'), Some(14));
3047     /// ```
3048     ///
3049     /// More complex patterns with closures:
3050     ///
3051     /// ```
3052     /// let s = "Löwe 老虎 Léopard";
3053     ///
3054     /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
3055     /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
3056     /// ```
3057     ///
3058     /// Not finding the pattern:
3059     ///
3060     /// ```
3061     /// let s = "Löwe 老虎 Léopard";
3062     /// let x: &[_] = &['1', '2'];
3063     ///
3064     /// assert_eq!(s.rfind(x), None);
3065     /// ```
3066     #[stable(feature = "rust1", since = "1.0.0")]
3067     #[inline]
3068     pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
3069     where
3070         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3071     {
3072         pat.into_searcher(self).next_match_back().map(|(i, _)| i)
3073     }
3074
3075     /// An iterator over substrings of this string slice, separated by
3076     /// characters matched by a pattern.
3077     ///
3078     /// The pattern can be any type that implements the Pattern trait. Notable
3079     /// examples are `&str`, [`char`], and closures that determines the split.
3080     ///
3081     /// # Iterator behavior
3082     ///
3083     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3084     /// allows a reverse search and forward/reverse search yields the same
3085     /// elements. This is true for, e.g., [`char`], but not for `&str`.
3086     ///
3087     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3088     ///
3089     /// If the pattern allows a reverse search but its results might differ
3090     /// from a forward search, the [`rsplit`] method can be used.
3091     ///
3092     /// [`rsplit`]: #method.rsplit
3093     ///
3094     /// # Examples
3095     ///
3096     /// Simple patterns:
3097     ///
3098     /// ```
3099     /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
3100     /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
3101     ///
3102     /// let v: Vec<&str> = "".split('X').collect();
3103     /// assert_eq!(v, [""]);
3104     ///
3105     /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
3106     /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
3107     ///
3108     /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
3109     /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3110     ///
3111     /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
3112     /// assert_eq!(v, ["abc", "def", "ghi"]);
3113     ///
3114     /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
3115     /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3116     /// ```
3117     ///
3118     /// A more complex pattern, using a closure:
3119     ///
3120     /// ```
3121     /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
3122     /// assert_eq!(v, ["abc", "def", "ghi"]);
3123     /// ```
3124     ///
3125     /// If a string contains multiple contiguous separators, you will end up
3126     /// with empty strings in the output:
3127     ///
3128     /// ```
3129     /// let x = "||||a||b|c".to_string();
3130     /// let d: Vec<_> = x.split('|').collect();
3131     ///
3132     /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3133     /// ```
3134     ///
3135     /// Contiguous separators are separated by the empty string.
3136     ///
3137     /// ```
3138     /// let x = "(///)".to_string();
3139     /// let d: Vec<_> = x.split('/').collect();
3140     ///
3141     /// assert_eq!(d, &["(", "", "", ")"]);
3142     /// ```
3143     ///
3144     /// Separators at the start or end of a string are neighbored
3145     /// by empty strings.
3146     ///
3147     /// ```
3148     /// let d: Vec<_> = "010".split("0").collect();
3149     /// assert_eq!(d, &["", "1", ""]);
3150     /// ```
3151     ///
3152     /// When the empty string is used as a separator, it separates
3153     /// every character in the string, along with the beginning
3154     /// and end of the string.
3155     ///
3156     /// ```
3157     /// let f: Vec<_> = "rust".split("").collect();
3158     /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
3159     /// ```
3160     ///
3161     /// Contiguous separators can lead to possibly surprising behavior
3162     /// when whitespace is used as the separator. This code is correct:
3163     ///
3164     /// ```
3165     /// let x = "    a  b c".to_string();
3166     /// let d: Vec<_> = x.split(' ').collect();
3167     ///
3168     /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3169     /// ```
3170     ///
3171     /// It does _not_ give you:
3172     ///
3173     /// ```,ignore
3174     /// assert_eq!(d, &["a", "b", "c"]);
3175     /// ```
3176     ///
3177     /// Use [`split_whitespace`] for this behavior.
3178     ///
3179     /// [`split_whitespace`]: #method.split_whitespace
3180     #[stable(feature = "rust1", since = "1.0.0")]
3181     #[inline]
3182     pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> {
3183         Split(SplitInternal {
3184             start: 0,
3185             end: self.len(),
3186             matcher: pat.into_searcher(self),
3187             allow_trailing_empty: true,
3188             finished: false,
3189         })
3190     }
3191
3192     /// An iterator over substrings of the given string slice, separated by
3193     /// characters matched by a pattern and yielded in reverse order.
3194     ///
3195     /// The pattern can be any type that implements the Pattern trait. Notable
3196     /// examples are `&str`, [`char`], and closures that determines the split.
3197     ///
3198     /// # Iterator behavior
3199     ///
3200     /// The returned iterator requires that the pattern supports a reverse
3201     /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3202     /// search yields the same elements.
3203     ///
3204     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3205     ///
3206     /// For iterating from the front, the [`split`] method can be used.
3207     ///
3208     /// [`split`]: #method.split
3209     ///
3210     /// # Examples
3211     ///
3212     /// Simple patterns:
3213     ///
3214     /// ```
3215     /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
3216     /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
3217     ///
3218     /// let v: Vec<&str> = "".rsplit('X').collect();
3219     /// assert_eq!(v, [""]);
3220     ///
3221     /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
3222     /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
3223     ///
3224     /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
3225     /// assert_eq!(v, ["leopard", "tiger", "lion"]);
3226     /// ```
3227     ///
3228     /// A more complex pattern, using a closure:
3229     ///
3230     /// ```
3231     /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
3232     /// assert_eq!(v, ["ghi", "def", "abc"]);
3233     /// ```
3234     #[stable(feature = "rust1", since = "1.0.0")]
3235     #[inline]
3236     pub fn rsplit<'a, P>(&'a self, pat: P) -> RSplit<'a, P>
3237     where
3238         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3239     {
3240         RSplit(self.split(pat).0)
3241     }
3242
3243     /// An iterator over substrings of the given string slice, separated by
3244     /// characters matched by a pattern.
3245     ///
3246     /// The pattern can be any type that implements the Pattern trait. Notable
3247     /// examples are `&str`, [`char`], and closures that determines the split.
3248     ///
3249     /// Equivalent to [`split`], except that the trailing substring
3250     /// is skipped if empty.
3251     ///
3252     /// [`split`]: #method.split
3253     ///
3254     /// This method can be used for string data that is _terminated_,
3255     /// rather than _separated_ by a pattern.
3256     ///
3257     /// # Iterator behavior
3258     ///
3259     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3260     /// allows a reverse search and forward/reverse search yields the same
3261     /// elements. This is true for, e.g., [`char`], but not for `&str`.
3262     ///
3263     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3264     ///
3265     /// If the pattern allows a reverse search but its results might differ
3266     /// from a forward search, the [`rsplit_terminator`] method can be used.
3267     ///
3268     /// [`rsplit_terminator`]: #method.rsplit_terminator
3269     ///
3270     /// # Examples
3271     ///
3272     /// Basic usage:
3273     ///
3274     /// ```
3275     /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
3276     /// assert_eq!(v, ["A", "B"]);
3277     ///
3278     /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
3279     /// assert_eq!(v, ["A", "", "B", ""]);
3280     /// ```
3281     #[stable(feature = "rust1", since = "1.0.0")]
3282     #[inline]
3283     pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
3284         SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
3285     }
3286
3287     /// An iterator over substrings of `self`, separated by characters
3288     /// matched by a pattern and yielded in reverse order.
3289     ///
3290     /// The pattern can be any type that implements the Pattern trait. Notable
3291     /// examples are `&str`, [`char`], and closures that determines the split.
3292     /// Additional libraries might provide more complex patterns like
3293     /// regular expressions.
3294     ///
3295     /// Equivalent to [`split`], except that the trailing substring is
3296     /// skipped if empty.
3297     ///
3298     /// [`split`]: #method.split
3299     ///
3300     /// This method can be used for string data that is _terminated_,
3301     /// rather than _separated_ by a pattern.
3302     ///
3303     /// # Iterator behavior
3304     ///
3305     /// The returned iterator requires that the pattern supports a
3306     /// reverse search, and it will be double ended if a forward/reverse
3307     /// search yields the same elements.
3308     ///
3309     /// For iterating from the front, the [`split_terminator`] method can be
3310     /// used.
3311     ///
3312     /// [`split_terminator`]: #method.split_terminator
3313     ///
3314     /// # Examples
3315     ///
3316     /// ```
3317     /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
3318     /// assert_eq!(v, ["B", "A"]);
3319     ///
3320     /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
3321     /// assert_eq!(v, ["", "B", "", "A"]);
3322     /// ```
3323     #[stable(feature = "rust1", since = "1.0.0")]
3324     #[inline]
3325     pub fn rsplit_terminator<'a, P>(&'a self, pat: P) -> RSplitTerminator<'a, P>
3326     where
3327         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3328     {
3329         RSplitTerminator(self.split_terminator(pat).0)
3330     }
3331
3332     /// An iterator over substrings of the given string slice, separated by a
3333     /// pattern, restricted to returning at most `n` items.
3334     ///
3335     /// If `n` substrings are returned, the last substring (the `n`th substring)
3336     /// will contain the remainder of the string.
3337     ///
3338     /// The pattern can be any type that implements the Pattern trait. Notable
3339     /// examples are `&str`, [`char`], and closures that determines the split.
3340     ///
3341     /// # Iterator behavior
3342     ///
3343     /// The returned iterator will not be double ended, because it is
3344     /// not efficient to support.
3345     ///
3346     /// If the pattern allows a reverse search, the [`rsplitn`] method can be
3347     /// used.
3348     ///
3349     /// [`rsplitn`]: #method.rsplitn
3350     ///
3351     /// # Examples
3352     ///
3353     /// Simple patterns:
3354     ///
3355     /// ```
3356     /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
3357     /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
3358     ///
3359     /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
3360     /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
3361     ///
3362     /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
3363     /// assert_eq!(v, ["abcXdef"]);
3364     ///
3365     /// let v: Vec<&str> = "".splitn(1, 'X').collect();
3366     /// assert_eq!(v, [""]);
3367     /// ```
3368     ///
3369     /// A more complex pattern, using a closure:
3370     ///
3371     /// ```
3372     /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
3373     /// assert_eq!(v, ["abc", "defXghi"]);
3374     /// ```
3375     #[stable(feature = "rust1", since = "1.0.0")]
3376     #[inline]
3377     pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> {
3378         SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
3379     }
3380
3381     /// An iterator over substrings of this string slice, separated by a
3382     /// pattern, starting from the end of the string, restricted to returning
3383     /// at most `n` items.
3384     ///
3385     /// If `n` substrings are returned, the last substring (the `n`th substring)
3386     /// will contain the remainder of the string.
3387     ///
3388     /// The pattern can be any type that implements the Pattern trait. Notable
3389     /// examples are `&str`, [`char`], and closures that determines the split.
3390     ///
3391     /// # Iterator behavior
3392     ///
3393     /// The returned iterator will not be double ended, because it is not
3394     /// efficient to support.
3395     ///
3396     /// For splitting from the front, the [`splitn`] method can be used.
3397     ///
3398     /// [`splitn`]: #method.splitn
3399     ///
3400     /// # Examples
3401     ///
3402     /// Simple patterns:
3403     ///
3404     /// ```
3405     /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
3406     /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
3407     ///
3408     /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
3409     /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
3410     ///
3411     /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
3412     /// assert_eq!(v, ["leopard", "lion::tiger"]);
3413     /// ```
3414     ///
3415     /// A more complex pattern, using a closure:
3416     ///
3417     /// ```
3418     /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
3419     /// assert_eq!(v, ["ghi", "abc1def"]);
3420     /// ```
3421     #[stable(feature = "rust1", since = "1.0.0")]
3422     #[inline]
3423     pub fn rsplitn<'a, P>(&'a self, n: usize, pat: P) -> RSplitN<'a, P>
3424     where
3425         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3426     {
3427         RSplitN(self.splitn(n, pat).0)
3428     }
3429
3430     /// An iterator over the disjoint matches of a pattern within the given string
3431     /// slice.
3432     ///
3433     /// The pattern can be a `&str`, [`char`], or a closure that determines if
3434     /// a character matches.
3435     ///
3436     /// # Iterator behavior
3437     ///
3438     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3439     /// allows a reverse search and forward/reverse search yields the same
3440     /// elements. This is true for, e.g., [`char`], but not for `&str`.
3441     ///
3442     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3443     ///
3444     /// If the pattern allows a reverse search but its results might differ
3445     /// from a forward search, the [`rmatches`] method can be used.
3446     ///
3447     /// [`rmatches`]: #method.rmatches
3448     ///
3449     /// # Examples
3450     ///
3451     /// Basic usage:
3452     ///
3453     /// ```
3454     /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
3455     /// assert_eq!(v, ["abc", "abc", "abc"]);
3456     ///
3457     /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
3458     /// assert_eq!(v, ["1", "2", "3"]);
3459     /// ```
3460     #[stable(feature = "str_matches", since = "1.2.0")]
3461     #[inline]
3462     pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> {
3463         Matches(MatchesInternal(pat.into_searcher(self)))
3464     }
3465
3466     /// An iterator over the disjoint matches of a pattern within this string slice,
3467     /// yielded in reverse order.
3468     ///
3469     /// The pattern can be a `&str`, [`char`], or a closure that determines if
3470     /// a character matches.
3471     ///
3472     /// # Iterator behavior
3473     ///
3474     /// The returned iterator requires that the pattern supports a reverse
3475     /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3476     /// search yields the same elements.
3477     ///
3478     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3479     ///
3480     /// For iterating from the front, the [`matches`] method can be used.
3481     ///
3482     /// [`matches`]: #method.matches
3483     ///
3484     /// # Examples
3485     ///
3486     /// Basic usage:
3487     ///
3488     /// ```
3489     /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
3490     /// assert_eq!(v, ["abc", "abc", "abc"]);
3491     ///
3492     /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
3493     /// assert_eq!(v, ["3", "2", "1"]);
3494     /// ```
3495     #[stable(feature = "str_matches", since = "1.2.0")]
3496     #[inline]
3497     pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
3498     where
3499         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3500     {
3501         RMatches(self.matches(pat).0)
3502     }
3503
3504     /// An iterator over the disjoint matches of a pattern within this string
3505     /// slice as well as the index that the match starts at.
3506     ///
3507     /// For matches of `pat` within `self` that overlap, only the indices
3508     /// corresponding to the first match are returned.
3509     ///
3510     /// The pattern can be a `&str`, [`char`], or a closure that determines
3511     /// if a character matches.
3512     ///
3513     /// # Iterator behavior
3514     ///
3515     /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3516     /// allows a reverse search and forward/reverse search yields the same
3517     /// elements. This is true for, e.g., [`char`], but not for `&str`.
3518     ///
3519     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3520     ///
3521     /// If the pattern allows a reverse search but its results might differ
3522     /// from a forward search, the [`rmatch_indices`] method can be used.
3523     ///
3524     /// [`rmatch_indices`]: #method.rmatch_indices
3525     ///
3526     /// # Examples
3527     ///
3528     /// Basic usage:
3529     ///
3530     /// ```
3531     /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
3532     /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
3533     ///
3534     /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
3535     /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
3536     ///
3537     /// let v: Vec<_> = "ababa".match_indices("aba").collect();
3538     /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
3539     /// ```
3540     #[stable(feature = "str_match_indices", since = "1.5.0")]
3541     #[inline]
3542     pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> {
3543         MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
3544     }
3545
3546     /// An iterator over the disjoint matches of a pattern within `self`,
3547     /// yielded in reverse order along with the index of the match.
3548     ///
3549     /// For matches of `pat` within `self` that overlap, only the indices
3550     /// corresponding to the last match are returned.
3551     ///
3552     /// The pattern can be a `&str`, [`char`], or a closure that determines if a
3553     /// character matches.
3554     ///
3555     /// # Iterator behavior
3556     ///
3557     /// The returned iterator requires that the pattern supports a reverse
3558     /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3559     /// search yields the same elements.
3560     ///
3561     /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3562     ///
3563     /// For iterating from the front, the [`match_indices`] method can be used.
3564     ///
3565     /// [`match_indices`]: #method.match_indices
3566     ///
3567     /// # Examples
3568     ///
3569     /// Basic usage:
3570     ///
3571     /// ```
3572     /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
3573     /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
3574     ///
3575     /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
3576     /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
3577     ///
3578     /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
3579     /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
3580     /// ```
3581     #[stable(feature = "str_match_indices", since = "1.5.0")]
3582     #[inline]
3583     pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
3584     where
3585         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3586     {
3587         RMatchIndices(self.match_indices(pat).0)
3588     }
3589
3590     /// Returns a string slice with leading and trailing whitespace removed.
3591     ///
3592     /// 'Whitespace' is defined according to the terms of the Unicode Derived
3593     /// Core Property `White_Space`.
3594     ///
3595     /// # Examples
3596     ///
3597     /// Basic usage:
3598     ///
3599     /// ```
3600     /// let s = " Hello\tworld\t";
3601     ///
3602     /// assert_eq!("Hello\tworld", s.trim());
3603     /// ```
3604     #[must_use = "this returns the trimmed string as a slice, \
3605                   without modifying the original"]
3606     #[stable(feature = "rust1", since = "1.0.0")]
3607     pub fn trim(&self) -> &str {
3608         self.trim_matches(|c: char| c.is_whitespace())
3609     }
3610
3611     /// Returns a string slice with leading whitespace removed.
3612     ///
3613     /// 'Whitespace' is defined according to the terms of the Unicode Derived
3614     /// Core Property `White_Space`.
3615     ///
3616     /// # Text directionality
3617     ///
3618     /// A string is a sequence of bytes. `start` in this context means the first
3619     /// position of that byte string; for a left-to-right language like English or
3620     /// Russian, this will be left side, and for right-to-left languages like
3621     /// Arabic or Hebrew, this will be the right side.
3622     ///
3623     /// # Examples
3624     ///
3625     /// Basic usage:
3626     ///
3627     /// ```
3628     /// let s = " Hello\tworld\t";
3629     /// assert_eq!("Hello\tworld\t", s.trim_start());
3630     /// ```
3631     ///
3632     /// Directionality:
3633     ///
3634     /// ```
3635     /// let s = "  English  ";
3636     /// assert!(Some('E') == s.trim_start().chars().next());
3637     ///
3638     /// let s = "  עברית  ";
3639     /// assert!(Some('ע') == s.trim_start().chars().next());
3640     /// ```
3641     #[must_use = "this returns the trimmed string as a new slice, \
3642                   without modifying the original"]
3643     #[stable(feature = "trim_direction", since = "1.30.0")]
3644     pub fn trim_start(&self) -> &str {
3645         self.trim_start_matches(|c: char| c.is_whitespace())
3646     }
3647
3648     /// Returns a string slice with trailing whitespace removed.
3649     ///
3650     /// 'Whitespace' is defined according to the terms of the Unicode Derived
3651     /// Core Property `White_Space`.
3652     ///
3653     /// # Text directionality
3654     ///
3655     /// A string is a sequence of bytes. `end` in this context means the last
3656     /// position of that byte string; for a left-to-right language like English or
3657     /// Russian, this will be right side, and for right-to-left languages like
3658     /// Arabic or Hebrew, this will be the left side.
3659     ///
3660     /// # Examples
3661     ///
3662     /// Basic usage:
3663     ///
3664     /// ```
3665     /// let s = " Hello\tworld\t";
3666     /// assert_eq!(" Hello\tworld", s.trim_end());
3667     /// ```
3668     ///
3669     /// Directionality:
3670     ///
3671     /// ```
3672     /// let s = "  English  ";
3673     /// assert!(Some('h') == s.trim_end().chars().rev().next());
3674     ///
3675     /// let s = "  עברית  ";
3676     /// assert!(Some('ת') == s.trim_end().chars().rev().next());
3677     /// ```
3678     #[must_use = "this returns the trimmed string as a new slice, \
3679                   without modifying the original"]
3680     #[stable(feature = "trim_direction", since = "1.30.0")]
3681     pub fn trim_end(&self) -> &str {
3682         self.trim_end_matches(|c: char| c.is_whitespace())
3683     }
3684
3685     /// Returns a string slice with leading whitespace removed.
3686     ///
3687     /// 'Whitespace' is defined according to the terms of the Unicode Derived
3688     /// Core Property `White_Space`.
3689     ///
3690     /// # Text directionality
3691     ///
3692     /// A string is a sequence of bytes. 'Left' in this context means the first
3693     /// position of that byte string; for a language like Arabic or Hebrew
3694     /// which are 'right to left' rather than 'left to right', this will be
3695     /// the _right_ side, not the left.
3696     ///
3697     /// # Examples
3698     ///
3699     /// Basic usage:
3700     ///
3701     /// ```
3702     /// let s = " Hello\tworld\t";
3703     ///
3704     /// assert_eq!("Hello\tworld\t", s.trim_left());
3705     /// ```
3706     ///
3707     /// Directionality:
3708     ///
3709     /// ```
3710     /// let s = "  English";
3711     /// assert!(Some('E') == s.trim_left().chars().next());
3712     ///
3713     /// let s = "  עברית";
3714     /// assert!(Some('ע') == s.trim_left().chars().next());
3715     /// ```
3716     #[stable(feature = "rust1", since = "1.0.0")]
3717     #[rustc_deprecated(
3718         since = "1.33.0",
3719         reason = "superseded by `trim_start`",
3720         suggestion = "trim_start"
3721     )]
3722     pub fn trim_left(&self) -> &str {
3723         self.trim_start()
3724     }
3725
3726     /// Returns a string slice with trailing whitespace removed.
3727     ///
3728     /// 'Whitespace' is defined according to the terms of the Unicode Derived
3729     /// Core Property `White_Space`.
3730     ///
3731     /// # Text directionality
3732     ///
3733     /// A string is a sequence of bytes. 'Right' in this context means the last
3734     /// position of that byte string; for a language like Arabic or Hebrew
3735     /// which are 'right to left' rather than 'left to right', this will be
3736     /// the _left_ side, not the right.
3737     ///
3738     /// # Examples
3739     ///
3740     /// Basic usage:
3741     ///
3742     /// ```
3743     /// let s = " Hello\tworld\t";
3744     ///
3745     /// assert_eq!(" Hello\tworld", s.trim_right());
3746     /// ```
3747     ///
3748     /// Directionality:
3749     ///
3750     /// ```
3751     /// let s = "English  ";
3752     /// assert!(Some('h') == s.trim_right().chars().rev().next());
3753     ///
3754     /// let s = "עברית  ";
3755     /// assert!(Some('ת') == s.trim_right().chars().rev().next());
3756     /// ```
3757     #[stable(feature = "rust1", since = "1.0.0")]
3758     #[rustc_deprecated(
3759         since = "1.33.0",
3760         reason = "superseded by `trim_end`",
3761         suggestion = "trim_end"
3762     )]
3763     pub fn trim_right(&self) -> &str {
3764         self.trim_end()
3765     }
3766
3767     /// Returns a string slice with all prefixes and suffixes that match a
3768     /// pattern repeatedly removed.
3769     ///
3770     /// The pattern can be a [`char`] or a closure that determines if a
3771     /// character matches.
3772     ///
3773     /// # Examples
3774     ///
3775     /// Simple patterns:
3776     ///
3777     /// ```
3778     /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
3779     /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
3780     ///
3781     /// let x: &[_] = &['1', '2'];
3782     /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
3783     /// ```
3784     ///
3785     /// A more complex pattern, using a closure:
3786     ///
3787     /// ```
3788     /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
3789     /// ```
3790     #[must_use = "this returns the trimmed string as a new slice, \
3791                   without modifying the original"]
3792     #[stable(feature = "rust1", since = "1.0.0")]
3793     pub fn trim_matches<'a, P>(&'a self, pat: P) -> &'a str
3794     where
3795         P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
3796     {
3797         let mut i = 0;
3798         let mut j = 0;
3799         let mut matcher = pat.into_searcher(self);
3800         if let Some((a, b)) = matcher.next_reject() {
3801             i = a;
3802             j = b; // Remember earliest known match, correct it below if
3803             // last match is different
3804         }
3805         if let Some((_, b)) = matcher.next_reject_back() {
3806             j = b;
3807         }
3808         unsafe {
3809             // Searcher is known to return valid indices
3810             self.get_unchecked(i..j)
3811         }
3812     }
3813
3814     /// Returns a string slice with all prefixes that match a pattern
3815     /// repeatedly removed.
3816     ///
3817     /// The pattern can be a `&str`, [`char`], or a closure that determines if
3818     /// a character matches.
3819     ///
3820     /// # Text directionality
3821     ///
3822     /// A string is a sequence of bytes. `start` in this context means the first
3823     /// position of that byte string; for a left-to-right language like English or
3824     /// Russian, this will be left side, and for right-to-left languages like
3825     /// Arabic or Hebrew, this will be the right side.
3826     ///
3827     /// # Examples
3828     ///
3829     /// Basic usage:
3830     ///
3831     /// ```
3832     /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
3833     /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
3834     ///
3835     /// let x: &[_] = &['1', '2'];
3836     /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
3837     /// ```
3838     #[must_use = "this returns the trimmed string as a new slice, \
3839                   without modifying the original"]
3840     #[stable(feature = "trim_direction", since = "1.30.0")]
3841     pub fn trim_start_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
3842         let mut i = self.len();
3843         let mut matcher = pat.into_searcher(self);
3844         if let Some((a, _)) = matcher.next_reject() {
3845             i = a;
3846         }
3847         unsafe {
3848             // Searcher is known to return valid indices
3849             self.get_unchecked(i..self.len())
3850         }
3851     }
3852
3853     /// Returns a string slice with the prefix removed.
3854     ///
3855     /// If the string starts with the pattern `prefix`, `Some` is returned with the substring where
3856     /// the prefix is removed. Unlike `trim_start_matches`, this method removes the prefix exactly
3857     /// once.
3858     ///
3859     /// If the string does not start with `prefix`, `None` is returned.
3860     ///
3861     /// # Examples
3862     ///
3863     /// ```
3864     /// #![feature(str_strip)]
3865     ///
3866     /// assert_eq!("foobar".strip_prefix("foo"), Some("bar"));
3867     /// assert_eq!("foobar".strip_prefix("bar"), None);
3868     /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
3869     /// ```
3870     #[must_use = "this returns the remaining substring as a new slice, \
3871                   without modifying the original"]
3872     #[unstable(feature = "str_strip", reason = "newly added", issue = "67302")]
3873     pub fn strip_prefix<'a, P: Pattern<'a>>(&'a self, prefix: P) -> Option<&'a str> {
3874         let mut matcher = prefix.into_searcher(self);
3875         if let SearchStep::Match(start, len) = matcher.next() {
3876             debug_assert_eq!(
3877                 start, 0,
3878                 "The first search step from Searcher \
3879                 must include the first character"
3880             );
3881             unsafe {
3882                 // Searcher is known to return valid indices.
3883                 Some(self.get_unchecked(len..))
3884             }
3885         } else {
3886             None
3887         }
3888     }
3889
3890     /// Returns a string slice with the suffix removed.
3891     ///
3892     /// If the string ends with the pattern `suffix`, `Some` is returned with the substring where
3893     /// the suffix is removed. Unlike `trim_end_matches`, this method removes the suffix exactly
3894     /// once.
3895     ///
3896     /// If the string does not end with `suffix`, `None` is returned.
3897     ///
3898     /// # Examples
3899     ///
3900     /// ```
3901     /// #![feature(str_strip)]
3902     /// assert_eq!("barfoo".strip_suffix("foo"), Some("bar"));
3903     /// assert_eq!("barfoo".strip_suffix("bar"), None);
3904     /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
3905     /// ```
3906     #[must_use = "this returns the remaining substring as a new slice, \
3907                   without modifying the original"]
3908     #[unstable(feature = "str_strip", reason = "newly added", issue = "67302")]
3909     pub fn strip_suffix<'a, P>(&'a self, suffix: P) -> Option<&'a str>
3910     where
3911         P: Pattern<'a>,
3912         <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
3913     {
3914         let mut matcher = suffix.into_searcher(self);
3915         if let SearchStep::Match(start, end) = matcher.next_back() {
3916             debug_assert_eq!(
3917                 end,
3918                 self.len(),
3919                 "The first search step from ReverseSearcher \
3920                 must include the last character"
3921             );
3922             unsafe {
3923                 // Searcher is known to return valid indices.
3924                 Some(self.get_unchecked(..start))
3925             }
3926         } else {
3927             None
3928         }
3929     }
3930
3931     /// Returns a string slice with all suffixes that match a pattern
3932     /// repeatedly removed.
3933     ///
3934     /// The pattern can be a `&str`, [`char`], or a closure that
3935     /// determines if a character matches.
3936     ///
3937     /// # Text directionality
3938     ///
3939     /// A string is a sequence of bytes. `end` in this context means the last
3940     /// position of that byte string; for a left-to-right language like English or
3941     /// Russian, this will be right side, and for right-to-left languages like
3942     /// Arabic or Hebrew, this will be the left side.
3943     ///
3944     /// # Examples
3945     ///
3946     /// Simple patterns:
3947     ///
3948     /// ```
3949     /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
3950     /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
3951     ///
3952     /// let x: &[_] = &['1', '2'];
3953     /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
3954     /// ```
3955     ///
3956     /// A more complex pattern, using a closure:
3957     ///
3958     /// ```
3959     /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
3960     /// ```
3961     #[must_use = "this returns the trimmed string as a new slice, \
3962                   without modifying the original"]
3963     #[stable(feature = "trim_direction", since = "1.30.0")]
3964     pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str
3965     where
3966         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3967     {
3968         let mut j = 0;
3969         let mut matcher = pat.into_searcher(self);
3970         if let Some((_, b)) = matcher.next_reject_back() {
3971             j = b;
3972         }
3973         unsafe {
3974             // Searcher is known to return valid indices
3975             self.get_unchecked(0..j)
3976         }
3977     }
3978
3979     /// Returns a string slice with all prefixes that match a pattern
3980     /// repeatedly removed.
3981     ///
3982     /// The pattern can be a `&str`, [`char`], or a closure that determines if
3983     /// a character matches.
3984     ///
3985     /// [`char`]: primitive.char.html
3986     ///
3987     /// # Text directionality
3988     ///
3989     /// A string is a sequence of bytes. 'Left' in this context means the first
3990     /// position of that byte string; for a language like Arabic or Hebrew
3991     /// which are 'right to left' rather than 'left to right', this will be
3992     /// the _right_ side, not the left.
3993     ///
3994     /// # Examples
3995     ///
3996     /// Basic usage:
3997     ///
3998     /// ```
3999     /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
4000     /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
4001     ///
4002     /// let x: &[_] = &['1', '2'];
4003     /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
4004     /// ```
4005     #[stable(feature = "rust1", since = "1.0.0")]
4006     #[rustc_deprecated(
4007         since = "1.33.0",
4008         reason = "superseded by `trim_start_matches`",
4009         suggestion = "trim_start_matches"
4010     )]
4011     pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
4012         self.trim_start_matches(pat)
4013     }
4014
4015     /// Returns a string slice with all suffixes that match a pattern
4016     /// repeatedly removed.
4017     ///
4018     /// The pattern can be a `&str`, [`char`], or a closure that
4019     /// determines if a character matches.
4020     ///
4021     /// [`char`]: primitive.char.html
4022     ///
4023     /// # Text directionality
4024     ///
4025     /// A string is a sequence of bytes. 'Right' in this context means the last
4026     /// position of that byte string; for a language like Arabic or Hebrew
4027     /// which are 'right to left' rather than 'left to right', this will be
4028     /// the _left_ side, not the right.
4029     ///
4030     /// # Examples
4031     ///
4032     /// Simple patterns:
4033     ///
4034     /// ```
4035     /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
4036     /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
4037     ///
4038     /// let x: &[_] = &['1', '2'];
4039     /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
4040     /// ```
4041     ///
4042     /// A more complex pattern, using a closure:
4043     ///
4044     /// ```
4045     /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
4046     /// ```
4047     #[stable(feature = "rust1", since = "1.0.0")]
4048     #[rustc_deprecated(
4049         since = "1.33.0",
4050         reason = "superseded by `trim_end_matches`",
4051         suggestion = "trim_end_matches"
4052     )]
4053     pub fn trim_right_matches<'a, P>(&'a self, pat: P) -> &'a str
4054     where
4055         P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
4056     {
4057         self.trim_end_matches(pat)
4058     }
4059
4060     /// Parses this string slice into another type.
4061     ///
4062     /// Because `parse` is so general, it can cause problems with type
4063     /// inference. As such, `parse` is one of the few times you'll see
4064     /// the syntax affectionately known as the 'turbofish': `::<>`. This
4065     /// helps the inference algorithm understand specifically which type
4066     /// you're trying to parse into.
4067     ///
4068     /// `parse` can parse any type that implements the [`FromStr`] trait.
4069     ///
4070     /// [`FromStr`]: str/trait.FromStr.html
4071     ///
4072     /// # Errors
4073     ///
4074     /// Will return [`Err`] if it's not possible to parse this string slice into
4075     /// the desired type.
4076     ///
4077     /// [`Err`]: str/trait.FromStr.html#associatedtype.Err
4078     ///
4079     /// # Examples
4080     ///
4081     /// Basic usage
4082     ///
4083     /// ```
4084     /// let four: u32 = "4".parse().unwrap();
4085     ///
4086     /// assert_eq!(4, four);
4087     /// ```
4088     ///
4089     /// Using the 'turbofish' instead of annotating `four`:
4090     ///
4091     /// ```
4092     /// let four = "4".parse::<u32>();
4093     ///
4094     /// assert_eq!(Ok(4), four);
4095     /// ```
4096     ///
4097     /// Failing to parse:
4098     ///
4099     /// ```
4100     /// let nope = "j".parse::<u32>();
4101     ///
4102     /// assert!(nope.is_err());
4103     /// ```
4104     #[inline]
4105     #[stable(feature = "rust1", since = "1.0.0")]
4106     pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
4107         FromStr::from_str(self)
4108     }
4109
4110     /// Checks if all characters in this string are within the ASCII range.
4111     ///
4112     /// # Examples
4113     ///
4114     /// ```
4115     /// let ascii = "hello!\n";
4116     /// let non_ascii = "Grüße, Jürgen ❤";
4117     ///
4118     /// assert!(ascii.is_ascii());
4119     /// assert!(!non_ascii.is_ascii());
4120     /// ```
4121     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4122     #[inline]
4123     pub fn is_ascii(&self) -> bool {
4124         // We can treat each byte as character here: all multibyte characters
4125         // start with a byte that is not in the ascii range, so we will stop
4126         // there already.
4127         self.bytes().all(|b| b.is_ascii())
4128     }
4129
4130     /// Checks that two strings are an ASCII case-insensitive match.
4131     ///
4132     /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
4133     /// but without allocating and copying temporaries.
4134     ///
4135     /// # Examples
4136     ///
4137     /// ```
4138     /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
4139     /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
4140     /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
4141     /// ```
4142     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4143     #[inline]
4144     pub fn eq_ignore_ascii_case(&self, other: &str) -> bool {
4145         self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
4146     }
4147
4148     /// Converts this string to its ASCII upper case equivalent in-place.
4149     ///
4150     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4151     /// but non-ASCII letters are unchanged.
4152     ///
4153     /// To return a new uppercased value without modifying the existing one, use
4154     /// [`to_ascii_uppercase`].
4155     ///
4156     /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
4157     ///
4158     /// # Examples
4159     ///
4160     /// ```
4161     /// let mut s = String::from("Grüße, Jürgen ❤");
4162     ///
4163     /// s.make_ascii_uppercase();
4164     ///
4165     /// assert_eq!("GRüßE, JüRGEN ❤", s);
4166     /// ```
4167     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4168     pub fn make_ascii_uppercase(&mut self) {
4169         let me = unsafe { self.as_bytes_mut() };
4170         me.make_ascii_uppercase()
4171     }
4172
4173     /// Converts this string to its ASCII lower case equivalent in-place.
4174     ///
4175     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4176     /// but non-ASCII letters are unchanged.
4177     ///
4178     /// To return a new lowercased value without modifying the existing one, use
4179     /// [`to_ascii_lowercase`].
4180     ///
4181     /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
4182     ///
4183     /// # Examples
4184     ///
4185     /// ```
4186     /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
4187     ///
4188     /// s.make_ascii_lowercase();
4189     ///
4190     /// assert_eq!("grÜße, jÜrgen ❤", s);
4191     /// ```
4192     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4193     pub fn make_ascii_lowercase(&mut self) {
4194         let me = unsafe { self.as_bytes_mut() };
4195         me.make_ascii_lowercase()
4196     }
4197
4198     /// Return an iterator that escapes each char in `self` with [`char::escape_debug`].
4199     ///
4200     /// Note: only extended grapheme codepoints that begin the string will be
4201     /// escaped.
4202     ///
4203     /// [`char::escape_debug`]: ../std/primitive.char.html#method.escape_debug
4204     ///
4205     /// # Examples
4206     ///
4207     /// As an iterator:
4208     ///
4209     /// ```
4210     /// for c in "❤\n!".escape_debug() {
4211     ///     print!("{}", c);
4212     /// }
4213     /// println!();
4214     /// ```
4215     ///
4216     /// Using `println!` directly:
4217     ///
4218     /// ```
4219     /// println!("{}", "❤\n!".escape_debug());
4220     /// ```
4221     ///
4222     ///
4223     /// Both are equivalent to:
4224     ///
4225     /// ```
4226     /// println!("❤\\n!");
4227     /// ```
4228     ///
4229     /// Using `to_string`:
4230     ///
4231     /// ```
4232     /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
4233     /// ```
4234     #[stable(feature = "str_escape", since = "1.34.0")]
4235     pub fn escape_debug(&self) -> EscapeDebug<'_> {
4236         let mut chars = self.chars();
4237         EscapeDebug {
4238             inner: chars
4239                 .next()
4240                 .map(|first| first.escape_debug_ext(true))
4241                 .into_iter()
4242                 .flatten()
4243                 .chain(chars.flat_map(CharEscapeDebugContinue)),
4244         }
4245     }
4246
4247     /// Return an iterator that escapes each char in `self` with [`char::escape_default`].
4248     ///
4249     /// [`char::escape_default`]: ../std/primitive.char.html#method.escape_default
4250     ///
4251     /// # Examples
4252     ///
4253     /// As an iterator:
4254     ///
4255     /// ```
4256     /// for c in "❤\n!".escape_default() {
4257     ///     print!("{}", c);
4258     /// }
4259     /// println!();
4260     /// ```
4261     ///
4262     /// Using `println!` directly:
4263     ///
4264     /// ```
4265     /// println!("{}", "❤\n!".escape_default());
4266     /// ```
4267     ///
4268     ///
4269     /// Both are equivalent to:
4270     ///
4271     /// ```
4272     /// println!("\\u{{2764}}\\n!");
4273     /// ```
4274     ///
4275     /// Using `to_string`:
4276     ///
4277     /// ```
4278     /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
4279     /// ```
4280     #[stable(feature = "str_escape", since = "1.34.0")]
4281     pub fn escape_default(&self) -> EscapeDefault<'_> {
4282         EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
4283     }
4284
4285     /// Return an iterator that escapes each char in `self` with [`char::escape_unicode`].
4286     ///
4287     /// [`char::escape_unicode`]: ../std/primitive.char.html#method.escape_unicode
4288     ///
4289     /// # Examples
4290     ///
4291     /// As an iterator:
4292     ///
4293     /// ```
4294     /// for c in "❤\n!".escape_unicode() {
4295     ///     print!("{}", c);
4296     /// }
4297     /// println!();
4298     /// ```
4299     ///
4300     /// Using `println!` directly:
4301     ///
4302     /// ```
4303     /// println!("{}", "❤\n!".escape_unicode());
4304     /// ```
4305     ///
4306     ///
4307     /// Both are equivalent to:
4308     ///
4309     /// ```
4310     /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
4311     /// ```
4312     ///
4313     /// Using `to_string`:
4314     ///
4315     /// ```
4316     /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
4317     /// ```
4318     #[stable(feature = "str_escape", since = "1.34.0")]
4319     pub fn escape_unicode(&self) -> EscapeUnicode<'_> {
4320         EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
4321     }
4322 }
4323
4324 impl_fn_for_zst! {
4325     #[derive(Clone)]
4326     struct CharEscapeDebugContinue impl Fn = |c: char| -> char::EscapeDebug {
4327         c.escape_debug_ext(false)
4328     };
4329
4330     #[derive(Clone)]
4331     struct CharEscapeUnicode impl Fn = |c: char| -> char::EscapeUnicode {
4332         c.escape_unicode()
4333     };
4334     #[derive(Clone)]
4335     struct CharEscapeDefault impl Fn = |c: char| -> char::EscapeDefault {
4336         c.escape_default()
4337     };
4338 }
4339
4340 #[stable(feature = "rust1", since = "1.0.0")]
4341 impl AsRef<[u8]> for str {
4342     #[inline]
4343     fn as_ref(&self) -> &[u8] {
4344         self.as_bytes()
4345     }
4346 }
4347
4348 #[stable(feature = "rust1", since = "1.0.0")]
4349 impl Default for &str {
4350     /// Creates an empty str
4351     fn default() -> Self {
4352         ""
4353     }
4354 }
4355
4356 #[stable(feature = "default_mut_str", since = "1.28.0")]
4357 impl Default for &mut str {
4358     /// Creates an empty mutable str
4359     fn default() -> Self {
4360         unsafe { from_utf8_unchecked_mut(&mut []) }
4361     }
4362 }
4363
4364 /// An iterator over the non-whitespace substrings of a string,
4365 /// separated by any amount of whitespace.
4366 ///
4367 /// This struct is created by the [`split_whitespace`] method on [`str`].
4368 /// See its documentation for more.
4369 ///
4370 /// [`split_whitespace`]: ../../std/primitive.str.html#method.split_whitespace
4371 /// [`str`]: ../../std/primitive.str.html
4372 #[stable(feature = "split_whitespace", since = "1.1.0")]
4373 #[derive(Clone, Debug)]
4374 pub struct SplitWhitespace<'a> {
4375     inner: Filter<Split<'a, IsWhitespace>, IsNotEmpty>,
4376 }
4377
4378 /// An iterator over the non-ASCII-whitespace substrings of a string,
4379 /// separated by any amount of ASCII whitespace.
4380 ///
4381 /// This struct is created by the [`split_ascii_whitespace`] method on [`str`].
4382 /// See its documentation for more.
4383 ///
4384 /// [`split_ascii_whitespace`]: ../../std/primitive.str.html#method.split_ascii_whitespace
4385 /// [`str`]: ../../std/primitive.str.html
4386 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4387 #[derive(Clone, Debug)]
4388 pub struct SplitAsciiWhitespace<'a> {
4389     inner: Map<Filter<SliceSplit<'a, u8, IsAsciiWhitespace>, BytesIsNotEmpty>, UnsafeBytesToStr>,
4390 }
4391
4392 impl_fn_for_zst! {
4393     #[derive(Clone)]
4394     struct IsWhitespace impl Fn = |c: char| -> bool {
4395         c.is_whitespace()
4396     };
4397
4398     #[derive(Clone)]
4399     struct IsAsciiWhitespace impl Fn = |byte: &u8| -> bool {
4400         byte.is_ascii_whitespace()
4401     };
4402
4403     #[derive(Clone)]
4404     struct IsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b str| -> bool {
4405         !s.is_empty()
4406     };
4407
4408     #[derive(Clone)]
4409     struct BytesIsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b [u8]| -> bool {
4410         !s.is_empty()
4411     };
4412
4413     #[derive(Clone)]
4414     struct UnsafeBytesToStr impl<'a> Fn = |bytes: &'a [u8]| -> &'a str {
4415         unsafe { from_utf8_unchecked(bytes) }
4416     };
4417 }
4418
4419 #[stable(feature = "split_whitespace", since = "1.1.0")]
4420 impl<'a> Iterator for SplitWhitespace<'a> {
4421     type Item = &'a str;
4422
4423     #[inline]
4424     fn next(&mut self) -> Option<&'a str> {
4425         self.inner.next()
4426     }
4427
4428     #[inline]
4429     fn size_hint(&self) -> (usize, Option<usize>) {
4430         self.inner.size_hint()
4431     }
4432
4433     #[inline]
4434     fn last(mut self) -> Option<&'a str> {
4435         self.next_back()
4436     }
4437 }
4438
4439 #[stable(feature = "split_whitespace", since = "1.1.0")]
4440 impl<'a> DoubleEndedIterator for SplitWhitespace<'a> {
4441     #[inline]
4442     fn next_back(&mut self) -> Option<&'a str> {
4443         self.inner.next_back()
4444     }
4445 }
4446
4447 #[stable(feature = "fused", since = "1.26.0")]
4448 impl FusedIterator for SplitWhitespace<'_> {}
4449
4450 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4451 impl<'a> Iterator for SplitAsciiWhitespace<'a> {
4452     type Item = &'a str;
4453
4454     #[inline]
4455     fn next(&mut self) -> Option<&'a str> {
4456         self.inner.next()
4457     }
4458
4459     #[inline]
4460     fn size_hint(&self) -> (usize, Option<usize>) {
4461         self.inner.size_hint()
4462     }
4463
4464     #[inline]
4465     fn last(mut self) -> Option<&'a str> {
4466         self.next_back()
4467     }
4468 }
4469
4470 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4471 impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a> {
4472     #[inline]
4473     fn next_back(&mut self) -> Option<&'a str> {
4474         self.inner.next_back()
4475     }
4476 }
4477
4478 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4479 impl FusedIterator for SplitAsciiWhitespace<'_> {}
4480
4481 /// An iterator of [`u16`] over the string encoded as UTF-16.
4482 ///
4483 /// [`u16`]: ../../std/primitive.u16.html
4484 ///
4485 /// This struct is created by the [`encode_utf16`] method on [`str`].
4486 /// See its documentation for more.
4487 ///
4488 /// [`encode_utf16`]: ../../std/primitive.str.html#method.encode_utf16
4489 /// [`str`]: ../../std/primitive.str.html
4490 #[derive(Clone)]
4491 #[stable(feature = "encode_utf16", since = "1.8.0")]
4492 pub struct EncodeUtf16<'a> {
4493     chars: Chars<'a>,
4494     extra: u16,
4495 }
4496
4497 #[stable(feature = "collection_debug", since = "1.17.0")]
4498 impl fmt::Debug for EncodeUtf16<'_> {
4499     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4500         f.pad("EncodeUtf16 { .. }")
4501     }
4502 }
4503
4504 #[stable(feature = "encode_utf16", since = "1.8.0")]
4505 impl<'a> Iterator for EncodeUtf16<'a> {
4506     type Item = u16;
4507
4508     #[inline]
4509     fn next(&mut self) -> Option<u16> {
4510         if self.extra != 0 {
4511             let tmp = self.extra;
4512             self.extra = 0;
4513             return Some(tmp);
4514         }
4515
4516         let mut buf = [0; 2];
4517         self.chars.next().map(|ch| {
4518             let n = ch.encode_utf16(&mut buf).len();
4519             if n == 2 {
4520                 self.extra = buf[1];
4521             }
4522             buf[0]
4523         })
4524     }
4525
4526     #[inline]
4527     fn size_hint(&self) -> (usize, Option<usize>) {
4528         let (low, high) = self.chars.size_hint();
4529         // every char gets either one u16 or two u16,
4530         // so this iterator is between 1 or 2 times as
4531         // long as the underlying iterator.
4532         (low, high.and_then(|n| n.checked_mul(2)))
4533     }
4534 }
4535
4536 #[stable(feature = "fused", since = "1.26.0")]
4537 impl FusedIterator for EncodeUtf16<'_> {}
4538
4539 /// The return type of [`str::escape_debug`].
4540 ///
4541 /// [`str::escape_debug`]: ../../std/primitive.str.html#method.escape_debug
4542 #[stable(feature = "str_escape", since = "1.34.0")]
4543 #[derive(Clone, Debug)]
4544 pub struct EscapeDebug<'a> {
4545     inner: Chain<
4546         Flatten<option::IntoIter<char::EscapeDebug>>,
4547         FlatMap<Chars<'a>, char::EscapeDebug, CharEscapeDebugContinue>,
4548     >,
4549 }
4550
4551 /// The return type of [`str::escape_default`].
4552 ///
4553 /// [`str::escape_default`]: ../../std/primitive.str.html#method.escape_default
4554 #[stable(feature = "str_escape", since = "1.34.0")]
4555 #[derive(Clone, Debug)]
4556 pub struct EscapeDefault<'a> {
4557     inner: FlatMap<Chars<'a>, char::EscapeDefault, CharEscapeDefault>,
4558 }
4559
4560 /// The return type of [`str::escape_unicode`].
4561 ///
4562 /// [`str::escape_unicode`]: ../../std/primitive.str.html#method.escape_unicode
4563 #[stable(feature = "str_escape", since = "1.34.0")]
4564 #[derive(Clone, Debug)]
4565 pub struct EscapeUnicode<'a> {
4566     inner: FlatMap<Chars<'a>, char::EscapeUnicode, CharEscapeUnicode>,
4567 }
4568
4569 macro_rules! escape_types_impls {
4570     ($( $Name: ident ),+) => {$(
4571         #[stable(feature = "str_escape", since = "1.34.0")]
4572         impl<'a> fmt::Display for $Name<'a> {
4573             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4574                 self.clone().try_for_each(|c| f.write_char(c))
4575             }
4576         }
4577
4578         #[stable(feature = "str_escape", since = "1.34.0")]
4579         impl<'a> Iterator for $Name<'a> {
4580             type Item = char;
4581
4582             #[inline]
4583             fn next(&mut self) -> Option<char> { self.inner.next() }
4584
4585             #[inline]
4586             fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
4587
4588             #[inline]
4589             fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
4590                 Self: Sized, Fold: FnMut(Acc, Self::Item) -> R, R: Try<Ok=Acc>
4591             {
4592                 self.inner.try_fold(init, fold)
4593             }
4594
4595             #[inline]
4596             fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
4597                 where Fold: FnMut(Acc, Self::Item) -> Acc,
4598             {
4599                 self.inner.fold(init, fold)
4600             }
4601         }
4602
4603         #[stable(feature = "str_escape", since = "1.34.0")]
4604         impl<'a> FusedIterator for $Name<'a> {}
4605     )+}
4606 }
4607
4608 escape_types_impls!(EscapeDebug, EscapeDefault, EscapeUnicode);