/*
 * Copyright 2008 Pirion Systems Pty Ltd, 139 Warry St,
 * Fortitude Valley, Queensland, Australia
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
package com.sun.pdfview;

import java.io.*;
import java.util.Map;
import java.util.HashMap;
import java.nio.CharBuffer;
import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;

/**
 * <p> Utility methods for dealing with PDF Strings, such as:
 * <ul>
 * <li>{@link #asTextString(String) converting to text strings}
 * <li>{@link #asPDFDocEncoded(String) converting to PDFDocEncoded strings}
 * <li>{@link #asUTF16BEEncoded converting to UTF-16BE strings}
 * <li>converting basic strings between {@link #asBytes(String) byte} and
 * {@link #asBasicString(byte[], int, int) string} representations
 * </ul></p>
 *
 * <p>We refer to basic strings as those corresponding to the PDF 'string' type.
 * PDFRenderer represents these as {@link String}s, though this is somewhat
 * deceiving, as they are, effectively, just sequences of bytes, although byte
 * values &lt;= 127 do correspond to the ASCII character set. Outside of this,
 * the 'string' type, as repesented by basic strings do not possess any
 * character set or encoding, and byte values &gt;= 128 are entirely acceptable.
 * For a basic string as represented by a String, each character has a value
 * less than 256 and is represented in the String as if the bytes represented as
 * it were in ISO-8859-1 encoding. This, however, is merely for convenience. For
 * strings that are user visible, and that don't merely represent some
 * identifying token, the PDF standard employs a 'text string' type that offers
 * the basic string as an encoding of in either UTF-16BE (with a byte order
 * marking) or a specific 8-byte encoding, PDFDocEncoding. Using a basic string
 * without conversion when the actual type is a 'text string' is erroneous
 * (though without consequence if the string consists only of ASCII
 * alphanumeric values). Care must be taken to either convert basic strings to
 * text strings (also expressed as a String) when appropriate, using either the
 * methods in this class, or {@link PDFObject#getTextStringValue()}}. For
 * strings that are 'byte strings', {@link #asBytes(String)} or {@link
 * PDFObject#getStream()} should be used. </p>.
 *
 * @author Luke Kirby
 */
public class PDFStringUtil {

    /**
     * <p>Take a basic PDF string and determine if it is in UTF-16BE encoding
     * by looking at the lead characters for a byte order marking (BOM). If it
     * appears to be UTF-16BE, we return the string representation of the
     * UTF-16BE encoding of those bytes. If the BOM is not present, the bytes
     * from the input string are decoded using the PDFDocEncoding charset.</p>
     *
     * <p>From the PDF Reference 1.7, p158:
     *
     * <blockquote>The text string type is used for character strings that are
     * encoded in either PDFDocEncoding or the UTF-16BE Unicode character
     * encoding scheme. PDFDocEncoding can encode all of the ISO Latin 1
     * character set and is documented in Appendix D. UTF-16BE can encode all
     * Unicode characters. UTF-16BE and Unicode character encoding are
     * described in the Unicode Standard by the Unicode Consortium (see the
     * Bibliography). Note that PDFDocEncoding does not support all Unicode
     * characters whereas UTF-16BE does.</blockquote>
     * </p>
     *
     * @param basicString the basic PDF string, as offered by {@link
     *  PDFObject#getStringValue()}
     * @return either the original input, or the input decoded as UTF-16
     */
    public static String asTextString(String basicString) {
        if (basicString == null) {
            return null;
        }

        if (basicString.length() >= 2) {
            if ((basicString.charAt(0) == (char) 0xFE
                    && basicString.charAt(1) == (char) 0xFF)) {
                // found the BOM!
                return asUTF16BEEncoded(basicString);
            }
        }

        // it's not UTF16-BE encoded, so it must be
        return asPDFDocEncoded(basicString);
    }

    /**
     * Take a basic PDF string and produce a string of its bytes as encoded in
     * PDFDocEncoding. The PDFDocEncoding is described in the PDF Reference.
     *
     * @param basicString the basic PDF string, as offered by {@link
     *  PDFObject#getStringValue()}
     * @return the decoding of the string's bytes in PDFDocEncoding
     */
    public static String asPDFDocEncoded(String basicString) {
        final StringBuilder buf = new StringBuilder(basicString.length());
        for (int i = 0; i < basicString.length(); ++i) {
            final char c = PDF_DOC_ENCODING_MAP[basicString.charAt(i) & 0xFF];
            buf.append(c);
        }
        return buf.toString();
    }

    public byte[] toPDFDocEncoded(String string)
            throws CharacterCodingException {
        // we can just grab array since we know that if charset completes
        // without error then there's the output buffer will be exactly
        // correct in size, since there's only ever 1 byte for one char.
        return new PDFDocCharsetEncoder().encode(CharBuffer.wrap(string)).
                array();
    }

    /**
     * Take a basic PDF string and produce a string from its bytes as an
     * UTF16-BE encoding. The first 2 bytes are presumed to be the big-endian
     * byte markers, 0xFE and 0xFF; that is not checked by this method.
     *
     * @param basicString the basic PDF string, as offered by {@link
     *  PDFObject#getStringValue()}
     * @return the decoding of the string's bytes in UTF16-BE
     */
    public static String asUTF16BEEncoded(String basicString) {
        try {
            return new String(asBytes(basicString),
                    2, basicString.length() - 2, "UTF-16BE");
        } catch (UnsupportedEncodingException e) {
            // UTF-16BE should always be available
            throw new RuntimeException("No UTF-16BE charset!");
        }
    }

    /**
     * Get the corresponding byte array for a basic string. This is effectively
     * the char[] array cast to bytes[], as chars in basic strings only use the
     * least significant byte.
     *
     * @param basicString the basic PDF string, as offered by {@link
     *  PDFObject#getStringValue()}
     * @return the bytes corresponding to its characters
     */
    public static byte[] asBytes(String basicString) {
        final byte[] b = new byte[basicString.length()];
        for (int i = 0; i < b.length; ++i) {
            b[i] = (byte) basicString.charAt(i);
        }
        return b;
    }

    /**
     * Create a basic string from bytes. This is effectively the byte array
     * cast to a char array and turned into a String.
     * @param bytes the source of the bytes for the basic string
     * @param offset the offset into butes where the string starts
     * @param length the number of bytes to turn into a string
     * @return the corresponding string
     */
    public static String asBasicString(
            byte[] bytes, int offset, int length) {
        final char[] c = new char[length];
        for (int i = 0; i < c.length; ++i) {
            c[i] = (char) bytes[i + offset];
        }
        return new String(c);
    }

    /**
     * Create a basic string from bytes. This is effectively the byte array
     * cast to a char array and turned into a String.
     * @param bytes the bytes, all of which are used
     * @return the corresponding string
     */
    public static String asBasicString(byte[] bytes) {
        return asBasicString(bytes, 0, bytes.length);
    }

    /**
     * Maps from PDFDocEncoding bytes to unicode characters. Table generated
     * by PDFDocEncodingMapGenerator.
     */
    final static char[] PDF_DOC_ENCODING_MAP = new char[] {
        0x0000, 0x0001, 0x0002, 0x0003, 0x0004, 0x0005, 0x0006, 0x0007,  //00-07
        0x0008, 0x0009, 0x000A, 0x000B, 0x000C, 0x000D, 0x000E, 0x000F,  //08-0F
        0x0010, 0x0011, 0x0012, 0x0013, 0x0014, 0x0015, 0x0016, 0x0017,  //10-17
        0x02D8, 0x02C7, 0x02C6, 0x02D9, 0x02DD, 0x02DB, 0x02DA, 0x02DC,  //18-1F
        0x0020, 0x0021, 0x0022, 0x0023, 0x0024, 0x0025, 0x0026, 0x0027,  //20-27
        0x0028, 0x0029, 0x002A, 0x002B, 0x002C, 0x002D, 0x002E, 0x002F,  //28-2F
        0x0030, 0x0031, 0x0032, 0x0033, 0x0034, 0x0035, 0x0036, 0x0037,  //30-37
        0x0038, 0x0039, 0x003A, 0x003B, 0x003C, 0x003D, 0x003E, 0x003F,  //38-3F
        0x0040, 0x0041, 0x0042, 0x0043, 0x0044, 0x0045, 0x0046, 0x0047,  //40-47
        0x0048, 0x0049, 0x004A, 0x004B, 0x004C, 0x004D, 0x004E, 0x004F,  //48-4F
        0x0050, 0x0051, 0x0052, 0x0053, 0x0054, 0x0055, 0x0056, 0x0057,  //50-57
        0x0058, 0x0059, 0x005A, 0x005B, 0x005C, 0x005D, 0x005E, 0x005F,  //58-5F
        0x0060, 0x0061, 0x0062, 0x0063, 0x0064, 0x0065, 0x0066, 0x0067,  //60-67
        0x0068, 0x0069, 0x006A, 0x006B, 0x006C, 0x006D, 0x006E, 0x006F,  //68-6F
        0x0070, 0x0071, 0x0072, 0x0073, 0x0074, 0x0075, 0x0076, 0x0077,  //70-77
        0x0078, 0x0079, 0x007A, 0x007B, 0x007C, 0x007D, 0x007E, 0xFFFD,  //78-7F
        0x2022, 0x2020, 0x2021, 0x2026, 0x2014, 0x2013, 0x0192, 0x2044,  //80-87
        0x2039, 0x203A, 0x2212, 0x2030, 0x201E, 0x201C, 0x201D, 0x2018,  //88-8F
        0x2019, 0x201A, 0x2122, 0xFB01, 0xFB02, 0x0141, 0x0152, 0x0160,  //90-97
        0x0178, 0x017D, 0x0131, 0x0142, 0x0153, 0x0161, 0x017E, 0xFFFD,  //98-9F
        0x20AC, 0x00A1, 0x00A2, 0x00A3, 0x00A4, 0x00A5, 0x00A6, 0x00A7,  //A0-A7
        0x00A8, 0x00A9, 0x00AA, 0x00AB, 0x00AC, 0xFFFD, 0x00AE, 0x00AF,  //A8-AF
        0x00B0, 0x00B1, 0x00B2, 0x00B3, 0x00B4, 0x00B5, 0x00B6, 0x00B7,  //B0-B7
        0x00B8, 0x00B9, 0x00BA, 0x00BB, 0x00BC, 0x00BD, 0x00BE, 0x00BF,  //B8-BF
        0x00C0, 0x00C1, 0x00C2, 0x00C3, 0x00C4, 0x00C5, 0x00C6, 0x00C7,  //C0-C7
        0x00C8, 0x00C9, 0x00CA, 0x00CB, 0x00CC, 0x00CD, 0x00CE, 0x00CF,  //C8-CF
        0x00D0, 0x00D1, 0x00D2, 0x00D3, 0x00D4, 0x00D5, 0x00D6, 0x00D7,  //D0-D7
        0x00D8, 0x00D9, 0x00DA, 0x00DB, 0x00DC, 0x00DD, 0x00DE, 0x00DF,  //D8-DF
        0x00E0, 0x00E1, 0x00E2, 0x00E3, 0x00E4, 0x00E5, 0x00E6, 0x00E7,  //E0-E7
        0x00E8, 0x00E9, 0x00EA, 0x00EB, 0x00EC, 0x00ED, 0x00EE, 0x00EF,  //E8-EF
        0x00F0, 0x00F1, 0x00F2, 0x00F3, 0x00F4, 0x00F5, 0x00F6, 0x00F7,  //F0-F7
        0x00F8, 0x00F9, 0x00FA, 0x00FB, 0x00FC, 0x00FD, 0x00FE, 0x00FF,  //F8-FF
    };



}