    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    package org.apache.commons.lang3.text.translate;
    018
    019    import java.io.IOException;
    020    import java.io.Writer;
    021    import java.io.StringWriter;
    022    import java.util.Locale;
    023
    024    /**
    025     * An API for translating text.
    026     * Its core use is to escape and unescape text. Because escaping and unescaping
    027     * is completely contextual, the API does not present two separate signatures.
    028     *
    029     * @author Apache Software Foundation
    030     * @since 3.0
    031     * @version $Id: CharSequenceTranslator.java 967237 2010-07-23 20:08:57Z mbenson $
    032     */
    033    public abstract class CharSequenceTranslator {
    034
    035        /**
    036         * Translate a set of codepoints, represented by an int index into a CharSequence,
    037         * into another set of codepoints. The number of codepoints consumed must be returned,
    038         * and the only IOExceptions thrown must be from interacting with the Writer so that
    039         * the top level API may reliable ignore StringWriter IOExceptions.
    040         *
    041         * @param input CharSequence that is being translated
    042         * @param index int representing the current point of translation
    043         * @param out Writer to translate the text to
    044         * @return int count of codepoints consumed
    045         * @throws IOException if and only if the Writer produces an IOException
    046         */
    047        public abstract int translate(CharSequence input, int index, Writer out) throws IOException;
    048
    049        /**
    050         * Helper for non-Writer usage.
    051         * @param input CharSequence to be translated
    052         * @return String output of translation
    053         */
    054        public final String translate(CharSequence input) {
    055            if (input == null) {
    056                return null;
    057            }
    058            try {
    059                StringWriter writer = new StringWriter(input.length() * 2);  // TODO: Make the 2 part of the API???
    060                translate(input, writer);
    061                return writer.toString();
    062            } catch (IOException ioe) {
    063                // this should never ever happen while writing to a StringWriter
    064                throw new RuntimeException(ioe);
    065            }
    066        }
    067
    068        // TODO: Point to CsvEscaper as a way to 'override'?
    069        /**
    070         * Translate an input onto a Writer. This is intentionally final as its algorithm is
    071         * tightly coupled with the abstract method of this class.
    072         *
    073         * @param input CharSequence that is being translated
    074         * @param out Writer to translate the text to
    075         * @throws IOException if and only if the Writer produces an IOException
    076         */
    077        public final void translate(CharSequence input, Writer out) throws IOException {
    078            if (out == null) {
    079                throw new IllegalArgumentException("The Writer must not be null");
    080            }
    081            if (input == null) {
    082                return;
    083            }
    084            int sz = Character.codePointCount(input, 0, input.length());
    085            for (int i = 0; i < sz; i++) {
    086
    087                // consumed is the number of codepoints consumed
    088                int consumed = translate(input, i, out);
    089
    090                if(consumed == 0) {
    091                    out.write( Character.toChars( Character.codePointAt(input, i) ) );
    092                } else {
    093                    // contract with translators is that they have to understand codepoints and they just took care of a surrogate pair
    094                    for(int j=0; j<consumed; j++) {
    095                        if(i < sz - 2) {
    096                            i += Character.charCount( Character.codePointAt(input, i) );
    097                        } else {
    098                            // If the String ends with a high surrogate, just add the 1 and don't worry about such things
    099                            i++;
    100                        }
    101                    }
    102                    // for loop will increment 1 anyway, so remove 1 to account for that
    103                    i--;
    104                }
    105            }
    106        }
    107
    108        /**
    109         * Helper method to create a merger of this translator with another set of
    110         * translators. Useful in customizing the standard functionality.
    111         *
    112         * @param translators CharSequenceTranslator array of translators to merge with this one
    113         * @return CharSequenceTranslator merging this translator with the others
    114         */
    115        public final CharSequenceTranslator with(CharSequenceTranslator... translators) {
    116            CharSequenceTranslator[] newArray = new CharSequenceTranslator[translators.length + 1];
    117            newArray[0] = this;
    118            System.arraycopy(translators, 0, newArray, 1, translators.length);
    119            return new AggregateTranslator(newArray);
    120        }
    121
    122        /**
    123         * <p>Returns an upper case hexadecimal <code>String</code> for the given
    124         * character.</p>
    125         *
    126         * @param codepoint The codepoint to convert.
    127         * @return An upper case hexadecimal <code>String</code>
    128         */
    129        public static String hex(int codepoint) {
    130            return Integer.toHexString(codepoint).toUpperCase(Locale.ENGLISH);
    131        }
    132
    133    }