Implement split_left_inclusive for string slices

Author: Jules Bertholet

library/alloc/tests/str.rs

@@ -1438,6 +1438,63 @@ fn test_split_char_iterator_inclusive_rev() {
     assert_eq!(split, ["CaT", "TurtlE", "SharK", "SheeP"]);
 }
 
+#[test]
+fn test_split_char_iterator_left_inclusive() {
+    let split: Vec<&str> = "\n\n\n\n".split_left_inclusive('\n').collect();
+    assert_eq!(split, ["\n", "\n", "\n", "\n"]);
+
+    let split: Vec<&str> = "".split_left_inclusive('\n').collect();
+    let rhs: [&str; 0] = [];
+    assert_eq!(split, rhs);
+
+    let data = "\nMäry häd ä little lämb\nLittle lämb\n";
+
+    let split: Vec<&str> = data.split_left_inclusive('\n').collect();
+    assert_eq!(split, ["\nMäry häd ä little lämb", "\nLittle lämb", "\n"]);
+
+    let uppercase_separated = "SheePSharKTurtlECaT";
+    let mut first_char = true;
+    let split: Vec<&str> = uppercase_separated
+        .split_left_inclusive(|c: char| {
+            let split = !first_char && c.is_uppercase();
+            first_char = split;
+            split
+        })
+        .collect();
+    assert_eq!(split, ["Shee", "PShar", "KTurtl", "ECa", "T"]);
+}
+
+#[test]
+fn test_split_char_iterator_left_inclusive_rev() {
+    let split: Vec<&str> = "\n\n\n\n".split_left_inclusive('\n').rev().collect();
+    assert_eq!(split, ["\n", "\n", "\n", "\n"]);
+
+    let split: Vec<&str> = "".split_left_inclusive('\n').rev().collect();
+    let rhs: [&str; 0] = [];
+    assert_eq!(split, rhs);
+
+    let data = "\nMäry häd ä little lämb\nLittle lämb\n";
+
+    let split: Vec<&str> = data.split_left_inclusive('\n').rev().collect();
+    assert_eq!(split, ["\n", "\nLittle lämb", "\nMäry häd ä little lämb"]);
+
+    // Note that the predicate is stateful and thus dependent
+    // on the iteration order.
+    // (A different predicate is needed for reverse iterator vs normal iterator.)
+    // Not sure if anything can be done though.
+    let uppercase_separated = "SheePSharKTurtlECaT";
+    let mut term_char = true;
+    let split: Vec<&str> = uppercase_separated
+        .split_left_inclusive(|c: char| {
+            let split = term_char && c.is_uppercase();
+            term_char = c.is_uppercase();
+            split
+        })
+        .rev()
+        .collect();
+    assert_eq!(split, ["T", "ECa", "KTurtl", "PShar", "Shee",]);
+}
+
 #[test]
 fn test_rsplit() {
     let data = "\nMäry häd ä little lämb\nLittle lämb\n";

library/core/src/str/iter.rs

@@ -563,7 +563,7 @@ pub(super) struct SplitInternal<'a, P: Pattern<'a>> {
     pub(super) start: usize,
     pub(super) end: usize,
     pub(super) matcher: P::Searcher,
-    pub(super) allow_trailing_empty: bool,
+    pub(super) allow_bookending_empty: bool,
     pub(super) finished: bool,
 }
 
@@ -576,7 +576,7 @@ where
             .field("start", &self.start)
             .field("end", &self.end)
             .field("matcher", &self.matcher)
-            .field("allow_trailing_empty", &self.allow_trailing_empty)
+            .field("allow_bookending_empty", &self.allow_bookending_empty)
             .field("finished", &self.finished)
             .finish()
     }
@@ -585,7 +585,7 @@ where
 impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
     #[inline]
     fn get_end(&mut self) -> Option<&'a str> {
-        if !self.finished && (self.allow_trailing_empty || self.end - self.start > 0) {
+        if !self.finished && (self.allow_bookending_empty || self.end - self.start > 0) {
             self.finished = true;
             // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
             unsafe {
@@ -635,6 +635,38 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
         }
     }
 
+    #[inline]
+    fn next_left_inclusive(&mut self) -> Option<&'a str> {
+        if self.finished {
+            return None;
+        }
+
+        if !self.allow_bookending_empty {
+            self.allow_bookending_empty = true;
+            match self.next_left_inclusive() {
+                Some(elt) if !elt.is_empty() => return Some(elt),
+                _ => {
+                    if self.finished {
+                        return None;
+                    }
+                }
+            }
+        }
+
+        let haystack = self.matcher.haystack();
+        match self.matcher.next_match() {
+            // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary,
+            // and self.start is either the start of the original string,
+            // or `b` was assigned to it, so it also lies on unicode boundary.
+            Some((b, _)) => unsafe {
+                let elt = haystack.get_unchecked(self.start..b);
+                self.start = b;
+                Some(elt)
+            },
+            None => self.get_end(),
+        }
+    }
+
     #[inline]
     fn next_back(&mut self) -> Option<&'a str>
     where
@@ -644,8 +676,8 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
             return None;
         }
 
-        if !self.allow_trailing_empty {
-            self.allow_trailing_empty = true;
+        if !self.allow_bookending_empty {
+            self.allow_bookending_empty = true;
             match self.next_back() {
                 Some(elt) if !elt.is_empty() => return Some(elt),
                 _ => {
@@ -681,8 +713,8 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
             return None;
         }
 
-        if !self.allow_trailing_empty {
-            self.allow_trailing_empty = true;
+        if !self.allow_bookending_empty {
+            self.allow_bookending_empty = true;
             match self.next_back_inclusive() {
                 Some(elt) if !elt.is_empty() => return Some(elt),
                 _ => {
@@ -715,6 +747,40 @@ impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
         }
     }
 
+    #[inline]
+    fn next_back_left_inclusive(&mut self) -> Option<&'a str>
+    where
+        P::Searcher: ReverseSearcher<'a>,
+    {
+        if self.finished {
+            return None;
+        }
+
+        let haystack = self.matcher.haystack();
+        match self.matcher.next_match_back() {
+            // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary,
+            // and self.end is either the end of the original string,
+            // or `b` was assigned to it, so it also lies on unicode boundary.
+            Some((b, _)) => unsafe {
+                let elt = haystack.get_unchecked(b..self.end);
+                self.end = b;
+                if self.start == b {
+                    self.finished = true;
+                }
+                Some(elt)
+            },
+            // SAFETY: self.start is either the start of the original string,
+            // or start of a substring that represents the part of the string that hasn't
+            // iterated yet. Either way, it is guaranteed to lie on unicode boundary.
+            // self.end is either the end of the original string,
+            // or `b` was assigned to it, so it also lies on unicode boundary.
+            None => unsafe {
+                self.finished = true;
+                Some(haystack.get_unchecked(self.start..self.end))
+            },
+        }
+    }
+
     #[inline]
     fn as_str(&self) -> &'a str {
         // `Self::get_end` doesn't change `self.start`
@@ -1190,18 +1256,6 @@ pub struct SplitAsciiWhitespace<'a> {
         Map<Filter<SliceSplit<'a, u8, IsAsciiWhitespace>, BytesIsNotEmpty>, UnsafeBytesToStr>,
 }
 
-/// An iterator over the substrings of a string,
-/// terminated by a substring matching to a predicate function
-/// Unlike `Split`, it contains the matched part as a terminator
-/// of the subslice.
-///
-/// This struct is created by the [`split_inclusive`] method on [`str`].
-/// See its documentation for more.
-///
-/// [`split_inclusive`]: str::split_inclusive
-#[stable(feature = "split_inclusive", since = "1.51.0")]
-pub struct SplitInclusive<'a, P: Pattern<'a>>(pub(super) SplitInternal<'a, P>);
-
 #[stable(feature = "split_whitespace", since = "1.1.0")]
 impl<'a> Iterator for SplitWhitespace<'a> {
     type Item = &'a str;
@@ -1319,6 +1373,18 @@ impl<'a> SplitAsciiWhitespace<'a> {
     }
 }
 
+/// An iterator over the substrings of a string,
+/// terminated by a substring matching to a predicate function
+/// Unlike `Split`, it contains the matched part as a terminator
+/// of the subslice.
+///
+/// This struct is created by the [`split_inclusive`] method on [`str`].
+/// See its documentation for more.
+///
+/// [`split_inclusive`]: str::split_inclusive
+#[stable(feature = "split_inclusive", since = "1.51.0")]
+pub struct SplitInclusive<'a, P: Pattern<'a>>(pub(super) SplitInternal<'a, P>);
+
 #[stable(feature = "split_inclusive", since = "1.51.0")]
 impl<'a, P: Pattern<'a>> Iterator for SplitInclusive<'a, P> {
     type Item = &'a str;
@@ -1378,6 +1444,78 @@ impl<'a, P: Pattern<'a>> SplitInclusive<'a, P> {
     }
 }
 
+/// An iterator over the substrings of a string,
+/// terminated by a substring matching to a predicate function
+/// Unlike `Split`, it contains the matched part as an initiator
+/// of the subslice.
+///
+/// This struct is created by the [`split_left_inclusive`] method on [`str`].
+/// See its documentation for more.
+///
+/// [`split_left_inclusive`]: str::split_left_inclusive
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+pub struct SplitLeftInclusive<'a, P: Pattern<'a>>(pub(super) SplitInternal<'a, P>);
+
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+impl<'a, P: Pattern<'a>> Iterator for SplitLeftInclusive<'a, P> {
+    type Item = &'a str;
+
+    #[inline]
+    fn next(&mut self) -> Option<&'a str> {
+        self.0.next_left_inclusive()
+    }
+}
+
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+impl<'a, P: Pattern<'a, Searcher: fmt::Debug>> fmt::Debug for SplitLeftInclusive<'a, P> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("SplitLeftInclusive").field("0", &self.0).finish()
+    }
+}
+
+// FIXME(#26925) Remove in favor of `#[derive(Clone)]`
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+impl<'a, P: Pattern<'a, Searcher: Clone>> Clone for SplitLeftInclusive<'a, P> {
+    fn clone(&self) -> Self {
+        SplitLeftInclusive(self.0.clone())
+    }
+}
+
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+impl<'a, P: Pattern<'a, Searcher: ReverseSearcher<'a>>> DoubleEndedIterator
+    for SplitLeftInclusive<'a, P>
+{
+    #[inline]
+    fn next_back(&mut self) -> Option<&'a str> {
+        self.0.next_back_left_inclusive()
+    }
+}
+
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+impl<'a, P: Pattern<'a>> FusedIterator for SplitLeftInclusive<'a, P> {}
+
+impl<'a, P: Pattern<'a>> SplitLeftInclusive<'a, P> {
+    /// Returns remainder of the splitted string
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(str_split_inclusive_as_str)]
+    /// #![feature(split_left_inclusive)]
+    /// let mut split = "Mary had a little lamb".split_left_inclusive(' ');
+    /// assert_eq!(split.as_str(), "Mary had a little lamb");
+    /// split.next();
+    /// assert_eq!(split.as_str(), " had a little lamb");
+    /// split.by_ref().for_each(drop);
+    /// assert_eq!(split.as_str(), "");
+    /// ```
+    #[inline]
+    #[unstable(feature = "str_split_inclusive_as_str", issue = "77998")]
+    pub fn as_str(&self) -> &'a str {
+        self.0.as_str()
+    }
+}
+
 /// An iterator of [`u16`] over the string encoded as UTF-16.
 ///
 /// This struct is created by the [`encode_utf16`] method on [`str`].

library/core/src/str/mod.rs

@@ -69,6 +69,9 @@ pub use iter::SplitAsciiWhitespace;
 #[stable(feature = "split_inclusive", since = "1.51.0")]
 pub use iter::SplitInclusive;
 
+#[unstable(feature = "split_left_inclusive", issue = "none")]
+pub use iter::SplitLeftInclusive;
+
 #[unstable(feature = "str_internals", issue = "none")]
 pub use validations::{next_code_point, utf8_char_width};
 
@@ -1327,7 +1330,7 @@ impl str {
             start: 0,
             end: self.len(),
             matcher: pat.into_searcher(self),
-            allow_trailing_empty: true,
+            allow_bookending_empty: true,
             finished: false,
         })
     }
@@ -1367,11 +1370,53 @@ impl str {
             start: 0,
             end: self.len(),
             matcher: pat.into_searcher(self),
-            allow_trailing_empty: false,
+            allow_bookending_empty: false,
             finished: false,
         })
     }
 
+    /// An iterator over substrings of this string slice, separated by
+    /// characters matched by a pattern. Differs from the iterator produced by
+    /// `split` in that `split_left_inclusive` leaves the matched part as the
+    /// initiator of the substring.
+    ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: prim@char
+    /// [pattern]: self::pattern
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(split_left_inclusive)]
+    /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb."
+    ///     .split_left_inclusive('\n').collect();
+    /// assert_eq!(v, ["Mary had a little lamb", "\nlittle lamb", "\nlittle lamb."]);
+    /// ```
+    ///
+    /// If the last element of the string is matched,
+    /// that element will be considered the initiator of a new substring.
+    /// That substring will be the last item returned by the iterator.
+    ///
+    /// ```
+    /// #![feature(split_left_inclusive)]
+    /// let v: Vec<&str> = "\nMary had a little lamb\nlittle lamb\nlittle lamb.\n"
+    ///     .split_left_inclusive('\n').collect();
+    /// assert_eq!(v, ["\nMary had a little lamb", "\nlittle lamb", "\nlittle lamb.", "\n"]);
+    /// ```
+    #[unstable(feature = "split_left_inclusive", issue = "none")]
+    #[inline]
+    pub fn split_left_inclusive<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitLeftInclusive<'a, P> {
+        SplitLeftInclusive(SplitInternal {
+            start: 0,
+            end: self.len(),
+            matcher: pat.into_searcher(self),
+            allow_bookending_empty: false,
+            finished: self.is_empty(),
+        })
+    }
+
     /// An iterator over substrings of the given string slice, separated by
     /// characters matched by a pattern and yielded in reverse order.
     ///
@@ -1469,7 +1514,7 @@ impl str {
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
     pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
-        SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
+        SplitTerminator(SplitInternal { allow_bookending_empty: false, ..self.split(pat).0 })
     }
 
     /// An iterator over substrings of `self`, separated by characters