org.lwes.util
Class NumberCodec

java.lang.Object
  org.lwes.util.NumberCodec

public final class NumberCodec
extends java.lang.Object

This is a class to efficiently encode built-in primitive types into byte arrays and decode them back. While this can be done with a combination of ByteArrayOutputStreams, DataOutputStreams, ByteArrayInputStreams, DataInputStreams, merely creating those objects is quite costly and it is difficult to make them persistent. As such, this contains code lifted from the guts of the Data*Stream classes. Also, this class defines functions to convert primitive types and byte arrays to and from hexadecimal strings. Hopefully, support for these operations will be added to the standard Java API and this class can be retired.

Since:

0.0.1

Version:

%I%, %G%

Author:

Preston Pfarner, Michael P. Lum

Field Summary

static int	BYTE_BITS
static int	BYTE_BYTES
static short	BYTE_MASK
static int	INT_BITS
static int	INT_BYTES
static long	INT_MASK
static int	LONG_BITS
static int	LONG_BYTES
static int	SHORT_BITS
static int	SHORT_BYTES
static int	SHORT_MASK

Method Summary

static java.lang.String	byteArrayToHexString(byte[] bytes) Return a String encoding the bytes in a byte array in hex form.
static java.lang.String	byteArrayToHexString(byte[] bytes, int offset, int length) Return a String encoding the bytes from a portion of a byte array in hex form.
static byte	byteFromHexString(java.lang.String s) Output a byte in unsigned hexadecimal form, padding with zeroes.
static void	checkRange(int minLength, byte[] buffer, int offset, int length) Verifies that the buffer exists, that the writeable region fits into the buffer, and that the writeable length is long enough.
static byte	decodeByte(byte[] buffer, int offset, int length) Decode a byte out of a byte-array buffer.
static byte	decodeByteUnchecked(byte[] buffer, int offset) Extract and decode a byte out of a byte-array buffer.
static int	decodeInt(byte[] pBytes) Decode a int out of a byte-array buffer.
static int	decodeInt(byte[] buffer, int offset, int length) Decode an int out of a byte-array buffer.
static int	decodeIntUnchecked(byte[] buffer, int offset) Extract and decode an int out of a byte-array buffer.
static long	decodeLong(byte[] pBytes) Decode a long out of a byte-array buffer.
static long	decodeLong(byte[] buffer, int offset, int length) Decode a long out of a byte-array buffer.
static long	decodeLongUnchecked(byte[] buffer, int offset) Extract and decode a long out of a byte-array buffer.
static short	decodeShort(byte[] buffer, int offset, int length) Decode a short out of a byte-array buffer.
static short	decodeShortUnchecked(byte[] buffer, int offset) Extract and decode a short out of a byte-array buffer.
static void	encodeByte(byte b, byte[] buffer, int offset, int length) Encode a byte into a byte-array buffer.
static void	encodeByteUnchecked(byte b, byte[] buffer, int offset) Encode a byte into a byte-array buffer.
static byte[]	encodeInt(int pInt) Encode a int into a byte-array buffer.
static void	encodeInt(int i, byte[] buffer, int offset, int length) Encode an int into a byte-array buffer.
static void	encodeIntUnchecked(int i, byte[] buffer, int offset) Encode an int into a byte-array buffer.
static byte[]	encodeLong(long pLong) Encode a long into a byte-array buffer.
static void	encodeLong(long l, byte[] buffer, int offset, int length) Encode a long into a byte-array buffer.
static void	encodeLongUnchecked(long l, byte[] buffer, int offset) Encode a long into a byte-array buffer.
static void	encodeShort(short s, byte[] buffer, int offset, int length) Encode a short into a byte-array buffer.
static void	encodeShortUnchecked(short s, byte[] buffer, int offset) Encode a short into a byte-array buffer.
static byte[]	hexStringToByteArray(java.lang.String aString)
static int	intFromHexString(java.lang.String s) Output an int in unsigned hexadecimal form, padding with zeroes.
static long	longFromHexString(java.lang.String s) Output a long in unsigned hexadecimal form, padding with zeroes.
static short	shortFromHexString(java.lang.String s) Output a short in unsigned hexadecimal form, padding with zeroes.
static java.lang.String	toHexString(java.math.BigInteger bi) Output a BigInteger in unsigned hexadecimal form, padding with zeroes.
static java.lang.String	toHexString(byte b) Output a byte in unsigned hexadecimal form, padding with zeroes.
static java.lang.String	toHexString(int i) Output an int in unsigned hexadecimal form, padding with zeroes.
static java.lang.String	toHexString(long l) Output a long in unsigned hexadecimal form, padding with zeroes.
static java.lang.String	toHexString(short s) Output a short in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(byte b, byte[] bytes, int offset) Write a byte in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(byte b, java.lang.StringBuffer buf) Write a byte in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(int value, byte[] bytes, int offset) Write a int in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(int i, java.lang.StringBuffer buf) Write a int in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(long value, byte[] bytes, int offset) Write a long in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(long l, java.lang.StringBuffer buf) Write a long in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(short value, byte[] bytes, int offset) Write a short in unsigned hexadecimal form, padding with zeroes.
static void	writeHexString(short s, java.lang.StringBuffer buf) Write a short in unsigned hexadecimal form, padding with zeroes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BYTE_BYTES

public static final int BYTE_BYTES

See Also:

Constant Field Values

SHORT_BYTES

public static final int SHORT_BYTES

See Also:

Constant Field Values

INT_BYTES

public static final int INT_BYTES

See Also:

Constant Field Values

LONG_BYTES

public static final int LONG_BYTES

See Also:

Constant Field Values

BYTE_BITS

public static final int BYTE_BITS

See Also:

Constant Field Values

SHORT_BITS

public static final int SHORT_BITS

See Also:

Constant Field Values

INT_BITS

public static final int INT_BITS

See Also:

Constant Field Values

LONG_BITS

public static final int LONG_BITS

See Also:

Constant Field Values

BYTE_MASK

public static final short BYTE_MASK

See Also:

Constant Field Values

SHORT_MASK

public static final int SHORT_MASK

See Also:

Constant Field Values

INT_MASK

public static final long INT_MASK

See Also:

Constant Field Values

Method Detail

encodeByteUnchecked

public static void encodeByteUnchecked(byte b,
                                       byte[] buffer,
                                       int offset)

Encode a byte into a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

b - the byte to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

encodeByte

public static void encodeByte(byte b,
                              byte[] buffer,
                              int offset,
                              int length)
                       throws java.lang.IllegalArgumentException

Encode a byte into a byte-array buffer.

Parameters:

b - the byte to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

length - the maximum number of bytes that may be written

Throws:

java.lang.IllegalArgumentException

encodeShortUnchecked

public static void encodeShortUnchecked(short s,
                                        byte[] buffer,
                                        int offset)

Encode a short into a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

s - the short to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

encodeShort

public static void encodeShort(short s,
                               byte[] buffer,
                               int offset,
                               int length)
                        throws java.lang.IllegalArgumentException

Encode a short into a byte-array buffer.

Parameters:

s - the short to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

length - the maximum number of bytes that may be written

Throws:

java.lang.IllegalArgumentException

encodeIntUnchecked

public static void encodeIntUnchecked(int i,
                                      byte[] buffer,
                                      int offset)

Encode an int into a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

i - the int to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

encodeInt

public static void encodeInt(int i,
                             byte[] buffer,
                             int offset,
                             int length)
                      throws java.lang.IllegalArgumentException

Encode an int into a byte-array buffer.

Parameters:

i - the int to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

length - the maximum number of bytes that may be written

Throws:

java.lang.IllegalArgumentException

encodeLongUnchecked

public static void encodeLongUnchecked(long l,
                                       byte[] buffer,
                                       int offset)

Encode a long into a byte-array buffer.

Parameters:

l - the long to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

encodeLong

public static void encodeLong(long l,
                              byte[] buffer,
                              int offset,
                              int length)
                       throws java.lang.IllegalArgumentException

Encode a long into a byte-array buffer.

Parameters:

l - the long to be encoded

buffer - the byte array into which the encoding should be written

offset - the position in the array to start writing the encoding

length - the maximum number of bytes that may be written

Throws:

java.lang.IllegalArgumentException

decodeByteUnchecked

public static final byte decodeByteUnchecked(byte[] buffer,
                                             int offset)

Extract and decode a byte out of a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

decodeByte

public static final byte decodeByte(byte[] buffer,
                                    int offset,
                                    int length)
                             throws java.lang.IllegalArgumentException

Decode a byte out of a byte-array buffer.

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

length - the maximum number of bytes that may be read

Throws:

java.lang.IllegalArgumentException

decodeShortUnchecked

public static short decodeShortUnchecked(byte[] buffer,
                                         int offset)

Extract and decode a short out of a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

decodeShort

public static short decodeShort(byte[] buffer,
                                int offset,
                                int length)
                         throws java.lang.IllegalArgumentException

Decode a short out of a byte-array buffer.

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

length - the maximum number of bytes that may be read

Throws:

java.lang.IllegalArgumentException

decodeIntUnchecked

public static int decodeIntUnchecked(byte[] buffer,
                                     int offset)

Extract and decode an int out of a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

decodeInt

public static int decodeInt(byte[] buffer,
                            int offset,
                            int length)
                     throws java.lang.IllegalArgumentException

Decode an int out of a byte-array buffer.

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

length - the maximum number of bytes that may be read

Throws:

java.lang.IllegalArgumentException

decodeLongUnchecked

public static long decodeLongUnchecked(byte[] buffer,
                                       int offset)

Extract and decode a long out of a byte-array buffer.
This version does not perform any null or range checks!

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

decodeLong

public static long decodeLong(byte[] buffer,
                              int offset,
                              int length)
                       throws java.lang.IllegalArgumentException

Decode a long out of a byte-array buffer.

Parameters:

buffer - the byte array from which the encoded form should be read

offset - the position in the array to start reading the encoded form

length - the maximum number of bytes that may be read

Throws:

java.lang.IllegalArgumentException

checkRange

public static void checkRange(int minLength,
                              byte[] buffer,
                              int offset,
                              int length)
                       throws java.lang.IllegalArgumentException

Verifies that the buffer exists, that the writeable region fits into the buffer, and that the writeable length is long enough.

Parameters:

minLength - the length that will be written

buffer - the destination array

offset - the first position that should be written

length - the number of bytes that may be written

Throws:

java.lang.IllegalArgumentException - if the check fails

toHexString

public static java.lang.String toHexString(byte b)

Output a byte in unsigned hexadecimal form, padding with zeroes.

Parameters:

b - the byte

Returns:

a String representing the byte.

toHexString

public static java.lang.String toHexString(short s)

Output a short in unsigned hexadecimal form, padding with zeroes.

Parameters:

s - the short

Returns:

a String representing the short.

toHexString

public static java.lang.String toHexString(int i)

Output an int in unsigned hexadecimal form, padding with zeroes.

Parameters:

i - the int

Returns:

a String representing the int.

toHexString

public static java.lang.String toHexString(long l)

Output a long in unsigned hexadecimal form, padding with zeroes.

Parameters:

l - the long

Returns:

a String representing the long.

toHexString

public static java.lang.String toHexString(java.math.BigInteger bi)

Output a BigInteger in unsigned hexadecimal form, padding with zeroes.

Parameters:

bi - the BigInteger

Returns:

a String representing the BigInteger.

writeHexString

public static void writeHexString(byte b,
                                  java.lang.StringBuffer buf)

Write a byte in unsigned hexadecimal form, padding with zeroes.

Parameters:

buf - the StringBuffer into which to write

b - the byte

writeHexString

public static void writeHexString(short s,
                                  java.lang.StringBuffer buf)

Write a short in unsigned hexadecimal form, padding with zeroes.

Parameters:

buf - the StringBuffer into which to write

s - the short

writeHexString

public static void writeHexString(int i,
                                  java.lang.StringBuffer buf)

Write a int in unsigned hexadecimal form, padding with zeroes.

Parameters:

buf - the StringBuffer into which to write

i - the int

writeHexString

public static void writeHexString(long l,
                                  java.lang.StringBuffer buf)

Write a long in unsigned hexadecimal form, padding with zeroes.

Parameters:

buf - the StringBuffer into which to write

l - the long

writeHexString

public static void writeHexString(byte b,
                                  byte[] bytes,
                                  int offset)

Write a byte in unsigned hexadecimal form, padding with zeroes.

Parameters:

b - the byte

bytes - the byte array into which to write

offset - the index in the byte array to start writing

writeHexString

public static void writeHexString(short value,
                                  byte[] bytes,
                                  int offset)

Write a short in unsigned hexadecimal form, padding with zeroes.

Parameters:

value - the value to write

bytes - the byte array into which to write

offset - the index in the byte array to start writing

writeHexString

public static void writeHexString(int value,
                                  byte[] bytes,
                                  int offset)

Write a int in unsigned hexadecimal form, padding with zeroes.

Parameters:

value - the value to write

bytes - the byte array into which to write

offset - the index in the byte array to start writing

writeHexString

public static void writeHexString(long value,
                                  byte[] bytes,
                                  int offset)

Write a long in unsigned hexadecimal form, padding with zeroes.

Parameters:

value - the value to write

bytes - the byte array into which to write

offset - the index in the byte array to start writing

byteArrayToHexString

public static java.lang.String byteArrayToHexString(byte[] bytes,
                                                    int offset,
                                                    int length)

Return a String encoding the bytes from a portion of a byte array in hex form.

Parameters:

bytes - the byte array

offset - the first byte to output

length - the number of bytes to output

Returns:

the hex dump of the byte array

hexStringToByteArray

public static byte[] hexStringToByteArray(java.lang.String aString)

byteArrayToHexString

public static java.lang.String byteArrayToHexString(byte[] bytes)

Return a String encoding the bytes in a byte array in hex form.
This is equivalent to byteArrayToHexString(bytes,0,bytes.length);

Parameters:

bytes - the byte array

Returns:

the hex dump of the byte array

byteFromHexString

public static byte byteFromHexString(java.lang.String s)

Output a byte in unsigned hexadecimal form, padding with zeroes.

Parameters:

s - the String representing the byte.

Returns:

the parsed byte

shortFromHexString

public static short shortFromHexString(java.lang.String s)

Output a short in unsigned hexadecimal form, padding with zeroes.

Parameters:

s - the String representing the short

Returns:

the parsed short

intFromHexString

public static int intFromHexString(java.lang.String s)

Output an int in unsigned hexadecimal form, padding with zeroes.

Parameters:

s - the String representing the int.

Returns:

the parsed int

longFromHexString

public static long longFromHexString(java.lang.String s)

Output a long in unsigned hexadecimal form, padding with zeroes.

Parameters:

s - the String representing the long.

Returns:

the parsed long

decodeLong

public static long decodeLong(byte[] pBytes)
                       throws java.lang.NumberFormatException

Decode a long out of a byte-array buffer. (convienience method)

Parameters:

pBytes - the byte array from which the encoded form should be read

Returns:

long decoded from bytes

Throws:

java.lang.NumberFormatException

encodeLong

public static byte[] encodeLong(long pLong)

Encode a long into a byte-array buffer. (convienience method)

Parameters:

pLong - the long to be encoded

Returns:

encoded bytes of the long

decodeInt

public static int decodeInt(byte[] pBytes)
                     throws java.lang.NumberFormatException

Decode a int out of a byte-array buffer. (convienience method)

Parameters:

pBytes - the byte array from which the encoded form should be read

Returns:

int decoded from bytes

Throws:

java.lang.NumberFormatException

encodeInt

public static byte[] encodeInt(int pInt)
                        throws java.lang.NumberFormatException

Encode a int into a byte-array buffer. (convienience method)

Parameters:

pInt - the int to be encoded

Returns:

encoded bytes of the int

Throws:

java.lang.NumberFormatException