hypercast
Class ByteArrayUtility

java.lang.Object
  |
  +--hypercast.ByteArrayUtility

public class ByteArrayUtility
extends java.lang.Object

This class contains some general functions for reading values from a byte array and for writing values to a byte array.

Note that the functionality in this class closely resembles that of java.lang.reflect.Array as well as java.nio.ByteBuffer. It is not entirely clear why neither of these built in classes are used instead of code in this class. In the case of java.nio.ByteBuffer, Java NIO was not added to the JDK until version 1.4; the code in this class predates version 1.4. Also, deployment of HyperCast to hand-held computers is limited by the fact that such platforms do not, as of this writing, support Java features after 1.2. In the case of java.lang.reflect.Array, perhaps the reflection was seen as a performance penalty.

Bitwise Arithmetic

A note on Java bitwise arithmetic: The code in this class does a lot of arithmetic using byte values. Care must be used in such operations since Java "sign-extends" values when promoting a smaller type to a larger type. For example, the byte value of 0x80 will be 0xFF80 if cast to a short, whereas the byte value 0x7F will be 0x007F if cast to a short. Said another way: the value of the high order bit of a byte is very important/tricky. As a result, the code in this class contains many explicit bitwise AND operations that clearly specify which bits will be retained so that sign-extended values to not cause incorrect results. This means that when converting the byte value to a larger type, e.g short, an explicit bitwise AND operation will be used as in:

(data[index] & 0xFF) << 8

Although this bitwise AND seems superfluous it is not; if data[index] had its high order bit set to 1, the result could be incorrect.

Unsigned Values

A note about signed and unsigned values: The Java Programming Language 3rd ed. section 6.2 "Types and Literals" has a paragraph concerning unsigned types. It says that a Java program needing to use unsigned types should use a "larger signed type" for arithmetic. HyperCast does not fully espouse this doctrine, rather when storing an unsigned quantity (i.e. an instance variable of an object) HyperCast uses a type that is the same size as the unsigned quantity that it is using. For example, HyperCast will use a short (2 bytes) to represent a 2 byte unsigned quantity instead of the larger signed type of int, or an int to store an unsigned 4 byte quantity rather than a long (note that the Java built-in 2 byte unsigned char type is never used in HyperCast). This means that HyperCast must be careful when performing arithmetic on quantities that are interpretted as unsigned. The arithmetic operations must use the next larger signed type and then convert back to the smaller type. An example of this is seen in OL_Message.decrementHopLimit().

See Also:

The ByteArrayUtility class provides several methods that claim to read "unsigned" values from a byte array. These methods conform to the "larger signed type" idea described above. That is, they read an amount of data from a byte array that is smaller than the type that they return, this ensures that the high order bit is not used so negative numbers cannot be represented. For example, an unsigned integer can be created using toUnsignedInt from 1, 2, or 3, but not 4 bytes. Using a fourth byte would allow the high order bit of the integer to indicate a negative value. (NB in Java 2's complement is used so there is no "sign bit" per se as in "signed-magnitude" bit encoding, nevertheless, all negative values in 2's complement have the high order bit set to 1).


Field Summary
static int SIZEOF_BYTE
          Length of byte primitive type in bits
static int SIZEOF_INT
          Length of int primitive type in bits
static int SIZEOF_LONG
          Length of long primitive type in bits
static int SIZEOF_SHORT
          Length of short primitive type in bits
 
Constructor Summary
ByteArrayUtility()
           
 
Method Summary
static java.lang.String byteToBits(byte x)
          Creates a string that represents the bit pattern of the specified byte value.
static byte[] concatenate(byte[] source1, byte[] source2)
          Concatenates two byte arrays into one new byte array
static java.lang.String intToBits(int x)
          Creates a string that represents the bit pattern of the specified int value.
static boolean isBytesZero(byte[] data, int offset, int length)
          Checks out if the specified part of a byte array is all zero.
static java.lang.String longToBits(long x)
          Creates a string that represents the bit pattern of the specified long value.
static void main(java.lang.String[] args)
           
static void setBytesZero(byte[] data, int offset, int length)
          Sets a specified part of a byte array to all zeros.
static java.lang.String shortToBits(short x)
          Creates a string that represents the bit pattern of the specified short value.
static byte[] toByteArray(int value)
          Converts an integer to a byte array of length 4
static byte[] toByteArray(long value)
          Converts a long to a byte array
static byte[] toByteArray(short value)
          Converts an short integer to a byte array of length 2.
static int toInteger(byte[] data, int index)
          Converts four bytes of a byte array to an integer.
static long toLong(byte[] data, int index)
          Converts a byte array to a long integer.
static short toShort(byte[] data, int index)
          Converts two bytes in a byte array to a signed short integer.
static int toUnsignedInteger(byte[] data, int index, int length)
          Converts one, two, or three bytes of a byte array to an unsigned integer.
static int toUnsignedLong(byte[] data, int index, int length)
          Converts between one and seven bytes of a byte array to an unsigned long.
static short toUnsignedShort(byte[] data, int index)
          Converts a byte in a byte array to an unsigned short integer.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SIZEOF_BYTE

public static final int SIZEOF_BYTE
Length of byte primitive type in bits

See Also:
Constant Field Values

SIZEOF_SHORT

public static final int SIZEOF_SHORT
Length of short primitive type in bits

See Also:
Constant Field Values

SIZEOF_INT

public static final int SIZEOF_INT
Length of int primitive type in bits

See Also:
Constant Field Values

SIZEOF_LONG

public static final int SIZEOF_LONG
Length of long primitive type in bits

See Also:
Constant Field Values
Constructor Detail

ByteArrayUtility

public ByteArrayUtility()
Method Detail

toShort

public static short toShort(byte[] data,
                            int index)
Converts two bytes in a byte array to a signed short integer.

Parameters:
data - a byte array having a two byte short quantity encoded beginning at position index.
index - position in the array data where a two byte short quantity is encoded.
Returns:
a short integer based on the value of the two bytes beginning at position index of the array data.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

toUnsignedShort

public static short toUnsignedShort(byte[] data,
                                    int index)
Converts a byte in a byte array to an unsigned short integer. Can be thought of as an unsigned byte contained in the next larger integral type, i.e. short.

Parameters:
data - a byte array having a one byte unsigned short quantity encoded at position index.
index - position in the array data where a one byte unsigned short quantity is encoded.
Returns:
a short integer based on the value of the byte at position index of the array data.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

toByteArray

public static byte[] toByteArray(short value)
Converts an short integer to a byte array of length 2.

Parameters:
value - a short integer
Returns:
a byte array representing the short integer

toInteger

public static int toInteger(byte[] data,
                            int index)
Converts four bytes of a byte array to an integer.

Parameters:
data - a byte array having an integer quantity encoded beginning at position index.
index - position in the array data where an integer quantity is encoded.
Returns:
an integer based on the value of the specifed bytes beginning at position index of the array data.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

toUnsignedInteger

public static int toUnsignedInteger(byte[] data,
                                    int index,
                                    int length)
Converts one, two, or three bytes of a byte array to an unsigned integer. Can be thought of as using a larger, i.e. 32 bit integer, integral type to hold an unsigned 8 bit, 16 bit, or 24 bit value.

Parameters:
data - a byte array having an integer quantity encoded beginning at position index.
index - position in the array data where an integer quantity is encoded.
length - the number of bytes comprising the integer data, can be 1, 2, or 3. Anything longer than 3 bytes will allow negative integer values to be encoded, breaking the contract that an unsigned value is returned.
Returns:
an integer of length bytes based on the value of the specifed bytes beginning at position index of the array data.
Throws:
java.lang.IllegalArgumentException - if length is not 1, 2, or 3.
java.lang.ArrayIndexOutOfBoundsException - if the values of index and length cause an illegal array access.

toByteArray

public static byte[] toByteArray(int value)
Converts an integer to a byte array of length 4

Parameters:
value - an integer
Returns:
a byte array representing the integer

toLong

public static long toLong(byte[] data,
                          int index)
Converts a byte array to a long integer.

Parameters:
data - a byte array
index - a starting index in the array
Returns:
a long integer
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

toUnsignedLong

public static int toUnsignedLong(byte[] data,
                                 int index,
                                 int length)
Converts between one and seven bytes of a byte array to an unsigned long. Can be thought of as using a larger, i.e. 64 bit long, integral type to hold an unsigned quantity represented as an array of size ranging fom one to seven bytes.

Parameters:
data - a byte array having a long quantity encoded beginning at position index.
index - position in the array data where an long quantity is encoded.
length - the number of bytes comprising the long data, can be 1-7 inclusive. Anything longer than 7 bytes will allow negative long values to be encoded, breaking the contract that an unsigned value is returned.
Returns:
a long of length bytes based on the value of the specifed bytes beginning at position index of the array data.
Throws:
java.lang.IllegalArgumentException - if length is not in the range 1-7 inclusive.
java.lang.ArrayIndexOutOfBoundsException - if the values of index and length cause an illegal array access.

toByteArray

public static byte[] toByteArray(long value)
Converts a long to a byte array

Parameters:
value - a long integer
Returns:
a byte array representing the long integer

isBytesZero

public static boolean isBytesZero(byte[] data,
                                  int offset,
                                  int length)
Checks out if the specified part of a byte array is all zero.

Parameters:
data - a byte array
offset - the start position to check
length - the total length of bytes to be checked
Returns:
true, if all the bytes checked out to be all zero, false if not
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

setBytesZero

public static void setBytesZero(byte[] data,
                                int offset,
                                int length)
Sets a specified part of a byte array to all zeros.

Parameters:
data - a byte array
offset - starting position
length - number of bytes to set to zero
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

concatenate

public static byte[] concatenate(byte[] source1,
                                 byte[] source2)
Concatenates two byte arrays into one new byte array

Parameters:
source1 - the first byte array (will be at the beginning of the new array)
source2 - the second byte array (will be at the end of the new array)
Returns:
the concatenation of the two arrays
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of index causes an illegal array access.

byteToBits

public static java.lang.String byteToBits(byte x)
Creates a string that represents the bit pattern of the specified byte value.

Parameters:
x - A byte value
Returns:
A string representing the bit pattern of the specified byte.

shortToBits

public static java.lang.String shortToBits(short x)
Creates a string that represents the bit pattern of the specified short value.

Parameters:
x - A short value
Returns:
A string representing the bit pattern of the specified short.

intToBits

public static java.lang.String intToBits(int x)
Creates a string that represents the bit pattern of the specified int value.

Parameters:
x - A int value
Returns:
A string representing the bit pattern of the specified int.

longToBits

public static java.lang.String longToBits(long x)
Creates a string that represents the bit pattern of the specified long value.

Parameters:
x - A long value
Returns:
A string representing the bit pattern of the specified long.

main

public static void main(java.lang.String[] args)