Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.codec.language
Class Soundex

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

All Implemented Interfaces:
  Encoder, StringEncoder

    public class Soundex

extends 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 1352268 2012-06-20 19:04:08Z ggregory $

Field Summary
`static Soundex` | `US_ENGLISH` An instance of Soundex using the US_ENGLISH_MAPPING mapping.
`static String` | `US_ENGLISH_MAPPING_STRING` This is a default mapping of the 26 letters used in US English.

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

Method Summary
`int` | `difference(String s1, String s2)` Encodes the Strings and returns the number of characters in the two encoded Strings that are the same.
`Object` | `encode(Object obj)` Encodes an Object using the soundex algorithm.
`String` | `encode(String str)` Encodes a String using the soundex algorithm.
`int` | `getMaxLength()` Deprecated. This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
`void` | `setMaxLength(int maxLength)` Deprecated. This feature is not needed since the encoding size must be constant. Will be removed in 2.0.
`String` | `soundex(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 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

    public static final Soundex US_ENGLISH

  An instance of Soundex using the US_ENGLISH_MAPPING mapping.

  See Also:
    `US_ENGLISH_MAPPING`

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(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(String s1,
                          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 Object encode(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
    `IllegalArgumentException` - if a character is not mapped

### encode

    public String encode(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:
    `IllegalArgumentException` - if a 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

### 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 String soundex(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:
    `IllegalArgumentException` - if a character is not mapped

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2012 The Apache Software Foundation. All Rights Reserved.