Add another implementation of Levenshtein distance (#702)

* chore: add `edit_distance.rs` to DIRECTORY.md

* feat: implement Edit Distance algorithm

* chore(tests): add few more checks

* chore: rename files
- rename `src/string/levenshtein_distance.rs` to `src/string/levenshtein_distance/optimized_dp.rs`
- move and rename `src/dynamic_programming/edit_distance.rs` to `src/string/levenshtein_distance/naive_dp.rs`

* chore: rename `levenshtein_distance` function

* chore: update DIRECTORY.md

* chore: update `mod.rs` files

* chore: format code with `fmt`

* chore: update DIRECTORY.md

* feat: implement levenshtein distance in both naive and optimized version using DP

* chore: update DIRECTORY.md

* chore(tests): update tests

* ref: Refactor tests for Levenshtein distance calculation
- Consolidated test cases into a constant array for improved readability and maintainability
- Simplified test structure by removing macro-based test generation, enhancing code clarity
- Introduced a `run_test_case` function to encapsulate test logic, enhancing test function conciseness.
- Organized test suite into separate modules for naive and optimized implementations, promoting code organization.

---------

Co-authored-by: Piotr Idzik <[email protected]>

Author: sozelfist

src/string/levenshtein_distance.rs

@@ -1,52 +1,122 @@
+//! Provides functions to calculate the Levenshtein distance between two strings.
+//!
+//! The Levenshtein distance is a measure of the similarity between two strings by calculating the minimum number of single-character
+//! edits (insertions, deletions, or substitutions) required to change one string into the other.
+
 use std::cmp::min;
 
-/// The Levenshtein distance (or edit distance) between 2 strings.\
-/// This edit distance is defined as being 1 point per insertion, substitution, or deletion which must be made to make the strings equal.
-/// This function iterates over the bytes in the string, so it may not behave entirely as expected for non-ASCII strings.
+/// Calculates the Levenshtein distance between two strings using a naive dynamic programming approach.
+///
+/// The Levenshtein distance is a measure of the similarity between two strings by calculating the minimum number of single-character
+/// edits (insertions, deletions, or substitutions) required to change one string into the other.
+///
+/// # Arguments
+///
+/// * `string1` - A reference to the first string.
+/// * `string2` - A reference to the second string.
+///
+/// # Returns
+///
+/// The Levenshtein distance between the two input strings.
+///
+/// This function computes the Levenshtein distance by constructing a dynamic programming matrix and iteratively filling it in.
+/// It follows the standard top-to-bottom, left-to-right approach for filling in the matrix.
+///
+/// # Complexity
+///
+/// - Time complexity: O(nm),
+/// - Space complexity: O(nm),
+///
+/// where n and m are lengths of `string1` and `string2`.
+///
+/// Note that this implementation uses a straightforward dynamic programming approach without any space optimization.
+/// It may consume more memory for larger input strings compared to the optimized version.
+pub fn naive_levenshtein_distance(string1: &str, string2: &str) -> usize {
+    let distance_matrix: Vec<Vec<usize>> = (0..=string1.len())
+        .map(|i| {
+            (0..=string2.len())
+                .map(|j| {
+                    if i == 0 {
+                        j
+                    } else if j == 0 {
+                        i
+                    } else {
+                        0
+                    }
+                })
+                .collect()
+        })
+        .collect();
+
+    let updated_matrix = (1..=string1.len()).fold(distance_matrix, |matrix, i| {
+        (1..=string2.len()).fold(matrix, |mut inner_matrix, j| {
+            let cost = if string1.as_bytes()[i - 1] == string2.as_bytes()[j - 1] {
+                0
+            } else {
+                1
+            };
+            inner_matrix[i][j] = (inner_matrix[i - 1][j - 1] + cost)
+                .min(inner_matrix[i][j - 1] + 1)
+                .min(inner_matrix[i - 1][j] + 1);
+            inner_matrix
+        })
+    });
+
+    updated_matrix[string1.len()][string2.len()]
+}
+
+/// Calculates the Levenshtein distance between two strings using an optimized dynamic programming approach.
 ///
-/// For a detailed explanation, check the example on Uncyclopedia: <https://en.wikipedia.org/wiki/Levenshtein_distance>\
-/// (see the examples with the matrices, for instance between KITTEN and SITTING)
+/// This edit distance is defined as 1 point per insertion, substitution, or deletion required to make the strings equal.
 ///
-/// Note that although we compute a matrix, left-to-right, top-to-bottom, at each step all we need to compute `cell[i][j]` is:
-///   - `cell[i][j-1]`
-///   - `cell[i-j][j]`
-///   - `cell[i-i][j-1]`
+/// # Arguments
 ///
-/// This can be achieved by only using one "rolling" row and one additional variable, when computed `cell[i][j]` (or `row[i]`):
-///   - `cell[i][j-1]` is the value to the left, on the same row (the one we just computed, `row[i-1]`)
-///   - `cell[i-1][j]` is the value at `row[i]`, the one we're changing
-///   - `cell[i-1][j-1]` was the value at `row[i-1]` before we changed it, for that we'll use a variable
+/// * `string1` - The first string.
+/// * `string2` - The second string.
+///
+/// # Returns
+///
+/// The Levenshtein distance between the two input strings.
+/// For a detailed explanation, check the example on [Uncyclopedia](https://en.wikipedia.org/wiki/Levenshtein_distance).
+/// This function iterates over the bytes in the string, so it may not behave entirely as expected for non-ASCII strings.
 ///
-/// Doing this reduces space complexity from O(nm) to O(n)
+/// Note that this implementation utilizes an optimized dynamic programming approach, significantly reducing the space complexity from O(nm) to O(n), where n and m are the lengths of `string1` and `string2`.
 ///
-/// Second note: if we want to minimize space, since we're now O(n) make sure you use the shortest string horizontally, and the longest vertically
+/// Additionally, it minimizes space usage by leveraging the shortest string horizontally and the longest string vertically in the computation matrix.
 ///
 /// # Complexity
-///   - time complexity: O(nm),
-///   - space complexity: O(n),
 ///
-/// where n and m are lengths of `str_a` and `str_b`
-pub fn levenshtein_distance(string1: &str, string2: &str) -> usize {
+/// - Time complexity: O(nm),
+/// - Space complexity: O(n),
+///
+/// where n and m are lengths of `string1` and `string2`.
+pub fn optimized_levenshtein_distance(string1: &str, string2: &str) -> usize {
     if string1.is_empty() {
         return string2.len();
     }
     let l1 = string1.len();
     let mut prev_dist: Vec<usize> = (0..=l1).collect();
 
     for (row, c2) in string2.chars().enumerate() {
-        let mut prev_substitution_cost = prev_dist[0]; // we'll keep a reference to matrix[i-1][j-1] (top-left cell)
-        prev_dist[0] = row + 1; // diff with empty string, since `row` starts at 0, it's `row + 1`
+        // we'll keep a reference to matrix[i-1][j-1] (top-left cell)
+        let mut prev_substitution_cost = prev_dist[0];
+        // diff with empty string, since `row` starts at 0, it's `row + 1`
+        prev_dist[0] = row + 1;
 
         for (col, c1) in string1.chars().enumerate() {
-            let deletion_cost = prev_dist[col] + 1; // "on the left" in the matrix (i.e. the value we just computed)
-            let insertion_cost = prev_dist[col + 1] + 1; // "on the top" in the matrix (means previous)
+            // "on the left" in the matrix (i.e. the value we just computed)
+            let deletion_cost = prev_dist[col] + 1;
+            // "on the top" in the matrix (means previous)
+            let insertion_cost = prev_dist[col + 1] + 1;
             let substitution_cost = if c1 == c2 {
-                prev_substitution_cost // last char is the same on both ends, so the min_distance is left unchanged from matrix[i-1][i+1]
+                // last char is the same on both ends, so the min_distance is left unchanged from matrix[i-1][i+1]
+                prev_substitution_cost
             } else {
-                prev_substitution_cost + 1 // substitute the last character
+                // substitute the last character
+                prev_substitution_cost + 1
             };
-
-            prev_substitution_cost = prev_dist[col + 1]; // save the old value at (i-1, j-1)
+            // save the old value at (i-1, j-1)
+            prev_substitution_cost = prev_dist[col + 1];
             prev_dist[col + 1] = _min3(deletion_cost, insertion_cost, substitution_cost);
         }
     }
@@ -60,94 +130,39 @@ fn _min3<T: Ord>(a: T, b: T, c: T) -> T {
 
 #[cfg(test)]
 mod tests {
-    use super::_min3;
-    use super::levenshtein_distance;
-
-    #[test]
-    fn test_doc_example() {
-        assert_eq!(2, levenshtein_distance("FROG", "DOG"));
-    }
-
-    #[test]
-    fn return_0_with_empty_strings() {
-        assert_eq!(0, levenshtein_distance("", ""));
-    }
-
-    #[test]
-    fn return_1_with_empty_and_a() {
-        assert_eq!(1, levenshtein_distance("", "a"));
-    }
-
-    #[test]
-    fn return_1_with_a_and_empty() {
-        assert_eq!(1, levenshtein_distance("a", ""));
-    }
-
-    #[test]
-    fn return_1_with_ab_and_a() {
-        assert_eq!(1, levenshtein_distance("ab", "a"));
-    }
-
-    #[test]
-    fn return_0_with_foobar_and_foobar() {
-        assert_eq!(0, levenshtein_distance("foobar", "foobar"));
-    }
-
-    #[test]
-    fn return_6_with_foobar_and_barfoo() {
-        assert_eq!(6, levenshtein_distance("foobar", "barfoo"));
-    }
-
-    #[test]
-    fn return_1_with_kind_and_bind() {
-        assert_eq!(1, levenshtein_distance("kind", "bind"));
-    }
-
-    #[test]
-    fn return_3_with_winner_and_win() {
-        assert_eq!(3, levenshtein_distance("winner", "win"));
-    }
-
-    #[test]
-    fn equal_strings() {
-        assert_eq!(0, levenshtein_distance("Hello, world!", "Hello, world!"));
-        assert_eq!(0, levenshtein_distance("Hello, world!", "Hello, world!"));
-        assert_eq!(0, levenshtein_distance("Test_Case_#1", "Test_Case_#1"));
-        assert_eq!(0, levenshtein_distance("Test_Case_#1", "Test_Case_#1"));
-    }
-
-    #[test]
-    fn one_edit_difference() {
-        assert_eq!(1, levenshtein_distance("Hello, world!", "Hell, world!"));
-        assert_eq!(1, levenshtein_distance("Test_Case_#1", "Test_Case_#2"));
-        assert_eq!(1, levenshtein_distance("Test_Case_#1", "Test_Case_#10"));
-        assert_eq!(1, levenshtein_distance("Hello, world!", "Hell, world!"));
-        assert_eq!(1, levenshtein_distance("Test_Case_#1", "Test_Case_#2"));
-        assert_eq!(1, levenshtein_distance("Test_Case_#1", "Test_Case_#10"));
-    }
-
-    #[test]
-    fn several_differences() {
-        assert_eq!(2, levenshtein_distance("My Cat", "My Case"));
-        assert_eq!(7, levenshtein_distance("Hello, world!", "Goodbye, world!"));
-        assert_eq!(6, levenshtein_distance("Test_Case_#3", "Case #3"));
-        assert_eq!(2, levenshtein_distance("My Cat", "My Case"));
-        assert_eq!(7, levenshtein_distance("Hello, world!", "Goodbye, world!"));
-        assert_eq!(6, levenshtein_distance("Test_Case_#3", "Case #3"));
-    }
-
-    #[test]
-    fn return_1_with_1_2_3() {
-        assert_eq!(1, _min3(1, 2, 3));
-    }
-
-    #[test]
-    fn return_1_with_3_2_1() {
-        assert_eq!(1, _min3(3, 2, 1));
-    }
-
-    #[test]
-    fn return_1_with_2_3_1() {
-        assert_eq!(1, _min3(2, 3, 1));
-    }
+    const LEVENSHTEIN_DISTANCE_TEST_CASES: &[(&str, &str, usize)] = &[
+        ("", "", 0),
+        ("Hello, World!", "Hello, World!", 0),
+        ("", "Rust", 4),
+        ("horse", "ros", 3),
+        ("tan", "elephant", 6),
+        ("execute", "intention", 8),
+    ];
+
+    macro_rules! levenshtein_distance_tests {
+        ($function:ident) => {
+            mod $function {
+                use super::*;
+
+                fn run_test_case(string1: &str, string2: &str, expected_distance: usize) {
+                    assert_eq!(super::super::$function(string1, string2), expected_distance);
+                    assert_eq!(super::super::$function(string2, string1), expected_distance);
+                    assert_eq!(super::super::$function(string1, string1), 0);
+                    assert_eq!(super::super::$function(string2, string2), 0);
+                }
+
+                #[test]
+                fn test_levenshtein_distance() {
+                    for &(string1, string2, expected_distance) in
+                        LEVENSHTEIN_DISTANCE_TEST_CASES.iter()
+                    {
+                        run_test_case(string1, string2, expected_distance);
+                    }
+                }
+            }
+        };
+    }
+
+    levenshtein_distance_tests!(naive_levenshtein_distance);
+    levenshtein_distance_tests!(optimized_levenshtein_distance);
 }

src/string/mod.rs

@@ -32,7 +32,7 @@ pub use self::duval_algorithm::duval_algorithm;
 pub use self::hamming_distance::hamming_distance;
 pub use self::jaro_winkler_distance::jaro_winkler_distance;
 pub use self::knuth_morris_pratt::knuth_morris_pratt;
-pub use self::levenshtein_distance::levenshtein_distance;
+pub use self::levenshtein_distance::{naive_levenshtein_distance, optimized_levenshtein_distance};
 pub use self::lipogram::is_lipogram;
 pub use self::manacher::manacher;
 pub use self::palindrome::is_palindrome;