001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.text.similarity;
018
019/**
020 * A similarity algorithm indicating the length of the longest common subsequence between two strings.
021 *
022 * <p>
023 * The Longest common subsequence algorithm returns the length of the longest subsequence that two strings have in
024 * common. Two strings that are entirely different, return a value of 0, and two strings that return a value
025 * of the commonly shared length implies that the strings are completely the same in value and position.
026 * <i>Note.</i>  Generally this algorithm is fairly inefficient, as for length <i>m</i>, <i>n</i> of the input
027 * {@code CharSequence}'s {@code left} and {@code right} respectively, the runtime of the
028 * algorithm is <i>O(m*n)</i>.
029 * </p>
030 *
031 * <p>
032 * This implementation is based on the Longest Commons Substring algorithm
033 * from <a href="https://en.wikipedia.org/wiki/Longest_common_subsequence_problem">
034 * https://en.wikipedia.org/wiki/Longest_common_subsequence_problem</a>.
035 * </p>
036 *
037 * <p>For further reading see:</p>
038 *
039 * <p>Lothaire, M. <i>Applied combinatorics on words</i>. New York: Cambridge U Press, 2005. <b>12-13</b></p>
040 *
041 * @since 1.0
042 */
043public class LongestCommonSubsequence implements SimilarityScore<Integer> {
044
045    /**
046     * Calculates longest common subsequence similarity score of two {@code CharSequence}'s passed as
047     * input.
048     *
049     * @param left first character sequence
050     * @param right second character sequence
051     * @return longestCommonSubsequenceLength
052     * @throws IllegalArgumentException
053     *             if either String input {@code null}
054     */
055    @Override
056    public Integer apply(final CharSequence left, final CharSequence right) {
057        // Quick return for invalid inputs
058        if (left == null || right == null) {
059            throw new IllegalArgumentException("Inputs must not be null");
060        }
061        return longestCommonSubsequence(left, right).length();
062    }
063
064    /**
065     * Computes the longest common subsequence between the two {@code CharSequence}'s passed as input.
066     *
067     * <p>
068     * Note, a substring and subsequence are not necessarily the same thing. Indeed, {@code abcxyzqrs} and
069     * {@code xyzghfm} have both the same common substring and subsequence, namely {@code xyz}. However,
070     * {@code axbyczqrs} and {@code abcxyzqtv} have the longest common subsequence {@code xyzq} because a
071     * subsequence need not have adjacent characters.
072     * </p>
073     *
074     * <p>
075     * For reference, we give the definition of a subsequence for the reader: a <i>subsequence</i> is a sequence that
076     * can be derived from another sequence by deleting some elements without changing the order of the remaining
077     * elements.
078     * </p>
079     *
080     * @param left first character sequence
081     * @param right second character sequence
082     * @return The longest common subsequence found
083     * @throws IllegalArgumentException
084     *             if either String input {@code null}
085     * @deprecated Deprecated as of 1.2 due to a typo in the method name.
086     *              Use {@link #longestCommonSubsequence(CharSequence, CharSequence)} instead.
087     *              This method will be removed in 2.0.
088     */
089    @Deprecated
090    public CharSequence logestCommonSubsequence(final CharSequence left, final CharSequence right) {
091        return longestCommonSubsequence(left, right);
092    }
093
094   /**
095    * Computes the longest common subsequence between the two {@code CharSequence}'s passed as
096    * input.
097    *
098    * <p>
099    * Note, a substring and subsequence are not necessarily the same thing. Indeed, {@code abcxyzqrs} and
100    * {@code xyzghfm} have both the same common substring and subsequence, namely {@code xyz}. However,
101    * {@code axbyczqrs} and {@code abcxyzqtv} have the longest common subsequence {@code xyzq} because a
102    * subsequence need not have adjacent characters.
103    * </p>
104    *
105    * <p>
106    * For reference, we give the definition of a subsequence for the reader: a <i>subsequence</i> is a sequence that
107    * can be derived from another sequence by deleting some elements without changing the order of the remaining
108    * elements.
109    * </p>
110    *
111    * @param left first character sequence
112    * @param right second character sequence
113    * @return The longest common subsequence found
114    * @throws IllegalArgumentException
115    *             if either String input {@code null}
116    * @since 1.2
117    */
118   public CharSequence longestCommonSubsequence(final CharSequence left, final CharSequence right) {
119       // Quick return
120       if (left == null || right == null) {
121           throw new IllegalArgumentException("Inputs must not be null");
122       }
123       final StringBuilder longestCommonSubstringArray = new StringBuilder(Math.max(left.length(), right.length()));
124       final int[][] lcsLengthArray = longestCommonSubstringLengthArray(left, right);
125       int i = left.length() - 1;
126       int j = right.length() - 1;
127       int k = lcsLengthArray[left.length()][right.length()] - 1;
128       while (k >= 0) {
129           if (left.charAt(i) == right.charAt(j)) {
130               longestCommonSubstringArray.append(left.charAt(i));
131               i = i - 1;
132               j = j - 1;
133               k = k - 1;
134           } else if (lcsLengthArray[i + 1][j] < lcsLengthArray[i][j + 1]) {
135               i = i - 1;
136           } else {
137               j = j - 1;
138           }
139       }
140       return longestCommonSubstringArray.reverse().toString();
141   }
142
143    /**
144     *
145     * Computes the lcsLengthArray for the sake of doing the actual lcs calculation. This is the
146     * dynamic programming portion of the algorithm, and is the reason for the runtime complexity being
147     * O(m*n), where m=left.length() and n=right.length().
148     *
149     * @param left first character sequence
150     * @param right second character sequence
151     * @return lcsLengthArray
152     */
153    public int[][] longestCommonSubstringLengthArray(final CharSequence left, final CharSequence right) {
154        final int[][] lcsLengthArray = new int[left.length() + 1][right.length() + 1];
155        for (int i = 0; i < left.length(); i++) {
156            for (int j = 0; j < right.length(); j++) {
157                if (i == 0) {
158                    lcsLengthArray[i][j] = 0;
159                }
160                if (j == 0) {
161                    lcsLengthArray[i][j] = 0;
162                }
163                if (left.charAt(i) == right.charAt(j)) {
164                    lcsLengthArray[i + 1][j + 1] = lcsLengthArray[i][j] + 1;
165                } else {
166                    lcsLengthArray[i + 1][j + 1] = Math.max(lcsLengthArray[i + 1][j], lcsLengthArray[i][j + 1]);
167                }
168            }
169        }
170        return lcsLengthArray;
171    }
172
173}