release: 0.2.2

CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
 
+## [0.2.2](https://github.com/Blobfolio/trimothy/releases/tag/v0.2.2) - 2023-10-04
+
+### New
+
+* `NormalizeWhitespace::normalized_control_and_whitespace` member method
+
+
+
 ## [0.2.1](https://github.com/Blobfolio/trimothy/releases/tag/v0.2.1) - 2023-10-04
 
 ### Changed

CREDITS.md

@@ -1,6 +1,6 @@
 # Project Dependencies
  Package: trimothy
- Version: 0.2.1
- Generated: 2023-10-05 01:56:28 UTC
+ Version: 0.2.2
+ Generated: 2023-10-05 03:27:02 UTC
 
 This package has no dependencies.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "trimothy"
-version = "0.2.1"
+version = "0.2.2"
 authors = ["Blobfolio, LLC. <[email protected]>"]
 edition = "2021"
 rust-version = "1.56"

README.md

@@ -62,11 +62,14 @@ This trait brings _mutable_ match-based trimming `String`, `Vec<u8>`, and `Box<[
 
 ### NormalizeWhitespace
 
-This trait exposes an iterator over byte/string slice contents with the edges trimmed, and all contiguous inner whitespace converted to a single horizontal space. This trait is also implemented for existing `u8`/`char` iterators.
+This trait exposes an iterator over byte/string slice contents that trims the edges and compacts/converts all inner, contiguous spans of whitespace to a single horizontal space.
+
+This trait is implemented for `&[u8]`, `&str`, and `Iterator`s with `u8`/`char` items.
 
 | Method | Description |
 | ------ | ----------- |
-| `normalized_whitespace` | Return said iterator. |
+| `normalized_whitespace` | Return a whitespace-normalizing iterator. |
+| `normalized_control_and_whitespace` | Return a control- and whitespace-normalizing iterator. |
 
 
 

src/iter.rs

@@ -20,14 +20,41 @@ use core::{
 /// trimming the edges and compacting any inner whitespace spans, converting
 /// them to single horizontal spaces (one per span).
 ///
+/// To trim/compact control characters too, use the
+/// `normalized_control_and_whitespace` method instead.
+///
 /// This can be called on an `&[u8]` or `&str` directly, or any iterator
 /// yielding owned `u8` or `char` items.
+///
+/// Normalization can optionally be extended to cover control characters too,
+/// trimming and compacting them as if they were whitespace (along with any
+/// actual whitespace).
+///
+/// ```
+/// use trimothy::NormalizeWhitespace;
+///
+/// let abnormal = " \0Hello\0\t\0Dolly\0\0";
+///
+/// // Normally, crap like \0 won't get normalized.
+/// let normal: String = abnormal.normalized_whitespace().collect();
+/// assert_eq!(normal, "\0Hello\0 \0Dolly\0\0");
+///
+/// // But it can be.
+/// let normal: String = abnormal.normalized_control_and_whitespace().collect();
+/// assert_eq!(normal, "Hello Dolly");
+/// ```
 pub trait NormalizeWhitespace<T: Copy + Sized, I: Iterator<Item=T>> {
  /// # Normalized Whitespace Iterator.
  ///
  /// Modify a byte or char iterator to trim the ends, and convert all
  /// contiguous inner whitespace to a single horizontal space.
  fn normalized_whitespace(self) -> NormalizeWhiteSpaceIter<T, I>;
+
+ /// # Normalized Control/Whitespace Iterator.
+ ///
+ /// Same as `normalized_whitespace`, but also trim/normalize control
+ /// characters.
+ fn normalized_control_and_whitespace(self) -> NormalizeWhiteSpaceIter<T, I>;
 }
 
 impl<'a> NormalizeWhitespace<u8, Copied<Iter<'a, u8>>> for &'a [u8] {
@@ -64,6 +91,25 @@ impl<'a> NormalizeWhitespace<u8, Copied<Iter<'a, u8>>> for &'a [u8] {
  fn normalized_whitespace(self) -> NormalizeWhiteSpaceIter<u8, Copied<Iter<'a, u8>>> {
  self.iter().copied().normalized_whitespace()
  }
+
+ /// # Normalized Control/Whitespace Iterator.
+ ///
+ /// Same as `normalized_whitespace`, but also trim/normalize control
+ /// characters.
+ ///
+ /// ## Examples
+ ///
+ /// ```
+ /// use trimothy::NormalizeWhitespace;
+ ///
+ /// let abnormal: &[u8] = b" \0Hello\x1b\0World!\0";
+ /// let normal: Vec<u8> = abnormal.normalized_control_and_whitespace().collect();
+ /// assert_eq!(normal, b"Hello World!");
+ /// ```
+ fn normalized_control_and_whitespace(self)
+ -> NormalizeWhiteSpaceIter<u8, Copied<Iter<'a, u8>>> {
+ self.iter().copied().normalized_control_and_whitespace()
+ }
 }
 
 impl<'a> NormalizeWhitespace<char, Chars<'a>> for &'a str {
@@ -99,6 +145,25 @@ impl<'a> NormalizeWhitespace<char, Chars<'a>> for &'a str {
  fn normalized_whitespace(self) -> NormalizeWhiteSpaceIter<char, Chars<'a>> {
  self.chars().normalized_whitespace()
  }
+
+ /// # Normalized Control/Whitespace Iterator.
+ ///
+ /// Same as `normalized_whitespace`, but also trim/normalize control
+ /// characters.
+ ///
+ /// ## Examples
+ ///
+ /// ```
+ /// use trimothy::NormalizeWhitespace;
+ ///
+ /// let abnormal: &str = " \0Hello\x1b\0World!\0";
+ /// let normal: String = abnormal.normalized_control_and_whitespace().collect();
+ /// assert_eq!(normal, "Hello World!");
+ /// ```
+ fn normalized_control_and_whitespace(self)
+ -> NormalizeWhiteSpaceIter<char, Chars<'a>> {
+ self.chars().normalized_control_and_whitespace()
+ }
 }
 
 
@@ -110,23 +175,37 @@ impl<'a> NormalizeWhitespace<char, Chars<'a>> for &'a str {
 /// `NormalizeWhitespace::normalized_whitespace` implementation.
 pub struct NormalizeWhiteSpaceIter<T: Copy + Sized, I: Iterator<Item=T>> {
  iter: I,
+ normalize_control: bool,
  next: Option<T>,
 }
 
-/// # Helper: Implementations
+/// # Implementation Helper
 ///
 /// Implement our custom `NormalizeWhitespace` trait for existing iterators,
 /// and implement `Iterator` for the corresponding `NormalizeWhiteSpaceIter`
 /// struct.
 macro_rules! iter {
- ($ty:ty, $is:ident, $ws:literal) => (
+ ($ty:ty, $is_ws:ident, $is_ctrl:ident, $ws:literal) => (
  impl<I: Iterator<Item=$ty>> NormalizeWhitespace<$ty, I> for I {
  fn normalized_whitespace(mut self) -> NormalizeWhiteSpaceIter<$ty, I> {
  // Return the iterator, starting with the first non-whitespace
  // character.
- let next = self.by_ref().find(|n| ! n.$is());
+ let next = self.by_ref().find(|n| ! n.$is_ws());
  NormalizeWhiteSpaceIter {
  iter: self,
+ normalize_control: false,
+ next,
+ }
+ }
+
+ fn normalized_control_and_whitespace(mut self)
+ -> NormalizeWhiteSpaceIter<$ty, I> {
+ // Return the iterator, starting with the first non-whitespace,
+ // non-control character.
+ let next = self.by_ref().find(|n| ! n.$is_ws() && ! n.$is_ctrl());
+ NormalizeWhiteSpaceIter {
+ iter: self,
+ normalize_control: true,
  next,
  }
  }
@@ -136,29 +215,75 @@ macro_rules! iter {
  type Item = $ty;
 
  fn next(&mut self) -> Option<Self::Item> {
- // Anything in the buffer?
+ // Anything in the buffer from last time? Return it!
  if let Some(next) = self.next.take() { return Some(next); }
 
- // Pull the next thing.
+ // Pull the next thing!
  let next = self.iter.next()?;
- if next.$is() {
- // If there's something other than whitespace later on, return a
- // single horizontal space. Otherwise we're done.
- self.next = self.by_ref().find(|n| ! n.$is());
+
+ // Normalization required.
+ if next.$is_ws() || (self.normalize_control && next.$is_ctrl()) {
+ // Make sure there's something _after_ this that won't get
+ // normalized away, otherwise we've reached the end.
+ let ctrl = self.normalize_control;
+ self.next = self.by_ref().find(|n| ! n.$is_ws() && (! ctrl || ! n.$is_ctrl()));
  if self.next.is_some() { Some($ws) }
  else { None }
  }
- // Passthrough any non-whitespace bits.
+ // It's fine as-is.
  else { Some(next) }
  }
 
  fn size_hint(&self) -> (usize, Option<usize>) {
+ // Because we're potentially dropping things, the lower limit
+ // is at most one.
+ let lower = usize::from(self.next.is_some());
  let (_, upper) = self.iter.size_hint();
- (0, upper)
+ (lower, upper.map(|n| n + lower))
  }
  }
  );
 }
 
-iter!(char, is_whitespace, ' ');
-iter!(u8, is_ascii_whitespace, b' ');
+iter!(char, is_whitespace, is_control, ' ');
+iter!(u8, is_ascii_whitespace, is_ascii_control, b' ');
+
+
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use alloc::{
+ string::String,
+ vec::Vec,
+ };
+
+ #[test]
+ fn t_normalized_control() {
+ let example = " \0 Hello\0 Dolly. \x1b";
+ // Control is control.
+ assert_eq!(
+ example.normalized_whitespace().collect::<String>(),
+ "\0 Hello\0 Dolly. \x1b",
+ );
+
+ // Control is whitespace.
+ assert_eq!(
+ example.normalized_control_and_whitespace().collect::<String>(),
+ "Hello Dolly.",
+ );
+
+ let example = example.as_bytes();
+ // Control is control.
+ assert_eq!(
+ example.normalized_whitespace().collect::<Vec<u8>>(),
+ b"\0 Hello\0 Dolly. \x1b",
+ );
+
+ // Control is whitespace.
+ assert_eq!(
+ example.normalized_control_and_whitespace().collect::<Vec<u8>>(),
+ b"Hello Dolly.",
+ );
+ }
+}

src/lib.rs

@@ -64,11 +64,14 @@ This trait brings _mutable_ match-based trimming `String`, `Vec<u8>`, and `Box<[
 
 ### [`NormalizeWhitespace`]
 
-This trait exposes an iterator over byte/string slice contents with the edges trimmed, and all contiguous inner whitespace converted to a single horizontal space. This trait is also implemented for existing `u8`/`char` iterators.
+This trait exposes an iterator over byte/string slice contents that trims the edges and compacts/converts all inner, contiguous spans of whitespace to a single horizontal space.
+
+This trait is implemented for `&[u8]`, `&str`, and `Iterator`s with `u8`/`char` items.
 
 | Method | Description |
 | ------ | ----------- |
-| `normalized_whitespace` | Return said iterator. |
+| `normalized_whitespace` | Return a whitespace-normalizing iterator. |
+| `normalized_control_and_whitespace` | Return a control- and whitespace-normalizing iterator. |
 */
 
 #![forbid(unsafe_code)]