RefinedSoundex (Encode/Decode Utilities (Version 1.10))
Date: 2016-03-08

org.apache.commons.codec.language

## Class RefinedSoundex

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

- All Implemented Interfaces:
    Encoder, StringEncoder

      public class RefinedSoundex
      extends Object
      implements StringEncoder

  Encodes a string into a Refined Soundex value. A refined soundex code is optimized for spell checking words. Soundex method originally developed by Margaret Odell and Robert Russell.

  This class is immutable and thread-safe.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private char[]` | `soundexMapping` Every letter of the alphabet is "mapped" to a numerical value.
    `static RefinedSoundex` | `US_ENGLISH` This static variable contains an instance of the RefinedSoundex using the US_ENGLISH mapping.
    `private static char[]` | `US_ENGLISH_MAPPING` RefinedSoundex is *refined* for a number of reasons one being that the mappings have been altered.
    `static String` | `US_ENGLISH_MAPPING_STRING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RefinedSoundex()` Creates an instance of the RefinedSoundex object using the default US English mapping.
    `RefinedSoundex(char[] mapping)` Creates a refined soundex instance using a custom mapping.
    `RefinedSoundex(String mapping)` Creates a refined Soundex instance using a custom mapping.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `difference(String s1, String s2)` Returns the number of characters in the two encoded Strings that are the same.
    `Object` | `encode(Object obj)` Encodes an Object using the refined soundex algorithm.
    `String` | `encode(String str)` Encodes a String using the refined soundex algorithm.
    `(package private) char` | `getMappingCode(char c)` Returns the mapping code for a given character.
    `String` | `soundex(String str)` Retrieves the Refined 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

      Since:
        1.4
      See Also:
        Constant Field Values

    - #### US_ENGLISH_MAPPING

          private static final char[] US_ENGLISH_MAPPING

      RefinedSoundex is *refined* for a number of reasons one being that the mappings have been altered. This implementation contains default mappings for US English.

    - #### 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

    - #### US_ENGLISH

          public static final RefinedSoundex US_ENGLISH

      This static variable contains an instance of the RefinedSoundex using the US_ENGLISH mapping.

  - ### Constructor Detail

    - #### RefinedSoundex

          public RefinedSoundex()

      Creates an instance of the RefinedSoundex object using the default US English mapping.

    - #### RefinedSoundex

          public RefinedSoundex(char[] 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 array to use when finding the corresponding code for a given character

    - #### RefinedSoundex

          public RefinedSoundex(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

      Returns the number of characters in the two encoded Strings that are the same. This return value ranges from 0 to the length of the shortest encoded String: 0 indicates little or no similarity, and 4 out of 4 (for example) indicates strong similarity or identical values. For refined Soundex, the return value can be greater than 4.
      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 to the length of the shortest encoded String.
      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 refined 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 refined soundex code which corresponds to the String supplied.
      Throws:
        `EncoderException` - if the parameter supplied is not of type java.lang.String

    - #### encode

          public String encode(String str)

      Encodes a String using the refined soundex algorithm.
      Specified by:
        `encode` in interface `StringEncoder`
      Parameters:
        `str` - A String object to encode
      Returns:
        A Soundex code corresponding to the String supplied

    - #### getMappingCode

          char getMappingCode(char c)

      Returns the mapping code for a given character. The mapping codes are maintained in an internal char array named soundexMapping, and the default values of these mappings are US English.
      Parameters:
        `c` - char to get mapping for
      Returns:
        A character (really a numeral) to return for the given char

    - #### soundex

          public String soundex(String str)

      Retrieves the Refined Soundex code for a given String object.
      Parameters:
        `str` - String to encode using the Refined Soundex algorithm
      Returns:
        A soundex code for the String supplied

commons-codec version 1.10 - Copyright © 2002-2016 - Apache Software Foundation