src/libcore/str/mod.rs

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