View Javadoc
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 org.apache.commons.lang3.Validate;
20  
21  /**
22   * Stores a {@link EditDistance} implementation and a {@link CharSequence} "left" string.
23   * The {@link #apply(CharSequence right)} method accepts the "right" string and invokes the
24   * comparison function for the pair of strings.
25   *
26   * <p>
27   * The following is an example which finds the most similar string:
28   * </p>
29   * <pre>
30   * EditDistance&lt;Integer&gt; editDistance = new LevenshteinDistance();
31   * String target = "Apache";
32   * EditDistanceFrom&lt;Integer&gt; editDistanceFrom =
33   *     new EditDistanceFrom&lt;Integer&gt;(editDistance, target);
34   * String mostSimilar = null;
35   * Integer shortestDistance = null;
36   *
37   * for (String test : new String[] { "Appaloosa", "a patchy", "apple" }) {
38   *     Integer distance = editDistanceFrom.apply(test);
39   *     if (shortestDistance == null || distance &lt; shortestDistance) {
40   *         shortestDistance = distance;
41   *         mostSimilar = test;
42   *     }
43   * }
44   *
45   * System.out.println("The string most similar to \"" + target + "\" "
46   *     + "is \"" + mostSimilar + "\" because "
47   *     + "its distance is only " + shortestDistance + ".");
48   * </pre>
49   *
50   * @param <R> This is the type of similarity score used by the EditDistance function.
51   * @since 1.0
52   */
53  public class EditDistanceFrom<R> {
54  
55      /**
56       * Edit distance.
57       */
58      private final EditDistance<R> editDistance;
59  
60      /**
61       * Left parameter used in distance function.
62       */
63      private final CharSequence left;
64  
65      /**
66       * Constructs the edit distance implementation and the "left" string.
67       *
68       * @param editDistance This may not be null.
69       * @param left This may be null here,
70       *             but the EditDistance#compare(CharSequence left, CharSequence right)
71       *             implementation may not accept nulls.
72       */
73      public EditDistanceFrom(final EditDistance<R> editDistance, final CharSequence left) {
74          Validate.isTrue(editDistance != null, "The edit distance may not be null.");
75          this.editDistance = editDistance;
76          this.left = left;
77      }
78  
79      /**
80       * Compares "left" field against the "right" parameter
81       * using the "edit distance" implementation.
82       *
83       * @param right the second CharSequence
84       * @return The similarity score between two CharSequences
85       */
86      public R apply(final CharSequence right) {
87          return editDistance.apply(left, right);
88      }
89  
90      /**
91       * Gets the edit distance.
92       *
93       * @return The edit distance
94       */
95      public EditDistance<R> getEditDistance() {
96          return editDistance;
97      }
98  
99      /**
100      * Gets the left parameter.
101      *
102      * @return The left parameter
103      */
104     public CharSequence getLeft() {
105         return left;
106     }
107 
108 }