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 /**
20 * Measures the Jaro-Winkler distance of two character sequences.
21 * It is the complementary of Jaro-Winkler similarity.
22 *
23 * @since 1.0
24 */
25 public class JaroWinklerDistance implements EditDistance<Double> {
26
27 /**
28 * @deprecated Deprecated as of 1.7. This constant will be removed in 2.0.
29 */
30 @Deprecated
31 public static final int INDEX_NOT_FOUND = -1;
32
33 /**
34 * This method returns the Jaro-Winkler string matches, half transpositions, prefix array.
35 *
36 * @param first the first string to be matched
37 * @param second the second string to be matched
38 * @return mtp array containing: matches, half transpositions, and prefix
39 * @deprecated Deprecated as of 1.7. This method will be removed in 2.0, and moved to a Jaro Winkler similarity
40 * class. TODO see TEXT-104.
41 */
42 @Deprecated
43 protected static int[] matches(final CharSequence first, final CharSequence second) {
44 return JaroWinklerSimilarity.matches(first, second);
45 }
46
47 /**
48 * Computes the Jaro Winkler Distance between two character sequences.
49 *
50 * <pre>
51 * distance.apply(null, null) = IllegalArgumentException
52 * distance.apply("foo", null) = IllegalArgumentException
53 * distance.apply(null, "foo") = IllegalArgumentException
54 * distance.apply("", "") = 0.0
55 * distance.apply("foo", "foo") = 0.0
56 * distance.apply("foo", "foo ") = 0.06
57 * distance.apply("foo", "foo ") = 0.09
58 * distance.apply("foo", " foo ") = 0.13
59 * distance.apply("foo", " foo") = 0.49
60 * distance.apply("", "a") = 1.0
61 * distance.apply("aaapppp", "") = 1.0
62 * distance.apply("frog", "fog") = 0.07
63 * distance.apply("fly", "ant") = 1.0
64 * distance.apply("elephant", "hippo") = 0.56
65 * distance.apply("hippo", "elephant") = 0.56
66 * distance.apply("hippo", "zzzzzzzz") = 1.0
67 * distance.apply("hello", "hallo") = 0.12
68 * distance.apply("ABC Corporation", "ABC Corp") = 0.09
69 * distance.apply("D N H Enterprises Inc", "D & H Enterprises, Inc.") = 0.05
70 * distance.apply("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.08
71 * distance.apply("PENNSYLVANIA", "PENNCISYLVNIA") = 0.12
72 * </pre>
73 *
74 * @param left the first CharSequence, must not be null
75 * @param right the second CharSequence, must not be null
76 * @return result distance
77 * @throws IllegalArgumentException if either CharSequence input is {@code null}
78 */
79 @Override
80 public Double apply(final CharSequence left, final CharSequence right) {
81
82 if (left == null || right == null) {
83 throw new IllegalArgumentException("CharSequences must not be null");
84 }
85
86 return 1 - JaroWinklerSimilarity.INSTANCE.apply(left, right);
87 }
88 }