org.apache.commons.codec.language.ColognePhonetic Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of xapi-dev Show documentation
Everything needed to run a comprehensive dev environment. Just type X_ and pick a service from autocomplete; new dev modules will be added as they are built. The only dev service not included in the uber jar is xapi-dev-maven, as it includes all runtime dependencies of maven, adding ~4 seconds to build time, and 6 megabytes to the final output jar size (without xapi-dev-maven, it's ~1MB).
The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.codec.language;

import java.util.Locale;

import org.apache.commons.codec.EncoderException;
import org.apache.commons.codec.StringEncoder;

/**
 * 
 * Encodes a string into a Cologne Phonetic value.
 * 
 * 
 * Implements the Kölner Phonetik (Cologne Phonetic)
 * 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.
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 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
 * 
 * (Source: Wikipedia (de):
 * Kölner Phonetik -- Buchstabencodes)
 * 
 * 
 * Example:
 * 
 * {@code "M}ü{@code ller-L}ü{@code denscheidt" => "MULLERLUDENSCHEIDT" => "6005507500206880022"}
 * 
 * 
 * 
 * 
 * Step 2:
 * Collapse of all multiple consecutive code digits.
 * Example:
 * {@code "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:
 * {@code "6050750206802" => "65752682"}
 * 
 * 
 * 
 * @see Wikipedia (de): Kölner Phonetik (in German)
 * @author Apache Software Foundation
 * @since 1.5
 */
public class ColognePhonetic implements StringEncoder {

    private abstract class CologneBuffer {

        protected final char[] data;

        protected int length = 0;

        public CologneBuffer(char[] data) {
            this.data = data;
            this.length = data.length;
        }

        public CologneBuffer(int buffSize) {
            this.data = new char[buffSize];
            this.length = 0;
        }

        protected abstract char[] copyData(int start, final int length);

        public int length() {
            return length;
        }

        @Override
        public String toString() {
            return new String(copyData(0, length));
        }
    }

    private class CologneOutputBuffer extends CologneBuffer {

        public CologneOutputBuffer(int buffSize) {
            super(buffSize);
        }

        public void addRight(char chr) {
            data[length] = chr;
            length++;
        }

        @Override
        protected char[] copyData(int start, final int length) {
            char[] newData = new char[length];
            System.arraycopy(data, start, newData, 0, length);
            return newData;
        }
    }

    private class CologneInputBuffer extends CologneBuffer {

        public CologneInputBuffer(char[] data) {
            super(data);
        }

        public void addLeft(char ch) {
            length++;
            data[getNextPos()] = ch;
        }

        @Override
        protected char[] copyData(int start, final int length) {
            char[] newData = new char[length];
            System.arraycopy(data, data.length - this.length + start, newData, 0, length);
            return newData;
        }

        public char getNextChar() {
            return data[getNextPos()];
        }

        protected int getNextPos() {
            return data.length - length;
        }

        public char removeNext() {
            char ch = getNextChar();
            length--;
            return ch;
        }
    }

    /**
     * Maps some Germanic characters to plain for internal processing. The following characters are mapped:
     * 
     * capital a, umlaut mark
     * capital u, umlaut mark
     * capital o, umlaut mark
     * small sharp s, German
     * 
     */
    private static final char[][] PREPROCESS_MAP = new char[][]{
        {'\u00C4', 'A'}, // capital a, umlaut mark
        {'\u00DC', 'U'}, // capital u, umlaut mark
        {'\u00D6', 'O'}, // capital o, umlaut mark
        {'\u00DF', 'S'} // small sharp s, German
    };

    /*
     * Returns whether the array contains the key, or not.
     */
    private static boolean arrayContains(char[] arr, char key) {
        for (char element : arr) {
            if (element == key) {
                return true;
            }
        }
        return false;
    }

    /**
     * 
     * Implements the Kölner Phonetik algorithm.
     * 
     * 
     * In contrast to the initial description of the algorithm, this implementation does the encoding in one pass.
     * 
     * 
     * @param text
     * @return the corresponding encoding according to the Kölner Phonetik algorithm
     */
    public String colognePhonetic(String text) {
        if (text == null) {
            return null;
        }

        text = preprocess(text);

        CologneOutputBuffer output = new CologneOutputBuffer(text.length() * 2);
        CologneInputBuffer input = new CologneInputBuffer(text.toCharArray());

        char nextChar;

        char lastChar = '-';
        char lastCode = '/';
        char code;
        char chr;

        int rightLength = input.length();

        while (rightLength > 0) {
            chr = input.removeNext();

            if ((rightLength = input.length()) > 0) {
                nextChar = input.getNextChar();
            } else {
                nextChar = '-';
            }

            if (arrayContains(new char[]{'A', 'E', 'I', 'J', 'O', 'U', 'Y'}, chr)) {
                code = '0';
            } else if (chr == 'H' || chr < 'A' || chr > 'Z') {
                if (lastCode == '/') {
                    continue;
                }
                code = '-';
            } else if (chr == 'B' || (chr == 'P' && nextChar != 'H')) {
                code = '1';
            } else if ((chr == 'D' || chr == 'T') && !arrayContains(new char[]{'S', 'C', 'Z'}, nextChar)) {
                code = '2';
            } else if (arrayContains(new char[]{'W', 'F', 'P', 'V'}, chr)) {
                code = '3';
            } else if (arrayContains(new char[]{'G', 'K', 'Q'}, chr)) {
                code = '4';
            } else if (chr == 'X' && !arrayContains(new char[]{'C', 'K', 'Q'}, lastChar)) {
                code = '4';
                input.addLeft('S');
                rightLength++;
            } else if (chr == 'S' || chr == 'Z') {
                code = '8';
            } else if (chr == 'C') {
                if (lastCode == '/') {
                    if (arrayContains(new char[]{'A', 'H', 'K', 'L', 'O', 'Q', 'R', 'U', 'X'}, nextChar)) {
                        code = '4';
                    } else {
                        code = '8';
                    }
                } else {
                    if (arrayContains(new char[]{'S', 'Z'}, lastChar) ||
                        !arrayContains(new char[]{'A', 'H', 'O', 'U', 'K', 'Q', 'X'}, nextChar)) {
                        code = '8';
                    } else {
                        code = '4';
                    }
                }
            } else if (arrayContains(new char[]{'T', 'D', 'X'}, chr)) {
                code = '8';
            } else if (chr == 'R') {
                code = '7';
            } else if (chr == 'L') {
                code = '5';
            } else if (chr == 'M' || chr == 'N') {
                code = '6';
            } else {
                code = chr;
            }

            if (code != '-' && (lastCode != code && (code != '0' || lastCode == '/') || code < '0' || code > '8')) {
                output.addRight(code);
            }

            lastChar = chr;
            lastCode = code;
        }
        return output.toString();
    }

    public Object encode(Object object) throws EncoderException {
        if (!(object instanceof String)) {
            throw new EncoderException("This method's parameter was expected to be of the type " +
                String.class.getName() +
                ". But actually it was of the type " +
                object.getClass().getName() +
                ".");
        }
        return encode((String) object);
    }

    public String encode(String text) {
        return colognePhonetic(text);
    }

    public boolean isEncodeEqual(String text1, String text2) {
        return colognePhonetic(text1).equals(colognePhonetic(text2));
    }

    /**
     * Converts the string to upper case and replaces germanic characters as defined in {@link #PREPROCESS_MAP}.
     */
    private String preprocess(String text) {
        text = text.toUpperCase(Locale.GERMAN);

        char[] chrs = text.toCharArray();

        for (int index = 0; index < chrs.length; index++) {
            if (chrs[index] > 'Z') {
                for (char[] element : PREPROCESS_MAP) {
                    if (chrs[index] == element[0]) {
                        chrs[index] = element[1];
                        break;
                    }
                }
            }
        }
        return new String(chrs);
    }
}
Letter	Context	Code
A, E, I, J, O, U, Y		0
H		-
B		1
P	not before H	1
D, T	not before C, S, Z	2
F, V, W		3
P	before H	3
G, K, Q		4
C	at onset before A, H, K, L, O, Q, R, U, X
C	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