iter.rs - source
Description: Source of the Rust file `library/core/src/str/iter.rs`.

#
core/str/
iter.rs

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