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    }