library/core/src/str/iter.rs

   1 //! Iterators for `str` methods.
   2
   3 use crate::char;
   4 use crate::fmt::{self, Write};
   5 use crate::iter::{Chain, FlatMap, Flatten};
   6 use crate::iter::{Copied, Filter, FusedIterator, Map, TrustedLen};
   7 use crate::iter::{TrustedRandomAccess, TrustedRandomAccessNoCoerce};
   8 use crate::ops::Try;
   9 use crate::option;
  10 use crate::slice::{self, Split as SliceSplit};
  11
  12 use super::from_utf8_unchecked;
  13 use super::pattern::Pattern;
  14 use super::pattern::{DoubleEndedSearcher, ReverseSearcher, Searcher};
  15 use super::validations::{next_code_point, next_code_point_reverse};
  16 use super::LinesAnyMap;
  17 use super::{BytesIsNotEmpty, UnsafeBytesToStr};
  18 use super::{CharEscapeDebugContinue, CharEscapeDefault, CharEscapeUnicode};
  19 use super::{IsAsciiWhitespace, IsNotEmpty, IsWhitespace};
  20
  21 /// An iterator over the [`char`]s of a string slice.
  22 ///
  23 ///
  24 /// This struct is created by the [`chars`] method on [`str`].
  25 /// See its documentation for more.
  26 ///
  27 /// [`char`]: prim@char
  28 /// [`chars`]: str::chars
  29 #[derive(Clone)]
  30 #[must_use = "iterators are lazy and do nothing unless consumed"]
  31 #[stable(feature = "rust1", since = "1.0.0")]
  32 pub struct Chars<'a> {
  33     pub(super) iter: slice::Iter<'a, u8>,
  34 }
  35
  36 #[stable(feature = "rust1", since = "1.0.0")]
  37 impl<'a> Iterator for Chars<'a> {
  38     type Item = char;
  39
  40     #[inline]
  41     fn next(&mut self) -> Option<char> {
  42         // SAFETY: `str` invariant says `self.iter` is a valid UTF-8 string and
  43         // the resulting `ch` is a valid Unicode Scalar Value.
  44         unsafe { next_code_point(&mut self.iter).map(|ch| char::from_u32_unchecked(ch)) }
  45     }
  46
  47     #[inline]
  48     fn count(self) -> usize {
  49         super::count::count_chars(self.as_str())
  50     }
  51
  52     #[inline]
  53     fn size_hint(&self) -> (usize, Option<usize>) {
  54         let len = self.iter.len();
  55         // `(len + 3)` can't overflow, because we know that the `slice::Iter`
  56         // belongs to a slice in memory which has a maximum length of
  57         // `isize::MAX` (that's well below `usize::MAX`).
  58         ((len + 3) / 4, Some(len))
  59     }
  60
  61     #[inline]
  62     fn last(mut self) -> Option<char> {
  63         // No need to go through the entire string.
  64         self.next_back()
  65     }
  66 }
  67
  68 #[stable(feature = "chars_debug_impl", since = "1.38.0")]
  69 impl fmt::Debug for Chars<'_> {
  70     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  71         write!(f, "Chars(")?;
  72         f.debug_list().entries(self.clone()).finish()?;
  73         write!(f, ")")?;
  74         Ok(())
  75     }
  76 }
  77
  78 #[stable(feature = "rust1", since = "1.0.0")]
  79 impl<'a> DoubleEndedIterator for Chars<'a> {
  80     #[inline]
  81     fn next_back(&mut self) -> Option<char> {
  82         // SAFETY: `str` invariant says `self.iter` is a valid UTF-8 string and
  83         // the resulting `ch` is a valid Unicode Scalar Value.
  84         unsafe { next_code_point_reverse(&mut self.iter).map(|ch| char::from_u32_unchecked(ch)) }
  85     }
  86 }
  87
  88 #[stable(feature = "fused", since = "1.26.0")]
  89 impl FusedIterator for Chars<'_> {}
  90
  91 impl<'a> Chars<'a> {
  92     /// Views the underlying data as a subslice of the original data.
  93     ///
  94     /// This has the same lifetime as the original slice, and so the
  95     /// iterator can continue to be used while this exists.
  96     ///
  97     /// # Examples
  98     ///
  99     /// ```
 100     /// let mut chars = "abc".chars();
 101     ///
 102     /// assert_eq!(chars.as_str(), "abc");
 103     /// chars.next();
 104     /// assert_eq!(chars.as_str(), "bc");
 105     /// chars.next();
 106     /// chars.next();
 107     /// assert_eq!(chars.as_str(), "");
 108     /// ```
 109     #[stable(feature = "iter_to_slice", since = "1.4.0")]
 110     #[must_use]
 111     #[inline]
 112     pub fn as_str(&self) -> &'a str {
 113         // SAFETY: `Chars` is only made from a str, which guarantees the iter is valid UTF-8.
 114         unsafe { from_utf8_unchecked(self.iter.as_slice()) }
 115     }
 116 }
 117
 118 /// An iterator over the [`char`]s of a string slice, and their positions.
 119 ///
 120 /// This struct is created by the [`char_indices`] method on [`str`].
 121 /// See its documentation for more.
 122 ///
 123 /// [`char`]: prim@char
 124 /// [`char_indices`]: str::char_indices
 125 #[derive(Clone, Debug)]
 126 #[must_use = "iterators are lazy and do nothing unless consumed"]
 127 #[stable(feature = "rust1", since = "1.0.0")]
 128 pub struct CharIndices<'a> {
 129     pub(super) front_offset: usize,
 130     pub(super) iter: Chars<'a>,
 131 }
 132
 133 #[stable(feature = "rust1", since = "1.0.0")]
 134 impl<'a> Iterator for CharIndices<'a> {
 135     type Item = (usize, char);
 136
 137     #[inline]
 138     fn next(&mut self) -> Option<(usize, char)> {
 139         let pre_len = self.iter.iter.len();
 140         match self.iter.next() {
 141             None => None,
 142             Some(ch) => {
 143                 let index = self.front_offset;
 144                 let len = self.iter.iter.len();
 145                 self.front_offset += pre_len - len;
 146                 Some((index, ch))
 147             }
 148         }
 149     }
 150
 151     #[inline]
 152     fn count(self) -> usize {
 153         self.iter.count()
 154     }
 155
 156     #[inline]
 157     fn size_hint(&self) -> (usize, Option<usize>) {
 158         self.iter.size_hint()
 159     }
 160
 161     #[inline]
 162     fn last(mut self) -> Option<(usize, char)> {
 163         // No need to go through the entire string.
 164         self.next_back()
 165     }
 166 }
 167
 168 #[stable(feature = "rust1", since = "1.0.0")]
 169 impl<'a> DoubleEndedIterator for CharIndices<'a> {
 170     #[inline]
 171     fn next_back(&mut self) -> Option<(usize, char)> {
 172         self.iter.next_back().map(|ch| {
 173             let index = self.front_offset + self.iter.iter.len();
 174             (index, ch)
 175         })
 176     }
 177 }
 178
 179 #[stable(feature = "fused", since = "1.26.0")]
 180 impl FusedIterator for CharIndices<'_> {}
 181
 182 impl<'a> CharIndices<'a> {
 183     /// Views the underlying data as a subslice of the original data.
 184     ///
 185     /// This has the same lifetime as the original slice, and so the
 186     /// iterator can continue to be used while this exists.
 187     #[stable(feature = "iter_to_slice", since = "1.4.0")]
 188     #[must_use]
 189     #[inline]
 190     pub fn as_str(&self) -> &'a str {
 191         self.iter.as_str()
 192     }
 193
 194     /// Returns the byte position of the next character, or the length
 195     /// of the underlying string if there are no more characters.
 196     ///
 197     /// # Examples
 198     ///
 199     /// ```
 200     /// #![feature(char_indices_offset)]
 201     /// let mut chars = "a楽".char_indices();
 202     ///
 203     /// assert_eq!(chars.offset(), 0);
 204     /// assert_eq!(chars.next(), Some((0, 'a')));
 205     ///
 206     /// assert_eq!(chars.offset(), 1);
 207     /// assert_eq!(chars.next(), Some((1, '楽')));
 208     ///
 209     /// assert_eq!(chars.offset(), 4);
 210     /// assert_eq!(chars.next(), None);
 211     /// ```
 212     #[inline]
 213     #[must_use]
 214     #[unstable(feature = "char_indices_offset", issue = "83871")]
 215     pub fn offset(&self) -> usize {
 216         self.front_offset
 217     }
 218 }
 219
 220 /// An iterator over the bytes of a string slice.
 221 ///
 222 /// This struct is created by the [`bytes`] method on [`str`].
 223 /// See its documentation for more.
 224 ///
 225 /// [`bytes`]: str::bytes
 226 #[must_use = "iterators are lazy and do nothing unless consumed"]
 227 #[stable(feature = "rust1", since = "1.0.0")]
 228 #[derive(Clone, Debug)]
 229 pub struct Bytes<'a>(pub(super) Copied<slice::Iter<'a, u8>>);
 230
 231 #[stable(feature = "rust1", since = "1.0.0")]
 232 impl Iterator for Bytes<'_> {
 233     type Item = u8;
 234
 235     #[inline]
 236     fn next(&mut self) -> Option<u8> {
 237         self.0.next()
 238     }
 239
 240     #[inline]
 241     fn size_hint(&self) -> (usize, Option<usize>) {
 242         self.0.size_hint()
 243     }
 244
 245     #[inline]
 246     fn count(self) -> usize {
 247         self.0.count()
 248     }
 249
 250     #[inline]
 251     fn last(self) -> Option<Self::Item> {
 252         self.0.last()
 253     }
 254
 255     #[inline]
 256     fn nth(&mut self, n: usize) -> Option<Self::Item> {
 257         self.0.nth(n)
 258     }
 259
 260     #[inline]
 261     fn all<F>(&mut self, f: F) -> bool
 262     where
 263         F: FnMut(Self::Item) -> bool,
 264     {
 265         self.0.all(f)
 266     }
 267
 268     #[inline]
 269     fn any<F>(&mut self, f: F) -> bool
 270     where
 271         F: FnMut(Self::Item) -> bool,
 272     {
 273         self.0.any(f)
 274     }
 275
 276     #[inline]
 277     fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
 278     where
 279         P: FnMut(&Self::Item) -> bool,
 280     {
 281         self.0.find(predicate)
 282     }
 283
 284     #[inline]
 285     fn position<P>(&mut self, predicate: P) -> Option<usize>
 286     where
 287         P: FnMut(Self::Item) -> bool,
 288     {
 289         self.0.position(predicate)
 290     }
 291
 292     #[inline]
 293     fn rposition<P>(&mut self, predicate: P) -> Option<usize>
 294     where
 295         P: FnMut(Self::Item) -> bool,
 296     {
 297         self.0.rposition(predicate)
 298     }
 299
 300     #[inline]
 301     unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> u8 {
 302         // SAFETY: the caller must uphold the safety contract
 303         // for `Iterator::__iterator_get_unchecked`.
 304         unsafe { self.0.__iterator_get_unchecked(idx) }
 305     }
 306 }
 307
 308 #[stable(feature = "rust1", since = "1.0.0")]
 309 impl DoubleEndedIterator for Bytes<'_> {
 310     #[inline]
 311     fn next_back(&mut self) -> Option<u8> {
 312         self.0.next_back()
 313     }
 314
 315     #[inline]
 316     fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
 317         self.0.nth_back(n)
 318     }
 319
 320     #[inline]
 321     fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
 322     where
 323         P: FnMut(&Self::Item) -> bool,
 324     {
 325         self.0.rfind(predicate)
 326     }
 327 }
 328
 329 #[stable(feature = "rust1", since = "1.0.0")]
 330 impl ExactSizeIterator for Bytes<'_> {
 331     #[inline]
 332     fn len(&self) -> usize {
 333         self.0.len()
 334     }
 335
 336     #[inline]
 337     fn is_empty(&self) -> bool {
 338         self.0.is_empty()
 339     }
 340 }
 341
 342 #[stable(feature = "fused", since = "1.26.0")]
 343 impl FusedIterator for Bytes<'_> {}
 344
 345 #[unstable(feature = "trusted_len", issue = "37572")]
 346 unsafe impl TrustedLen for Bytes<'_> {}
 347
 348 #[doc(hidden)]
 349 #[unstable(feature = "trusted_random_access", issue = "none")]
 350 unsafe impl TrustedRandomAccess for Bytes<'_> {}
 351
 352 #[doc(hidden)]
 353 #[unstable(feature = "trusted_random_access", issue = "none")]
 354 unsafe impl TrustedRandomAccessNoCoerce for Bytes<'_> {
 355     const MAY_HAVE_SIDE_EFFECT: bool = false;
 356 }
 357
 358 /// This macro generates a Clone impl for string pattern API
 359 /// wrapper types of the form X<'a, P>
 360 macro_rules! derive_pattern_clone {
 361     (clone $t:ident with |$s:ident| $e:expr) => {
 362         impl<'a, P> Clone for $t<'a, P>
 363         where
 364             P: Pattern<'a, Searcher: Clone>,
 365         {
 366             fn clone(&self) -> Self {
 367                 let $s = self;
 368                 $e
 369             }
 370         }
 371     };
 372 }
 373
 374 /// This macro generates two public iterator structs
 375 /// wrapping a private internal one that makes use of the `Pattern` API.
 376 ///
 377 /// For all patterns `P: Pattern<'a>` the following items will be
 378 /// generated (generics omitted):
 379 ///
 380 /// struct $forward_iterator($internal_iterator);
 381 /// struct $reverse_iterator($internal_iterator);
 382 ///
 383 /// impl Iterator for $forward_iterator
 384 /// { /* internal ends up calling Searcher::next_match() */ }
 385 ///
 386 /// impl DoubleEndedIterator for $forward_iterator
 387 ///       where P::Searcher: DoubleEndedSearcher
 388 /// { /* internal ends up calling Searcher::next_match_back() */ }
 389 ///
 390 /// impl Iterator for $reverse_iterator
 391 ///       where P::Searcher: ReverseSearcher
 392 /// { /* internal ends up calling Searcher::next_match_back() */ }
 393 ///
 394 /// impl DoubleEndedIterator for $reverse_iterator
 395 ///       where P::Searcher: DoubleEndedSearcher
 396 /// { /* internal ends up calling Searcher::next_match() */ }
 397 ///
 398 /// The internal one is defined outside the macro, and has almost the same
 399 /// semantic as a DoubleEndedIterator by delegating to `pattern::Searcher` and
 400 /// `pattern::ReverseSearcher` for both forward and reverse iteration.
 401 ///
 402 /// "Almost", because a `Searcher` and a `ReverseSearcher` for a given
 403 /// `Pattern` might not return the same elements, so actually implementing
 404 /// `DoubleEndedIterator` for it would be incorrect.
 405 /// (See the docs in `str::pattern` for more details)
 406 ///
 407 /// However, the internal struct still represents a single ended iterator from
 408 /// either end, and depending on pattern is also a valid double ended iterator,
 409 /// so the two wrapper structs implement `Iterator`
 410 /// and `DoubleEndedIterator` depending on the concrete pattern type, leading
 411 /// to the complex impls seen above.
 412 macro_rules! generate_pattern_iterators {
 413     {
 414         // Forward iterator
 415         forward:
 416             $(#[$forward_iterator_attribute:meta])*
 417             struct $forward_iterator:ident;
 418
 419         // Reverse iterator
 420         reverse:
 421             $(#[$reverse_iterator_attribute:meta])*
 422             struct $reverse_iterator:ident;
 423
 424         // Stability of all generated items
 425         stability:
 426             $(#[$common_stability_attribute:meta])*
 427
 428         // Internal almost-iterator that is being delegated to
 429         internal:
 430             $internal_iterator:ident yielding ($iterty:ty);
 431
 432         // Kind of delegation - either single ended or double ended
 433         delegate $($t:tt)*
 434     } => {
 435         $(#[$forward_iterator_attribute])*
 436         $(#[$common_stability_attribute])*
 437         pub struct $forward_iterator<'a, P: Pattern<'a>>(pub(super) $internal_iterator<'a, P>);
 438
 439         $(#[$common_stability_attribute])*
 440         impl<'a, P> fmt::Debug for $forward_iterator<'a, P>
 441         where
 442             P: Pattern<'a, Searcher: fmt::Debug>,
 443         {
 444             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 445                 f.debug_tuple(stringify!($forward_iterator))
 446                     .field(&self.0)
 447                     .finish()
 448             }
 449         }
 450
 451         $(#[$common_stability_attribute])*
 452         impl<'a, P: Pattern<'a>> Iterator for $forward_iterator<'a, P> {
 453             type Item = $iterty;
 454
 455             #[inline]
 456             fn next(&mut self) -> Option<$iterty> {
 457                 self.0.next()
 458             }
 459         }
 460
 461         $(#[$common_stability_attribute])*
 462         impl<'a, P> Clone for $forward_iterator<'a, P>
 463         where
 464             P: Pattern<'a, Searcher: Clone>,
 465         {
 466             fn clone(&self) -> Self {
 467                 $forward_iterator(self.0.clone())
 468             }
 469         }
 470
 471         $(#[$reverse_iterator_attribute])*
 472         $(#[$common_stability_attribute])*
 473         pub struct $reverse_iterator<'a, P: Pattern<'a>>(pub(super) $internal_iterator<'a, P>);
 474
 475         $(#[$common_stability_attribute])*
 476         impl<'a, P> fmt::Debug for $reverse_iterator<'a, P>
 477         where
 478             P: Pattern<'a, Searcher: fmt::Debug>,
 479         {
 480             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 481                 f.debug_tuple(stringify!($reverse_iterator))
 482                     .field(&self.0)
 483                     .finish()
 484             }
 485         }
 486
 487         $(#[$common_stability_attribute])*
 488         impl<'a, P> Iterator for $reverse_iterator<'a, P>
 489         where
 490             P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
 491         {
 492             type Item = $iterty;
 493
 494             #[inline]
 495             fn next(&mut self) -> Option<$iterty> {
 496                 self.0.next_back()
 497             }
 498         }
 499
 500         $(#[$common_stability_attribute])*
 501         impl<'a, P> Clone for $reverse_iterator<'a, P>
 502         where
 503             P: Pattern<'a, Searcher: Clone>,
 504         {
 505             fn clone(&self) -> Self {
 506                 $reverse_iterator(self.0.clone())
 507             }
 508         }
 509
 510         #[stable(feature = "fused", since = "1.26.0")]
 511         impl<'a, P: Pattern<'a>> FusedIterator for $forward_iterator<'a, P> {}
 512
 513         #[stable(feature = "fused", since = "1.26.0")]
 514         impl<'a, P> FusedIterator for $reverse_iterator<'a, P>
 515         where
 516             P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
 517         {}
 518
 519         generate_pattern_iterators!($($t)* with $(#[$common_stability_attribute])*,
 520                                                 $forward_iterator,
 521                                                 $reverse_iterator, $iterty);
 522     };
 523     {
 524         double ended; with $(#[$common_stability_attribute:meta])*,
 525                            $forward_iterator:ident,
 526                            $reverse_iterator:ident, $iterty:ty
 527     } => {
 528         $(#[$common_stability_attribute])*
 529         impl<'a, P> DoubleEndedIterator for $forward_iterator<'a, P>
 530         where
 531             P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
 532         {
 533             #[inline]
 534             fn next_back(&mut self) -> Option<$iterty> {
 535                 self.0.next_back()
 536             }
 537         }
 538
 539         $(#[$common_stability_attribute])*
 540         impl<'a, P> DoubleEndedIterator for $reverse_iterator<'a, P>
 541         where
 542             P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
 543         {
 544             #[inline]
 545             fn next_back(&mut self) -> Option<$iterty> {
 546                 self.0.next()
 547             }
 548         }
 549     };
 550     {
 551         single ended; with $(#[$common_stability_attribute:meta])*,
 552                            $forward_iterator:ident,
 553                            $reverse_iterator:ident, $iterty:ty
 554     } => {}
 555 }
 556
 557 derive_pattern_clone! {
 558     clone SplitInternal
 559     with |s| SplitInternal { matcher: s.matcher.clone(), ..*s }
 560 }
 561
 562 pub(super) struct SplitInternal<'a, P: Pattern<'a>> {
 563     pub(super) start: usize,
 564     pub(super) end: usize,
 565     pub(super) matcher: P::Searcher,
 566     pub(super) allow_trailing_empty: bool,
 567     pub(super) finished: bool,
 568 }
 569
 570 impl<'a, P> fmt::Debug for SplitInternal<'a, P>
 571 where
 572     P: Pattern<'a, Searcher: fmt::Debug>,
 573 {
 574     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 575         f.debug_struct("SplitInternal")
 576             .field("start", &self.start)
 577             .field("end", &self.end)
 578             .field("matcher", &self.matcher)
 579             .field("allow_trailing_empty", &self.allow_trailing_empty)
 580             .field("finished", &self.finished)
 581             .finish()
 582     }
 583 }
 584
 585 impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
 586     #[inline]
 587     fn get_end(&mut self) -> Option<&'a str> {
 588         if !self.finished && (self.allow_trailing_empty || self.end - self.start > 0) {
 589             self.finished = true;
 590             // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
 591             unsafe {
 592                 let string = self.matcher.haystack().get_unchecked(self.start..self.end);
 593                 Some(string)
 594             }
 595         } else {
 596             None
 597         }
 598     }
 599
 600     #[inline]
 601     fn next(&mut self) -> Option<&'a str> {
 602         if self.finished {
 603             return None;
 604         }
 605
 606         let haystack = self.matcher.haystack();
 607         match self.matcher.next_match() {
 608             // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries.
 609             Some((a, b)) => unsafe {
 610                 let elt = haystack.get_unchecked(self.start..a);
 611                 self.start = b;
 612                 Some(elt)
 613             },
 614             None => self.get_end(),
 615         }
 616     }
 617
 618     #[inline]
 619     fn next_inclusive(&mut self) -> Option<&'a str> {
 620         if self.finished {
 621             return None;
 622         }
 623
 624         let haystack = self.matcher.haystack();
 625         match self.matcher.next_match() {
 626             // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary,
 627             // and self.start is either the start of the original string,
 628             // or `b` was assigned to it, so it also lies on unicode boundary.
 629             Some((_, b)) => unsafe {
 630                 let elt = haystack.get_unchecked(self.start..b);
 631                 self.start = b;
 632                 Some(elt)
 633             },
 634             None => self.get_end(),
 635         }
 636     }
 637
 638     #[inline]
 639     fn next_back(&mut self) -> Option<&'a str>
 640     where
 641         P::Searcher: ReverseSearcher<'a>,
 642     {
 643         if self.finished {
 644             return None;
 645         }
 646
 647         if !self.allow_trailing_empty {
 648             self.allow_trailing_empty = true;
 649             match self.next_back() {
 650                 Some(elt) if !elt.is_empty() => return Some(elt),
 651                 _ => {
 652                     if self.finished {
 653                         return None;
 654                     }
 655                 }
 656             }
 657         }
 658
 659         let haystack = self.matcher.haystack();
 660         match self.matcher.next_match_back() {
 661             // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries.
 662             Some((a, b)) => unsafe {
 663                 let elt = haystack.get_unchecked(b..self.end);
 664                 self.end = a;
 665                 Some(elt)
 666             },
 667             // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
 668             None => unsafe {
 669                 self.finished = true;
 670                 Some(haystack.get_unchecked(self.start..self.end))
 671             },
 672         }
 673     }
 674
 675     #[inline]
 676     fn next_back_inclusive(&mut self) -> Option<&'a str>
 677     where
 678         P::Searcher: ReverseSearcher<'a>,
 679     {
 680         if self.finished {
 681             return None;
 682         }
 683
 684         if !self.allow_trailing_empty {
 685             self.allow_trailing_empty = true;
 686             match self.next_back_inclusive() {
 687                 Some(elt) if !elt.is_empty() => return Some(elt),
 688                 _ => {
 689                     if self.finished {
 690                         return None;
 691                     }
 692                 }
 693             }
 694         }
 695
 696         let haystack = self.matcher.haystack();
 697         match self.matcher.next_match_back() {
 698             // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary,
 699             // and self.end is either the end of the original string,
 700             // or `b` was assigned to it, so it also lies on unicode boundary.
 701             Some((_, b)) => unsafe {
 702                 let elt = haystack.get_unchecked(b..self.end);
 703                 self.end = b;
 704                 Some(elt)
 705             },
 706             // SAFETY: self.start is either the start of the original string,
 707             // or start of a substring that represents the part of the string that hasn't
 708             // iterated yet. Either way, it is guaranteed to lie on unicode boundary.
 709             // self.end is either the end of the original string,
 710             // or `b` was assigned to it, so it also lies on unicode boundary.
 711             None => unsafe {
 712                 self.finished = true;
 713                 Some(haystack.get_unchecked(self.start..self.end))
 714             },
 715         }
 716     }
 717
 718     #[inline]
 719     fn as_str(&self) -> &'a str {
 720         // `Self::get_end` doesn't change `self.start`
 721         if self.finished {
 722             return "";
 723         }
 724
 725         // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
 726         unsafe { self.matcher.haystack().get_unchecked(self.start..self.end) }
 727     }
 728 }
 729
 730 generate_pattern_iterators! {
 731     forward:
 732         /// Created with the method [`split`].
 733         ///
 734         /// [`split`]: str::split
 735         struct Split;
 736     reverse:
 737         /// Created with the method [`rsplit`].
 738         ///
 739         /// [`rsplit`]: str::rsplit
 740         struct RSplit;
 741     stability:
 742         #[stable(feature = "rust1", since = "1.0.0")]
 743     internal:
 744         SplitInternal yielding (&'a str);
 745     delegate double ended;
 746 }
 747
 748 impl<'a, P: Pattern<'a>> Split<'a, P> {
 749     /// Returns remainder of the split string
 750     ///
 751     /// # Examples
 752     ///
 753     /// ```
 754     /// #![feature(str_split_as_str)]
 755     /// let mut split = "Mary had a little lamb".split(' ');
 756     /// assert_eq!(split.as_str(), "Mary had a little lamb");
 757     /// split.next();
 758     /// assert_eq!(split.as_str(), "had a little lamb");
 759     /// split.by_ref().for_each(drop);
 760     /// assert_eq!(split.as_str(), "");
 761     /// ```
 762     #[inline]
 763     #[unstable(feature = "str_split_as_str", issue = "77998")]
 764     pub fn as_str(&self) -> &'a str {
 765         self.0.as_str()
 766     }
 767 }
 768
 769 impl<'a, P: Pattern<'a>> RSplit<'a, P> {
 770     /// Returns remainder of the split string
 771     ///
 772     /// # Examples
 773     ///
 774     /// ```
 775     /// #![feature(str_split_as_str)]
 776     /// let mut split = "Mary had a little lamb".rsplit(' ');
 777     /// assert_eq!(split.as_str(), "Mary had a little lamb");
 778     /// split.next();
 779     /// assert_eq!(split.as_str(), "Mary had a little");
 780     /// split.by_ref().for_each(drop);
 781     /// assert_eq!(split.as_str(), "");
 782     /// ```
 783     #[inline]
 784     #[unstable(feature = "str_split_as_str", issue = "77998")]
 785     pub fn as_str(&self) -> &'a str {
 786         self.0.as_str()
 787     }
 788 }
 789
 790 generate_pattern_iterators! {
 791     forward:
 792         /// Created with the method [`split_terminator`].
 793         ///
 794         /// [`split_terminator`]: str::split_terminator
 795         struct SplitTerminator;
 796     reverse:
 797         /// Created with the method [`rsplit_terminator`].
 798         ///
 799         /// [`rsplit_terminator`]: str::rsplit_terminator
 800         struct RSplitTerminator;
 801     stability:
 802         #[stable(feature = "rust1", since = "1.0.0")]
 803     internal:
 804         SplitInternal yielding (&'a str);
 805     delegate double ended;
 806 }
 807
 808 impl<'a, P: Pattern<'a>> SplitTerminator<'a, P> {
 809     /// Returns remainder of the split string
 810     ///
 811     /// # Examples
 812     ///
 813     /// ```
 814     /// #![feature(str_split_as_str)]
 815     /// let mut split = "A..B..".split_terminator('.');
 816     /// assert_eq!(split.as_str(), "A..B..");
 817     /// split.next();
 818     /// assert_eq!(split.as_str(), ".B..");
 819     /// split.by_ref().for_each(drop);
 820     /// assert_eq!(split.as_str(), "");
 821     /// ```
 822     #[inline]
 823     #[unstable(feature = "str_split_as_str", issue = "77998")]
 824     pub fn as_str(&self) -> &'a str {
 825         self.0.as_str()
 826     }
 827 }
 828
 829 impl<'a, P: Pattern<'a>> RSplitTerminator<'a, P> {
 830     /// Returns remainder of the split string
 831     ///
 832     /// # Examples
 833     ///
 834     /// ```
 835     /// #![feature(str_split_as_str)]
 836     /// let mut split = "A..B..".rsplit_terminator('.');
 837     /// assert_eq!(split.as_str(), "A..B..");
 838     /// split.next();
 839     /// assert_eq!(split.as_str(), "A..B");
 840     /// split.by_ref().for_each(drop);
 841     /// assert_eq!(split.as_str(), "");
 842     /// ```
 843     #[inline]
 844     #[unstable(feature = "str_split_as_str", issue = "77998")]
 845     pub fn as_str(&self) -> &'a str {
 846         self.0.as_str()
 847     }
 848 }
 849
 850 derive_pattern_clone! {
 851     clone SplitNInternal
 852     with |s| SplitNInternal { iter: s.iter.clone(), ..*s }
 853 }
 854
 855 pub(super) struct SplitNInternal<'a, P: Pattern<'a>> {
 856     pub(super) iter: SplitInternal<'a, P>,
 857     /// The number of splits remaining
 858     pub(super) count: usize,
 859 }
 860
 861 impl<'a, P> fmt::Debug for SplitNInternal<'a, P>
 862 where
 863     P: Pattern<'a, Searcher: fmt::Debug>,
 864 {
 865     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 866         f.debug_struct("SplitNInternal")
 867             .field("iter", &self.iter)
 868             .field("count", &self.count)
 869             .finish()
 870     }
 871 }
 872
 873 impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> {
 874     #[inline]
 875     fn next(&mut self) -> Option<&'a str> {
 876         match self.count {
 877             0 => None,
 878             1 => {
 879                 self.count = 0;
 880                 self.iter.get_end()
 881             }
 882             _ => {
 883                 self.count -= 1;
 884                 self.iter.next()
 885             }
 886         }
 887     }
 888
 889     #[inline]
 890     fn next_back(&mut self) -> Option<&'a str>
 891     where
 892         P::Searcher: ReverseSearcher<'a>,
 893     {
 894         match self.count {
 895             0 => None,
 896             1 => {
 897                 self.count = 0;
 898                 self.iter.get_end()
 899             }
 900             _ => {
 901                 self.count -= 1;
 902                 self.iter.next_back()
 903             }
 904         }
 905     }
 906
 907     #[inline]
 908     fn as_str(&self) -> &'a str {
 909         self.iter.as_str()
 910     }
 911 }
 912
 913 generate_pattern_iterators! {
 914     forward:
 915         /// Created with the method [`splitn`].
 916         ///
 917         /// [`splitn`]: str::splitn
 918         struct SplitN;
 919     reverse:
 920         /// Created with the method [`rsplitn`].
 921         ///
 922         /// [`rsplitn`]: str::rsplitn
 923         struct RSplitN;
 924     stability:
 925         #[stable(feature = "rust1", since = "1.0.0")]
 926     internal:
 927         SplitNInternal yielding (&'a str);
 928     delegate single ended;
 929 }
 930
 931 impl<'a, P: Pattern<'a>> SplitN<'a, P> {
 932     /// Returns remainder of the split string
 933     ///
 934     /// # Examples
 935     ///
 936     /// ```
 937     /// #![feature(str_split_as_str)]
 938     /// let mut split = "Mary had a little lamb".splitn(3, ' ');
 939     /// assert_eq!(split.as_str(), "Mary had a little lamb");
 940     /// split.next();
 941     /// assert_eq!(split.as_str(), "had a little lamb");
 942     /// split.by_ref().for_each(drop);
 943     /// assert_eq!(split.as_str(), "");
 944     /// ```
 945     #[inline]
 946     #[unstable(feature = "str_split_as_str", issue = "77998")]
 947     pub fn as_str(&self) -> &'a str {
 948         self.0.as_str()
 949     }
 950 }
 951
 952 impl<'a, P: Pattern<'a>> RSplitN<'a, P> {
 953     /// Returns remainder of the split string
 954     ///
 955     /// # Examples
 956     ///
 957     /// ```
 958     /// #![feature(str_split_as_str)]
 959     /// let mut split = "Mary had a little lamb".rsplitn(3, ' ');
 960     /// assert_eq!(split.as_str(), "Mary had a little lamb");
 961     /// split.next();
 962     /// assert_eq!(split.as_str(), "Mary had a little");
 963     /// split.by_ref().for_each(drop);
 964     /// assert_eq!(split.as_str(), "");
 965     /// ```
 966     #[inline]
 967     #[unstable(feature = "str_split_as_str", issue = "77998")]
 968     pub fn as_str(&self) -> &'a str {
 969         self.0.as_str()
 970     }
 971 }
 972
 973 derive_pattern_clone! {
 974     clone MatchIndicesInternal
 975     with |s| MatchIndicesInternal(s.0.clone())
 976 }
 977
 978 pub(super) struct MatchIndicesInternal<'a, P: Pattern<'a>>(pub(super) P::Searcher);
 979
 980 impl<'a, P> fmt::Debug for MatchIndicesInternal<'a, P>
 981 where
 982     P: Pattern<'a, Searcher: fmt::Debug>,
 983 {
 984     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 985         f.debug_tuple("MatchIndicesInternal").field(&self.0).finish()
 986     }
 987 }
 988
 989 impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
 990     #[inline]
 991     fn next(&mut self) -> Option<(usize, &'a str)> {
 992         self.0
 993             .next_match()
 994             // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
 995             .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
 996     }
 997
 998     #[inline]
 999     fn next_back(&mut self) -> Option<(usize, &'a str)>
1000     where
1001         P::Searcher: ReverseSearcher<'a>,
1002     {
1003         self.0
1004             .next_match_back()
1005             // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1006             .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1007     }
1008 }
1009
1010 generate_pattern_iterators! {
1011     forward:
1012         /// Created with the method [`match_indices`].
1013         ///
1014         /// [`match_indices`]: str::match_indices
1015         struct MatchIndices;
1016     reverse:
1017         /// Created with the method [`rmatch_indices`].
1018         ///
1019         /// [`rmatch_indices`]: str::rmatch_indices
1020         struct RMatchIndices;
1021     stability:
1022         #[stable(feature = "str_match_indices", since = "1.5.0")]
1023     internal:
1024         MatchIndicesInternal yielding ((usize, &'a str));
1025     delegate double ended;
1026 }
1027
1028 derive_pattern_clone! {
1029     clone MatchesInternal
1030     with |s| MatchesInternal(s.0.clone())
1031 }
1032
1033 pub(super) struct MatchesInternal<'a, P: Pattern<'a>>(pub(super) P::Searcher);
1034
1035 impl<'a, P> fmt::Debug for MatchesInternal<'a, P>
1036 where
1037     P: Pattern<'a, Searcher: fmt::Debug>,
1038 {
1039     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1040         f.debug_tuple("MatchesInternal").field(&self.0).finish()
1041     }
1042 }
1043
1044 impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
1045     #[inline]
1046     fn next(&mut self) -> Option<&'a str> {
1047         // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1048         self.0.next_match().map(|(a, b)| unsafe {
1049             // Indices are known to be on utf8 boundaries
1050             self.0.haystack().get_unchecked(a..b)
1051         })
1052     }
1053
1054     #[inline]
1055     fn next_back(&mut self) -> Option<&'a str>
1056     where
1057         P::Searcher: ReverseSearcher<'a>,
1058     {
1059         // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1060         self.0.next_match_back().map(|(a, b)| unsafe {
1061             // Indices are known to be on utf8 boundaries
1062             self.0.haystack().get_unchecked(a..b)
1063         })
1064     }
1065 }
1066
1067 generate_pattern_iterators! {
1068     forward:
1069         /// Created with the method [`matches`].
1070         ///
1071         /// [`matches`]: str::matches
1072         struct Matches;
1073     reverse:
1074         /// Created with the method [`rmatches`].
1075         ///
1076         /// [`rmatches`]: str::rmatches
1077         struct RMatches;
1078     stability:
1079         #[stable(feature = "str_matches", since = "1.2.0")]
1080     internal:
1081         MatchesInternal yielding (&'a str);
1082     delegate double ended;
1083 }
1084
1085 /// An iterator over the lines of a string, as string slices.
1086 ///
1087 /// This struct is created with the [`lines`] method on [`str`].
1088 /// See its documentation for more.
1089 ///
1090 /// [`lines`]: str::lines
1091 #[stable(feature = "rust1", since = "1.0.0")]
1092 #[must_use = "iterators are lazy and do nothing unless consumed"]
1093 #[derive(Clone, Debug)]
1094 pub struct Lines<'a>(pub(super) Map<SplitTerminator<'a, char>, LinesAnyMap>);
1095
1096 #[stable(feature = "rust1", since = "1.0.0")]
1097 impl<'a> Iterator for Lines<'a> {
1098     type Item = &'a str;
1099
1100     #[inline]
1101     fn next(&mut self) -> Option<&'a str> {
1102         self.0.next()
1103     }
1104
1105     #[inline]
1106     fn size_hint(&self) -> (usize, Option<usize>) {
1107         self.0.size_hint()
1108     }
1109
1110     #[inline]
1111     fn last(mut self) -> Option<&'a str> {
1112         self.next_back()
1113     }
1114 }
1115
1116 #[stable(feature = "rust1", since = "1.0.0")]
1117 impl<'a> DoubleEndedIterator for Lines<'a> {
1118     #[inline]
1119     fn next_back(&mut self) -> Option<&'a str> {
1120         self.0.next_back()
1121     }
1122 }
1123
1124 #[stable(feature = "fused", since = "1.26.0")]
1125 impl FusedIterator for Lines<'_> {}
1126
1127 /// Created with the method [`lines_any`].
1128 ///
1129 /// [`lines_any`]: str::lines_any
1130 #[stable(feature = "rust1", since = "1.0.0")]
1131 #[deprecated(since = "1.4.0", note = "use lines()/Lines instead now")]
1132 #[must_use = "iterators are lazy and do nothing unless consumed"]
1133 #[derive(Clone, Debug)]
1134 #[allow(deprecated)]
1135 pub struct LinesAny<'a>(pub(super) Lines<'a>);
1136
1137 #[stable(feature = "rust1", since = "1.0.0")]
1138 #[allow(deprecated)]
1139 impl<'a> Iterator for LinesAny<'a> {
1140     type Item = &'a str;
1141
1142     #[inline]
1143     fn next(&mut self) -> Option<&'a str> {
1144         self.0.next()
1145     }
1146
1147     #[inline]
1148     fn size_hint(&self) -> (usize, Option<usize>) {
1149         self.0.size_hint()
1150     }
1151 }
1152
1153 #[stable(feature = "rust1", since = "1.0.0")]
1154 #[allow(deprecated)]
1155 impl<'a> DoubleEndedIterator for LinesAny<'a> {
1156     #[inline]
1157     fn next_back(&mut self) -> Option<&'a str> {
1158         self.0.next_back()
1159     }
1160 }
1161
1162 #[stable(feature = "fused", since = "1.26.0")]
1163 #[allow(deprecated)]
1164 impl FusedIterator for LinesAny<'_> {}
1165
1166 /// An iterator over the non-whitespace substrings of a string,
1167 /// separated by any amount of whitespace.
1168 ///
1169 /// This struct is created by the [`split_whitespace`] method on [`str`].
1170 /// See its documentation for more.
1171 ///
1172 /// [`split_whitespace`]: str::split_whitespace
1173 #[stable(feature = "split_whitespace", since = "1.1.0")]
1174 #[derive(Clone, Debug)]
1175 pub struct SplitWhitespace<'a> {
1176     pub(super) inner: Filter<Split<'a, IsWhitespace>, IsNotEmpty>,
1177 }
1178
1179 /// An iterator over the non-ASCII-whitespace substrings of a string,
1180 /// separated by any amount of ASCII whitespace.
1181 ///
1182 /// This struct is created by the [`split_ascii_whitespace`] method on [`str`].
1183 /// See its documentation for more.
1184 ///
1185 /// [`split_ascii_whitespace`]: str::split_ascii_whitespace
1186 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
1187 #[derive(Clone, Debug)]
1188 pub struct SplitAsciiWhitespace<'a> {
1189     pub(super) inner:
1190         Map<Filter<SliceSplit<'a, u8, IsAsciiWhitespace>, BytesIsNotEmpty>, UnsafeBytesToStr>,
1191 }
1192
1193 /// An iterator over the substrings of a string,
1194 /// terminated by a substring matching to a predicate function
1195 /// Unlike `Split`, it contains the matched part as a terminator
1196 /// of the subslice.
1197 ///
1198 /// This struct is created by the [`split_inclusive`] method on [`str`].
1199 /// See its documentation for more.
1200 ///
1201 /// [`split_inclusive`]: str::split_inclusive
1202 #[stable(feature = "split_inclusive", since = "1.51.0")]
1203 pub struct SplitInclusive<'a, P: Pattern<'a>>(pub(super) SplitInternal<'a, P>);
1204
1205 #[stable(feature = "split_whitespace", since = "1.1.0")]
1206 impl<'a> Iterator for SplitWhitespace<'a> {
1207     type Item = &'a str;
1208
1209     #[inline]
1210     fn next(&mut self) -> Option<&'a str> {
1211         self.inner.next()
1212     }
1213
1214     #[inline]
1215     fn size_hint(&self) -> (usize, Option<usize>) {
1216         self.inner.size_hint()
1217     }
1218
1219     #[inline]
1220     fn last(mut self) -> Option<&'a str> {
1221         self.next_back()
1222     }
1223 }
1224
1225 #[stable(feature = "split_whitespace", since = "1.1.0")]
1226 impl<'a> DoubleEndedIterator for SplitWhitespace<'a> {
1227     #[inline]
1228     fn next_back(&mut self) -> Option<&'a str> {
1229         self.inner.next_back()
1230     }
1231 }
1232
1233 #[stable(feature = "fused", since = "1.26.0")]
1234 impl FusedIterator for SplitWhitespace<'_> {}
1235
1236 impl<'a> SplitWhitespace<'a> {
1237     /// Returns remainder of the split string
1238     ///
1239     /// # Examples
1240     ///
1241     /// ```
1242     /// #![feature(str_split_whitespace_as_str)]
1243     ///
1244     /// let mut split = "Mary had a little lamb".split_whitespace();
1245     /// assert_eq!(split.as_str(), "Mary had a little lamb");
1246     ///
1247     /// split.next();
1248     /// assert_eq!(split.as_str(), "had a little lamb");
1249     ///
1250     /// split.by_ref().for_each(drop);
1251     /// assert_eq!(split.as_str(), "");
1252     /// ```
1253     #[inline]
1254     #[must_use]
1255     #[unstable(feature = "str_split_whitespace_as_str", issue = "77998")]
1256     pub fn as_str(&self) -> &'a str {
1257         self.inner.iter.as_str()
1258     }
1259 }
1260
1261 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
1262 impl<'a> Iterator for SplitAsciiWhitespace<'a> {
1263     type Item = &'a str;
1264
1265     #[inline]
1266     fn next(&mut self) -> Option<&'a str> {
1267         self.inner.next()
1268     }
1269
1270     #[inline]
1271     fn size_hint(&self) -> (usize, Option<usize>) {
1272         self.inner.size_hint()
1273     }
1274
1275     #[inline]
1276     fn last(mut self) -> Option<&'a str> {
1277         self.next_back()
1278     }
1279 }
1280
1281 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
1282 impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a> {
1283     #[inline]
1284     fn next_back(&mut self) -> Option<&'a str> {
1285         self.inner.next_back()
1286     }
1287 }
1288
1289 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
1290 impl FusedIterator for SplitAsciiWhitespace<'_> {}
1291
1292 impl<'a> SplitAsciiWhitespace<'a> {
1293     /// Returns remainder of the split string
1294     ///
1295     /// # Examples
1296     ///
1297     /// ```
1298     /// #![feature(str_split_whitespace_as_str)]
1299     ///
1300     /// let mut split = "Mary had a little lamb".split_ascii_whitespace();
1301     /// assert_eq!(split.as_str(), "Mary had a little lamb");
1302     ///
1303     /// split.next();
1304     /// assert_eq!(split.as_str(), "had a little lamb");
1305     ///
1306     /// split.by_ref().for_each(drop);
1307     /// assert_eq!(split.as_str(), "");
1308     /// ```
1309     #[inline]
1310     #[must_use]
1311     #[unstable(feature = "str_split_whitespace_as_str", issue = "77998")]
1312     pub fn as_str(&self) -> &'a str {
1313         if self.inner.iter.iter.finished {
1314             return "";
1315         }
1316
1317         // SAFETY: Slice is created from str.
1318         unsafe { crate::str::from_utf8_unchecked(&self.inner.iter.iter.v) }
1319     }
1320 }
1321
1322 #[stable(feature = "split_inclusive", since = "1.51.0")]
1323 impl<'a, P: Pattern<'a>> Iterator for SplitInclusive<'a, P> {
1324     type Item = &'a str;
1325
1326     #[inline]
1327     fn next(&mut self) -> Option<&'a str> {
1328         self.0.next_inclusive()
1329     }
1330 }
1331
1332 #[stable(feature = "split_inclusive", since = "1.51.0")]
1333 impl<'a, P: Pattern<'a, Searcher: fmt::Debug>> fmt::Debug for SplitInclusive<'a, P> {
1334     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1335         f.debug_struct("SplitInclusive").field("0", &self.0).finish()
1336     }
1337 }
1338
1339 // FIXME(#26925) Remove in favor of `#[derive(Clone)]`
1340 #[stable(feature = "split_inclusive", since = "1.51.0")]
1341 impl<'a, P: Pattern<'a, Searcher: Clone>> Clone for SplitInclusive<'a, P> {
1342     fn clone(&self) -> Self {
1343         SplitInclusive(self.0.clone())
1344     }
1345 }
1346
1347 #[stable(feature = "split_inclusive", since = "1.51.0")]
1348 impl<'a, P: Pattern<'a, Searcher: ReverseSearcher<'a>>> DoubleEndedIterator
1349     for SplitInclusive<'a, P>
1350 {
1351     #[inline]
1352     fn next_back(&mut self) -> Option<&'a str> {
1353         self.0.next_back_inclusive()
1354     }
1355 }
1356
1357 #[stable(feature = "split_inclusive", since = "1.51.0")]
1358 impl<'a, P: Pattern<'a>> FusedIterator for SplitInclusive<'a, P> {}
1359
1360 impl<'a, P: Pattern<'a>> SplitInclusive<'a, P> {
1361     /// Returns remainder of the split string
1362     ///
1363     /// # Examples
1364     ///
1365     /// ```
1366     /// #![feature(str_split_inclusive_as_str)]
1367     /// let mut split = "Mary had a little lamb".split_inclusive(' ');
1368     /// assert_eq!(split.as_str(), "Mary had a little lamb");
1369     /// split.next();
1370     /// assert_eq!(split.as_str(), "had a little lamb");
1371     /// split.by_ref().for_each(drop);
1372     /// assert_eq!(split.as_str(), "");
1373     /// ```
1374     #[inline]
1375     #[unstable(feature = "str_split_inclusive_as_str", issue = "77998")]
1376     pub fn as_str(&self) -> &'a str {
1377         self.0.as_str()
1378     }
1379 }
1380
1381 /// An iterator of [`u16`] over the string encoded as UTF-16.
1382 ///
1383 /// This struct is created by the [`encode_utf16`] method on [`str`].
1384 /// See its documentation for more.
1385 ///
1386 /// [`encode_utf16`]: str::encode_utf16
1387 #[derive(Clone)]
1388 #[stable(feature = "encode_utf16", since = "1.8.0")]
1389 pub struct EncodeUtf16<'a> {
1390     pub(super) chars: Chars<'a>,
1391     pub(super) extra: u16,
1392 }
1393
1394 #[stable(feature = "collection_debug", since = "1.17.0")]
1395 impl fmt::Debug for EncodeUtf16<'_> {
1396     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1397         f.debug_struct("EncodeUtf16").finish_non_exhaustive()
1398     }
1399 }
1400
1401 #[stable(feature = "encode_utf16", since = "1.8.0")]
1402 impl<'a> Iterator for EncodeUtf16<'a> {
1403     type Item = u16;
1404
1405     #[inline]
1406     fn next(&mut self) -> Option<u16> {
1407         if self.extra != 0 {
1408             let tmp = self.extra;
1409             self.extra = 0;
1410             return Some(tmp);
1411         }
1412
1413         let mut buf = [0; 2];
1414         self.chars.next().map(|ch| {
1415             let n = ch.encode_utf16(&mut buf).len();
1416             if n == 2 {
1417                 self.extra = buf[1];
1418             }
1419             buf[0]
1420         })
1421     }
1422
1423     #[inline]
1424     fn size_hint(&self) -> (usize, Option<usize>) {
1425         let (low, high) = self.chars.size_hint();
1426         // every char gets either one u16 or two u16,
1427         // so this iterator is between 1 or 2 times as
1428         // long as the underlying iterator.
1429         (low, high.and_then(|n| n.checked_mul(2)))
1430     }
1431 }
1432
1433 #[stable(feature = "fused", since = "1.26.0")]
1434 impl FusedIterator for EncodeUtf16<'_> {}
1435
1436 /// The return type of [`str::escape_debug`].
1437 #[stable(feature = "str_escape", since = "1.34.0")]
1438 #[derive(Clone, Debug)]
1439 pub struct EscapeDebug<'a> {
1440     pub(super) inner: Chain<
1441         Flatten<option::IntoIter<char::EscapeDebug>>,
1442         FlatMap<Chars<'a>, char::EscapeDebug, CharEscapeDebugContinue>,
1443     >,
1444 }
1445
1446 /// The return type of [`str::escape_default`].
1447 #[stable(feature = "str_escape", since = "1.34.0")]
1448 #[derive(Clone, Debug)]
1449 pub struct EscapeDefault<'a> {
1450     pub(super) inner: FlatMap<Chars<'a>, char::EscapeDefault, CharEscapeDefault>,
1451 }
1452
1453 /// The return type of [`str::escape_unicode`].
1454 #[stable(feature = "str_escape", since = "1.34.0")]
1455 #[derive(Clone, Debug)]
1456 pub struct EscapeUnicode<'a> {
1457     pub(super) inner: FlatMap<Chars<'a>, char::EscapeUnicode, CharEscapeUnicode>,
1458 }
1459
1460 macro_rules! escape_types_impls {
1461     ($( $Name: ident ),+) => {$(
1462         #[stable(feature = "str_escape", since = "1.34.0")]
1463         impl<'a> fmt::Display for $Name<'a> {
1464             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1465                 self.clone().try_for_each(|c| f.write_char(c))
1466             }
1467         }
1468
1469         #[stable(feature = "str_escape", since = "1.34.0")]
1470         impl<'a> Iterator for $Name<'a> {
1471             type Item = char;
1472
1473             #[inline]
1474             fn next(&mut self) -> Option<char> { self.inner.next() }
1475
1476             #[inline]
1477             fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
1478
1479             #[inline]
1480             fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
1481                 Self: Sized, Fold: FnMut(Acc, Self::Item) -> R, R: Try<Output = Acc>
1482             {
1483                 self.inner.try_fold(init, fold)
1484             }
1485
1486             #[inline]
1487             fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
1488                 where Fold: FnMut(Acc, Self::Item) -> Acc,
1489             {
1490                 self.inner.fold(init, fold)
1491             }
1492         }
1493
1494         #[stable(feature = "str_escape", since = "1.34.0")]
1495         impl<'a> FusedIterator for $Name<'a> {}
1496     )+}
1497 }
1498
1499 escape_types_impls!(EscapeDebug, EscapeDefault, EscapeUnicode);