Soundex (commons-codec (Version 1.10))

java.lang.Object
- org.apache.commons.codec.language.Soundex

All Implemented Interfaces:

Encoder, StringEncoder
```
public class Soundex
extends java.lang.Object
implements StringEncoder
```
Encodes a string into a Soundex value. Soundex is an encoding used to relate similar names, but can also be used as a general purpose scheme to find word with similar phonemes. This class is thread-safe. Although not strictly immutable, the maxLength field is not actually used.

Version:

$Id: Soundex.java 1429868 2013-01-07 16:08:05Z ggregory $

Field Summary

Fields
Modifier and Type	Field	Description
`private int`	`maxLength`	Deprecated. This feature is not needed since the encoding size must be constant.
`private char[]`	`soundexMapping`	Every letter of the alphabet is "mapped" to a numerical value.
`static Soundex`	`US_ENGLISH`	An instance of Soundex using the US_ENGLISH_MAPPING mapping.
`private static char[]`	`US_ENGLISH_MAPPING`	This is a default mapping of the 26 letters used in US English.
`static java.lang.String`	`US_ENGLISH_MAPPING_STRING`	This is a default mapping of the 26 letters used in US English.

Constructor Summary

Constructors
Constructor	Description
`Soundex()`	Creates an instance using US_ENGLISH_MAPPING
`Soundex(char[] mapping)`	Creates a soundex instance using the given mapping.
`Soundex(java.lang.String mapping)`	Creates a refined soundex instance using a custom mapping.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`int`	`difference(java.lang.String s1, java.lang.String s2)`	Encodes the Strings and returns the number of characters in the two encoded Strings that are the same.
`java.lang.Object`	`encode(java.lang.Object obj)`	Encodes an Object using the soundex algorithm.
`java.lang.String`	`encode(java.lang.String str)`	Encodes a String using the soundex algorithm.
`private char`	`getMappingCode(java.lang.String str, int index)`	Used internally by the SoundEx algorithm.
`int`	`getMaxLength()`	Deprecated. This feature is not needed since the encoding size must be constant.
`private char[]`	`getSoundexMapping()`	Returns the soundex mapping.
`private char`	`map(char ch)`	Maps the given upper-case character to its Soundex code.
`void`	`setMaxLength(int maxLength)`	Deprecated. This feature is not needed since the encoding size must be constant.
`java.lang.String`	`soundex(java.lang.String str)`	Retrieves the Soundex code for a given String object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - US_ENGLISH_MAPPING_STRING
```
public static final java.lang.String US_ENGLISH_MAPPING_STRING
```
    This is a default mapping of the 26 letters used in US English. A value of 0 for a letter position means do not encode.
    (This constant is provided as both an implementation convenience and to allow Javadoc to pick up the value for the constant values page.)
    
    See Also:
    
    US_ENGLISH_MAPPING, Constant Field Values
  - US_ENGLISH_MAPPING
```
private static final char[] US_ENGLISH_MAPPING
```
    This is a default mapping of the 26 letters used in US English. A value of 0 for a letter position means do not encode.
    
    See Also:
    
    Soundex(char[])
  - US_ENGLISH
```
public static final Soundex US_ENGLISH
```
    An instance of Soundex using the US_ENGLISH_MAPPING mapping.
    
    See Also:
    
    US_ENGLISH_MAPPING
  - maxLength
```
@Deprecated
private int maxLength
```
    Deprecated.
    This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
    
    The maximum length of a Soundex code - Soundex codes are only four characters by definition.
  - soundexMapping
```
private final char[] soundexMapping
```
    Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each letter is mapped. This implementation contains a default map for US_ENGLISH
- Constructor Detail
  - Soundex
```
public Soundex()
```
    Creates an instance using US_ENGLISH_MAPPING
    
    See Also:
    
    Soundex(char[]), US_ENGLISH_MAPPING
  - Soundex
```
public Soundex(char[] mapping)
```
    Creates a soundex instance using the given mapping. This constructor can be used to provide an internationalized mapping for a non-Western character set. Every letter of the alphabet is "mapped" to a numerical value. This char array holds the values to which each letter is mapped. This implementation contains a default map for US_ENGLISH
    
    Parameters:
    
    mapping - Mapping array to use when finding the corresponding code for a given character
  - Soundex
```
public Soundex(java.lang.String mapping)
```
    Creates a refined soundex instance using a custom mapping. This constructor can be used to customize the mapping, and/or possibly provide an internationalized mapping for a non-Western character set.
    
    Parameters:
    
    mapping - Mapping string to use when finding the corresponding code for a given character
    
    Since:
    
    1.4
- Method Detail
  - difference
```
public int difference(java.lang.String s1,
                      java.lang.String s2)
               throws EncoderException
```
    Encodes the Strings and returns the number of characters in the two encoded Strings that are the same. This return value ranges from 0 through 4: 0 indicates little or no similarity, and 4 indicates strong similarity or identical values.
    
    Parameters:
    
    s1 - A String that will be encoded and compared.
    
    s2 - A String that will be encoded and compared.
    
    Returns:
    
    The number of characters in the two encoded Strings that are the same from 0 to 4.
    
    Throws:
    
    EncoderException - if an error occurs encoding one of the strings
    
    Since:
    
    1.3
    
    See Also:
    
    SoundexUtils.difference(StringEncoder,String,String), MS T-SQL DIFFERENCE
  - encode
```
public java.lang.Object encode(java.lang.Object obj)
                        throws EncoderException
```
    Encodes an Object using the soundex algorithm. This method is provided in order to satisfy the requirements of the Encoder interface, and will throw an EncoderException if the supplied object is not of type java.lang.String.
    
    Specified by:
    
    encode in interface Encoder
    
    Parameters:
    
    obj - Object to encode
    
    Returns:
    
    An object (or type java.lang.String) containing the soundex code which corresponds to the String supplied.
    
    Throws:
    
    EncoderException - if the parameter supplied is not of type java.lang.String
    
    java.lang.IllegalArgumentException - if a character is not mapped
  - encode
```
public java.lang.String encode(java.lang.String str)
```
    Encodes a String using the soundex algorithm.
    
    Specified by:
    
    encode in interface StringEncoder
    
    Parameters:
    
    str - A String object to encode
    
    Returns:
    
    A Soundex code corresponding to the String supplied
    
    Throws:
    
    java.lang.IllegalArgumentException - if a character is not mapped
  - getMappingCode
```
private char getMappingCode(java.lang.String str,
                            int index)
```
    Used internally by the SoundEx algorithm. Consonants from the same code group separated by W or H are treated as one.
    
    Parameters:
    
    str - the cleaned working string to encode (in upper case).
    
    index - the character position to encode
    
    Returns:
    
    Mapping code for a particular character
    
    Throws:
    
    java.lang.IllegalArgumentException - if the character is not mapped
  - getMaxLength
```
@Deprecated
public int getMaxLength()
```
    Deprecated.
    This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
    
    Returns the maxLength. Standard Soundex
    
    Returns:
    
    int
  - getSoundexMapping
```
private char[] getSoundexMapping()
```
    Returns the soundex mapping.
    
    Returns:
    
    soundexMapping.
  - map
```
private char map(char ch)
```
    Maps the given upper-case character to its Soundex code.
    
    Parameters:
    
    ch - An upper-case character.
    
    Returns:
    
    A Soundex code.
    
    Throws:
    
    java.lang.IllegalArgumentException - Thrown if ch is not mapped.
  - setMaxLength
```
@Deprecated
public void setMaxLength(int maxLength)
```
    Deprecated.
    This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
    
    Sets the maxLength.
    
    Parameters:
    
    maxLength - The maxLength to set
  - soundex
```
public java.lang.String soundex(java.lang.String str)
```
    Retrieves the Soundex code for a given String object.
    
    Parameters:
    
    str - String to encode using the Soundex algorithm
    
    Returns:
    
    A soundex code for the String supplied
    
    Throws:
    
    java.lang.IllegalArgumentException - if a character is not mapped

Class Soundex

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

US_ENGLISH_MAPPING_STRING

US_ENGLISH_MAPPING

US_ENGLISH

maxLength

soundexMapping

Constructor Detail

Soundex

Soundex

Soundex

Method Detail

difference

encode

encode

getMappingCode

getMaxLength

getSoundexMapping

map

setMaxLength

soundex