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: u32| 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: char| {
220 let index: usize = 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&mut DebugStruct<'_, '_>.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(name:"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&mut DebugStruct<'_, '_>.debug_struct("SplitNInternal")
934 .field("iter", &self.iter)
935 .field(name:"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(name:"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: usize, end: usize)| 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: usize, end: usize)| 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(name:"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: usize, b: usize)| 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: usize, b: usize)| 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(name:"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(name:"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);
1611