ColognePhonetic (Apache Commons Codec 1.22.0 API)
Description: declaration: package: org.apache.commons.codec.language, class: ColognePhonetic

Package org.apache.commons.codec.language

# Class ColognePhonetic

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

All Implemented Interfaces:
  `Encoder`, `StringEncoder`

public class ColognePhonetic extends Object implements StringEncoder
Encodes a string into a Cologne Phonetic value.

Implements the Kölner Phonetik (Cologne phonetics) algorithm issued by Hans Joachim Postel in 1969.

The Kölner Phonetik is a phonetic algorithm which is optimized for the German language. It is related to the well-known Soundex algorithm.

## Algorithm

- ### Step 1:

  After preprocessing (conversion to upper case, transcription of germanic umlauts, removal of non alphabetical characters) the letters of the supplied text are replaced by their phonetic code according to the following table.

  (Source: Wikipedia (de): Kölner Phonetik -- Buchstabencodes)
  Letter | Context | Code
  --- | --- | ---
  A, E, I, J, O, U, Y |  | 0
  H |  | -
  B |  | 1
  P | not before H
  D, T | not before C, S, Z | 2
  F, V, W |  | 3
  P | before H
  G, K, Q |  | 4
  C | at onset before A, H, K, L, O, Q, R, U, X
  before A, H, K, O, Q, U, X except after S, Z
  X | not after C, K, Q | 48
  L |  | 5
  M, N |  | 6
  R |  | 7
  S, Z |  | 8
  C | after S, Z
  at onset except before A, H, K, L, O, Q, R, U, X
  not before A, H, K, O, Q, U, X
  D, T | before C, S, Z
  X | after C, K, Q

  #### Example:

  `"M`ü`ller-L`ü`denscheidt"` -> `"MULLERLUDENSCHEIDT"` -> `"6005507500206880022"`

- ### Step 2:

  Collapse of all multiple consecutive code digits.

  #### Example:

  `"6005507500206880022"` -> `"6050750206802"`

- ### Step 3:

  Removal of all codes "0" except at the beginning. This means that two or more identical consecutive digits can occur if they occur after removing the "0" digits.

  #### Example:

  `"6050750206802"` -> `"65752682"`

This class is thread-safe.

Since:
  1.5
See Also:
  - Wikipedia: Cologne phonetics
  - Wikipedia (de): Kölner Phonetik (in German)

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ColognePhonetic()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `colognePhonetic(String text)`
  Implements the Kölner Phonetik algorithm.
  `Object`
  `encode(Object object)`
  Encodes an "Object" and returns the encoded content as an Object.
  `String`
  `encode(String text)`
  Encodes a String and returns a String.
  `boolean`
  `isEncodeEqual(String text1, String text2)`
  Compares the first encoded string to the second encoded string.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ColognePhonetic

    public ColognePhonetic()
    Constructs a new instance.

- ## Method Details

  - ### colognePhonetic

    public String colognePhonetic(String text)

    Implements the Kölner Phonetik algorithm.

    In contrast to the initial description of the algorithm, this implementation does the encoding in one pass.

    Parameters:
      `text` - The source text to encode.
    Returns:
      the corresponding encoding according to the Kölner Phonetik algorithm.

  - ### encode

    public Object encode(Object object) throws EncoderException
    Description copied from interface: `Encoder`
    Encodes an "Object" and returns the encoded content as an Object. The Objects here may just be `byte[]` or `String`s depending on the implementation used.
    Specified by:
      `encode` in interface `Encoder`
    Parameters:
      `object` - An object to encode.
    Returns:
      An "encoded" Object.
    Throws:
      `EncoderException` - An encoder exception is thrown if the encoder experiences a failure condition during the encoding process.

  - ### encode

    public String encode(String text)
    Description copied from interface: `StringEncoder`
    Encodes a String and returns a String.
    Specified by:
      `encode` in interface `StringEncoder`
    Parameters:
      `text` - the String to encode.
    Returns:
      the encoded String.

  - ### isEncodeEqual

    public boolean isEncodeEqual(String text1, String text2)
    Compares the first encoded string to the second encoded string.
    Parameters:
      `text1` - source text to encode before testing for equality.
      `text2` - source text to encode before testing for equality.
    Returns:
      `true` if the encoding the first string equals the encoding of the second string, `false` otherwise.