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    *      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  import org.apache.commons.lang3.Validate;
20  
21  /**
22   * Stores a {@link SimilarityScore} 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   * SimilarityScore&lt;Integer&gt; similarityScore = new LevenshteinDistance();
31   * String target = "Apache";
32   * SimilarityScoreFrom&lt;Integer&gt; similarityScoreFrom =
33   *     new SimilarityScoreFrom&lt;Integer&gt;(similarityScore, target);
34   * String mostSimilar = null;
35   * Integer shortestDistance = null;
36   *
37   * for (String test : new String[] { "Appaloosa", "a patchy", "apple" }) {
38   *     Integer distance = similarityScoreFrom.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 SimilarityScore function.
51   * @since 1.0
52   */
53  public class SimilarityScoreFrom<R> {
54  
55      /**
56       * Similarity score.
57       */
58      private final SimilarityScore<R> similarityScore;
59  
60      /**
61       * Left parameter used in distance function.
62       */
63      private final CharSequence left;
64  
65      /**
66       * Constructs a new instance for a similarity score implementation and the "left" string.
67       *
68       * @param similarityScore This may not be null.
69       * @param left            This may be null here, but the SimilarityScore#compare(CharSequence left, CharSequence right) implementation may not accept nulls.
70       */
71      public SimilarityScoreFrom(final SimilarityScore<R> similarityScore, final CharSequence left) {
72          Validate.isTrue(similarityScore != null, "The edit distance may not be null.");
73          this.similarityScore = similarityScore;
74          this.left = left;
75      }
76  
77      /**
78       * Compares "left" field against the "right" parameter using the "similarity score" implementation.
79       *
80       * @param right the second CharSequence.
81       * @return The similarity score between two CharSequences.
82       */
83      public R apply(final CharSequence right) {
84          return similarityScore.apply(left, right);
85      }
86  
87      /**
88       * Gets the left parameter.
89       *
90       * @return The left parameter.
91       */
92      public CharSequence getLeft() {
93          return left;
94      }
95  
96      /**
97       * Gets the edit distance.
98       *
99       * @return The edit distance.
100      */
101     public SimilarityScore<R> getSimilarityScore() {
102         return similarityScore;
103     }
104 
105 }