    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 *      http://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 org.apache.commons.codec.EncoderException;
    021import org.apache.commons.codec.StringEncoder;
    022import org.apache.commons.codec.binary.StringUtils;
    023
    024/**
    025 * Encodes a string into a double metaphone value. This Implementation is based on the algorithm by <CITE>Lawrence
    026 * Philips</CITE>.
    027 * <p>
    028 * This class is conditionally thread-safe. The instance field {@link #maxCodeLen} is mutable
    029 * {@link #setMaxCodeLen(int)} but is not volatile, and accesses are not synchronized. If an instance of the class is
    030 * shared between threads, the caller needs to ensure that suitable synchronization is used to ensure safe publication
    031 * of the value between threads, and must not invoke {@link #setMaxCodeLen(int)} after initial setup.
    032 *
    033 * @see <a href="http://drdobbs.com/184401251?pgno=2">Original Article</a>
    034 * @see <a href="http://en.wikipedia.org/wiki/Metaphone">http://en.wikipedia.org/wiki/Metaphone</a>
    035 *
    036 */
    037public class DoubleMetaphone implements StringEncoder {
    038
    039    /**
    040     * "Vowels" to test for
    041     */
    042    private static final String VOWELS = "AEIOUY";
    043
    044    /**
    045     * Prefixes when present which are not pronounced
    046     */
    047    private static final String[] SILENT_START =
    048        { "GN", "KN", "PN", "WR", "PS" };
    049    private static final String[] L_R_N_M_B_H_F_V_W_SPACE =
    050        { "L", "R", "N", "M", "B", "H", "F", "V", "W", " " };
    051    private static final String[] ES_EP_EB_EL_EY_IB_IL_IN_IE_EI_ER =
    052        { "ES", "EP", "EB", "EL", "EY", "IB", "IL", "IN", "IE", "EI", "ER" };
    053    private static final String[] L_T_K_S_N_M_B_Z =
    054        { "L", "T", "K", "S", "N", "M", "B", "Z" };
    055
    056    /**
    057     * Maximum length of an encoding, default is 4
    058     */
    059    private int maxCodeLen = 4;
    060
    061    /**
    062     * Creates an instance of this DoubleMetaphone encoder
    063     */
    064    public DoubleMetaphone() {
    065        super();
    066    }
    067
    068    /**
    069     * Encode a value with Double Metaphone.
    070     *
    071     * @param value String to encode
    072     * @return an encoded string
    073     */
    074    public String doubleMetaphone(final String value) {
    075        return doubleMetaphone(value, false);
    076    }
    077
    078    /**
    079     * Encode a value with Double Metaphone, optionally using the alternate encoding.
    080     *
    081     * @param value String to encode
    082     * @param alternate use alternate encode
    083     * @return an encoded string
    084     */
    085    public String doubleMetaphone(String value, final boolean alternate) {
    086        value = cleanInput(value);
    087        if (value == null) {
    088            return null;
    089        }
    090
    091        final boolean slavoGermanic = isSlavoGermanic(value);
    092        int index = isSilentStart(value) ? 1 : 0;
    093
    094        final DoubleMetaphoneResult result = new DoubleMetaphoneResult(this.getMaxCodeLen());
    095
    096        while (!result.isComplete() && index <= value.length() - 1) {
    097            switch (value.charAt(index)) {
    098            case 'A':
    099            case 'E':
    100            case 'I':
    101            case 'O':
    102            case 'U':
    103            case 'Y':
    104                index = handleAEIOUY(result, index);
    105                break;
    106            case 'B':
    107                result.append('P');
    108                index = charAt(value, index + 1) == 'B' ? index + 2 : index + 1;
    109                break;
    110            case '\u00C7':
    111                // A C with a Cedilla
    112                result.append('S');
    113                index++;
    114                break;
    115            case 'C':
    116                index = handleC(value, result, index);
    117                break;
    118            case 'D':
    119                index = handleD(value, result, index);
    120                break;
    121            case 'F':
    122                result.append('F');
    123                index = charAt(value, index + 1) == 'F' ? index + 2 : index + 1;
    124                break;
    125            case 'G':
    126                index = handleG(value, result, index, slavoGermanic);
    127                break;
    128            case 'H':
    129                index = handleH(value, result, index);
    130                break;
    131            case 'J':
    132                index = handleJ(value, result, index, slavoGermanic);
    133                break;
    134            case 'K':
    135                result.append('K');
    136                index = charAt(value, index + 1) == 'K' ? index + 2 : index + 1;
    137                break;
    138            case 'L':
    139                index = handleL(value, result, index);
    140                break;
    141            case 'M':
    142                result.append('M');
    143                index = conditionM0(value, index) ? index + 2 : index + 1;
    144                break;
    145            case 'N':
    146                result.append('N');
    147                index = charAt(value, index + 1) == 'N' ? index + 2 : index + 1;
    148                break;
    149            case '\u00D1':
    150                // N with a tilde (spanish ene)
    151                result.append('N');
    152                index++;
    153                break;
    154            case 'P':
    155                index = handleP(value, result, index);
    156                break;
    157            case 'Q':
    158                result.append('K');
    159                index = charAt(value, index + 1) == 'Q' ? index + 2 : index + 1;
    160                break;
    161            case 'R':
    162                index = handleR(value, result, index, slavoGermanic);
    163                break;
    164            case 'S':
    165                index = handleS(value, result, index, slavoGermanic);
    166                break;
    167            case 'T':
    168                index = handleT(value, result, index);
    169                break;
    170            case 'V':
    171                result.append('F');
    172                index = charAt(value, index + 1) == 'V' ? index + 2 : index + 1;
    173                break;
    174            case 'W':
    175                index = handleW(value, result, index);
    176                break;
    177            case 'X':
    178                index = handleX(value, result, index);
    179                break;
    180            case 'Z':
    181                index = handleZ(value, result, index, slavoGermanic);
    182                break;
    183            default:
    184                index++;
    185                break;
    186            }
    187        }
    188
    189        return alternate ? result.getAlternate() : result.getPrimary();
    190    }
    191
    192    /**
    193     * Encode the value using DoubleMetaphone.  It will only work if
    194     * <code>obj</code> is a <code>String</code> (like <code>Metaphone</code>).
    195     *
    196     * @param obj Object to encode (should be of type String)
    197     * @return An encoded Object (will be of type String)
    198     * @throws EncoderException encode parameter is not of type String
    199     */
    200    @Override
    201    public Object encode(final Object obj) throws EncoderException {
    202        if (!(obj instanceof String)) {
    203            throw new EncoderException("DoubleMetaphone encode parameter is not of type String");
    204        }
    205        return doubleMetaphone((String) obj);
    206    }
    207
    208    /**
    209     * Encode the value using DoubleMetaphone.
    210     *
    211     * @param value String to encode
    212     * @return An encoded String
    213     */
    214    @Override
    215    public String encode(final String value) {
    216        return doubleMetaphone(value);
    217    }
    218
    219    /**
    220     * Check if the Double Metaphone values of two <code>String</code> values
    221     * are equal.
    222     *
    223     * @param value1 The left-hand side of the encoded {@link String#equals(Object)}.
    224     * @param value2 The right-hand side of the encoded {@link String#equals(Object)}.
    225     * @return <code>true</code> if the encoded <code>String</code>s are equal;
    226     *          <code>false</code> otherwise.
    227     * @see #isDoubleMetaphoneEqual(String,String,boolean)
    228     */
    229    public boolean isDoubleMetaphoneEqual(final String value1, final String value2) {
    230        return isDoubleMetaphoneEqual(value1, value2, false);
    231    }
    232
    233    /**
    234     * Check if the Double Metaphone values of two <code>String</code> values
    235     * are equal, optionally using the alternate value.
    236     *
    237     * @param value1 The left-hand side of the encoded {@link String#equals(Object)}.
    238     * @param value2 The right-hand side of the encoded {@link String#equals(Object)}.
    239     * @param alternate use the alternate value if <code>true</code>.
    240     * @return <code>true</code> if the encoded <code>String</code>s are equal;
    241     *          <code>false</code> otherwise.
    242     */
    243    public boolean isDoubleMetaphoneEqual(final String value1, final String value2, final boolean alternate) {
    244        return StringUtils.equals(doubleMetaphone(value1, alternate), doubleMetaphone(value2, alternate));
    245    }
    246
    247    /**
    248     * Returns the maxCodeLen.
    249     * @return int
    250     */
    251    public int getMaxCodeLen() {
    252        return this.maxCodeLen;
    253    }
    254
    255    /**
    256     * Sets the maxCodeLen.
    257     * @param maxCodeLen The maxCodeLen to set
    258     */
    259    public void setMaxCodeLen(final int maxCodeLen) {
    260        this.maxCodeLen = maxCodeLen;
    261    }
    262
    263    //-- BEGIN HANDLERS --//
    264
    265    /**
    266     * Handles 'A', 'E', 'I', 'O', 'U', and 'Y' cases.
    267     */
    268    private int handleAEIOUY(final DoubleMetaphoneResult result, final int index) {
    269        if (index == 0) {
    270            result.append('A');
    271        }
    272        return index + 1;
    273    }
    274
    275    /**
    276     * Handles 'C' cases.
    277     */
    278    private int handleC(final String value, final DoubleMetaphoneResult result, int index) {
    279        if (conditionC0(value, index)) {  // very confusing, moved out
    280            result.append('K');
    281            index += 2;
    282        } else if (index == 0 && contains(value, index, 6, "CAESAR")) {
    283            result.append('S');
    284            index += 2;
    285        } else if (contains(value, index, 2, "CH")) {
    286            index = handleCH(value, result, index);
    287        } else if (contains(value, index, 2, "CZ") &&
    288                   !contains(value, index - 2, 4, "WICZ")) {
    289            //-- "Czerny" --//
    290            result.append('S', 'X');
    291            index += 2;
    292        } else if (contains(value, index + 1, 3, "CIA")) {
    293            //-- "focaccia" --//
    294            result.append('X');
    295            index += 3;
    296        } else if (contains(value, index, 2, "CC") &&
    297                   !(index == 1 && charAt(value, 0) == 'M')) {
    298            //-- double "cc" but not "McClelland" --//
    299            return handleCC(value, result, index);
    300        } else if (contains(value, index, 2, "CK", "CG", "CQ")) {
    301            result.append('K');
    302            index += 2;
    303        } else if (contains(value, index, 2, "CI", "CE", "CY")) {
    304            //-- Italian vs. English --//
    305            if (contains(value, index, 3, "CIO", "CIE", "CIA")) {
    306                result.append('S', 'X');
    307            } else {
    308                result.append('S');
    309            }
    310            index += 2;
    311        } else {
    312            result.append('K');
    313            if (contains(value, index + 1, 2, " C", " Q", " G")) {
    314                //-- Mac Caffrey, Mac Gregor --//
    315                index += 3;
    316            } else if (contains(value, index + 1, 1, "C", "K", "Q") &&
    317                       !contains(value, index + 1, 2, "CE", "CI")) {
    318                index += 2;
    319            } else {
    320                index++;
    321            }
    322        }
    323
    324        return index;
    325    }
    326
    327    /**
    328     * Handles 'CC' cases.
    329     */
    330    private int handleCC(final String value, final DoubleMetaphoneResult result, int index) {
    331        if (contains(value, index + 2, 1, "I", "E", "H") &&
    332            !contains(value, index + 2, 2, "HU")) {
    333            //-- "bellocchio" but not "bacchus" --//
    334            if ((index == 1 && charAt(value, index - 1) == 'A') ||
    335                contains(value, index - 1, 5, "UCCEE", "UCCES")) {
    336                //-- "accident", "accede", "succeed" --//
    337                result.append("KS");
    338            } else {
    339                //-- "bacci", "bertucci", other Italian --//
    340                result.append('X');
    341            }
    342            index += 3;
    343        } else {    // Pierce's rule
    344            result.append('K');
    345            index += 2;
    346        }
    347
    348        return index;
    349    }
    350
    351    /**
    352     * Handles 'CH' cases.
    353     */
    354    private int handleCH(final String value, final DoubleMetaphoneResult result, final int index) {
    355        if (index > 0 && contains(value, index, 4, "CHAE")) {   // Michael
    356            result.append('K', 'X');
    357            return index + 2;
    358        } else if (conditionCH0(value, index)) {
    359            //-- Greek roots ("chemistry", "chorus", etc.) --//
    360            result.append('K');
    361            return index + 2;
    362        } else if (conditionCH1(value, index)) {
    363            //-- Germanic, Greek, or otherwise 'ch' for 'kh' sound --//
    364            result.append('K');
    365            return index + 2;
    366        } else {
    367            if (index > 0) {
    368                if (contains(value, 0, 2, "MC")) {
    369                    result.append('K');
    370                } else {
    371                    result.append('X', 'K');
    372                }
    373            } else {
    374                result.append('X');
    375            }
    376            return index + 2;
    377        }
    378    }
    379
    380    /**
    381     * Handles 'D' cases.
    382     */
    383    private int handleD(final String value, final DoubleMetaphoneResult result, int index) {
    384        if (contains(value, index, 2, "DG")) {
    385            //-- "Edge" --//
    386            if (contains(value, index + 2, 1, "I", "E", "Y")) {
    387                result.append('J');
    388                index += 3;
    389                //-- "Edgar" --//
    390            } else {
    391                result.append("TK");
    392                index += 2;
    393            }
    394        } else if (contains(value, index, 2, "DT", "DD")) {
    395            result.append('T');
    396            index += 2;
    397        } else {
    398            result.append('T');
    399            index++;
    400        }
    401        return index;
    402    }
    403
    404    /**
    405     * Handles 'G' cases.
    406     */
    407    private int handleG(final String value, final DoubleMetaphoneResult result, int index,
    408                        final boolean slavoGermanic) {
    409        if (charAt(value, index + 1) == 'H') {
    410            index = handleGH(value, result, index);
    411        } else if (charAt(value, index + 1) == 'N') {
    412            if (index == 1 && isVowel(charAt(value, 0)) && !slavoGermanic) {
    413                result.append("KN", "N");
    414            } else if (!contains(value, index + 2, 2, "EY") &&
    415                       charAt(value, index + 1) != 'Y' && !slavoGermanic) {
    416                result.append("N", "KN");
    417            } else {
    418                result.append("KN");
    419            }
    420            index = index + 2;
    421        } else if (contains(value, index + 1, 2, "LI") && !slavoGermanic) {
    422            result.append("KL", "L");
    423            index += 2;
    424        } else if (index == 0 &&
    425                   (charAt(value, index + 1) == 'Y' ||
    426                    contains(value, index + 1, 2, ES_EP_EB_EL_EY_IB_IL_IN_IE_EI_ER))) {
    427            //-- -ges-, -gep-, -gel-, -gie- at beginning --//
    428            result.append('K', 'J');
    429            index += 2;
    430        } else if ((contains(value, index + 1, 2, "ER") ||
    431                    charAt(value, index + 1) == 'Y') &&
    432                   !contains(value, 0, 6, "DANGER", "RANGER", "MANGER") &&
    433                   !contains(value, index - 1, 1, "E", "I") &&
    434                   !contains(value, index - 1, 3, "RGY", "OGY")) {
    435            //-- -ger-, -gy- --//
    436            result.append('K', 'J');
    437            index += 2;
    438        } else if (contains(value, index + 1, 1, "E", "I", "Y") ||
    439                   contains(value, index - 1, 4, "AGGI", "OGGI")) {
    440            //-- Italian "biaggi" --//
    441            if (contains(value, 0 ,4, "VAN ", "VON ") ||
    442                contains(value, 0, 3, "SCH") ||
    443                contains(value, index + 1, 2, "ET")) {
    444                //-- obvious germanic --//
    445                result.append('K');
    446            } else if (contains(value, index + 1, 3, "IER")) {
    447                result.append('J');
    448            } else {
    449                result.append('J', 'K');
    450            }
    451            index += 2;
    452        } else if (charAt(value, index + 1) == 'G') {
    453            index += 2;
    454            result.append('K');
    455        } else {
    456            index++;
    457            result.append('K');
    458        }
    459        return index;
    460    }
    461
    462    /**
    463     * Handles 'GH' cases.
    464     */
    465    private int handleGH(final String value, final DoubleMetaphoneResult result, int index) {
    466        if (index > 0 && !isVowel(charAt(value, index - 1))) {
    467            result.append('K');
    468            index += 2;
    469        } else if (index == 0) {
    470            if (charAt(value, index + 2) == 'I') {
    471                result.append('J');
    472            } else {
    473                result.append('K');
    474            }
    475            index += 2;
    476        } else if ((index > 1 && contains(value, index - 2, 1, "B", "H", "D")) ||
    477                   (index > 2 && contains(value, index - 3, 1, "B", "H", "D")) ||
    478                   (index > 3 && contains(value, index - 4, 1, "B", "H"))) {
    479            //-- Parker's rule (with some further refinements) - "hugh"
    480            index += 2;
    481        } else {
    482            if (index > 2 && charAt(value, index - 1) == 'U' &&
    483                contains(value, index - 3, 1, "C", "G", "L", "R", "T")) {
    484                //-- "laugh", "McLaughlin", "cough", "gough", "rough", "tough"
    485                result.append('F');
    486            } else if (index > 0 && charAt(value, index - 1) != 'I') {
    487                result.append('K');
    488            }
    489            index += 2;
    490        }
    491        return index;
    492    }
    493
    494    /**
    495     * Handles 'H' cases.
    496     */
    497    private int handleH(final String value, final DoubleMetaphoneResult result, int index) {
    498        //-- only keep if first & before vowel or between 2 vowels --//
    499        if ((index == 0 || isVowel(charAt(value, index - 1))) &&
    500            isVowel(charAt(value, index + 1))) {
    501            result.append('H');
    502            index += 2;
    503            //-- also takes car of "HH" --//
    504        } else {
    505            index++;
    506        }
    507        return index;
    508    }
    509
    510    /**
    511     * Handles 'J' cases.
    512     */
    513    private int handleJ(final String value, final DoubleMetaphoneResult result, int index,
    514                        final boolean slavoGermanic) {
    515        if (contains(value, index, 4, "JOSE") || contains(value, 0, 4, "SAN ")) {
    516                //-- obvious Spanish, "Jose", "San Jacinto" --//
    517                if ((index == 0 && (charAt(value, index + 4) == ' ') ||
    518                     value.length() == 4) || contains(value, 0, 4, "SAN ")) {
    519                    result.append('H');
    520                } else {
    521                    result.append('J', 'H');
    522                }
    523                index++;
    524            } else {
    525                if (index == 0 && !contains(value, index, 4, "JOSE")) {
    526                    result.append('J', 'A');
    527                } else if (isVowel(charAt(value, index - 1)) && !slavoGermanic &&
    528                           (charAt(value, index + 1) == 'A' || charAt(value, index + 1) == 'O')) {
    529                    result.append('J', 'H');
    530                } else if (index == value.length() - 1) {
    531                    result.append('J', ' ');
    532                } else if (!contains(value, index + 1, 1, L_T_K_S_N_M_B_Z) &&
    533                           !contains(value, index - 1, 1, "S", "K", "L")) {
    534                    result.append('J');
    535                }
    536
    537                if (charAt(value, index + 1) == 'J') {
    538                    index += 2;
    539                } else {
    540                    index++;
    541                }
    542            }
    543        return index;
    544    }
    545
    546    /**
    547     * Handles 'L' cases.
    548     */
    549    private int handleL(final String value, final DoubleMetaphoneResult result, int index) {
    550        if (charAt(value, index + 1) == 'L') {
    551            if (conditionL0(value, index)) {
    552                result.appendPrimary('L');
    553            } else {
    554                result.append('L');
    555            }
    556            index += 2;
    557        } else {
    558            index++;
    559            result.append('L');
    560        }
    561        return index;
    562    }
    563
    564    /**
    565     * Handles 'P' cases.
    566     */
    567    private int handleP(final String value, final DoubleMetaphoneResult result, int index) {
    568        if (charAt(value, index + 1) == 'H') {
    569            result.append('F');
    570            index += 2;
    571        } else {
    572            result.append('P');
    573            index = contains(value, index + 1, 1, "P", "B") ? index + 2 : index + 1;
    574        }
    575        return index;
    576    }
    577
    578    /**
    579     * Handles 'R' cases.
    580     */
    581    private int handleR(final String value, final DoubleMetaphoneResult result, final int index,
    582                        final boolean slavoGermanic) {
    583        if (index == value.length() - 1 && !slavoGermanic &&
    584            contains(value, index - 2, 2, "IE") &&
    585            !contains(value, index - 4, 2, "ME", "MA")) {
    586            result.appendAlternate('R');
    587        } else {
    588            result.append('R');
    589        }
    590        return charAt(value, index + 1) == 'R' ? index + 2 : index + 1;
    591    }
    592
    593    /**
    594     * Handles 'S' cases.
    595     */
    596    private int handleS(final String value, final DoubleMetaphoneResult result, int index,
    597                        final boolean slavoGermanic) {
    598        if (contains(value, index - 1, 3, "ISL", "YSL")) {
    599            //-- special cases "island", "isle", "carlisle", "carlysle" --//
    600            index++;
    601        } else if (index == 0 && contains(value, index, 5, "SUGAR")) {
    602            //-- special case "sugar-" --//
    603            result.append('X', 'S');
    604            index++;
    605        } else if (contains(value, index, 2, "SH")) {
    606            if (contains(value, index + 1, 4, "HEIM", "HOEK", "HOLM", "HOLZ")) {
    607                //-- germanic --//
    608                result.append('S');
    609            } else {
    610                result.append('X');
    611            }
    612            index += 2;
    613        } else if (contains(value, index, 3, "SIO", "SIA") || contains(value, index, 4, "SIAN")) {
    614            //-- Italian and Armenian --//
    615            if (slavoGermanic) {
    616                result.append('S');
    617            } else {
    618                result.append('S', 'X');
    619            }
    620            index += 3;
    621        } else if ((index == 0 && contains(value, index + 1, 1, "M", "N", "L", "W")) ||
    622                   contains(value, index + 1, 1, "Z")) {
    623            //-- german & anglicisations, e.g. "smith" match "schmidt" //
    624            // "snider" match "schneider" --//
    625            //-- also, -sz- in slavic language although in hungarian it //
    626            //   is pronounced "s" --//
    627            result.append('S', 'X');
    628            index = contains(value, index + 1, 1, "Z") ? index + 2 : index + 1;
    629        } else if (contains(value, index, 2, "SC")) {
    630            index = handleSC(value, result, index);
    631        } else {
    632            if (index == value.length() - 1 && contains(value, index - 2, 2, "AI", "OI")) {
    633                //-- french e.g. "resnais", "artois" --//
    634                result.appendAlternate('S');
    635            } else {
    636                result.append('S');
    637            }
    638            index = contains(value, index + 1, 1, "S", "Z") ? index + 2 : index + 1;
    639        }
    640        return index;
    641    }
    642
    643    /**
    644     * Handles 'SC' cases.
    645     */
    646    private int handleSC(final String value, final DoubleMetaphoneResult result, final int index) {
    647        if (charAt(value, index + 2) == 'H') {
    648            //-- Schlesinger's rule --//
    649            if (contains(value, index + 3, 2, "OO", "ER", "EN", "UY", "ED", "EM")) {
    650                //-- Dutch origin, e.g. "school", "schooner" --//
    651                if (contains(value, index + 3, 2, "ER", "EN")) {
    652                    //-- "schermerhorn", "schenker" --//
    653                    result.append("X", "SK");
    654                } else {
    655                    result.append("SK");
    656                }
    657            } else {
    658                if (index == 0 && !isVowel(charAt(value, 3)) && charAt(value, 3) != 'W') {
    659                    result.append('X', 'S');
    660                } else {
    661                    result.append('X');
    662                }
    663            }
    664        } else if (contains(value, index + 2, 1, "I", "E", "Y")) {
    665            result.append('S');
    666        } else {
    667            result.append("SK");
    668        }
    669        return index + 3;
    670    }
    671
    672    /**
    673     * Handles 'T' cases.
    674     */
    675    private int handleT(final String value, final DoubleMetaphoneResult result, int index) {
    676        if (contains(value, index, 4, "TION")) {
    677            result.append('X');
    678            index += 3;
    679        } else if (contains(value, index, 3, "TIA", "TCH")) {
    680            result.append('X');
    681            index += 3;
    682        } else if (contains(value, index, 2, "TH") || contains(value, index, 3, "TTH")) {
    683            if (contains(value, index + 2, 2, "OM", "AM") ||
    684                //-- special case "thomas", "thames" or germanic --//
    685                contains(value, 0, 4, "VAN ", "VON ") ||
    686                contains(value, 0, 3, "SCH")) {
    687                result.append('T');
    688            } else {
    689                result.append('0', 'T');
    690            }
    691            index += 2;
    692        } else {
    693            result.append('T');
    694            index = contains(value, index + 1, 1, "T", "D") ? index + 2 : index + 1;
    695        }
    696        return index;
    697    }
    698
    699    /**
    700     * Handles 'W' cases.
    701     */
    702    private int handleW(final String value, final DoubleMetaphoneResult result, int index) {
    703        if (contains(value, index, 2, "WR")) {
    704            //-- can also be in middle of word --//
    705            result.append('R');
    706            index += 2;
    707        } else {
    708            if (index == 0 && (isVowel(charAt(value, index + 1)) ||
    709                               contains(value, index, 2, "WH"))) {
    710                if (isVowel(charAt(value, index + 1))) {
    711                    //-- Wasserman should match Vasserman --//
    712                    result.append('A', 'F');
    713                } else {
    714                    //-- need Uomo to match Womo --//
    715                    result.append('A');
    716                }
    717                index++;
    718            } else if ((index == value.length() - 1 && isVowel(charAt(value, index - 1))) ||
    719                       contains(value, index - 1, 5, "EWSKI", "EWSKY", "OWSKI", "OWSKY") ||
    720                       contains(value, 0, 3, "SCH")) {
    721                //-- Arnow should match Arnoff --//
    722                result.appendAlternate('F');
    723                index++;
    724            } else if (contains(value, index, 4, "WICZ", "WITZ")) {
    725                //-- Polish e.g. "filipowicz" --//
    726                result.append("TS", "FX");
    727                index += 4;
    728            } else {
    729                index++;
    730            }
    731        }
    732        return index;
    733    }
    734
    735    /**
    736     * Handles 'X' cases.
    737     */
    738    private int handleX(final String value, final DoubleMetaphoneResult result, int index) {
    739        if (index == 0) {
    740            result.append('S');
    741            index++;
    742        } else {
    743            if (!((index == value.length() - 1) &&
    744                  (contains(value, index - 3, 3, "IAU", "EAU") ||
    745                   contains(value, index - 2, 2, "AU", "OU")))) {
    746                //-- French e.g. breaux --//
    747                result.append("KS");
    748            }
    749            index = contains(value, index + 1, 1, "C", "X") ? index + 2 : index + 1;
    750        }
    751        return index;
    752    }
    753
    754    /**
    755     * Handles 'Z' cases.
    756     */
    757    private int handleZ(final String value, final DoubleMetaphoneResult result, int index,
    758                        final boolean slavoGermanic) {
    759        if (charAt(value, index + 1) == 'H') {
    760            //-- Chinese pinyin e.g. "zhao" or Angelina "Zhang" --//
    761            result.append('J');
    762            index += 2;
    763        } else {
    764            if (contains(value, index + 1, 2, "ZO", "ZI", "ZA") ||
    765                (slavoGermanic && (index > 0 && charAt(value, index - 1) != 'T'))) {
    766                result.append("S", "TS");
    767            } else {
    768                result.append('S');
    769            }
    770            index = charAt(value, index + 1) == 'Z' ? index + 2 : index + 1;
    771        }
    772        return index;
    773    }
    774
    775    //-- BEGIN CONDITIONS --//
    776
    777    /**
    778     * Complex condition 0 for 'C'.
    779     */
    780    private boolean conditionC0(final String value, final int index) {
    781        if (contains(value, index, 4, "CHIA")) {
    782            return true;
    783        } else if (index <= 1) {
    784            return false;
    785        } else if (isVowel(charAt(value, index - 2))) {
    786            return false;
    787        } else if (!contains(value, index - 1, 3, "ACH")) {
    788            return false;
    789        } else {
    790            final char c = charAt(value, index + 2);
    791            return (c != 'I' && c != 'E') ||
    792                    contains(value, index - 2, 6, "BACHER", "MACHER");
    793        }
    794    }
    795
    796    /**
    797     * Complex condition 0 for 'CH'.
    798     */
    799    private boolean conditionCH0(final String value, final int index) {
    800        if (index != 0) {
    801            return false;
    802        } else if (!contains(value, index + 1, 5, "HARAC", "HARIS") &&
    803                   !contains(value, index + 1, 3, "HOR", "HYM", "HIA", "HEM")) {
    804            return false;
    805        } else if (contains(value, 0, 5, "CHORE")) {
    806            return false;
    807        } else {
    808            return true;
    809        }
    810    }
    811
    812    /**
    813     * Complex condition 1 for 'CH'.
    814     */
    815    private boolean conditionCH1(final String value, final int index) {
    816        return ((contains(value, 0, 4, "VAN ", "VON ") || contains(value, 0, 3, "SCH")) ||
    817                contains(value, index - 2, 6, "ORCHES", "ARCHIT", "ORCHID") ||
    818                contains(value, index + 2, 1, "T", "S") ||
    819                ((contains(value, index - 1, 1, "A", "O", "U", "E") || index == 0) &&
    820                 (contains(value, index + 2, 1, L_R_N_M_B_H_F_V_W_SPACE) || index + 1 == value.length() - 1)));
    821    }
    822
    823    /**
    824     * Complex condition 0 for 'L'.
    825     */
    826    private boolean conditionL0(final String value, final int index) {
    827        if (index == value.length() - 3 &&
    828            contains(value, index - 1, 4, "ILLO", "ILLA", "ALLE")) {
    829            return true;
    830        } else if ((contains(value, value.length() - 2, 2, "AS", "OS") ||
    831                    contains(value, value.length() - 1, 1, "A", "O")) &&
    832                   contains(value, index - 1, 4, "ALLE")) {
    833            return true;
    834        } else {
    835            return false;
    836        }
    837    }
    838
    839    /**
    840     * Complex condition 0 for 'M'.
    841     */
    842    private boolean conditionM0(final String value, final int index) {
    843        if (charAt(value, index + 1) == 'M') {
    844            return true;
    845        }
    846        return contains(value, index - 1, 3, "UMB") &&
    847               ((index + 1) == value.length() - 1 || contains(value, index + 2, 2, "ER"));
    848    }
    849
    850    //-- BEGIN HELPER FUNCTIONS --//
    851
    852    /**
    853     * Determines whether or not a value is of slavo-germanic origin. A value is
    854     * of slavo-germanic origin if it contians any of 'W', 'K', 'CZ', or 'WITZ'.
    855     */
    856    private boolean isSlavoGermanic(final String value) {
    857        return value.indexOf('W') > -1 || value.indexOf('K') > -1 ||
    858            value.indexOf("CZ") > -1 || value.indexOf("WITZ") > -1;
    859    }
    860
    861    /**
    862     * Determines whether or not a character is a vowel or not
    863     */
    864    private boolean isVowel(final char ch) {
    865        return VOWELS.indexOf(ch) != -1;
    866    }
    867
    868    /**
    869     * Determines whether or not the value starts with a silent letter.  It will
    870     * return <code>true</code> if the value starts with any of 'GN', 'KN',
    871     * 'PN', 'WR' or 'PS'.
    872     */
    873    private boolean isSilentStart(final String value) {
    874        boolean result = false;
    875        for (final String element : SILENT_START) {
    876            if (value.startsWith(element)) {
    877                result = true;
    878                break;
    879            }
    880        }
    881        return result;
    882    }
    883
    884    /**
    885     * Cleans the input.
    886     */
    887    private String cleanInput(String input) {
    888        if (input == null) {
    889            return null;
    890        }
    891        input = input.trim();
    892        if (input.length() == 0) {
    893            return null;
    894        }
    895        return input.toUpperCase(java.util.Locale.ENGLISH);
    896    }
    897
    898    /*
    899     * Gets the character at index <code>index</code> if available, otherwise
    900     * it returns <code>Character.MIN_VALUE</code> so that there is some sort
    901     * of a default.
    902     */
    903    protected char charAt(final String value, final int index) {
    904        if (index < 0 || index >= value.length()) {
    905            return Character.MIN_VALUE;
    906        }
    907        return value.charAt(index);
    908    }
    909
    910    /*
    911     * Determines whether <code>value</code> contains any of the criteria starting at index <code>start</code> and
    912     * matching up to length <code>length</code>.
    913     */
    914    protected static boolean contains(final String value, final int start, final int length,
    915                                      final String... criteria) {
    916        boolean result = false;
    917        if (start >= 0 && start + length <= value.length()) {
    918            final String target = value.substring(start, start + length);
    919
    920            for (final String element : criteria) {
    921                if (target.equals(element)) {
    922                    result = true;
    923                    break;
    924                }
    925            }
    926        }
    927        return result;
    928    }
    929
    930    //-- BEGIN INNER CLASSES --//
    931
    932    /**
    933     * Inner class for storing results, since there is the optional alternate encoding.
    934     */
    935    public class DoubleMetaphoneResult {
    936
    937        private final StringBuilder primary = new StringBuilder(getMaxCodeLen());
    938        private final StringBuilder alternate = new StringBuilder(getMaxCodeLen());
    939        private final int maxLength;
    940
    941        public DoubleMetaphoneResult(final int maxLength) {
    942            this.maxLength = maxLength;
    943        }
    944
    945        public void append(final char value) {
    946            appendPrimary(value);
    947            appendAlternate(value);
    948        }
    949
    950        public void append(final char primary, final char alternate) {
    951            appendPrimary(primary);
    952            appendAlternate(alternate);
    953        }
    954
    955        public void appendPrimary(final char value) {
    956            if (this.primary.length() < this.maxLength) {
    957                this.primary.append(value);
    958            }
    959        }
    960
    961        public void appendAlternate(final char value) {
    962            if (this.alternate.length() < this.maxLength) {
    963                this.alternate.append(value);
    964            }
    965        }
    966
    967        public void append(final String value) {
    968            appendPrimary(value);
    969            appendAlternate(value);
    970        }
    971
    972        public void append(final String primary, final String alternate) {
    973            appendPrimary(primary);
    974            appendAlternate(alternate);
    975        }
    976
    977        public void appendPrimary(final String value) {
    978            final int addChars = this.maxLength - this.primary.length();
    979            if (value.length() <= addChars) {
    980                this.primary.append(value);
    981            } else {
    982                this.primary.append(value.substring(0, addChars));
    983            }
    984        }
    985
    986        public void appendAlternate(final String value) {
    987            final int addChars = this.maxLength - this.alternate.length();
    988            if (value.length() <= addChars) {
    989                this.alternate.append(value);
    990            } else {
    991                this.alternate.append(value.substring(0, addChars));
    992            }
    993        }
    994
    995        public String getPrimary() {
    996            return this.primary.toString();
    997        }
    998
    999        public String getAlternate() {
    1000            return this.alternate.toString();
    1001        }
    1002
    1003        public boolean isComplete() {
    1004            return this.primary.length() >= this.maxLength &&
    1005                   this.alternate.length() >= this.maxLength;
    1006        }
    1007    }
    1008}