src/libcore/str/mod.rs

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