1 // Mozilla has modified this file - see https://hg.mozilla.org/ for details.
2 /*
3  * Licensed to the Apache Software Foundation (ASF) under one or more
4  * contributor license agreements.  See the NOTICE file distributed with
5  * this work for additional information regarding copyright ownership.
6  * The ASF licenses this file to You under the Apache License, Version 2.0
7  * (the "License"); you may not use this file except in compliance with
8  * the License.  You may obtain a copy of the License at
9  *
10  *      http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 package org.mozilla.apache.commons.codec.language;
20 
21 import org.mozilla.apache.commons.codec.EncoderException;
22 import org.mozilla.apache.commons.codec.StringEncoder;
23 
24 /**
25  * Encodes a string into a Soundex value. Soundex is an encoding used to relate similar names, but can also be used as a
26  * general purpose scheme to find word with similar phonemes.
27  *
28  * @author Apache Software Foundation
29  * @version $Id: Soundex.java 1064454 2011-01-28 04:40:02Z ggregory $
30  */
31 public class Soundex implements StringEncoder {
32 
33     /**
34      * This is a default mapping of the 26 letters used in US English. A value of <code>0</code> for a letter position
35      * means do not encode.
36      * <p>
37      * (This constant is provided as both an implementation convenience and to allow Javadoc to pick
38      * up the value for the constant values page.)
39      * </p>
40      *
41      * @see #US_ENGLISH_MAPPING
42      */
43     public static final String US_ENGLISH_MAPPING_STRING = "01230120022455012623010202";
44 
45     /**
46      * This is a default mapping of the 26 letters used in US English. A value of <code>0</code> for a letter position
47      * means do not encode.
48      *
49      * @see Soundex#Soundex(char[])
50      */
51     private static final char[] US_ENGLISH_MAPPING = US_ENGLISH_MAPPING_STRING.toCharArray();
52 
53     /**
54      * An instance of Soundex using the US_ENGLISH_MAPPING mapping.
55      *
56      * @see #US_ENGLISH_MAPPING
57      */
58     public static final Soundex US_ENGLISH = new Soundex();
59 
60 
61     /**
62      * Encodes the Strings and returns the number of characters in the two encoded Strings that are the same. This
63      * return value ranges from 0 through 4: 0 indicates little or no similarity, and 4 indicates strong similarity or
64      * identical values.
65      *
66      * @param s1
67      *                  A String that will be encoded and compared.
68      * @param s2
69      *                  A String that will be encoded and compared.
70      * @return The number of characters in the two encoded Strings that are the same from 0 to 4.
71      *
72      * @see SoundexUtils#difference(StringEncoder,String,String)
73      * @see <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tsqlref/ts_de-dz_8co5.asp"> MS
74      *          T-SQL DIFFERENCE </a>
75      *
76      * @throws EncoderException
77      *                  if an error occurs encoding one of the strings
78      * @since 1.3
79      */
difference(String s1, String s2)80     public int difference(String s1, String s2) throws EncoderException {
81         return SoundexUtils.difference(this, s1, s2);
82     }
83 
84     /**
85      * The maximum length of a Soundex code - Soundex codes are only four characters by definition.
86      *
87      * @deprecated This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
88      */
89     private int maxLength = 4;
90 
91     /**
92      * Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each
93      * letter is mapped. This implementation contains a default map for US_ENGLISH
94      */
95     private final char[] soundexMapping;
96 
97     /**
98      * Creates an instance using US_ENGLISH_MAPPING
99      *
100      * @see Soundex#Soundex(char[])
101      * @see Soundex#US_ENGLISH_MAPPING
102      */
Soundex()103     public Soundex() {
104         this.soundexMapping = US_ENGLISH_MAPPING;
105     }
106 
107     /**
108      * Creates a soundex instance using the given mapping. This constructor can be used to provide an internationalized
109      * mapping for a non-Western character set.
110      *
111      * Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each
112      * letter is mapped. This implementation contains a default map for US_ENGLISH
113      *
114      * @param mapping
115      *                  Mapping array to use when finding the corresponding code for a given character
116      */
Soundex(char[] mapping)117     public Soundex(char[] mapping) {
118         this.soundexMapping = new char[mapping.length];
119         System.arraycopy(mapping, 0, this.soundexMapping, 0, mapping.length);
120     }
121 
122     /**
123      * Creates a refined soundex instance using a custom mapping. This constructor can be used to customize the mapping,
124      * and/or possibly provide an internationalized mapping for a non-Western character set.
125      *
126      * @param mapping
127      *            Mapping string to use when finding the corresponding code for a given character
128      * @since 1.4
129      */
Soundex(String mapping)130     public Soundex(String mapping) {
131         this.soundexMapping = mapping.toCharArray();
132     }
133 
134     /**
135      * Encodes an Object using the soundex algorithm. This method is provided in order to satisfy the requirements of
136      * the Encoder interface, and will throw an EncoderException if the supplied object is not of type java.lang.String.
137      *
138      * @param pObject
139      *                  Object to encode
140      * @return An object (or type java.lang.String) containing the soundex code which corresponds to the String
141      *             supplied.
142      * @throws EncoderException
143      *                  if the parameter supplied is not of type java.lang.String
144      * @throws IllegalArgumentException
145      *                  if a character is not mapped
146      */
encode(Object pObject)147     public Object encode(Object pObject) throws EncoderException {
148         if (!(pObject instanceof String)) {
149             throw new EncoderException("Parameter supplied to Soundex encode is not of type java.lang.String");
150         }
151         return soundex((String) pObject);
152     }
153 
154     /**
155      * Encodes a String using the soundex algorithm.
156      *
157      * @param pString
158      *                  A String object to encode
159      * @return A Soundex code corresponding to the String supplied
160      * @throws IllegalArgumentException
161      *                  if a character is not mapped
162      */
encode(String pString)163     public String encode(String pString) {
164         return soundex(pString);
165     }
166 
167     /**
168      * Used internally by the SoundEx algorithm.
169      *
170      * Consonants from the same code group separated by W or H are treated as one.
171      *
172      * @param str
173      *                  the cleaned working string to encode (in upper case).
174      * @param index
175      *                  the character position to encode
176      * @return Mapping code for a particular character
177      * @throws IllegalArgumentException
178      *                  if the character is not mapped
179      */
getMappingCode(String str, int index)180     private char getMappingCode(String str, int index) {
181         // map() throws IllegalArgumentException
182         char mappedChar = this.map(str.charAt(index));
183         // HW rule check
184         if (index > 1 && mappedChar != '0') {
185             char hwChar = str.charAt(index - 1);
186             if ('H' == hwChar || 'W' == hwChar) {
187                 char preHWChar = str.charAt(index - 2);
188                 char firstCode = this.map(preHWChar);
189                 if (firstCode == mappedChar || 'H' == preHWChar || 'W' == preHWChar) {
190                     return 0;
191                 }
192             }
193         }
194         return mappedChar;
195     }
196 
197     /**
198      * Returns the maxLength. Standard Soundex
199      *
200      * @deprecated This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
201      * @return int
202      */
getMaxLength()203     public int getMaxLength() {
204         return this.maxLength;
205     }
206 
207     /**
208      * Returns the soundex mapping.
209      *
210      * @return soundexMapping.
211      */
getSoundexMapping()212     private char[] getSoundexMapping() {
213         return this.soundexMapping;
214     }
215 
216     /**
217      * Maps the given upper-case character to its Soundex code.
218      *
219      * @param ch
220      *                  An upper-case character.
221      * @return A Soundex code.
222      * @throws IllegalArgumentException
223      *                  Thrown if <code>ch</code> is not mapped.
224      */
map(char ch)225     private char map(char ch) {
226         int index = ch - 'A';
227         if (index < 0 || index >= this.getSoundexMapping().length) {
228             throw new IllegalArgumentException("The character is not mapped: " + ch);
229         }
230         return this.getSoundexMapping()[index];
231     }
232 
233     /**
234      * Sets the maxLength.
235      *
236      * @deprecated This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
237      * @param maxLength
238      *                  The maxLength to set
239      */
setMaxLength(int maxLength)240     public void setMaxLength(int maxLength) {
241         this.maxLength = maxLength;
242     }
243 
244     /**
245      * Retrieves the Soundex code for a given String object.
246      *
247      * @param str
248      *                  String to encode using the Soundex algorithm
249      * @return A soundex code for the String supplied
250      * @throws IllegalArgumentException
251      *                  if a character is not mapped
252      */
soundex(String str)253     public String soundex(String str) {
254         if (str == null) {
255             return null;
256         }
257         str = SoundexUtils.clean(str);
258         if (str.length() == 0) {
259             return str;
260         }
261         char out[] = {'0', '0', '0', '0'};
262         char last, mapped;
263         int incount = 1, count = 1;
264         out[0] = str.charAt(0);
265         // getMappingCode() throws IllegalArgumentException
266         last = getMappingCode(str, 0);
267         while ((incount < str.length()) && (count < out.length)) {
268             mapped = getMappingCode(str, incount++);
269             if (mapped != 0) {
270                 if ((mapped != '0') && (mapped != last)) {
271                     out[count++] = mapped;
272                 }
273                 last = mapped;
274             }
275         }
276         return new String(out);
277     }
278 
279 }
280