|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--hypercast.ByteArrayUtility
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.
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.
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()
.
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 |
public static final int SIZEOF_BYTE
public static final int SIZEOF_SHORT
public static final int SIZEOF_INT
public static final int SIZEOF_LONG
Constructor Detail |
public ByteArrayUtility()
Method Detail |
public static short toShort(byte[] data, int index)
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.
index
of the array data.
- Throws:
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.
public static short toUnsignedShort(byte[] data, int index)
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.
index
of the array data.
- Throws:
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.
public static byte[] toByteArray(short value)
value
- a short integer
public static int toInteger(byte[] data, int index)
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.
index
of the array data.
- Throws:
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.
public static int toUnsignedInteger(byte[] data, int index, int length)
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.
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.
public static byte[] toByteArray(int value)
value
- an integer
public static long toLong(byte[] data, int index)
data
- a byte arrayindex
- a starting index in the array
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.public static int toUnsignedLong(byte[] data, int index, int length)
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.
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.
public static byte[] toByteArray(long value)
value
- a long integer
public static boolean isBytesZero(byte[] data, int offset, int length)
data
- a byte arrayoffset
- the start position to checklength
- the total length of bytes to be checked
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.public static void setBytesZero(byte[] data, int offset, int length)
data
- a byte arrayoffset
- starting positionlength
- number of bytes to set to zero
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.public static byte[] concatenate(byte[] source1, byte[] source2)
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)
java.lang.ArrayIndexOutOfBoundsException
- if the value of index
causes an illegal array access.public static java.lang.String byteToBits(byte x)
x
- A byte value
public static java.lang.String shortToBits(short x)
x
- A short value
public static java.lang.String intToBits(int x)
x
- A int value
public static java.lang.String longToBits(long x)
x
- A long value
public static void main(java.lang.String[] args)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |