Merge branch 'master' into ref/string/z_algorithm

vil02 · web-flow · commit 4aaa25e7c7e9 · 2024-10-08T21:20:25.000+02:00
diff --git a/src/data_structures/trie.rs b/src/data_structures/trie.rs
@@ -1,18 +1,29 @@
+//! This module provides a generic implementation of a Trie (prefix tree).
+//! A Trie is a tree-like data structure that is commonly used to store sequences of keys
+//! (such as strings, integers, or other iterable types) where each node represents one element
+//! of the key, and values can be associated with full sequences.
+
 use std::collections::HashMap;
 use std::hash::Hash;
 
+/// A single node in the Trie structure, representing a key and an optional value.
 #[derive(Debug, Default)]
 struct Node<Key: Default, Type: Default> {
+    /// A map of children nodes where each key maps to another `Node`.
     children: HashMap<Key, Node<Key, Type>>,
+    /// The value associated with this node, if any.
     value: Option<Type>,
 }
 
+/// A generic Trie (prefix tree) data structure that allows insertion and lookup
+/// based on a sequence of keys.
 #[derive(Debug, Default)]
 pub struct Trie<Key, Type>
 where
     Key: Default + Eq + Hash,
     Type: Default,
 {
+    /// The root node of the Trie, which does not hold a value itself.
     root: Node<Key, Type>,
 }
 
@@ -21,12 +32,21 @@ where
     Key: Default + Eq + Hash,
     Type: Default,
 {
+    /// Creates a new, empty `Trie`.
+    ///
+    /// # Returns
+    /// A `Trie` instance with an empty root node.
     pub fn new() -> Self {
         Self {
             root: Node::default(),
         }
     }
 
+    /// Inserts a value into the Trie, associating it with a sequence of keys.
+    ///
+    /// # Arguments
+    /// - `key`: An iterable sequence of keys (e.g., characters in a string or integers in a vector).
+    /// - `value`: The value to associate with the sequence of keys.
     pub fn insert(&mut self, key: impl IntoIterator<Item = Key>, value: Type)
     where
         Key: Eq + Hash,
@@ -38,60 +58,98 @@ where
         node.value = Some(value);
     }
 
+    /// Retrieves a reference to the value associated with a sequence of keys, if it exists.
+    ///
+    /// # Arguments
+    /// - `key`: An iterable sequence of keys (e.g., characters in a string or integers in a vector).
+    ///
+    /// # Returns
+    /// An `Option` containing a reference to the value if the sequence of keys exists in the Trie,
+    /// or `None` if it does not.
     pub fn get(&self, key: impl IntoIterator<Item = Key>) -> Option<&Type>
     where
         Key: Eq + Hash,
     {
         let mut node = &self.root;
         for c in key {
-            if node.children.contains_key(&c) {
-                node = node.children.get(&c).unwrap()
-            } else {
-                return None;
-            }
+            node = node.children.get(&c)?;
         }
         node.value.as_ref()
     }
 }
 
 #[cfg(test)]
 mod tests {
-
     use super::*;
 
     #[test]
-    fn test_insertion() {
+    fn test_insertion_and_retrieval_with_strings() {
         let mut trie = Trie::new();
-        assert_eq!(trie.get("".chars()), None);
 
         trie.insert("foo".chars(), 1);
+        assert_eq!(trie.get("foo".chars()), Some(&1));
         trie.insert("foobar".chars(), 2);
+        assert_eq!(trie.get("foobar".chars()), Some(&2));
+        assert_eq!(trie.get("foo".chars()), Some(&1));
+        trie.insert("bar".chars(), 3);
+        assert_eq!(trie.get("bar".chars()), Some(&3));
+        assert_eq!(trie.get("baz".chars()), None);
+        assert_eq!(trie.get("foobarbaz".chars()), None);
+    }
 
+    #[test]
+    fn test_insertion_and_retrieval_with_integers() {
         let mut trie = Trie::new();
-        assert_eq!(trie.get(vec![1, 2, 3]), None);
 
         trie.insert(vec![1, 2, 3], 1);
-        trie.insert(vec![3, 4, 5], 2);
+        assert_eq!(trie.get(vec![1, 2, 3]), Some(&1));
+        trie.insert(vec![1, 2, 3, 4, 5], 2);
+        assert_eq!(trie.get(vec![1, 2, 3, 4, 5]), Some(&2));
+        assert_eq!(trie.get(vec![1, 2, 3]), Some(&1));
+        trie.insert(vec![10, 20, 30], 3);
+        assert_eq!(trie.get(vec![10, 20, 30]), Some(&3));
+        assert_eq!(trie.get(vec![4, 5, 6]), None);
+        assert_eq!(trie.get(vec![1, 2, 3, 4, 5, 6]), None);
     }
 
     #[test]
-    fn test_get() {
+    fn test_empty_trie() {
+        let trie: Trie<char, i32> = Trie::new();
+
+        assert_eq!(trie.get("foo".chars()), None);
+        assert_eq!(trie.get("".chars()), None);
+    }
+
+    #[test]
+    fn test_insert_empty_key() {
+        let mut trie: Trie<char, i32> = Trie::new();
+
+        trie.insert("".chars(), 42);
+        assert_eq!(trie.get("".chars()), Some(&42));
+        assert_eq!(trie.get("foo".chars()), None);
+    }
+
+    #[test]
+    fn test_overlapping_keys() {
         let mut trie = Trie::new();
-        trie.insert("foo".chars(), 1);
-        trie.insert("foobar".chars(), 2);
-        trie.insert("bar".chars(), 3);
-        trie.insert("baz".chars(), 4);
 
-        assert_eq!(trie.get("foo".chars()), Some(&1));
-        assert_eq!(trie.get("food".chars()), None);
+        trie.insert("car".chars(), 1);
+        trie.insert("cart".chars(), 2);
+        trie.insert("carter".chars(), 3);
+        assert_eq!(trie.get("car".chars()), Some(&1));
+        assert_eq!(trie.get("cart".chars()), Some(&2));
+        assert_eq!(trie.get("carter".chars()), Some(&3));
+        assert_eq!(trie.get("care".chars()), None);
+    }
 
+    #[test]
+    fn test_partial_match() {
         let mut trie = Trie::new();
-        trie.insert(vec![1, 2, 3, 4], 1);
-        trie.insert(vec![42], 2);
-        trie.insert(vec![42, 6, 1000], 3);
-        trie.insert(vec![1, 2, 4, 16, 32], 4);
 
-        assert_eq!(trie.get(vec![42, 6, 1000]), Some(&3));
-        assert_eq!(trie.get(vec![43, 44, 45]), None);
+        trie.insert("apple".chars(), 10);
+        assert_eq!(trie.get("app".chars()), None);
+        assert_eq!(trie.get("appl".chars()), None);
+        assert_eq!(trie.get("apple".chars()), Some(&10));
+        assert_eq!(trie.get("applepie".chars()), None);
     }
 }
diff --git a/src/string/pangram.rs b/src/string/pangram.rs
@@ -1,54 +1,53 @@
+//! This module provides functionality to check if a given string is a pangram.
+//!
+//! A pangram is a sentence that contains every letter of the alphabet at least once.
+//! This module can distinguish between a non-pangram, a regular pangram, and a
+//! perfect pangram, where each letter appears exactly once.
+
 use std::collections::HashSet;
 
+/// Represents the status of a string in relation to the pangram classification.
 #[derive(PartialEq, Debug)]
 pub enum PangramStatus {
     NotPangram,
     Pangram,
     PerfectPangram,
 }
 
-/// Function that checks if the slice is a pangram
-///
-/// ## Arguments
-///
-/// * `pangram_str` - the slice that will be checked if is a pangram
-///
-/// ## Examples
+fn compute_letter_counts(pangram_str: &str) -> std::collections::HashMap<char, usize> {
+    let mut letter_counts = std::collections::HashMap::new();
+
+    for ch in pangram_str
+        .to_lowercase()
+        .chars()
+        .filter(|c| c.is_ascii_alphabetic())
+    {
+        *letter_counts.entry(ch).or_insert(0) += 1;
+    }
+
+    letter_counts
+}
+
+/// Determines if the input string is a pangram, and classifies it as either a regular or perfect pangram.
 ///
-/// ```
-/// use the_algorithms_rust::string::is_pangram;
-/// use std::collections::HashSet;
-/// use the_algorithms_rust::string::PangramStatus;
+/// # Arguments
 ///
-/// assert_eq!(
-///    is_pangram("This is not a pangram"),
-///    PangramStatus::NotPangram
-/// );
+/// * `pangram_str` - A reference to the string slice to be checked for pangram status.
 ///
-/// assert_eq!(
-///    is_pangram("The quick brown fox jumps over the lazy dog"),
-///    PangramStatus::Pangram
-/// );
+/// # Returns
 ///
-/// assert_eq!(
-///    is_pangram("Mr. Jock, TV quiz PhD, bags few lynx"),
-///    PangramStatus::PerfectPangram
-/// );
-/// ```
+/// A `PangramStatus` enum indicating whether the string is a pangram, and if so, whether it is a perfect pangram.
 pub fn is_pangram(pangram_str: &str) -> PangramStatus {
-    let alphabet: HashSet<char> = "abcdefghijklmnopqrstuvwxyz".chars().collect();
+    let letter_counts = compute_letter_counts(pangram_str);
 
-    let letters_used: HashSet<char> = pangram_str
-        .to_lowercase()
-        .chars()
-        .filter(|c| c.is_ascii_alphabetic())
-        .collect();
+    let alphabet: HashSet<char> = ('a'..='z').collect();
+    let used_letters: HashSet<_> = letter_counts.keys().cloned().collect();
 
-    if letters_used != alphabet {
+    if used_letters != alphabet {
         return PangramStatus::NotPangram;
-    };
+    }
 
-    if pangram_str.chars().filter(|c| c.is_alphabetic()).count() == alphabet.len() {
+    if letter_counts.values().all(|&count| count == 1) {
         PangramStatus::PerfectPangram
     } else {
         PangramStatus::Pangram
@@ -59,46 +58,35 @@ pub fn is_pangram(pangram_str: &str) -> PangramStatus {
 mod tests {
     use super::*;
 
-    #[test]
-    fn test_not_pangram() {
-        assert_eq!(
-            is_pangram("This is not a pangram"),
-            PangramStatus::NotPangram
-        );
-        assert_eq!(is_pangram("today is a good day"), PangramStatus::NotPangram);
-        assert_eq!(
-            is_pangram(
-                "this is almost a pangram but it does not have bcfghjkqwxy and the last letter"
-            ),
-            PangramStatus::NotPangram
-        );
-    }
-
-    #[test]
-    fn test_pangram() {
-        assert_eq!(
-            is_pangram("The quick brown fox jumps over the lazy dog"),
-            PangramStatus::Pangram
-        );
-        assert_eq!(
-            is_pangram("A mad boxer shot a quick, gloved jab to the jaw of his dizzy opponent"),
-            PangramStatus::Pangram
-        );
-        assert_eq!(
-            is_pangram("Amazingly few discotheques provide jukeboxes"),
-            PangramStatus::Pangram
-        );
-        assert_eq!(
-            is_pangram("How vexingly quick daft zebras jump"),
-            PangramStatus::Pangram
-        );
+    macro_rules! pangram_tests {
+        ($($name:ident: $tc:expr,)*) => {
+            $(
+                #[test]
+                fn $name() {
+                    let (input, expected) = $tc;
+                    assert_eq!(is_pangram(input), expected);
+                }
+            )*
+        };
     }
 
-    #[test]
-    fn test_perfect_pangram() {
-        assert_eq!(
-            is_pangram("Mr. Jock, TV quiz PhD, bags few lynx"),
-            PangramStatus::PerfectPangram
-        );
+    pangram_tests! {
+        test_not_pangram_simple: ("This is not a pangram", PangramStatus::NotPangram),
+        test_not_pangram_day: ("today is a good day", PangramStatus::NotPangram),
+        test_not_pangram_almost: ("this is almost a pangram but it does not have bcfghjkqwxy and the last letter", PangramStatus::NotPangram),
+        test_pangram_standard: ("The quick brown fox jumps over the lazy dog", PangramStatus::Pangram),
+        test_pangram_boxer: ("A mad boxer shot a quick, gloved jab to the jaw of his dizzy opponent", PangramStatus::Pangram),
+        test_pangram_discotheques: ("Amazingly few discotheques provide jukeboxes", PangramStatus::Pangram),
+        test_pangram_zebras: ("How vexingly quick daft zebras jump", PangramStatus::Pangram),
+        test_perfect_pangram_jock: ("Mr. Jock, TV quiz PhD, bags few lynx", PangramStatus::PerfectPangram),
+        test_empty_string: ("", PangramStatus::NotPangram),
+        test_repeated_letter: ("aaaaa", PangramStatus::NotPangram),
+        test_non_alphabetic: ("12345!@#$%", PangramStatus::NotPangram),
+        test_mixed_case_pangram: ("ThE QuiCk BroWn FoX JumPs OveR tHe LaZy DoG", PangramStatus::Pangram),
+        test_perfect_pangram_with_symbols: ("Mr. Jock, TV quiz PhD, bags few lynx!", PangramStatus::PerfectPangram),
+        test_long_non_pangram: (&"a".repeat(1000), PangramStatus::NotPangram),
+        test_near_pangram_missing_one_letter: ("The quick brown fox jumps over the lazy do", PangramStatus::NotPangram),
+        test_near_pangram_missing_two_letters: ("The quick brwn f jumps ver the lazy dg", PangramStatus::NotPangram),
+        test_near_pangram_with_special_characters: ("Th3 qu!ck brown f0x jumps 0v3r th3 l@zy d0g.", PangramStatus::NotPangram),
     }
 }
