001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.text.similarity; 018 019import org.apache.commons.lang3.Validate; 020 021/** 022 * This stores a {@link SimilarityScore} implementation and a {@link CharSequence} "left" string. 023 * The {@link #apply(CharSequence right)} method accepts the "right" string and invokes the 024 * comparison function for the pair of strings. 025 * 026 * <p> 027 * The following is an example which finds the most similar string: 028 * </p> 029 * <pre> 030 * SimilarityScore<Integer> similarityScore = new LevenshteinDistance(); 031 * String target = "Apache"; 032 * SimilarityScoreFrom<Integer> similarityScoreFrom = 033 * new SimilarityScoreFrom<Integer>(similarityScore, target); 034 * String mostSimilar = null; 035 * Integer shortestDistance = null; 036 * 037 * for (String test : new String[] { "Appaloosa", "a patchy", "apple" }) { 038 * Integer distance = similarityScoreFrom.apply(test); 039 * if (shortestDistance == null || distance < shortestDistance) { 040 * shortestDistance = distance; 041 * mostSimilar = test; 042 * } 043 * } 044 * 045 * System.out.println("The string most similar to \"" + target + "\" " 046 * + "is \"" + mostSimilar + "\" because " 047 * + "its distance is only " + shortestDistance + "."); 048 * </pre> 049 * 050 * @param <R> This is the type of similarity score used by the SimilarityScore function. 051 * @since 1.0 052 */ 053public class SimilarityScoreFrom<R> { 054 055 /** 056 * Similarity score. 057 */ 058 private final SimilarityScore<R> similarityScore; 059 060 /** 061 * Left parameter used in distance function. 062 */ 063 private final CharSequence left; 064 065 /** 066 * This accepts the similarity score implementation and the "left" string. 067 * 068 * @param similarityScore This may not be null. 069 * @param left This may be null here, 070 * but the SimilarityScore#compare(CharSequence left, CharSequence right) 071 * implementation may not accept nulls. 072 */ 073 public SimilarityScoreFrom(final SimilarityScore<R> similarityScore, final CharSequence left) { 074 Validate.isTrue(similarityScore != null, "The edit distance may not be null."); 075 076 this.similarityScore = similarityScore; 077 this.left = left; 078 } 079 080 /** 081 * This compares "left" field against the "right" parameter 082 * using the "similarity score" implementation. 083 * 084 * @param right the second CharSequence 085 * @return The similarity score between two CharSequences 086 */ 087 public R apply(final CharSequence right) { 088 return similarityScore.apply(left, right); 089 } 090 091 /** 092 * Gets the left parameter. 093 * 094 * @return The left parameter 095 */ 096 public CharSequence getLeft() { 097 return left; 098 } 099 100 /** 101 * Gets the edit distance. 102 * 103 * @return The edit distance 104 */ 105 public SimilarityScore<R> getSimilarityScore() { 106 return similarityScore; 107 } 108 109}