add ascii_fields method

Author: owenthewizard

src/ext_slice.rs

@@ -1101,12 +1101,42 @@ pub trait ByteSlice: private::Sealed {
     ///
     /// assert_eq!(0, B("  \n\t\u{2003}\n  \t").fields().count());
     /// ```
+    #[doc(alias = "split_whitespace")]
     #[cfg(feature = "unicode")]
     #[inline]
     fn fields(&self) -> Fields<'_> {
         Fields::new(self.as_bytes())
     }
 
+    /// Returns an iterator over the fields in a byte string, separated
+    /// by contiguous ASCII whitespace.
+    ///
+    /// # Example
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use bstr::{B, ByteSlice};
+    ///
+    /// let s = B("  foo\tbar\t\nquux   \n");
+    /// let ascii_fields: Vec<&[u8]> = s.ascii_fields().collect();
+    /// assert_eq!(ascii_fields, vec![B("foo"), B("bar"), B("quux")]);
+    /// ```
+    ///
+    /// A byte string consisting of just whitespace yields no elements:
+    ///
+    /// ```
+    /// use bstr::{B, ByteSlice};
+    ///
+    /// assert_eq!(0, B("  \n\t\n  \t").fields().count());
+    /// ```
+    #[doc(alias = "split_ascii_whitespace")]
+    #[cfg(feature = "unicode")]
+    #[inline]
+    fn ascii_fields(&self) -> AsciiFields<'_> {
+        AsciiFields::new(self.as_bytes())
+    }
+
     /// Returns an iterator over the fields in a byte string, separated by
     /// contiguous codepoints satisfying the given predicate.
     ///
@@ -3356,6 +3386,38 @@ impl<'a> ExactSizeIterator for Bytes<'a> {
 
 impl<'a> iter::FusedIterator for Bytes<'a> {}
 
+/// An iterator over the fields in a byte string, separated by ASCII whitespace.
+///
+/// This iterator splits on contiguous runs of whitespace, such that the fields
+/// in `foo\t\t\n  \nbar` are `foo` and `bar`.
+///
+/// `'a` is the lifetime of the byte string being split.
+#[doc(alias = "SplitAsciiWhitespace")]
+#[cfg(feature = "unicode")]
+#[derive(Clone, Debug)]
+pub struct AsciiFields<'a> {
+    it: FieldsWith<'a, fn(char) -> bool>,
+}
+
+#[cfg(feature = "unicode")]
+impl<'a> AsciiFields<'a> {
+    fn new(bytes: &'a [u8]) -> AsciiFields<'a> {
+        AsciiFields {
+            it: bytes.fields_with(|x| char::is_ascii_whitespace(&x)),
+        }
+    }
+}
+
+#[cfg(feature = "unicode")]
+impl<'a> Iterator for AsciiFields<'a> {
+    type Item = &'a [u8];
+
+    #[inline]
+    fn next(&mut self) -> Option<&'a [u8]> {
+        self.it.next()
+    }
+}
+
 /// An iterator over the fields in a byte string, separated by whitespace.
 ///
 /// Whitespace for this iterator is defined by the Unicode property
@@ -3365,6 +3427,7 @@ impl<'a> iter::FusedIterator for Bytes<'a> {}
 /// in `foo\t\t\n  \nbar` are `foo` and `bar`.
 ///
 /// `'a` is the lifetime of the byte string being split.
+#[doc(alias = "SplitWhitespace")]
 #[cfg(feature = "unicode")]
 #[derive(Clone, Debug)]
 pub struct Fields<'a> {