//==============================================================================
// tribble/util/Hex.java
//------------------------------------------------------------------------------

package tribble.util;


// System imports

import java.lang.String;

import java.text.ParseException;


// Local imports

// (None)


/*******************************************************************************
* Hexadecimal encoding and decoding methods.
*
* <p>
* Hexadecimal encoding, a.k.a. radix-16 encoding, is a form of encoding binary
* data as hexadecimal digits.  (Each hexadecimal digit is 4 bits, providing 16
* distinct binary values, hence the term <i>hexadecimal</i> or <i>radix-16</i>.)
* Two hexadecimal digits can be encoded in a single 8-bit byte.
*
* <p>
* Converting straight binary data (as a sequence of 8-bit bytes) into a
* hexadecimal (radix-16) representation is the process of converting each byte
* of the data into two hexadecimal digit characters.
*
* <p>
* Converting hexadecimal (radix-16) encoded data (as a sequence of 8-bit
* characters) back into straight binary data is the reverse operation,
* substituting each pair of hexadecimal digit characters with its corresponding
* 8-bit byte value.
*
* <p>
* For example, the 8-byte array:
* <pre>
*    { 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF } </pre>
* is represented by the 16-character hexadecimal digit string:
* <pre>
*    "0123456789ABCDEF" </pre>
*
* @version	$Revision: 1.1 $ $Date: 2003/03/14 16:59:11 $
* @since	2003-03-14
* @author
*	David R. Tribble,
*	<a href="mailto:david@tribble.com">david@tribble.com</a>.
*	<br>
*	<a href="../Copyright.html">Copyright</a>
*	©2003 by David R. Tribble, all rights reserved.
*	<br>
*	Permission is granted to freely use and distribute this source
*	code provided that the original copyright and authorship notices
*	remain intact.
*
* @see	HexDump
*/

public abstract class Hex
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/util/Hex.java $Revision: 1.1 $ $Date: 2003/03/14 16:59:11 $\n";

    /** Class revision number. */
    public static final int	SERIES =	100;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Constants

    // (None)


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public static methods

    /***************************************************************************
    * Convert a 4-bit binary value into its corresponding hexadecimal (radix-16)
    * printable ASCII digit character.
    *
    * @param	v
    * A 4-bit binary value in the range <tt>[0,15]</tt>.
    *
    * @return
    * A hexadecimal digit, as a printable ASCII character code; or <tt>'?'</tt>,
    * indicating an invalid value.
    *
    * @since	1.1, 2003-03-14
    */

    public static final char toHex(int v)
    {
        // Convert a 4-bit value into a hex digit char
        if (v >= 0x0  &&  v <= 0xF)
            return ((char)(v < 0xA ? v+'0' : v-0xA+'A'));
        return ('?');
    }


    /***************************************************************************
    * Convert a hexadecimal (radix-16) digit character into its corresponding
    * 4-bit binary value.
    *
    * @param	ch
    * A hexadecimal (radix-16) ASCII digit character.
    *
    * @return
    * A 4-bit binary value in the range <tt>[0,15]</tt>;
    * or the value -1, indicating an invalid hexadecimal digit character.
    *
    * @since	1.1, 2003-03-14
    */

    public static final int fromHex(char ch)
    {
        if (ch <= '9')
        {
            if (ch >= '0')
                return (ch-'0');
            return (-1);
        }

        if (ch <= 'F')
        {
            if (ch >= 'A')
                return (ch-'A'+0xA);
            return (-1);
        }

        if (ch <= 'f')
        {
            if (ch >= 'a')
                return (ch-'a'+0xA);
            return (-1);
        }

        return (-1);
    }


    /***************************************************************************
    * Encode binary data as hexadecimal characters.
    *
    * @param	data
    * Binary data, as an array of bytes (8-bit octets).
    *
    * @return
    * A printable ASCII string containing the contents of <tt>data</tt> encoded
    * as hexadecimal (radix-16) digit characters.  This string will contain
    * exactly <tt>data.length*2</tt> characters.
    *
    * @since	1.1, 2003-03-14
    */

    public static String encode(/*const*/ byte[] data)
    {
        // Encode the binary data as radix-16 characters
        return (encode(data, 0, data.length));
    }


    /***************************************************************************
    * Encode binary data as hexadecimal characters.
    *
    * @param	data
    * Binary data, as an array of bytes (8-bit octets).
    *
    * @param	off
    * Index of the first byte (octet) within <tt>data</tt> to encode.
    *
    * @param	len
    * Number of bytes (octets) within <tt>data</tt> to encode.
    *
    * @return
    * A printable ASCII string containing the contents of <tt>data</tt> encoded
    * as hexadecimal (radix-16) digit characters.  This string will contain
    * exactly <tt>len*2</tt> characters.
    *
    * @since	1.1, 2003-03-14
    */

    public static String encode(/*const*/ byte[] data, int off, int len)
    {
        char[]	ch;
        int	i;

        // Convert bytes to hex digits
        ch = new char[data.length*2];
        i = 0;

        while (len-- > 0)
        {
            int		b;
            int		d;

            // Convert next byte into a hex digit pair
            b = data[off++] & 0xFF;

            d = b >> 4;
            d = (d < 0xA ? d+'0' : d-0xA+'A');
            ch[i++] = (char) d;

            d = b & 0xF;
            d = (d < 0xA ? d+'0' : d-0xA+'A');
            ch[i++] = (char) d;
        }

        return (new String(ch));
    }


    /***************************************************************************
    * Decode hexadecimal characters into binary data.
    *
    * @param	chars
    * Printable ASCII string containing binary data encoded as radix-16
    * characters.
    * Whitespace characters (spaces, tabs, newlines) and control characters are
    * ignored.
    *
    * @return
    * Binary data, as an array of bytes (8-bit octets).
    * This array will contain no more than <tt>chars.length()*2</tt> bytes.
    *
    * @since	1.1, 2003-03-14
    */

    public static byte[] decode(String chars)
        throws ParseException
    {
        byte[]	dec;
        int	len;

        // Initial size estimate of the decoded 8-bit data
        len = (chars.length()+1)/2;
        dec = new byte[len];

        // Decode the radix-16 character string
/*+INCOMPLETE
        ...use decode() below;
        ...;
+*/
        throw new Error("Method is not implemented yet");
    }


    /***************************************************************************
    * Decode hexadecimal characters into binary data.
    *
    * @param	chars
    * Printable ASCII string containing binary data encoded as radix-16
    * characters.
    * Whitespace characters (spaces, tabs, newlines) and control characters are
    * ignored.
    *
    * @param	dec
    * Decoded byte (8-bit octet) array, which is filled with the decoded data.
    *
    * @param	off
    * Index of the first byte (8-bit octet) within <tt>dec</tt> to write to.
    *
    * @param	len
    * Number of bytes (8-bit octets) to write into <tt>dec</tt>.
    *
    * @return
    * The number of bytes (8-bit octets) actually written into <tt>dec</tt>.
    * This will be no more than <tt>len</tt> or <tt>chars.length()*2</tt>,
    * whichever is less.
    *
    * @throws	ParseException
    * Thrown if <tt>chars</tt> is malformed or contains an invalid character
    * code.
    *
    * @since	1.1, 2003-03-14
    */

    public static int decode(String chars, byte[] dec, int off, int len)
        throws ParseException
    {
/*+INCOMPLETE
        ...;
+*/
        throw new Error("Method is not implemented yet");
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Variables

    // (None)


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constructors

    // (None)


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Methods

    // (None)


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Private constructors

    /***************************************************************************
    * Default constructor.
    * <b>Do not use this constructor.</b>
    *
    * @since	1.1, 2003-03-14
    */

    private Hex()
    {
        // Do nothing
    }
}

// End Hex.java