//==============================================================================
// 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.
*
*
* 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 hexadecimal or radix-16.)
* Two hexadecimal digits can be encoded in a single 8-bit byte.
*
*
* 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.
*
*
* 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.
*
*
* For example, the 8-byte array:
*
* { 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF }
* is represented by the 16-character hexadecimal digit string:
*
* "0123456789ABCDEF"
*
* @version $Revision: 1.1 $ $Date: 2003/03/14 16:59:11 $
* @since 2003-03-14
* @author
* David R. Tribble,
* david@tribble.com.
*
* Copyright
* ©2003 by David R. Tribble, all rights reserved.
*
* 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 [0,15].
*
* @return
* A hexadecimal digit, as a printable ASCII character code; or '?',
* 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 [0,15];
* 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 data encoded
* as hexadecimal (radix-16) digit characters. This string will contain
* exactly data.length*2 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 data to encode.
*
* @param len
* Number of bytes (octets) within data to encode.
*
* @return
* A printable ASCII string containing the contents of data encoded
* as hexadecimal (radix-16) digit characters. This string will contain
* exactly len*2 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 chars.length()*2 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 dec to write to.
*
* @param len
* Number of bytes (8-bit octets) to write into dec.
*
* @return
* The number of bytes (8-bit octets) actually written into dec.
* This will be no more than len or chars.length()*2,
* whichever is less.
*
* @throws ParseException
* Thrown if chars 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.
* Do not use this constructor.
*
* @since 1.1, 2003-03-14
*/
private Hex()
{
// Do nothing
}
}
// End Hex.java