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 18 package org.apache.commons.codec.language; 19 20 import org.apache.commons.codec.EncoderException; 21 import org.apache.commons.codec.StringEncoder; 22 23 /** 24 * Encodes a string into a Refined Soundex value. A refined soundex code is 25 * optimized for spell checking words. Soundex method originally developed by 26 * <CITE>Margaret Odell</CITE> and <CITE>Robert Russell</CITE>. 27 * 28 * <p>This class is immutable and thread-safe.</p> 29 * 30 * @version $Id: RefinedSoundex.java 1811347 2017-10-06 15:21:18Z ggregory $ 31 */ 32 public class RefinedSoundex implements StringEncoder { 33 34 /** 35 * Mapping: 36 * <pre> 37 * 0: A E I O U Y H W 38 * 1: B P 39 * 2: F V 40 * 3: C K S 41 * 4: G J 42 * 5: Q X Z 43 * 6: D T 44 * 7: L 45 * 8: M N 46 * 9: R 47 * </pre> 48 * @since 1.4 49 */ 50 // ABCDEFGHIJKLMNOPQRSTUVWXYZ 51 public static final String US_ENGLISH_MAPPING_STRING = "01360240043788015936020505"; 52 53 /** 54 * RefinedSoundex is *refined* for a number of reasons one being that the 55 * mappings have been altered. This implementation contains default 56 * mappings for US English. 57 */ 58 private static final char[] US_ENGLISH_MAPPING = US_ENGLISH_MAPPING_STRING.toCharArray(); 59 60 /** 61 * Every letter of the alphabet is "mapped" to a numerical value. This char 62 * array holds the values to which each letter is mapped. This 63 * implementation contains a default map for US_ENGLISH 64 */ 65 private final char[] soundexMapping; 66 67 /** 68 * This static variable contains an instance of the RefinedSoundex using 69 * the US_ENGLISH mapping. 70 */ 71 public static final RefinedSoundex US_ENGLISH = new RefinedSoundex(); 72 73 /** 74 * Creates an instance of the RefinedSoundex object using the default US 75 * English mapping. 76 */ 77 public RefinedSoundex() { 78 this.soundexMapping = US_ENGLISH_MAPPING; 79 } 80 81 /** 82 * Creates a refined soundex instance using a custom mapping. This 83 * constructor can be used to customize the mapping, and/or possibly 84 * provide an internationalized mapping for a non-Western character set. 85 * 86 * @param mapping 87 * Mapping array to use when finding the corresponding code for 88 * a given character 89 */ 90 public RefinedSoundex(final char[] mapping) { 91 this.soundexMapping = new char[mapping.length]; 92 System.arraycopy(mapping, 0, this.soundexMapping, 0, mapping.length); 93 } 94 95 /** 96 * Creates a refined Soundex instance using a custom mapping. This constructor can be used to customize the mapping, 97 * and/or possibly provide an internationalized mapping for a non-Western character set. 98 * 99 * @param mapping 100 * Mapping string to use when finding the corresponding code for a given character 101 * @since 1.4 102 */ 103 public RefinedSoundex(final String mapping) { 104 this.soundexMapping = mapping.toCharArray(); 105 } 106 107 /** 108 * Returns the number of characters in the two encoded Strings that are the 109 * same. This return value ranges from 0 to the length of the shortest 110 * encoded String: 0 indicates little or no similarity, and 4 out of 4 (for 111 * example) indicates strong similarity or identical values. For refined 112 * Soundex, the return value can be greater than 4. 113 * 114 * @param s1 115 * A String that will be encoded and compared. 116 * @param s2 117 * A String that will be encoded and compared. 118 * @return The number of characters in the two encoded Strings that are the 119 * same from 0 to to the length of the shortest encoded String. 120 * 121 * @see SoundexUtils#difference(StringEncoder,String,String) 122 * @see <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tsqlref/ts_de-dz_8co5.asp"> 123 * MS T-SQL DIFFERENCE</a> 124 * 125 * @throws EncoderException 126 * if an error occurs encoding one of the strings 127 * @since 1.3 128 */ 129 public int difference(final String s1, final String s2) throws EncoderException { 130 return SoundexUtils.difference(this, s1, s2); 131 } 132 133 /** 134 * Encodes an Object using the refined soundex algorithm. This method is 135 * provided in order to satisfy the requirements of the Encoder interface, 136 * and will throw an EncoderException if the supplied object is not of type 137 * java.lang.String. 138 * 139 * @param obj 140 * Object to encode 141 * @return An object (or type java.lang.String) containing the refined 142 * soundex code which corresponds to the String supplied. 143 * @throws EncoderException 144 * if the parameter supplied is not of type java.lang.String 145 */ 146 @Override 147 public Object encode(final Object obj) throws EncoderException { 148 if (!(obj instanceof String)) { 149 throw new EncoderException("Parameter supplied to RefinedSoundex encode is not of type java.lang.String"); 150 } 151 return soundex((String) obj); 152 } 153 154 /** 155 * Encodes a String using the refined soundex algorithm. 156 * 157 * @param str 158 * A String object to encode 159 * @return A Soundex code corresponding to the String supplied 160 */ 161 @Override 162 public String encode(final String str) { 163 return soundex(str); 164 } 165 166 /** 167 * Returns the mapping code for a given character. The mapping codes are 168 * maintained in an internal char array named soundexMapping, and the 169 * default values of these mappings are US English. 170 * 171 * @param c 172 * char to get mapping for 173 * @return A character (really a numeral) to return for the given char 174 */ 175 char getMappingCode(final char c) { 176 if (!Character.isLetter(c)) { 177 return 0; 178 } 179 return this.soundexMapping[Character.toUpperCase(c) - 'A']; 180 } 181 182 /** 183 * Retrieves the Refined Soundex code for a given String object. 184 * 185 * @param str 186 * String to encode using the Refined Soundex algorithm 187 * @return A soundex code for the String supplied 188 */ 189 public String soundex(String str) { 190 if (str == null) { 191 return null; 192 } 193 str = SoundexUtils.clean(str); 194 if (str.length() == 0) { 195 return str; 196 } 197 198 final StringBuilder sBuf = new StringBuilder(); 199 sBuf.append(str.charAt(0)); 200 201 char last, current; 202 last = '*'; 203 204 for (int i = 0; i < str.length(); i++) { 205 206 current = getMappingCode(str.charAt(i)); 207 if (current == last) { 208 continue; 209 } else if (current != 0) { 210 sBuf.append(current); 211 } 212 213 last = current; 214 215 } 216 217 return sBuf.toString(); 218 } 219 }