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 */ 017 018package org.apache.commons.codec.language; 019 020import org.apache.commons.codec.EncoderException; 021import org.apache.commons.codec.StringEncoder; 022 023/** 024 * Encodes a string into a Refined Soundex value. A refined Soundex code is 025 * optimized for spell checking words. Soundex method originally developed by 026 * <CITE>Margaret Odell</CITE> and <CITE>Robert Russell</CITE>. 027 * 028 * <p> 029 * This class is immutable and thread-safe. 030 * </p> 031 */ 032public class RefinedSoundex implements StringEncoder { 033 034 /** 035 * Mapping: 036 * <pre> 037 * 0: A E I O U Y H W 038 * 1: B P 039 * 2: F V 040 * 3: C K S 041 * 4: G J 042 * 5: Q X Z 043 * 6: D T 044 * 7: L 045 * 8: M N 046 * 9: R 047 * </pre> 048 * @since 1.4 049 */ 050 // ABCDEFGHIJKLMNOPQRSTUVWXYZ 051 public static final String US_ENGLISH_MAPPING_STRING = "01360240043788015936020505"; 052 053 /** 054 * RefinedSoundex is *refined* for a number of reasons one being that the 055 * mappings have been altered. This implementation contains default 056 * mappings for US English. 057 */ 058 private static final char[] US_ENGLISH_MAPPING = US_ENGLISH_MAPPING_STRING.toCharArray(); 059 060 /** 061 * This static variable contains an instance of the RefinedSoundex using 062 * the US_ENGLISH mapping. 063 */ 064 public static final RefinedSoundex US_ENGLISH = new RefinedSoundex(); 065 066 /** 067 * Every letter of the alphabet is "mapped" to a numerical value. This char 068 * array holds the values to which each letter is mapped. This 069 * implementation contains a default map for US_ENGLISH. 070 */ 071 private final char[] soundexMapping; 072 073 /** 074 * Creates an instance of the RefinedSoundex object using the default US 075 * English mapping. 076 */ 077 public RefinedSoundex() { 078 this.soundexMapping = US_ENGLISH_MAPPING; 079 } 080 081 /** 082 * Creates a refined Soundex instance using a custom mapping. This 083 * constructor can be used to customize the mapping, and/or possibly 084 * provide an internationalized mapping for a non-Western character set. 085 * 086 * @param mapping 087 * Mapping array to use when finding the corresponding code for 088 * a given character. 089 */ 090 public RefinedSoundex(final char[] mapping) { 091 this.soundexMapping = mapping.clone(); 092 } 093 094 /** 095 * Creates a refined Soundex instance using a custom mapping. This constructor can be used to customize the mapping, 096 * and/or possibly provide an internationalized mapping for a non-Western character set. 097 * 098 * @param mapping 099 * Mapping string to use when finding the corresponding code for a given character. 100 * @since 1.4 101 */ 102 public RefinedSoundex(final String mapping) { 103 this.soundexMapping = mapping.toCharArray(); 104 } 105 106 /** 107 * Returns the number of characters in the two encoded Strings that are the 108 * same. This return value ranges from 0 to the length of the shortest 109 * encoded String: 0 indicates little or no similarity, and 4 out of 4 (for 110 * example) indicates strong similarity or identical values. For refined 111 * Soundex, the return value can be greater than 4. 112 * 113 * @param s1 114 * A String that will be encoded and compared. 115 * @param s2 116 * A String that will be encoded and compared. 117 * @return The number of characters in the two encoded Strings that are the 118 * same from 0 to the length of the shortest encoded String. 119 * 120 * @see SoundexUtils#difference(StringEncoder,String,String) 121 * @see <a href="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/tsqlref/ts_de-dz_8co5.asp"> 122 * MS T-SQL DIFFERENCE</a> 123 * 124 * @throws EncoderException 125 * if an error occurs encoding one of the strings. 126 * @since 1.3 127 */ 128 public int difference(final String s1, final String s2) throws EncoderException { 129 return SoundexUtils.difference(this, s1, s2); 130 } 131 132 /** 133 * Encodes an Object using the refined Soundex algorithm. This method is 134 * provided in order to satisfy the requirements of the Encoder interface, 135 * and will throw an EncoderException if the supplied object is not of type 136 * {@link String}. 137 * 138 * @param obj 139 * Object to encode. 140 * @return An object (or type {@link String}) containing the refined. 141 * Soundex code which corresponds to the String supplied. 142 * @throws EncoderException 143 * if the parameter supplied is not of type {@link String} 144 */ 145 @Override 146 public Object encode(final Object obj) throws EncoderException { 147 if (!(obj instanceof String)) { 148 throw new EncoderException("Parameter supplied to RefinedSoundex encode is not of type java.lang.String"); 149 } 150 return soundex((String) obj); 151 } 152 153 /** 154 * Encodes a String using the refined Soundex algorithm. 155 * 156 * @param str 157 * A String object to encode. 158 * @return A Soundex code corresponding to the String supplied. 159 */ 160 @Override 161 public String encode(final String str) { 162 return soundex(str); 163 } 164 165 /** 166 * Returns the mapping code for a given character. The mapping codes are 167 * maintained in an internal char array named soundexMapping, and the 168 * default values of these mappings are US English. 169 * 170 * @param c 171 * char to get mapping for. 172 * @return A character (really a numeral) to return for the given char. 173 */ 174 char getMappingCode(final char c) { 175 if (!Character.isLetter(c)) { 176 return 0; 177 } 178 final int index = Character.toUpperCase(c) - 'A'; 179 if (index < 0 || index >= this.soundexMapping.length) { 180 return 0; 181 } 182 return this.soundexMapping[index]; 183 } 184 185 /** 186 * Retrieves the Refined Soundex code for a given String object. 187 * 188 * @param str 189 * String to encode using the Refined Soundex algorithm. 190 * @return A Soundex code for the String supplied. 191 */ 192 public String soundex(String str) { 193 if (str == null) { 194 return null; 195 } 196 str = SoundexUtils.clean(str); 197 if (str.isEmpty()) { 198 return str; 199 } 200 201 final StringBuilder sBuf = new StringBuilder(); 202 sBuf.append(str.charAt(0)); 203 204 char last, current; 205 last = '*'; 206 207 for (int i = 0; i < str.length(); i++) { 208 209 current = getMappingCode(str.charAt(i)); 210 if (current == last) { 211 continue; 212 } 213 if (current != 0) { 214 sBuf.append(current); 215 } 216 217 last = current; 218 219 } 220 221 return sBuf.toString(); 222 } 223}