1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.text.similarity;
18
19 import java.util.Arrays;
20
21 /**
22 * A similarity algorithm indicating the percentage of matched characters between two character sequences.
23 *
24 * <p>
25 * The Jaro measure is the weighted sum of percentage of matched characters
26 * from each file and transposed characters. Winkler increased this measure
27 * for matching initial characters.
28 * </p>
29 *
30 * <p>
31 * This implementation is based on the Jaro Winkler similarity algorithm
32 * from <a href="http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance">
33 * http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance</a>.
34 * </p>
35 *
36 * <p>
37 * This code has been adapted from Apache Commons Lang 3.3.
38 * </p>
39 *
40 * @since 1.0
41 */
42 public class JaroWinklerDistance implements SimilarityScore<Double> {
43
44 /**
45 * The default prefix length limit set to four.
46 */
47 private static final int PREFIX_LENGTH_LIMIT = 4;
48 /**
49 * Represents a failed index search.
50 */
51 public static final int INDEX_NOT_FOUND = -1;
52
53 /**
54 * Find the Jaro Winkler Distance which indicates the similarity score
55 * between two CharSequences.
56 *
57 * <pre>
58 * distance.apply(null, null) = IllegalArgumentException
59 * distance.apply("","") = 0.0
60 * distance.apply("","a") = 0.0
61 * distance.apply("aaapppp", "") = 0.0
62 * distance.apply("frog", "fog") = 0.93
63 * distance.apply("fly", "ant") = 0.0
64 * distance.apply("elephant", "hippo") = 0.44
65 * distance.apply("hippo", "elephant") = 0.44
66 * distance.apply("hippo", "zzzzzzzz") = 0.0
67 * distance.apply("hello", "hallo") = 0.88
68 * distance.apply("ABC Corporation", "ABC Corp") = 0.93
69 * distance.apply("D N H Enterprises Inc", "D & H Enterprises, Inc.") = 0.95
70 * distance.apply("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.92
71 * distance.apply("PENNSYLVANIA", "PENNCISYLVNIA") = 0.88
72 * </pre>
73 *
74 * @param left the first String, must not be null
75 * @param right the second String, must not be null
76 * @return result distance
77 * @throws IllegalArgumentException if either String input {@code null}
78 */
79 @Override
80 public Double apply(final CharSequence left, final CharSequence right) {
81 final double defaultScalingFactor = 0.1;
82 final double percentageRoundValue = 100.0;
83
84 if (left == null || right == null) {
85 throw new IllegalArgumentException("Strings must not be null");
86 }
87
88 int[] mtp = matches(left, right);
89 double m = mtp[0];
90 if (m == 0) {
91 return 0D;
92 }
93 double j = ((m / left.length() + m / right.length() + (m - mtp[1]) / m)) / 3;
94 double jw = j < 0.7D ? j : j + Math.min(defaultScalingFactor, 1D / mtp[3]) * mtp[2] * (1D - j);
95 return Math.round(jw * percentageRoundValue) / percentageRoundValue;
96 }
97
98 /**
99 * This method returns the Jaro-Winkler string matches, transpositions, prefix, max array.
100 *
101 * @param first the first string to be matched
102 * @param second the second string to be machted
103 * @return mtp array containing: matches, transpositions, prefix, and max length
104 */
105 protected static int[] matches(final CharSequence first, final CharSequence second) {
106 CharSequence max, min;
107 if (first.length() > second.length()) {
108 max = first;
109 min = second;
110 } else {
111 max = second;
112 min = first;
113 }
114 int range = Math.max(max.length() / 2 - 1, 0);
115 int[] matchIndexes = new int[min.length()];
116 Arrays.fill(matchIndexes, -1);
117 boolean[] matchFlags = new boolean[max.length()];
118 int matches = 0;
119 for (int mi = 0; mi < min.length(); mi++) {
120 char c1 = min.charAt(mi);
121 for (int xi = Math.max(mi - range, 0), xn = Math.min(mi + range + 1, max.length()); xi < xn; xi++) {
122 if (!matchFlags[xi] && c1 == max.charAt(xi)) {
123 matchIndexes[mi] = xi;
124 matchFlags[xi] = true;
125 matches++;
126 break;
127 }
128 }
129 }
130 char[] ms1 = new char[matches];
131 char[] ms2 = new char[matches];
132 for (int i = 0, si = 0; i < min.length(); i++) {
133 if (matchIndexes[i] != -1) {
134 ms1[si] = min.charAt(i);
135 si++;
136 }
137 }
138 for (int i = 0, si = 0; i < max.length(); i++) {
139 if (matchFlags[i]) {
140 ms2[si] = max.charAt(i);
141 si++;
142 }
143 }
144 int transpositions = 0;
145 for (int mi = 0; mi < ms1.length; mi++) {
146 if (ms1[mi] != ms2[mi]) {
147 transpositions++;
148 }
149 }
150 int prefix = 0;
151 for (int mi = 0; mi < min.length(); mi++) {
152 if (first.charAt(mi) == second.charAt(mi)) {
153 prefix++;
154 } else {
155 break;
156 }
157 }
158 return new int[] { matches, transpositions / 2, prefix, max.length() };
159 }
160
161 }