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 * https://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 java.util.Locale; 020 021/** 022 * A matching algorithm that is similar to the searching algorithms implemented in editors such 023 * as Sublime Text, TextMate, Atom and others. 024 * 025 * <p> 026 * One point is given for every matched character. Subsequent matches yield two bonus points. A higher score 027 * indicates a higher similarity. 028 * </p> 029 * 030 * <p> 031 * This code has been adapted from Apache Commons Lang 3.3. 032 * </p> 033 * 034 * @since 1.0 035 */ 036public class FuzzyScore { 037 038 /** 039 * Locale used to change the case of text. 040 */ 041 private final Locale locale; 042 043 /** 044 * This returns a {@link Locale}-specific {@link FuzzyScore}. 045 * 046 * @param locale The string matching logic is case insensitive. A {@link Locale} is necessary to normalize both Strings to lower case. 047 * @throws IllegalArgumentException This is thrown if the {@link Locale} parameter is {@code null}. 048 */ 049 public FuzzyScore(final Locale locale) { 050 if (locale == null) { 051 throw new IllegalArgumentException("Locale must not be null"); 052 } 053 this.locale = locale; 054 } 055 056 /** 057 * Find the Fuzzy Score which indicates the similarity score between two Strings. 058 * 059 * <pre> 060 * score.fuzzyScore(null, null) = IllegalArgumentException 061 * score.fuzzyScore("not null", null) = IllegalArgumentException 062 * score.fuzzyScore(null, "not null") = IllegalArgumentException 063 * score.fuzzyScore("", "") = 0 064 * score.fuzzyScore("Workshop", "b") = 0 065 * score.fuzzyScore("Room", "o") = 1 066 * score.fuzzyScore("Workshop", "w") = 1 067 * score.fuzzyScore("Workshop", "ws") = 2 068 * score.fuzzyScore("Workshop", "wo") = 4 069 * score.fuzzyScore("Apache Software Foundation", "asf") = 3 070 * </pre> 071 * 072 * @param term a full term that should be matched against, must not be null. 073 * @param query the query that will be matched against a term, must not be null. 074 * @return result score. 075 * @throws IllegalArgumentException if the term or query is {@code null}. 076 */ 077 public Integer fuzzyScore(final CharSequence term, final CharSequence query) { 078 if (term == null || query == null) { 079 throw new IllegalArgumentException("CharSequences must not be null"); 080 } 081 082 // fuzzy logic is case insensitive. We normalize the Strings to lower 083 // case right from the start. Turning characters to lower case 084 // via Character.toLowerCase(char) is unfortunately insufficient 085 // as it does not accept a locale. 086 final String termLowerCase = term.toString().toLowerCase(locale); 087 final String queryLowerCase = query.toString().toLowerCase(locale); 088 089 // the resulting score 090 int score = 0; 091 092 // the position in the term which will be scanned next for potential 093 // query character matches 094 int termIndex = 0; 095 096 // index of the previously matched character in the term 097 int previousMatchingCharacterIndex = Integer.MIN_VALUE; 098 099 for (int queryIndex = 0; queryIndex < queryLowerCase.length(); queryIndex++) { 100 final char queryChar = queryLowerCase.charAt(queryIndex); 101 102 boolean termCharacterMatchFound = false; 103 for (; termIndex < termLowerCase.length() 104 && !termCharacterMatchFound; termIndex++) { 105 final char termChar = termLowerCase.charAt(termIndex); 106 107 if (queryChar == termChar) { 108 // simple character matches result in one point 109 score++; 110 111 // subsequent character matches further improve 112 // the score. 113 if (previousMatchingCharacterIndex + 1 == termIndex) { 114 score += 2; 115 } 116 117 previousMatchingCharacterIndex = termIndex; 118 119 // we can leave the nested loop. Every character in the 120 // query can match at most one character in the term. 121 termCharacterMatchFound = true; 122 } 123 } 124 } 125 126 return score; 127 } 128 129 /** 130 * Gets the locale. 131 * 132 * @return The locale 133 */ 134 public Locale getLocale() { 135 return locale; 136 } 137 138}