library/core/src/str/mod.rs

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