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 * https://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 * Computes 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 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 * Creates a new instance.
49 */
50 public JaroWinklerDistance() {
51 // empty
52 }
53
54 /**
55 * Computes the Jaro Winkler Distance between two character sequences.
56 *
57 * <pre>
58 * distance.apply(null, null) = IllegalArgumentException
59 * distance.apply("foo", null) = IllegalArgumentException
60 * distance.apply(null, "foo") = IllegalArgumentException
61 * distance.apply("", "") = 0.0
62 * distance.apply("foo", "foo") = 0.0
63 * distance.apply("foo", "foo ") = 0.06
64 * distance.apply("foo", "foo ") = 0.09
65 * distance.apply("foo", " foo ") = 0.13
66 * distance.apply("foo", " foo") = 0.49
67 * distance.apply("", "a") = 1.0
68 * distance.apply("aaapppp", "") = 1.0
69 * distance.apply("frog", "fog") = 0.07
70 * distance.apply("fly", "ant") = 1.0
71 * distance.apply("elephant", "hippo") = 0.56
72 * distance.apply("hippo", "elephant") = 0.56
73 * distance.apply("hippo", "zzzzzzzz") = 1.0
74 * distance.apply("hello", "hallo") = 0.12
75 * distance.apply("ABC Corporation", "ABC Corp") = 0.09
76 * distance.apply("D N H Enterprises Inc", "D & H Enterprises, Inc.") = 0.05
77 * distance.apply("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.08
78 * distance.apply("PENNSYLVANIA", "PENNCISYLVNIA") = 0.12
79 * </pre>
80 *
81 * @param left the first input, must not be null.
82 * @param right the second input, must not be null.
83 * @return result distance.
84 * @throws IllegalArgumentException if either CharSequence input is {@code null}.
85 */
86 @Override
87 public Double apply(final CharSequence left, final CharSequence right) {
88 return apply(SimilarityInput.input(left), SimilarityInput.input(right));
89 }
90
91 /**
92 * Computes the Jaro Winkler Distance between two character sequences.
93 *
94 * <pre>
95 * distance.apply(null, null) = IllegalArgumentException
96 * distance.apply("foo", null) = IllegalArgumentException
97 * distance.apply(null, "foo") = IllegalArgumentException
98 * distance.apply("", "") = 0.0
99 * distance.apply("foo", "foo") = 0.0
100 * distance.apply("foo", "foo ") = 0.06
101 * distance.apply("foo", "foo ") = 0.09
102 * distance.apply("foo", " foo ") = 0.13
103 * distance.apply("foo", " foo") = 0.49
104 * distance.apply("", "a") = 1.0
105 * distance.apply("aaapppp", "") = 1.0
106 * distance.apply("frog", "fog") = 0.07
107 * distance.apply("fly", "ant") = 1.0
108 * distance.apply("elephant", "hippo") = 0.56
109 * distance.apply("hippo", "elephant") = 0.56
110 * distance.apply("hippo", "zzzzzzzz") = 1.0
111 * distance.apply("hello", "hallo") = 0.12
112 * distance.apply("ABC Corporation", "ABC Corp") = 0.09
113 * distance.apply("D N H Enterprises Inc", "D & H Enterprises, Inc.") = 0.05
114 * distance.apply("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.08
115 * distance.apply("PENNSYLVANIA", "PENNCISYLVNIA") = 0.12
116 * </pre>
117 *
118 * @param <E> The type of similarity score unit.
119 * @param left the first input, must not be null.
120 * @param right the second input, must not be null.
121 * @return result distance.
122 * @throws IllegalArgumentException if either CharSequence input is {@code null}.
123 * @since 1.13.0
124 */
125 public <E> Double apply(final SimilarityInput<E> left, final SimilarityInput<E> right) {
126 if (left == null || right == null) {
127 throw new IllegalArgumentException("CharSequences must not be null");
128 }
129 return 1 - JaroWinklerSimilarity.INSTANCE.apply(left, right);
130 }
131 }