    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.codec.language;
    019
    020import java.util.Arrays;
    021import java.util.Locale;
    022
    023import org.apache.commons.codec.EncoderException;
    024import org.apache.commons.codec.StringEncoder;
    025
    026/**
    027 * Encodes a string into a Cologne Phonetic value.
    028 * <p>
    029 * Implements the <a href="https://de.wikipedia.org/wiki/K%C3%B6lner_Phonetik">K&ouml;lner Phonetik</a> (Cologne
    030 * Phonetic) algorithm issued by Hans Joachim Postel in 1969.
    031 * </p>
    032 * <p>
    033 * The <em>K&ouml;lner Phonetik</em> is a phonetic algorithm which is optimized for the German language. It is related to
    034 * the well-known soundex algorithm.
    035 * </p>
    036 *
    037 * <h2>Algorithm</h2>
    038 *
    039 * <ul>
    040 *
    041 * <li>
    042 * <h3>Step 1:</h3>
    043 * After preprocessing (conversion to upper case, transcription of <a
    044 * href="https://en.wikipedia.org/wiki/Germanic_umlaut">germanic umlauts</a>, removal of non alphabetical characters) the
    045 * letters of the supplied text are replaced by their phonetic code according to the following table.
    046 * <table border="1">
    047 * <caption style="caption-side: bottom"><small><i>(Source: <a
    048 * href="https://de.wikipedia.org/wiki/K%C3%B6lner_Phonetik#Buchstabencodes">Wikipedia (de): K&ouml;lner Phonetik --
    049 * Buchstabencodes</a>)</i></small></caption> <tbody>
    050 * <tr>
    051 * <th>Letter</th>
    052 * <th>Context</th>
    053 * <th>Code</th>
    054 * </tr>
    055 * <tr>
    056 * <td>A, E, I, J, O, U, Y</td>
    057 * <td></td>
    058 * <td>0</td>
    059 * </tr>
    060 * <tr>
    061 *
    062 * <td>H</td>
    063 * <td></td>
    064 * <td>-</td>
    065 * </tr>
    066 * <tr>
    067 * <td>B</td>
    068 * <td></td>
    069 * <td rowspan="2">1</td>
    070 * </tr>
    071 * <tr>
    072 * <td>P</td>
    073 * <td>not before H</td>
    074 *
    075 * </tr>
    076 * <tr>
    077 * <td>D, T</td>
    078 * <td>not before C, S, Z</td>
    079 * <td>2</td>
    080 * </tr>
    081 * <tr>
    082 * <td>F, V, W</td>
    083 * <td></td>
    084 * <td rowspan="2">3</td>
    085 * </tr>
    086 * <tr>
    087 *
    088 * <td>P</td>
    089 * <td>before H</td>
    090 * </tr>
    091 * <tr>
    092 * <td>G, K, Q</td>
    093 * <td></td>
    094 * <td rowspan="3">4</td>
    095 * </tr>
    096 * <tr>
    097 * <td rowspan="2">C</td>
    098 * <td>at onset before A, H, K, L, O, Q, R, U, X</td>
    099 *
    100 * </tr>
    101 * <tr>
    102 * <td>before A, H, K, O, Q, U, X except after S, Z</td>
    103 * </tr>
    104 * <tr>
    105 * <td>X</td>
    106 * <td>not after C, K, Q</td>
    107 * <td>48</td>
    108 * </tr>
    109 * <tr>
    110 * <td>L</td>
    111 * <td></td>
    112 *
    113 * <td>5</td>
    114 * </tr>
    115 * <tr>
    116 * <td>M, N</td>
    117 * <td></td>
    118 * <td>6</td>
    119 * </tr>
    120 * <tr>
    121 * <td>R</td>
    122 * <td></td>
    123 * <td>7</td>
    124 * </tr>
    125 *
    126 * <tr>
    127 * <td>S, Z</td>
    128 * <td></td>
    129 * <td rowspan="6">8</td>
    130 * </tr>
    131 * <tr>
    132 * <td rowspan="3">C</td>
    133 * <td>after S, Z</td>
    134 * </tr>
    135 * <tr>
    136 * <td>at onset except before A, H, K, L, O, Q, R, U, X</td>
    137 * </tr>
    138 *
    139 * <tr>
    140 * <td>not before A, H, K, O, Q, U, X</td>
    141 * </tr>
    142 * <tr>
    143 * <td>D, T</td>
    144 * <td>before C, S, Z</td>
    145 * </tr>
    146 * <tr>
    147 * <td>X</td>
    148 * <td>after C, K, Q</td>
    149 * </tr>
    150 * </tbody>
    151 * </table>
    152 *
    153 * <h4>Example:</h4>
    154 *
    155 * {@code "M}&uuml;{@code ller-L}&uuml;<code>denscheidt"
    156 * =&gt; "MULLERLUDENSCHEIDT" =&gt; "6005507500206880022"</code>
    157 *
    158 * </li>
    159 *
    160 * <li>
    161 * <h3>Step 2:</h3>
    162 * Collapse of all multiple consecutive code digits.
    163 * <h4>Example:</h4>
    164 * {@code "6005507500206880022" =&gt; "6050750206802"}</li>
    165 *
    166 * <li>
    167 * <h3>Step 3:</h3>
    168 * Removal of all codes "0" except at the beginning. This means that two or more identical consecutive digits can occur
    169 * if they occur after removing the "0" digits.
    170 *
    171 * <h4>Example:</h4>
    172 * {@code "6050750206802" =&gt; "65752682"}</li>
    173 *
    174 * </ul>
    175 *
    176 * <p>
    177 * This class is thread-safe.
    178 * </p>
    179 *
    180 * @see <a href="https://de.wikipedia.org/wiki/K%C3%B6lner_Phonetik">Wikipedia (de): K&ouml;lner Phonetik (in German)</a>
    181 * @since 1.5
    182 */
    183public class ColognePhonetic implements StringEncoder {
    184
    185    /**
    186     * This class is not thread-safe; the field {@link #length} is mutable.
    187     * However, it is not shared between threads, as it is constructed on demand
    188     * by the method {@link ColognePhonetic#colognePhonetic(String)}
    189     */
    190    abstract static class CologneBuffer {
    191
    192        protected final char[] data;
    193
    194        protected int length;
    195
    196        CologneBuffer(final char[] data) {
    197            this.data = data;
    198            this.length = data.length;
    199        }
    200
    201        CologneBuffer(final int buffSize) {
    202            this.data = new char[buffSize];
    203            this.length = 0;
    204        }
    205
    206        protected abstract char[] copyData(int start, int length);
    207
    208        public boolean isEmpty() {
    209            return length() == 0;
    210        }
    211
    212        public int length() {
    213            return length;
    214        }
    215
    216        @Override
    217        public String toString() {
    218            return new String(copyData(0, length));
    219        }
    220    }
    221
    222    private final class CologneInputBuffer extends CologneBuffer {
    223
    224        CologneInputBuffer(final char[] data) {
    225            super(data);
    226        }
    227
    228        @Override
    229        protected char[] copyData(final int start, final int length) {
    230            final char[] newData = new char[length];
    231            System.arraycopy(data, data.length - this.length + start, newData, 0, length);
    232            return newData;
    233        }
    234
    235        public char getNextChar() {
    236            return data[getNextPos()];
    237        }
    238
    239        protected int getNextPos() {
    240            return data.length - length;
    241        }
    242
    243        public char removeNext() {
    244            final char ch = getNextChar();
    245            length--;
    246            return ch;
    247        }
    248    }
    249
    250    private final class CologneOutputBuffer extends CologneBuffer {
    251
    252        private char lastCode;
    253
    254        CologneOutputBuffer(final int buffSize) {
    255            super(buffSize);
    256            lastCode = '/'; // impossible value
    257        }
    258
    259        @Override
    260        protected char[] copyData(final int start, final int length) {
    261            return Arrays.copyOfRange(data, start, length);
    262        }
    263
    264        /**
    265         * Stores the next code in the output buffer, keeping track of the previous code.
    266         * '0' is only stored if it is the first entry.
    267         * Ignored chars are never stored.
    268         * If the code is the same as the last code (whether stored or not) it is not stored.
    269         *
    270         * @param code the code to store.
    271         */
    272        public void put(final char code) {
    273            if (code != CHAR_IGNORE && lastCode != code && (code != '0' || length == 0)) {
    274                data[length] = code;
    275                length++;
    276            }
    277            lastCode = code;
    278        }
    279    }
    280    // Predefined char arrays for better performance and less GC load
    281    private static final char[] AEIJOUY = { 'A', 'E', 'I', 'J', 'O', 'U', 'Y' };
    282    private static final char[] CSZ = { 'C', 'S', 'Z' };
    283    private static final char[] FPVW = { 'F', 'P', 'V', 'W' };
    284    private static final char[] GKQ = { 'G', 'K', 'Q' };
    285    private static final char[] CKQ = { 'C', 'K', 'Q' };
    286    private static final char[] AHKLOQRUX = { 'A', 'H', 'K', 'L', 'O', 'Q', 'R', 'U', 'X' };
    287
    288    private static final char[] SZ = { 'S', 'Z' };
    289
    290    private static final char[] AHKOQUX = { 'A', 'H', 'K', 'O', 'Q', 'U', 'X' };
    291
    292    private static final char[] DTX = { 'D', 'T', 'X' };
    293
    294    private static final char CHAR_IGNORE = '-';    // is this character to be ignored?
    295
    296    /*
    297     * Returns whether the array contains the key, or not.
    298     */
    299    private static boolean arrayContains(final char[] arr, final char key) {
    300        for (final char element : arr) {
    301            if (element == key) {
    302                return true;
    303            }
    304        }
    305        return false;
    306    }
    307
    308    /**
    309     * Constructs a new instance.
    310     */
    311    public ColognePhonetic() {
    312        // empty
    313    }
    314
    315    /**
    316     * <p>
    317     * Implements the <em>K&ouml;lner Phonetik</em> algorithm.
    318     * </p>
    319     * <p>
    320     * In contrast to the initial description of the algorithm, this implementation does the encoding in one pass.
    321     * </p>
    322     *
    323     * @param text The source text to encode
    324     * @return the corresponding encoding according to the <em>K&ouml;lner Phonetik</em> algorithm
    325     */
    326    public String colognePhonetic(final String text) {
    327        if (text == null) {
    328            return null;
    329        }
    330
    331        final CologneInputBuffer input = new CologneInputBuffer(preprocess(text));
    332        final CologneOutputBuffer output = new CologneOutputBuffer(input.length() * 2);
    333
    334        char nextChar;
    335
    336        char lastChar = CHAR_IGNORE;
    337        char chr;
    338
    339        while (!input.isEmpty()) {
    340            chr = input.removeNext();
    341
    342            if (!input.isEmpty()) {
    343                nextChar = input.getNextChar();
    344            } else {
    345                nextChar = CHAR_IGNORE;
    346            }
    347
    348            if (chr < 'A' || chr > 'Z') {
    349                    continue; // ignore unwanted characters
    350            }
    351
    352            if (arrayContains(AEIJOUY, chr)) {
    353                output.put('0');
    354            } else if (chr == 'B' || chr == 'P' && nextChar != 'H') {
    355                output.put('1');
    356            } else if ((chr == 'D' || chr == 'T') && !arrayContains(CSZ, nextChar)) {
    357                output.put('2');
    358            } else if (arrayContains(FPVW, chr)) {
    359                output.put('3');
    360            } else if (arrayContains(GKQ, chr)) {
    361                output.put('4');
    362            } else if (chr == 'X' && !arrayContains(CKQ, lastChar)) {
    363                output.put('4');
    364                output.put('8');
    365            } else if (chr == 'S' || chr == 'Z') {
    366                output.put('8');
    367            } else if (chr == 'C') {
    368                if (output.isEmpty()) {
    369                    if (arrayContains(AHKLOQRUX, nextChar)) {
    370                        output.put('4');
    371                    } else {
    372                        output.put('8');
    373                    }
    374                } else if (arrayContains(SZ, lastChar) || !arrayContains(AHKOQUX, nextChar)) {
    375                    output.put('8');
    376                } else {
    377                    output.put('4');
    378                }
    379            } else if (arrayContains(DTX, chr)) {
    380                output.put('8');
    381            } else {
    382                switch (chr) {
    383                case 'R':
    384                    output.put('7');
    385                    break;
    386                case 'L':
    387                    output.put('5');
    388                    break;
    389                case 'M':
    390                case 'N':
    391                    output.put('6');
    392                    break;
    393                case 'H':
    394                    output.put(CHAR_IGNORE); // needed by put
    395                    break;
    396                default:
    397                    break;
    398                }
    399            }
    400
    401            lastChar = chr;
    402        }
    403        return output.toString();
    404    }
    405
    406    @Override
    407    public Object encode(final Object object) throws EncoderException {
    408        if (!(object instanceof String)) {
    409            throw new EncoderException("This method's parameter was expected to be of the type " +
    410                String.class.getName() +
    411                ". But actually it was of the type " +
    412                object.getClass().getName() +
    413                ".");
    414        }
    415        return encode((String) object);
    416    }
    417
    418    @Override
    419    public String encode(final String text) {
    420        return colognePhonetic(text);
    421    }
    422
    423    /**
    424     * Compares the first encoded string to the second encoded string.
    425     *
    426     * @param text1 source text to encode before testing for equality.
    427     * @param text2 source text to encode before testing for equality.
    428     * @return {@code true} if the encoding the first string equals the encoding of the second string, {@code false}
    429     *         otherwise
    430     */
    431    public boolean isEncodeEqual(final String text1, final String text2) {
    432        return colognePhonetic(text1).equals(colognePhonetic(text2));
    433    }
    434
    435    /**
    436     * Converts the string to upper case and replaces Germanic umlaut characters
    437     * The following characters are mapped:
    438     * <ul>
    439     * <li>capital A, umlaut mark</li>
    440     * <li>capital U, umlaut mark</li>
    441     * <li>capital O, umlaut mark</li>
    442     * <li>small sharp s, German</li>
    443     * </ul>
    444     */
    445    private char[] preprocess(final String text) {
    446        // This converts German small sharp s (Eszett) to SS
    447        final char[] chrs = text.toUpperCase(Locale.GERMAN).toCharArray();
    448
    449        for (int index = 0; index < chrs.length; index++) {
    450            switch (chrs[index]) {
    451                case '\u00C4': // capital A, umlaut mark
    452                    chrs[index] = 'A';
    453                    break;
    454                case '\u00DC': // capital U, umlaut mark
    455                    chrs[index] = 'U';
    456                    break;
    457                case '\u00D6': // capital O, umlaut mark
    458                    chrs[index] = 'O';
    459                    break;
    460                default:
    461                    break;
    462            }
    463        }
    464        return chrs;
    465    }
    466}