[TEXT-235] Add Damerau-Levenshtein distance

Author: Eirik Lorgen Tanberg

src/main/java/org/apache/commons/text/similarity/DamerauLevenshteinDistance.java

@@ -0,0 +1,298 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.text.similarity;
+
+/**
+ * An algorithm for measuring the difference between two character sequences using the
+ * <a href="https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance">Damerau-Levenshtein Distance</a>.
+ *
+ * <p>
+ * This is the number of changes needed to change one sequence into another, where each change is a single character
+ * modification (deletion, insertion, substitution, or transposition of two adjacent characters).
+ * </p>
+ * <p>
+ * This implementation uses the optimal string alignment distance variant of the Damerau-Levenshtein distance,
+ * which uses O(min(m,n)) space complexity with rolling arrays.
+ * </p>
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance">Damerau-Levenshtein Distance on Wikipedia</a>
+ * @since 1.0
+ */
+public class DamerauLevenshteinDistance implements EditDistance<Integer> {
+
+    /**
+     * The singleton instance.
+     */
+    private static final DamerauLevenshteinDistance INSTANCE = new DamerauLevenshteinDistance();
+
+    /**
+     * Gets the default instance.
+     *
+     * @return The default instance.
+     */
+    public static DamerauLevenshteinDistance getDefaultInstance() {
+        return INSTANCE;
+    }
+
+    /**
+     * Finds the Damerau-Levenshtein distance between two CharSequences if it's less than or equal to a given threshold.
+     *
+     * @param left      the first SimilarityInput, must not be null.
+     * @param right     the second SimilarityInput, must not be null.
+     * @param threshold the target threshold, must not be negative.
+     * @return result distance, or -1 if distance exceeds threshold
+     */
+    private static <E> int limitedCompare(SimilarityInput<E> left, SimilarityInput<E> right, final int threshold) {
+        if (left == null || right == null) {
+            throw new IllegalArgumentException("CharSequences must not be null");
+        }
+        if (threshold < 0) {
+            throw new IllegalArgumentException("Threshold must not be negative");
+        }
+
+        int leftLength = left.length();
+        int rightLength = right.length();
+
+        // if one string is empty, the edit distance is necessarily the length of the other
+        if (leftLength == 0) {
+            return rightLength <= threshold ? rightLength : -1;
+        }
+        if (rightLength == 0) {
+            return leftLength <= threshold ? leftLength : -1;
+        }
+
+        // the edit distance cannot be less than the length difference
+        if (Math.abs(leftLength - rightLength) > threshold) {
+            return -1;
+        }
+
+        // Ensure left is the shorter string to minimize memory usage
+        if (leftLength > rightLength) {
+            SimilarityInput<E> temp = left;
+            left = right;
+            right = temp;
+            leftLength = left.length();
+            rightLength = right.length();
+        }
+
+        // Need 3 rows for transposition: current, previous, and before previous
+        int[] prevPrev = new int[rightLength + 1];
+        int[] prev = new int[rightLength + 1];
+        int[] curr = new int[rightLength + 1];
+
+        // Initialize the first row: transforming empty string to right[0..j] requires j insertions
+        for (int j = 0; j <= rightLength; j++) {
+            prev[j] = j;
+        }
+
+        for (int i = 1; i <= leftLength; i++) {
+            // Transforming left[0..i] to empty string requires i deletions
+            curr[0] = i;
+
+            int minInRow = curr[0]; // Track minimum value in current row for early termination
+
+            for (int j = 1; j <= rightLength; j++) {
+                int cost = left.at(i - 1).equals(right.at(j - 1)) ? 0 : 1;
+
+                curr[j] = Math.min(
+                        Math.min(
+                                prev[j] + 1,        // Delete from left
+                                curr[j - 1] + 1     // Insert into left
+                        ),
+                        prev[j - 1] + cost          // Substitute (or match)
+                );
+
+                // Check for transposition of adjacent characters
+                if (i > 1 && j > 1 &&
+                        left.at(i - 1).equals(right.at(j - 2)) &&
+                        left.at(i - 2).equals(right.at(j - 1))) {
+                    curr[j] = Math.min(curr[j], prevPrev[j - 2] + cost);
+                }
+
+                minInRow = Math.min(minInRow, curr[j]);
+            }
+
+            // Early termination: if minimum value in current row exceeds threshold,
+            // the final result will definitely exceed threshold
+            if (minInRow > threshold) {
+                return -1;
+            }
+
+            // Rotate arrays for next iteration: prevPrev <- prev <- curr
+            int[] temp = prevPrev;
+            prevPrev = prev;
+            prev = curr;
+            curr = temp;
+        }
+
+        return prev[rightLength] <= threshold ? prev[rightLength] : -1;
+    }
+
+    /**
+     * Finds the Damerau-Levenshtein distance between two inputs using optimal string alignment.
+     *
+     * @param left  the first CharSequence, must not be null.
+     * @param right the second CharSequence, must not be null.
+     * @return result distance.
+     * @throws IllegalArgumentException if either CharSequence input is {@code null}.
+     */
+    private static <E> int unlimitedCompare(SimilarityInput<E> left, SimilarityInput<E> right) {
+        if (left == null || right == null) {
+            throw new IllegalArgumentException("CharSequences must not be null");
+        }
+
+        int leftLength = left.length();
+        int rightLength = right.length();
+
+        if (leftLength == 0) {
+            return rightLength;
+        }
+        if (rightLength == 0) {
+            return leftLength;
+        }
+
+        // Ensure left is the shorter string to minimize memory usage
+        if (leftLength > rightLength) {
+            SimilarityInput<E> temp = left;
+            left = right;
+            right = temp;
+            leftLength = left.length();
+            rightLength = right.length();
+        }
+
+        // Need 3 rows for transposition: current, previous, and before previous
+        // prevPrev[j] = min ops to transform left[0..i-2] to right[0..j]
+        // prev[j] = min ops to transform left[0..i-1] to right[0..j]
+        // curr[j] = min ops to transform left[0..i] to right[0..j]
+        int[] prevPrev = new int[rightLength + 1];
+        int[] prev = new int[rightLength + 1];
+        int[] curr = new int[rightLength + 1];
+
+        // Initialize the first row: transforming empty string to right[0..j] requires j insertions
+        for (int j = 0; j <= rightLength; j++) {
+            prev[j] = j;
+        }
+
+        for (int i = 1; i <= leftLength; i++) {
+            // Transforming left[0..i] to empty string requires i deletions
+            curr[0] = i;
+
+            for (int j = 1; j <= rightLength; j++) {
+                int cost = left.at(i - 1).equals(right.at(j - 1)) ? 0 : 1;
+
+                curr[j] = Math.min(
+                        Math.min(
+                                prev[j] + 1,        // Delete from left
+                                curr[j - 1] + 1     // Insert into left
+                        ),
+                        prev[j - 1] + cost          // Substitute (or match)
+                );
+
+                // Check for transposition of adjacent characters
+                if (i > 1 && j > 1 &&
+                        left.at(i - 1).equals(right.at(j - 2)) &&
+                        left.at(i - 2).equals(right.at(j - 1))) {
+                    curr[j] = Math.min(curr[j], prevPrev[j - 2] + cost);
+                }
+            }
+
+            // Rotate arrays for next iteration: prevPrev <- prev <- curr
+            int[] temp = prevPrev;
+            prevPrev = prev;
+            prev = curr;
+            curr = temp;
+        }
+
+        return prev[rightLength];
+    }
+
+    /**
+     * Threshold.
+     */
+    private final Integer threshold;
+
+    /**
+     * Constructs a default instance that uses a version of the algorithm that does not use a threshold parameter.
+     *
+     * @see DamerauLevenshteinDistance#getDefaultInstance()
+     * @deprecated Use {@link #getDefaultInstance()}.
+     */
+    @Deprecated
+    public DamerauLevenshteinDistance() {
+        this(null);
+    }
+
+    /**
+     * Constructs a new instance. If the threshold is not null, distance calculations will be limited to a maximum length.
+     * If the threshold is null, the unlimited version of the algorithm will be used.
+     *
+     * @param threshold If this is null then distances calculations will not be limited. This may not be negative.
+     */
+    public DamerauLevenshteinDistance(final Integer threshold) {
+        if (threshold != null && threshold < 0) {
+            throw new IllegalArgumentException("Threshold must not be negative");
+        }
+        this.threshold = threshold;
+    }
+
+    /**
+     * Computes the Damerau-Levenshtein distance between two Strings.
+     *
+     * <p>
+     * A higher score indicates a greater distance.
+     * </p>
+     *
+     * @param left  the first input, must not be null.
+     * @param right the second input, must not be null.
+     * @return result distance, or -1 if threshold is exceeded.
+     * @throws IllegalArgumentException if either String input {@code null}.
+     */
+    @Override
+    public Integer apply(final CharSequence left, final CharSequence right) {
+        return apply(SimilarityInput.input(left), SimilarityInput.input(right));
+    }
+
+    /**
+     * Computes the Damerau-Levenshtein distance between two inputs.
+     *
+     * <p>
+     * A higher score indicates a greater distance.
+     * </p>
+     *
+     * @param <E>   The type of similarity score unit.
+     * @param left  the first input, must not be null.
+     * @param right the second input, must not be null.
+     * @return result distance, or -1 if threshold is exceeded.
+     * @throws IllegalArgumentException if either String input {@code null}.
+     * @since 1.13.0
+     */
+    public <E> Integer apply(final SimilarityInput<E> left, final SimilarityInput<E> right) {
+        if (threshold != null) {
+            return limitedCompare(left, right, threshold);
+        }
+        return unlimitedCompare(left, right);
+    }
+
+    /**
+     * Gets the distance threshold.
+     *
+     * @return The distance threshold.
+     */
+    public Integer getThreshold() {
+        return threshold;
+    }
+}