danger.util
Class ByteArray

java.lang.Object
  danger.util.ByteArray

public final class ByteArray
extends Object

Utilities for accessing instances of byte[]. Note: Many of these methods are performed in native code on a device.

Field Summary

static char

UNICODE_REPLACEMENT_CHARACTER standard Unicode replacement character for bogus data

Method Summary

static int	compareTo(byte[] bytesA, int offsetA, int lenA, byte[] bytesB, int offsetB, int lenB) Compare two ranges of bytes in arrays, returning one of {-1, 0, 1} to indicate whether (respectively) the first is "less than," "equal to," or "greater than" the second.
static boolean	contains(byte[] bytes, int offset, int len, byte[] key)
static boolean	containsIgnoreCase(byte[] bytes, int offset, int len, byte[] key) Determine whether a given section of one byte[] contains bytes equal to the full contents of another byte[], when considering the two arrays to be UTF-8 encoded character data and disregarding case when doing comparisons.
static int	decodeUtf8Char(byte[] bytes, int index, int maxIndex) Decode a UTF-8 character from the given byte array at the given index, but not using bytes at or beyond the given maximum index.
static boolean	endsWith(byte[] haystack, int hlen, byte[] needle, int nlen)
static boolean	equals(byte[] bytesA, byte[] bytesB) Compare two instances of byte[] for equality.
static byte[]	fromStream(InputStream in) Convert an InputStream to an array of bytes by reading the stream bytes until an EOF is encountered.
static int	indexOf(byte[] inBase, int inOffset, int inLength, byte[] inKey) Search for the first occurance of one byte[] within a span of another.
static int	readInt(byte[] bytes, int offset) Read an int out of a byte[] at the given offset, in little-endian form (that is, low-order byte first).
static int	readShort(byte[] bytes, int offset) Read a short out of a byte[] at the given offset, in little-endian form (that is, low-order byte first).
static boolean	regionMatches(byte[] a, int ax, byte[] b, int bx, int len)
static boolean	startsWith(byte[] bytes, int offset, int len, byte[] key) Determine whether a given section of one byte[] starts with the full contents of another byte[].
static boolean	startsWithIgnoreCase(byte[] bytes, int offset, int len, byte[] key)
static void	writeInt(byte[] bytes, int offset, int value) Write an int to byte[] at the given offset, in little-endian form (that is, low-order byte first).
static void	writeShort(byte[] bytes, int offset, int value) Write a short to byte[] at the given offset, in little-endian form (that is, low-order byte first).

Methods inherited from class java.lang.Object

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

Field Detail

UNICODE_REPLACEMENT_CHARACTER

public static final char UNICODE_REPLACEMENT_CHARACTER

standard Unicode replacement character for bogus data

See Also:

Constant Field Values

Method Detail

fromStream

public static byte[] fromStream(InputStream in)
                         throws IOException

Convert an InputStream to an array of bytes by reading the stream bytes until an EOF is encountered.

Parameters:

in - the stream to read the bytes from

Returns:

the array of bytes read from the stream.

Throws:

IOException - thrown if there is a problem with the input stream or buffer for building the byte array.

NullPointerException - thrown if in is passed as null

readInt

public static int readInt(byte[] bytes,
                          int offset)

Read an int out of a byte[] at the given offset, in little-endian form (that is, low-order byte first).

Parameters:

bytes - non-null; the array to read from

offset - the offset to start reading at

Returns:

the decoded int

Throws:

ArrayIndexOutOfBoundsException - thrown if offset is out of range

NullPointerException - thrown of bytes is passed as null

readShort

public static int readShort(byte[] bytes,
                            int offset)

Read a short out of a byte[] at the given offset, in little-endian form (that is, low-order byte first).

Parameters:

bytes - non-null; the array to read from

offset - the offset to start reading at

Returns:

the decoded short

Throws:

ArrayIndexOutOfBoundsException - thrown if offset is out of range

NullPointerException - thrown of bytes is passed as null

writeInt

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

Write an int to byte[] at the given offset, in little-endian form (that is, low-order byte first). If the offset is out of range, then an exception is thrown and the array is left unaltered.

Parameters:

bytes - non-null; the array to store into

offset - the offset to start storing at

value - the value to store

Throws:

ArrayIndexOutOfBoundsException - thrown if offset is out of range

NullPointerException - thrown of bytes is passed as null

writeShort

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

Write a short to byte[] at the given offset, in little-endian form (that is, low-order byte first). If the offset is out of range, then an exception is thrown and the array is left unaltered.

Parameters:

bytes - non-null; the array to store into

offset - the offset to start storing at

value - the value to store

Throws:

ArrayIndexOutOfBoundsException - thrown if offset is out of range

NullPointerException - thrown of bytes is passed as null

compareTo

public static int compareTo(byte[] bytesA,
                            int offsetA,
                            int lenA,
                            byte[] bytesB,
                            int offsetB,
                            int lenB)

Compare two ranges of bytes in arrays, returning one of {-1, 0, 1} to indicate whether (respectively) the first is "less than," "equal to," or "greater than" the second. If one of the arrays is passed as null, then it is considered to be "less than" the other, unless the other one is also null, in which case the two are considered equal. Otherwise, corresponding bytes are compared, starting from early offsets, up to the smaller of the two lengths passed. Whichever array contains a byte that is smaller than the other is considered "less than" the other. If all bytes compared are equal, then the range with the smaller length is considered "less than" the other. If the two lengths are the same, then the ranges are considered "equal."

Parameters:

bytesA - null-ok; an array to compare

offsetA - the offset to start at in bytesA

lenA - the number of bytes in the range in bytesA

bytesB - null-ok; another array to compare

offsetB - the offset to start at in bytesB

lenB - the number of bytes in the range in bytesB

Returns:

one of {-1, 0, 1} to indicate whether (respectively) the first range is "less than," "equal to," or "greater than" the second

Throws:

ArrayIndexOutOfBoundsException - thrown if the arguments end up demanding that an out-of-range element be accessed

equals

public static boolean equals(byte[] bytesA,
                             byte[] bytesB)

Compare two instances of byte[] for equality. They are considered equal if either: both are null; both are non-null, of the same length, and with equal contents.

Parameters:

bytesA - null-ok; an array to compare

bytesB - null-ok; an array to compare it to

Returns:

true if and only if the two arrays are considered "equal" to each other

startsWith

public static boolean startsWith(byte[] bytes,
                                 int offset,
                                 int len,
                                 byte[] key)

Determine whether a given section of one byte[] starts with the full contents of another byte[].

Parameters:

bytes - null-ok; an array to compare

offset - the offset to start at in bytes

len - the number of bytes in the range in bytes

key - non-null; the array whose contents may or may not be the initial bytes in the specified range in bytes

Returns:

true iff the contents of key match the first key.length bytes in the specified range; this is notably false if len < key.length

Throws:

NullPointerException - thrown if key == null

IllegalArgumentException - thrown if offset and len don't specify an existing range within bytes

startsWithIgnoreCase

public static boolean startsWithIgnoreCase(byte[] bytes,
                                           int offset,
                                           int len,
                                           byte[] key)

contains

public static boolean contains(byte[] bytes,
                               int offset,
                               int len,
                               byte[] key)

containsIgnoreCase

public static boolean containsIgnoreCase(byte[] bytes,
                                         int offset,
                                         int len,
                                         byte[] key)

Determine whether a given section of one byte[] contains bytes equal to the full contents of another byte[], when considering the two arrays to be UTF-8 encoded character data and disregarding case when doing comparisons. Per-character comparisons are done in the style of String.equalsIgnoreCase() (as opposed to the subtly different style in String.compareToIgnoreCase).

Parameters:

bytes - null-ok; an array to compare

offset - the offset to start at in bytes

len - the number of bytes in the range in bytes

key - non-null; the array whose contents may or may not be equal, without regard to case, to a portion of the bytes in the specified range in bytes

Returns:

true iff an equivalent of the contents of key are found inside bytes in the specified range

Throws:

NullPointerException - thrown if key == null or bytes == null

IllegalArgumentException - thrown if offset and len don't specify an existing range within bytes

decodeUtf8Char

public static int decodeUtf8Char(byte[] bytes,
                                 int index,
                                 int maxIndex)

Decode a UTF-8 character from the given byte array at the given index, but not using bytes at or beyond the given maximum index. The return value comes in two 16-bit halves; the lower half is the decoded character, and the upper half is the number of bytes consumed.

Note: This decodes in exactly the same way that String decodes, including error cases.

Parameters:

bytes - non-null; bytes to decode from

index - the start index for the character

maxIndex - the limit of decoding (exclusive)

Returns:

(bytesConsumed << 16) | decodedCharacter

Throws:

NullPointerException - thrown if bytes == null

IndexOutOfBoundsException - thrown if index is outside of the legal range for bytes or if maxIndex is out of range and index points at the start of a multibyte character that would overflow into out-of-range territory

regionMatches

public static boolean regionMatches(byte[] a,
                                    int ax,
                                    byte[] b,
                                    int bx,
                                    int len)

endsWith

public static boolean endsWith(byte[] haystack,
                               int hlen,
                               byte[] needle,
                               int nlen)

indexOf

public static final int indexOf(byte[] inBase,
                                int inOffset,
                                int inLength,
                                byte[] inKey)

Search for the first occurance of one byte[] within a span of another. Searching is done from inBase[inOffset] through inBase[inOffset + inLength].

Parameters:

inBase - non-null; the array in which to search

inOffset - the beginning of the span within inBase to search

inLength - the length of the span within inBase to search

Returns:

the index of the beginning of the first occurance of inKey within inBase, or -1 if not found.