Merge pull request #48 from NationalBI/levenshtein-limits

Add a limit parameter to the {Weighted,}Levenshtein distance.

Author: tdebatty

src/main/java/info/debatty/java/stringsimilarity/Levenshtein.java

@@ -13,6 +13,13 @@
 @Immutable
 public class Levenshtein implements MetricStringDistance {
 
+    /**
+     * Equivalent to distance(s1, s2, Integer.MAX_VALUE).
+     */
+    public final double distance(final String s1, final String s2) {
+        return distance(s1, s2, Integer.MAX_VALUE);
+    }
+
     /**
      * The Levenshtein distance, or edit distance, between two words is the
      * minimum number of single-character edits (insertions, deletions or
@@ -35,10 +42,16 @@ public class Levenshtein implements MetricStringDistance {
      *
      * @param s1 The first string to compare.
      * @param s2 The second string to compare.
+     * @param limit The maximum result to compute before stopping. This
+     *              means that the calculation can terminate early if you
+     *              only care about strings with a certain similarity.
+     *              Set this to Integer.MAX_VALUE if you want to run the
+     *              calculation to completion in every case.
      * @return The computed Levenshtein distance.
      * @throws NullPointerException if s1 or s2 is null.
      */
-    public final double distance(final String s1, final String s2) {
+    public final double distance(final String s1, final String s2,
+                                 final int limit) {
         if (s1 == null) {
             throw new NullPointerException("s1 must not be null");
         }
@@ -77,6 +90,8 @@ public final double distance(final String s1, final String s2) {
             //   edit distance is delete (i+1) chars from s to match empty t
             v1[0] = i + 1;
 
+            int minv1 = v1[0];
+
             // use formula to fill in the rest of the row
             for (int j = 0; j < s2.length(); j++) {
                 int cost = 1;
@@ -88,6 +103,12 @@ public final double distance(final String s1, final String s2) {
                         Math.min(
                                 v0[j + 1] + 1,  // Cost of remove
                                 v0[j] + cost)); // Cost of substitution
+
+                minv1 = Math.min(minv1, v1[j + 1]);
+            }
+
+            if (minv1 >= limit) {
+                return limit;
             }
 
             // copy v1 (current row) to v0 (previous row) for next iteration

src/main/java/info/debatty/java/stringsimilarity/WeightedLevenshtein.java

@@ -59,14 +59,27 @@ public WeightedLevenshtein(final CharacterSubstitutionInterface charsub,
         this.charchange = charchange;
     }
 
+    /**
+     * Equivalent to distance(s1, s2, Double.MAX_VALUE).
+     */
+    public final double distance(final String s1, final String s2) {
+        return distance(s1, s2, Double.MAX_VALUE);
+    }
+
     /**
      * Compute Levenshtein distance using provided weights for substitution.
      * @param s1 The first string to compare.
      * @param s2 The second string to compare.
+     * @param limit The maximum result to compute before stopping. This
+     *              means that the calculation can terminate early if you
+     *              only care about strings with a certain similarity.
+     *              Set this to Double.MAX_VALUE if you want to run the
+     *              calculation to completion in every case.
      * @return The computed weighted Levenshtein distance.
      * @throws NullPointerException if s1 or s2 is null.
      */
-    public final double distance(final String s1, final String s2) {
+    public final double distance(final String s1, final String s2,
+                                 final double limit) {
         if (s1 == null) {
             throw new NullPointerException("s1 must not be null");
         }
@@ -87,7 +100,7 @@ public final double distance(final String s1, final String s2) {
             return s1.length();
         }
 
-        // create two work vectors of integer distances
+        // create two work vectors of floating point (i.e. weighted) distances
         double[] v0 = new double[s2.length() + 1];
         double[] v1 = new double[s2.length() + 1];
         double[] vtemp;
@@ -110,6 +123,8 @@ public final double distance(final String s1, final String s2) {
             // to match empty t.
             v1[0] = v0[0] + deletion_cost;
 
+            double minv1 = v1[0];
+
             // use formula to fill in the rest of the row
             for (int j = 0; j < s2.length(); j++) {
                 char s2j = s2.charAt(j);
@@ -123,6 +138,12 @@ public final double distance(final String s1, final String s2) {
                         Math.min(
                                 v0[j + 1] + deletion_cost, // Cost of deletion
                                 v0[j] + cost)); // Cost of substitution
+
+                minv1 = Math.min(minv1, v1[j + 1]);
+            }
+
+            if (minv1 >= limit) {
+                return limit;
             }
 
             // copy v1 (current row) to v0 (previous row) for next iteration

src/test/java/info/debatty/java/stringsimilarity/LevenshteinTest.java

@@ -45,6 +45,11 @@ public final void testDistance() {
         assertEquals(2.0, instance.distance("My string", "M string2"), 0.0);
         assertEquals(1.0, instance.distance("My string", "My $tring"), 0.0);
 
+        // With limits.
+        assertEquals(2.0, instance.distance("My string", "M string2", 4), 0.0);
+        assertEquals(2.0, instance.distance("My string", "M string2", 2), 0.0);
+        assertEquals(1.0, instance.distance("My string", "M string2", 1), 0.0);
+
         NullEmptyTests.testDistance(instance);
     }
 }

src/test/java/info/debatty/java/stringsimilarity/WeightedLevenshteinTest.java

@@ -31,6 +31,15 @@ public double cost(char c1, char c2) {
         assertEquals(1.0, instance.distance("Strng", "String"), 0.1);
         assertEquals(1.0, instance.distance("String", "Strng"), 0.1);
 
+        // With limits.
+        assertEquals(0.0, instance.distance("String1", "String1", Double.MAX_VALUE), 0.1);
+        assertEquals(0.0, instance.distance("String1", "String1", 2.0), 0.1);
+        assertEquals(1.5, instance.distance("String1", "Srring2", Double.MAX_VALUE), 0.1);
+        assertEquals(1.5, instance.distance("String1", "Srring2", 2.0), 0.1);
+        assertEquals(1.5, instance.distance("String1", "Srring2", 1.5), 0.1);
+        assertEquals(1.0, instance.distance("String1", "Srring2", 1.0), 0.1);
+        assertEquals(4.0, instance.distance("String1", "Potato", 4.0), 0.1);
+
         NullEmptyTests.testDistance(instance);
     }
 
@@ -75,6 +84,16 @@ public double insertionCost(char c) {
         assertEquals(1.0, instance.distance("Strig", "String"), 0.1);
         assertEquals(1.0, instance.distance("String", "Strig"), 0.1);
 
+        // Same as above with limits.
+        assertEquals(0.0, instance.distance("String1", "String1", Double.MAX_VALUE), 0.1);
+        assertEquals(0.0, instance.distance("String1", "String1", 2.0), 0.1);
+        assertEquals(0.5, instance.distance("String1", "Srring1", Double.MAX_VALUE), 0.1);
+        assertEquals(0.5, instance.distance("String1", "Srring1", 2.0), 0.1);
+        assertEquals(1.5, instance.distance("String1", "Srring2", 2.0), 0.1);
+        assertEquals(1.5, instance.distance("String1", "Srring2", 1.5), 0.1);
+        assertEquals(1.0, instance.distance("String1", "Srring2", 1.0), 0.1);
+        assertEquals(4.0, instance.distance("String1", "Potato", 4.0), 0.1);
+
         NullEmptyTests.testDistance(instance);
     }
 }