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().array_chunks::<CHUNK_SIZE>();
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 + 3) / 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 + 2) / 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 + 2) / 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);