merge pull request #7

`trim_to_height()`

Author: cratelyn

src/str.rs

@@ -11,6 +11,7 @@ use self::ellipsis::{Ascii, Contd, Horizontal};
 /// see [`Limited`] for more information.
 pub mod ellipsis;
 
+mod trim_to_height;
 mod trim_to_length;
 mod trim_to_width;
 
@@ -72,6 +73,9 @@ pub trait Limited {
 
     /// returns a string limited by width.
     fn trim_to_width<E: Ellipsis>(&self, length: usize) -> String;
+
+    /// returns a string limited by height.
+    fn trim_to_height<E: Ellipsis>(&self, height: usize) -> String;
 }
 
 // === impl s: asref<str> ===
@@ -115,4 +119,20 @@ where
             .limited(width)
             .collect()
     }
+
+    fn trim_to_height<E: Ellipsis>(&self, height: usize) -> String {
+        use {self::trim_to_height::TrimToHeightIter, crate::iter::Limited};
+
+        let value: &'_ str = self.as_ref();
+
+        if value.is_empty() || height == 0 {
+            return String::default();
+        }
+
+        TrimToHeightIter::<E>::new(value)
+            .limited(height)
+            .collect::<Vec<&str>>()
+            .as_slice()
+            .join("\n")
+    }
 }

src/str/ellipsis.rs

@@ -12,6 +12,9 @@ pub struct Ascii;
 /// a more verbose ellipsis.
 pub struct Contd;
 
+/// an empty ellipsis.
+pub struct Empty;
+
 /// a horizontal utf-8 ellipsis.
 pub struct Horizontal;
 
@@ -31,6 +34,14 @@ impl Ellipsis for Contd {
     }
 }
 
+// === impl empty ===
+
+impl Ellipsis for Empty {
+    fn ellipsis() -> &'static str {
+        ""
+    }
+}
+
 // === impl horizontal ===
 
 impl Ellipsis for Horizontal {

tests/str.rs

@@ -189,3 +189,72 @@ mod strs_can_be_truncated {
         });
     }
 }
+
+mod strs_can_be_truncated_by_height {
+    use super::*;
+
+    const INPUT: &str = "\
+        first\n\
+        second\n\
+        third\
+    ";
+
+    #[test]
+    fn zero_lines_is_empty() {
+        INPUT
+            .trim_to_height::<ellipsis::Ascii>(0)
+            .pipe(|s| assert!(s.is_empty(), "{s} is not empty"))
+    }
+
+    #[test]
+    fn one_line_can_be_passed_through() {
+        "value"
+            .trim_to_height::<ellipsis::Empty>(1)
+            .pipe(|s| assert_eq!(s, "value"))
+    }
+
+    #[test]
+    fn one_line_with_a_trailing_newlines_can_be_passed_through() {
+        "value\n"
+            .trim_to_height::<ellipsis::Empty>(1)
+            .pipe(|s| assert_eq!(s, "value"))
+    }
+
+    #[test]
+    fn one_line_with_multiple_consecutibe_newlines_can_be_trimmed_to_a_height() {
+        "top\n\
+         \n\
+         \n\
+         bottom\n"
+            .trim_to_height::<ellipsis::Empty>(4)
+            .pipe(|s| {
+                assert_eq!(
+                    s,
+                    "\
+                    top\n\
+                    \n\
+                    \n\
+                    bottom"
+                )
+            })
+    }
+
+    #[test]
+    fn two_lines_tall() {
+        "\
+            first\n\
+            second\n\
+            third\
+        "
+        .trim_to_height::<ellipsis::Ascii>(2)
+        .pipe(|s| {
+            assert_eq!(
+                s,
+                "\
+                    first\n\
+                    ...\
+                ",
+            )
+        });
+    }
+}