net.sf.ivmaidns.util
Class ByteVector

java.lang.Object
  net.sf.ivmaidns.util.ByteVector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Indexable, ReallyCloneable, Sortable, Verifiable

public final class ByteVector
extends java.lang.Object
implements ReallyCloneable, java.io.Serializable, Indexable, Sortable, Verifiable

Class for 'byte' array wrappers. This class wraps a primitive byte-type array, and has the possibility to resize (when required) the wrapped array. This class supports cloning, serialization and comparison of its instances. In addition, the class contains static methods for byte arrays resizing, filling in, reversing, vector arithmetics (addition, subtraction, multiplication by a value, scalar multiplication, polynome evaluation), elements summing and non-zero elements counting, linear/binary searching in for a value or sequence, mismatches counting, signed/unsigned 'less-equal-greater' comparison, sorting, and also decimal/hexadecimal/radix-64 'to-string' and 'from-string' (parse) conversions.

Version:

2.0

Author:

Ivan Maidanski

See Also:

CharVector, DoubleVector, FloatVector, IntVector, LongVector, ShortVector, BooleanVector, ObjectVector, UnsignedInt, JavaConsts, Serialized Form

Field Summary

protected byte[]	array The wrapped (encapsulated) custom byte array.
protected static byte[]	EMPTY A constant initialized with an instance of empty byte array.

Constructor Summary

ByteVector()
Constructs an empty byte vector.

ByteVector(byte[] array)
Constructs a new byte array wrapper.

ByteVector(int size)
Constructs a new byte vector of the specified length.

Method Summary

static void	addTo(byte[] arrayA, byte[] arrayB) Adds a given vector (array) to another one.
byte[]	array() Returns array wrapped by this vector.
static int	binarySearch(byte[] array, int offset, int len, byte value, boolean isUnsigned) Searches (fast) for value in a given sorted array.
java.lang.Object	clone() Creates and returns a copy of this object.
static int	compare(byte[] arrayA, int offsetA, int lenA, byte[] arrayB, int offsetB, int lenB, boolean isUnsigned) Compares two given array regions.
void	copyAt(int srcOffset, int destOffset, int len) Copies a region of values at one offset to another offset in this vector.
static void	counterSort(byte[] array, int offset, int len, boolean isUnsigned) Sorts the elements in the region of a given array (by counting the amount of each possible value in it).
static int	countNonZero(byte[] array) Count non-zero elements in a given array.
static byte[]	ensureSize(byte[] array, int size) Ensures the length (capacity) of a given array.
void	ensureSize(int size) Ensures the size (capacity) of this vector.
static boolean	equals(byte[] arrayA, byte[] arrayB) Tests whether or not the specified two arrays are equal.
boolean	equals(java.lang.Object obj) Indicates whether this object is equal to the specified one.
static void	fill(byte[] array, int offset, int len, byte value) Fills in the region of a given array with the specified value.
java.lang.Object	getAt(int index) Returns the wrapped value of the element at the specified index.
byte	getByteAt(int index) Returns value of the element at the specified index.
boolean	greaterThan(java.lang.Object obj) Tests for being semantically greater than the argument.
int	hashCode() Computes and returns a hash code value for the object.
static int	hashCode(byte[] array) Produces a hash code value for a given array.
static int	indexOf(byte[] subArray, int offset, int len, int index, byte[] array) Searches forward for the specified sequence in a given array.
static int	indexOf(byte value, int index, byte[] array) Searches forward for value in a given array.
void	integrityCheck() Verifies this object for its integrity.
static int	lastIndexOf(byte[] subArray, int offset, int len, int index, byte[] array) Searches backward for the specified sequence in a given array.
static int	lastIndexOf(byte value, int index, byte[] array) Searches backward for value in a given array.
int	length() Returns the number of elements in this vector.
static int	mismatches(byte[] arrayA, int offsetA, byte[] arrayB, int offsetB, int len) Count the mismatches of two given array regions.
static void	multiplyBy(byte[] array, byte value) Multiplies a given vector (array) by a value.
static byte[]	parseBase64String(java.lang.String str, int beginIndex, int endIndex) Decodes 'radix-64' representation into a byte array.
static byte[]	parseHexString(java.lang.String str, int beginIndex, int endIndex, char separator, boolean emptyAsZero, int groupLen, boolean padArray) Decodes hexadecimal sequence into a byte array.
static int	polynome(int intValue, byte[] array, boolean isUnsigned) Computes the result of substitution of a given int value into the polynome specified by its coefficients.
static byte[]	resize(byte[] array, int size) Resizes a given array.
void	resize(int size) Resizes this vector.
static void	reverse(byte[] array) Reverses the elements order in a given array.
static int	scalarMul(byte[] arrayA, byte[] arrayB, boolean isUnsigned) Multiplies two given vectors (arrays) in a scalar way.
void	setArray(byte[] array) Sets another array to be wrapped by this vector.
void	setAt(int index, byte value) Assigns a new value to the element at the specified index.
static void	subtractFrom(byte[] arrayA, byte[] arrayB) Subtracts a given vector (array) from another one.
static int	sumOf(byte[] array, int offset, int len, boolean isUnsigned) Sums the elements in the region of a given array.
static java.lang.String	toBase64String(byte[] array, int offset, int len) Converts the byte-array region into its 'radix-64' representation.
static java.lang.String	toHexString(byte[] array, int offset, int len, boolean upperCase, char separator, int groupLen, boolean zeroPadding) Converts the byte-array region into its hexadecimal representation.
java.lang.String	toString() Converts this vector to its 'in-line' string representation.
static java.lang.String	toString(byte[] array, int offset, int len, char separator, boolean isUnsigned) Converts the region of a given array to its 'in-line' string representation.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

protected static final byte[] EMPTY

A constant initialized with an instance of empty byte array.

See Also:

array

array

protected byte[] array

The wrapped (encapsulated) custom byte array. array must be non-null.

See Also:

EMPTY, ByteVector(), ByteVector(int), ByteVector(byte[]), setArray(byte[]), array(), length(), resize(int), ensureSize(int), setAt(int, byte), getByteAt(int), copyAt(int, int, int), clone(), integrityCheck()

Constructor Detail

ByteVector

public ByteVector()

Constructs an empty byte vector. This constructor is used for the creation of a resizable vector. The length of such a vector is changed only by resize(int) and ensureSize(int) methods.

See Also:

ByteVector(int), ByteVector(byte[]), array(), length(), resize(int), ensureSize(int), setAt(int, byte), getByteAt(int), copyAt(int, int, int), clone(), toString()

ByteVector

public ByteVector(int size)

Constructs a new byte vector of the specified length. This constructor is typically used for the creation of a vector with a fixed size. All elements of the created vector are set to zero.

Parameters:

size - the initial length (unsigned) of the vector to be created.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

ByteVector(), ByteVector(byte[]), array(), length(), setAt(int, byte), getByteAt(int), copyAt(int, int, int), fill(byte[], int, int, byte), clone(), toString()

ByteVector

public ByteVector(byte[] array)
           throws java.lang.NullPointerException

Constructs a new byte array wrapper. This constructor is used for the creation of a vector which wraps the specified array (without copying it). The wrapped array may be further replaced with another one only by setArray(byte[]) and by resize(int), ensureSize(int) methods.

Parameters:

array - the byte array (must be non-null) to be wrapped.

Throws:

java.lang.NullPointerException - if array is null.

Since:

2.0

See Also:

ByteVector(), ByteVector(int), setArray(byte[]), array(), resize(int), ensureSize(int), setAt(int, byte), getByteAt(int), copyAt(int, int, int), clone(), toString()

Method Detail

setArray

public void setArray(byte[] array)
              throws java.lang.NullPointerException

Sets another array to be wrapped by this vector. Important notes: resize(int) and ensureSize(int) methods may change the array to be wrapped too (but only with its copy of a different length); this method does not copy array. If an exception is thrown then this vector remains unchanged.

Parameters:

array - the byte array (must be non-null) to be wrapped.

Throws:

java.lang.NullPointerException - if array is null.

Since:

2.0

See Also:

ByteVector(), ByteVector(byte[]), array(), resize(int), ensureSize(int), setAt(int, byte), getByteAt(int), copyAt(int, int, int), clone()

array

public final byte[] array()

Returns array wrapped by this vector. Important notes: this method does not copy array.

Returns:

the byte array (not null), which is wrapped.

Since:

1.8

See Also:

ByteVector(byte[]), setArray(byte[]), length(), resize(int), ensureSize(int), copyAt(int, int, int), clone()

length

public int length()

Returns the number of elements in this vector. The result is the same as length of array().

Specified by:

length in interface Indexable

Returns:

the length (non-negative value) of this vector.

Since:

1.8

See Also:

setArray(byte[]), array(), setAt(int, byte), resize(int), ensureSize(int), getByteAt(int), getAt(int)

getAt

public java.lang.Object getAt(int index)
                       throws java.lang.ArrayIndexOutOfBoundsException

Returns the wrapped value of the element at the specified index. The result is the same as of new Byte(array()[index]).

Specified by:

getAt in interface Indexable

Parameters:

index - the index (must be in the range) at which to return an element.

Returns:

an element (instance of Byte) at index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is negative or is not less than length().

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

getByteAt(int), array(), length()

getByteAt

public final byte getByteAt(int index)
                     throws java.lang.ArrayIndexOutOfBoundsException

Returns value of the element at the specified index. The result is the same as of array()[index].

Parameters:

index - the index (must be in the range) at which to return an element.

Returns:

a byte element at index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is negative or is not less than length().

See Also:

array(), length(), setAt(int, byte), resize(int), ensureSize(int)

setAt

public void setAt(int index,
                  byte value)
           throws java.lang.ArrayIndexOutOfBoundsException

Assigns a new value to the element at the specified index. If an exception is thrown then this vector remains unchanged.

Parameters:

index - the index (must be in the range) at which to assign a new value.

value - the value to be assigned.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is negative or is not less than length().

See Also:

setArray(byte[]), array(), length(), getByteAt(int), resize(int), ensureSize(int), copyAt(int, int, int), fill(byte[], int, int, byte)

copyAt

public void copyAt(int srcOffset,
                   int destOffset,
                   int len)
            throws java.lang.ArrayIndexOutOfBoundsException

Copies a region of values at one offset to another offset in this vector. Copying is performed here through arraycopy(Object, int, Object, int, int) method of System class. Negative len is treated as zero. If an exception is thrown then this vector remains unchanged.

Parameters:

srcOffset - the source first index (must be in the range) of the region to be copied.

destOffset - the first index (must be in the range) of the region copy destination.

len - the length of the region to be copied.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (srcOffset is negative or is greater than length() minus len, or destOffset is negative or is greater than length() minus len).

See Also:

array(), length(), setAt(int, byte), getByteAt(int), resize(int), ensureSize(int)

resize

public void resize(int size)

Resizes this vector. The result is the same as of setArray(resize(array(), size)). This method changes the length of this vector to the specified one. Important notes: if size (length) of the vector grows then its new elements are set to zero. If an exception is thrown then this vector remains unchanged.

Parameters:

size - the (unsigned) length of this vector to set.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

ByteVector(int), setArray(byte[]), array(), length(), ensureSize(int), resize(byte[], int)

ensureSize

public void ensureSize(int size)

Ensures the size (capacity) of this vector. The result is the same as of setArray(ensureSize(array(), size)). This method changes (only if size is greater than length()) the length of this vector to a value not less than size. Important notes: if size (length) of the vector grows then its new elements are set to zero. If an exception is thrown then this vector remains unchanged.

Parameters:

size - the (unsigned) length of this vector to be ensured.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

array(), length(), setAt(int, byte), resize(int), ensureSize(byte[], int)

resize

public static final byte[] resize(byte[] array,
                                  int size)
                           throws java.lang.NullPointerException

Resizes a given array. This method 'changes' (creates a new array and copies the content to it) the length of the specified array to the specified one. Important notes: array elements are not changed; if length of array is the same as size then array is returned else array content is copied into the result (all new elements are set to zero).

Parameters:

array - the array (must be non-null) to be resized.

size - the (unsigned) length of the array to set.

Returns:

the resized array (not null, with length equal to size).

Throws:

java.lang.NullPointerException - if array is null.

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

resize(int), ensureSize(byte[], int), fill(byte[], int, int, byte)

ensureSize

public static final byte[] ensureSize(byte[] array,
                                      int size)
                               throws java.lang.NullPointerException

Ensures the length (capacity) of a given array. This method 'grows' (only if size is greater than length of array) the length of array. Important notes: array elements are not changed; if length of array is greater or the same as size then array is returned else array content is copied into the result (all new elements are set to zero).

Parameters:

array - the array (must be non-null) to be length-ensured.

size - the (unsigned) length of the array to ensure.

Returns:

the length-ensured array (not null, with length not less than size).

Throws:

java.lang.NullPointerException - if array is null.

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

ensureSize(int), resize(byte[], int), fill(byte[], int, int, byte)

fill

public static final void fill(byte[] array,
                              int offset,
                              int len,
                              byte value)
                       throws java.lang.NullPointerException,
                              java.lang.ArrayIndexOutOfBoundsException

Fills in the region of a given array with the specified value. All the elements in the specified region of array are set to value. Negative len is treated as zero. If an exception is thrown then array remains unchanged. Else array content is altered. Important notes: region filling is performed using arraycopy(Object, int, Object, int, int) method of System class.

Parameters:

array - the array (must be non-null) to be filled in.

offset - the first index (must be in the range) of the region to fill in.

len - the length of the region to be filled.

value - the value to fill with.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

Since:

2.0

See Also:

array(), copyAt(int, int, int), indexOf(byte[], int, int, int, byte[]), lastIndexOf(byte[], int, int, int, byte[]), toString(byte[], int, int, char, boolean), counterSort(byte[], int, int, boolean), binarySearch(byte[], int, int, byte, boolean)

reverse

public static final void reverse(byte[] array)
                          throws java.lang.NullPointerException

Reverses the elements order in a given array. The first element is exchanged with the least one, the second one is exchanged with the element just before the last one, etc. array content is altered.

Parameters:

array - the array (must be non-null) to be reversed.

Throws:

java.lang.NullPointerException - if array is null.

See Also:

array(), addTo(byte[], byte[]), subtractFrom(byte[], byte[]), countNonZero(byte[]), indexOf(byte, int, byte[]), lastIndexOf(byte, int, byte[]), hashCode(byte[]), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean), mismatches(byte[], int, byte[], int, int)

addTo

public static final void addTo(byte[] arrayA,
                               byte[] arrayB)
                        throws java.lang.NullPointerException

Adds a given vector (array) to another one. Every element of the second array (missing element is treated to be zero) is added to the corresponding element (if not missing) of the first array (overflow is not checked). arrayA content is altered.

Parameters:

arrayA - the first array (must be non-null) to be added to.

arrayB - the second array (must be non-null) to add.

Throws:

java.lang.NullPointerException - if arrayA is null or arrayB is null.

Since:

2.0

See Also:

array(), reverse(byte[]), subtractFrom(byte[], byte[]), multiplyBy(byte[], byte), sumOf(byte[], int, int, boolean), scalarMul(byte[], byte[], boolean), polynome(int, byte[], boolean)

subtractFrom

public static final void subtractFrom(byte[] arrayA,
                                      byte[] arrayB)
                               throws java.lang.NullPointerException

Subtracts a given vector (array) from another one. Every element of the second array (missing element is treated to be zero) is subtracted from the corresponding element (if not missing) of the first array (overflow is not checked). arrayA content is altered.

Parameters:

arrayA - the first array (must be non-null) to be subtracted from.

arrayB - the second array (must be non-null) to subtract.

Throws:

java.lang.NullPointerException - if arrayA is null or arrayB is null.

Since:

2.0

See Also:

array(), reverse(byte[]), addTo(byte[], byte[]), multiplyBy(byte[], byte), sumOf(byte[], int, int, boolean), scalarMul(byte[], byte[], boolean), polynome(int, byte[], boolean)

multiplyBy

public static final void multiplyBy(byte[] array,
                                    byte value)
                             throws java.lang.NullPointerException

Multiplies a given vector (array) by a value. Every element of the specified array is multiplied by value (overflow is not checked). array content is altered.

Parameters:

array - the array (must be non-null) to be multiplied.

value - the value to multiply by.

Throws:

java.lang.NullPointerException - if array is null.

Since:

2.0

See Also:

array(), fill(byte[], int, int, byte), reverse(byte[]), addTo(byte[], byte[]), subtractFrom(byte[], byte[]), sumOf(byte[], int, int, boolean), scalarMul(byte[], byte[], boolean), polynome(int, byte[], boolean), countNonZero(byte[])

scalarMul

public static final int scalarMul(byte[] arrayA,
                                  byte[] arrayB,
                                  boolean isUnsigned)
                           throws java.lang.NullPointerException

Multiplies two given vectors (arrays) in a scalar way. Every element of the first array is multiplied by the corresponding element of the second array (missing element is treated to be zero) and the results of these multiplications are summed together (overflow is not checked).

Parameters:

arrayA - the first array (must be non-null) to multiply.

arrayB - the second array (must be non-null) to multiply.

isUnsigned - true if and only if array elements are (treated as) unsigned.

Returns:

the signed/unsigned multiplication result (int value).

Throws:

java.lang.NullPointerException - if arrayA is null or arrayB is null.

Since:

2.0

See Also:

array(), addTo(byte[], byte[]), subtractFrom(byte[], byte[]), multiplyBy(byte[], byte), sumOf(byte[], int, int, boolean), polynome(int, byte[], boolean), mismatches(byte[], int, byte[], int, int), equals(byte[], byte[])

polynome

public static final int polynome(int intValue,
                                 byte[] array,
                                 boolean isUnsigned)
                          throws java.lang.NullPointerException

Computes the result of substitution of a given int value into the polynome specified by its coefficients. The result is the same as of sum(array[index] * power(intValue, index)). Overflow is not checked. If length of array is zero then 0 is returned.

Parameters:

intValue - the value to be substituted.

array - the array (must be non-null) of the polynome coefficients, arranged by their weight.

isUnsigned - true if and only if array elements are (treated as) unsigned.

Returns:

the signed/unsigned result of the substitution of intValue.

Throws:

java.lang.NullPointerException - if array is null.

Since:

2.0

See Also:

array(), addTo(byte[], byte[]), subtractFrom(byte[], byte[]), multiplyBy(byte[], byte), scalarMul(byte[], byte[], boolean), sumOf(byte[], int, int, boolean), countNonZero(byte[])

sumOf

public static final int sumOf(byte[] array,
                              int offset,
                              int len,
                              boolean isUnsigned)
                       throws java.lang.NullPointerException,
                              java.lang.ArrayIndexOutOfBoundsException

Sums the elements in the region of a given array. The elements in the region are summed as either signed or unsigned values. Negative len is treated as zero. The sum overflow is not checked.

Parameters:

array - the array (must be non-null) which elements to be summed.

offset - the first index (must be in the range) of the region.

len - the length of the region.

isUnsigned - true if and only if array elements are (treated as) unsigned.

Returns:

the signed/unsigned sum (int value) for a given region.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

Since:

2.0

See Also:

array(), fill(byte[], int, int, byte), addTo(byte[], byte[]), subtractFrom(byte[], byte[]), multiplyBy(byte[], byte), countNonZero(byte[]), hashCode(byte[]), mismatches(byte[], int, byte[], int, int), scalarMul(byte[], byte[], boolean), polynome(int, byte[], boolean)

countNonZero

public static final int countNonZero(byte[] array)
                              throws java.lang.NullPointerException

Count non-zero elements in a given array. This method returns the count of elements of array which are not equal to zero.

Parameters:

array - the array (must be non-null) to count non-zero elements in.

Returns:

the count (non-negative and not greater than length of array) of non-zero elements.

Throws:

java.lang.NullPointerException - if array is null.

Since:

2.0

See Also:

array(), fill(byte[], int, int, byte), sumOf(byte[], int, int, boolean), scalarMul(byte[], byte[], boolean), polynome(int, byte[], boolean), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean), mismatches(byte[], int, byte[], int, int)

indexOf

public static final int indexOf(byte value,
                                int index,
                                byte[] array)
                         throws java.lang.NullPointerException

Searches forward for value in a given array. Negative index is treated as zero, too big index is treated as length of array. If value is not found then the result is -1.

Parameters:

value - the value to sequentially search for.

index - the first index, from which to begin forward searching.

array - the array (must be non-null) to be searched in.

Returns:

the index (non-negative) of the found value or -1 (if not found).

Throws:

java.lang.NullPointerException - if array is null.

See Also:

array(), lastIndexOf(byte, int, byte[]), indexOf(byte[], int, int, int, byte[]), binarySearch(byte[], int, int, byte, boolean), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean)

lastIndexOf

public static final int lastIndexOf(byte value,
                                    int index,
                                    byte[] array)
                             throws java.lang.NullPointerException

Searches backward for value in a given array. Negative index is treated as -1, too big index is treated as length of array minus one. If value is not found then the result is -1.

Parameters:

value - the value to sequentially search for.

index - the first index, from which to begin backward searching.

array - the array (must be non-null) to be searched in.

Returns:

the index (non-negative) of the found value or -1 (if not found).

Throws:

java.lang.NullPointerException - if array is null.

See Also:

array(), indexOf(byte, int, byte[]), lastIndexOf(byte[], int, int, int, byte[]), binarySearch(byte[], int, int, byte, boolean), reverse(byte[]), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean)

indexOf

public static final int indexOf(byte[] subArray,
                                int offset,
                                int len,
                                int index,
                                byte[] array)
                         throws java.lang.NullPointerException,
                                java.lang.ArrayIndexOutOfBoundsException

Searches forward for the specified sequence in a given array. The searched sequence of values is specified by subArray, offset and len. Negative len is treated as zero. Negative index is treated as zero, too big index is treated as length of array. If the sequence is not found then the result is -1.

Parameters:

subArray - the array (must be non-null) specifying the sequence of values to search for.

offset - the offset (must be in the range) of the sequence in subArray.

len - the length of the sequence.

index - the first index, from which to begin forward searching.

array - the array (must be non-null) to be searched in.

Returns:

the index (non-negative) of the found sequence or -1 (if not found).

Throws:

java.lang.NullPointerException - if subArray is null or array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of subArray minus len).

See Also:

array(), indexOf(byte, int, byte[]), lastIndexOf(byte[], int, int, int, byte[]), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean)

lastIndexOf

public static final int lastIndexOf(byte[] subArray,
                                    int offset,
                                    int len,
                                    int index,
                                    byte[] array)
                             throws java.lang.NullPointerException,
                                    java.lang.ArrayIndexOutOfBoundsException

Searches backward for the specified sequence in a given array. The searched sequence of values is specified by subArray, offset and len. Negative len is treated as zero. Negative index is treated as -1, too big index is treated as length of array minus one. If the sequence is not found then the result is -1.

Parameters:

subArray - the array (must be non-null) specifying the sequence of values to search for.

offset - the offset (must be in the range) of the sequence in subArray.

len - the length of the sequence.

index - the first index, from which to begin backward searching.

array - the array (must be non-null) to be searched in.

Returns:

the index (non-negative) of the found sequence or -1 (if not found).

Throws:

java.lang.NullPointerException - if subArray is null or array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of subArray minus len).

See Also:

array(), lastIndexOf(byte, int, byte[]), indexOf(byte[], int, int, int, byte[]), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean)

toString

public static final java.lang.String toString(byte[] array,
                                              int offset,
                                              int len,
                                              char separator,
                                              boolean isUnsigned)
                                       throws java.lang.NullPointerException,
                                              java.lang.ArrayIndexOutOfBoundsException

Converts the region of a given array to its 'in-line' string representation. The decimal string representations of signed or unsigned byte values (of the specified region of array) are placed into the resulting string in the direct index order, delimited by a single separator character. Negative len is treated as zero.

Parameters:

array - the array (must be non-null) to be converted.

offset - the first index (must be in the range) of the region to be converted.

len - the length of the region to be converted.

separator - the delimiter character.

isUnsigned - true if and only if array elements are (treated as) unsigned.

Returns:

the string representation (not null) of the specified region.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

array(), toString(), toHexString(byte[], int, int, boolean, char, int, boolean), toBase64String(byte[], int, int), fill(byte[], int, int, byte), counterSort(byte[], int, int, boolean), binarySearch(byte[], int, int, byte, boolean)

toHexString

public static final java.lang.String toHexString(byte[] array,
                                                 int offset,
                                                 int len,
                                                 boolean upperCase,
                                                 char separator,
                                                 int groupLen,
                                                 boolean zeroPadding)
                                          throws java.lang.NullPointerException,
                                                 java.lang.ArrayIndexOutOfBoundsException

Converts the byte-array region into its hexadecimal representation. The hexadecimal string representations of byte values (of the specified region of array) are placed into the resulting string in the direct index order, delimiting each group of bytes by a single separator character (unless groupLen is zero). The length of every group is specified by the absolute value of groupLen. The sign of groupLen specifies the side of group alignment (if non-negative then the last group may contain fewer bytes than the previous ones, else the first group may contain fewer bytes than the next ones). If zeroPadding is false then the insignificant zero digits (which may exist on the right of each group if groupLen is non-negative else on the left) are not placed into the result (but, at least, on digit for each group is put in the resulting string). If groupLen is zero then grouping is not used (this is the same as if groupLen == len). Negative len is treated as zero. The resulting string is 'in-line' (and with non-zero length() if and only if len is positive).

Parameters:

array - the array (must be non-null) to be converted.

offset - the first index (must be in the range) of the region to be converted.

len - the length of the region to be converted.

upperCase - true if and only if digit characters in the result are in the upper case.

separator - the group delimiter character.

groupLen - the byte length of each group (in the absolute value) and the alignment side specifier (if negative then the right-side alignment is used else left-side one).

zeroPadding - true if each group is zero-padded (on the left if right-side alignment is chosen else on the right), that is, zero bytes are not ignored, else padding is not used (but, netherless, if the alignment is on the left then the tail byte (in each group) is yet zero-padded (on the right side), else if the alignment is on the right and the first digit of a group is not decimal then one '0' is appended on its left).

Returns:

the string representation (not null) of the specified region.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

java.lang.OutOfMemoryError - if there is not enough memory.

Since:

1.1

See Also:

toString(), toString(byte[], int, int, char, boolean), toBase64String(byte[], int, int), parseBase64String(java.lang.String, int, int), parseHexString(java.lang.String, int, int, char, boolean, int, boolean)

parseHexString

public static final byte[] parseHexString(java.lang.String str,
                                          int beginIndex,
                                          int endIndex,
                                          char separator,
                                          boolean emptyAsZero,
                                          int groupLen,
                                          boolean padArray)
                                   throws java.lang.NullPointerException,
                                          java.lang.StringIndexOutOfBoundsException,
                                          ParserException

Decodes hexadecimal sequence into a byte array. This is the opposite to toHexString() method. The length of every group is specified by the absolute value of groupLen. The sign of groupLen specifies the side of group alignment. Any found insignificant zero digits (which may exist on the right of each group if groupLen is positive else on the left if groupLen is negative) are ignored. If emptyAsZero is false then all found empty groups are ignored else treated as filled with zeros. If padArray is true then the resulting array is always aligned on the group boundary. If groupLen is zero then grouping is not used and all the found separator characters are simply ignored. If an illegal character (neither a hexadecimal digit nor separator) is found then ParserException is thrown. If length() of str is zero then the resulting array length is zero too.

Parameters:

str - the string (must be non-null), which region to parse.

beginIndex - the string region beginning index (must be in the range), inclusive.

endIndex - the string region ending index (must be in the range), exclusive.

separator - the group delimiter character.

emptyAsZero - true if a particular group contains no digits then it is treated as if it contains zero digits otherwise this group is ignored.

groupLen - the byte length of each group (in the absolute value) and the alignment side specifier (if negative then the right-side alignment is used else left-side one).

padArray - true if the resulting byte array is zero-padded to the group boundary.

Returns:

the bytes (not null array, but may be with zero length) represented by str region.

Throws:

java.lang.NullPointerException - if str is null.

java.lang.StringIndexOutOfBoundsException - if beginIndex is negative, or if endIndex is less than beginIndex or is greater than length() of str.

java.lang.OutOfMemoryError - if there is not enough memory.

ParserException - if str region cannot be decoded (parsed) properly (error is set to 1 or 2 in the exception, meaning an illegal character is found or a group overflow occurs at index, respectively).

Since:

2.0

See Also:

toHexString(byte[], int, int, boolean, char, int, boolean), toBase64String(byte[], int, int), parseBase64String(java.lang.String, int, int)

toBase64String

public static final java.lang.String toBase64String(byte[] array,
                                                    int offset,
                                                    int len)
                                             throws java.lang.NullPointerException,
                                                    java.lang.ArrayIndexOutOfBoundsException

Converts the byte-array region into its 'radix-64' representation. The representation is as follows: every six-bit group of the specified byte array region is converted to a single character from the alphabet of 'A-Za-z0-9+/'; at the end if the region length is not aligned to a six-bit boundary then some '=' characters are added (one for every missing six-bit group). Negative len is treated as zero. The resulting string is 'in-line' and without spaces (and with non-zero length() if and only if len is positive).

Parameters:

array - the array (must be non-null) to be converted.

offset - the first index (must be in the range) of the region to be converted.

len - the length of the region to be converted.

Returns:

the string representation (not null) of the specified region.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toString(), toString(byte[], int, int, char, boolean), toHexString(byte[], int, int, boolean, char, int, boolean), parseBase64String(java.lang.String, int, int), parseHexString(java.lang.String, int, int, char, boolean, int, boolean)

parseBase64String

public static final byte[] parseBase64String(java.lang.String str,
                                             int beginIndex,
                                             int endIndex)
                                      throws java.lang.NullPointerException,
                                             java.lang.StringIndexOutOfBoundsException,
                                             ParserException

Decodes 'radix-64' representation into a byte array. This is the opposite to toBase64String() method. Any found space, tab, new-line, carriage-return and form-feed characters are ignored. Padding character ('=') may be used at any place (not only at the end). If an illegal character (not from 'A-Za-z0-9+/' alphabet) is found then ParserException is thrown. If length() of str is zero then the resulting array length is zero too.

Parameters:

str - the string (must be non-null), which region to parse.

beginIndex - the string region beginning index (must be in the range), inclusive.

endIndex - the string region ending index (must be in the range), exclusive.

Returns:

the bytes (not null array, but may be with zero length) represented by str region.

Throws:

java.lang.NullPointerException - if str is null.

java.lang.StringIndexOutOfBoundsException - if beginIndex is negative, or if endIndex is less than beginIndex or is greater than length() of str.

java.lang.OutOfMemoryError - if there is not enough memory.

ParserException - if str region cannot be decoded (parsed) properly (error is set to 1 in the exception, meaning an illegal character is found at index).

Since:

2.0

See Also:

toBase64String(byte[], int, int), toHexString(byte[], int, int, boolean, char, int, boolean), parseHexString(java.lang.String, int, int, char, boolean, int, boolean)

hashCode

public static final int hashCode(byte[] array)
                          throws java.lang.NullPointerException

Produces a hash code value for a given array. This method mixes all the elements (treated as unsigned) of array to produce a single hash code value.

Parameters:

array - the array (must be non-null) to evaluate hash of.

Returns:

the hash code value for array.

Throws:

java.lang.NullPointerException - if array is null.

See Also:

array(), hashCode(), fill(byte[], int, int, byte), reverse(byte[]), sumOf(byte[], int, int, boolean), countNonZero(byte[]), indexOf(byte, int, byte[]), lastIndexOf(byte, int, byte[]), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean), mismatches(byte[], int, byte[], int, int)

equals

public static final boolean equals(byte[] arrayA,
                                   byte[] arrayB)
                            throws java.lang.NullPointerException

Tests whether or not the specified two arrays are equal. This method returns true if and only if both of the arrays are of the same length and all the elements of the first array are equal to the corresponding elements of the second array.

Parameters:

arrayA - the first array (must be non-null) to be compared.

arrayB - the second array (must be non-null) to compare with.

Returns:

true if and only if arrayA content is the same as arrayB content.

Throws:

java.lang.NullPointerException - if arrayA is null or arrayB is null.

Since:

2.0

See Also:

array(), equals(java.lang.Object), fill(byte[], int, int, byte), reverse(byte[]), subtractFrom(byte[], byte[]), scalarMul(byte[], byte[], boolean), sumOf(byte[], int, int, boolean), indexOf(byte, int, byte[]), lastIndexOf(byte, int, byte[]), indexOf(byte[], int, int, int, byte[]), lastIndexOf(byte[], int, int, int, byte[]), hashCode(byte[]), compare(byte[], int, int, byte[], int, int, boolean), mismatches(byte[], int, byte[], int, int)

mismatches

public static final int mismatches(byte[] arrayA,
                                   int offsetA,
                                   byte[] arrayB,
                                   int offsetB,
                                   int len)
                            throws java.lang.NullPointerException,
                                   java.lang.ArrayIndexOutOfBoundsException

Count the mismatches of two given array regions. This method returns the count of elements of the first array region which are not equal to the corresponding elements of the second array region. Negative len is treated as zero.

Parameters:

arrayA - the first array (must be non-null) to be compared.

offsetA - the first index (must be in the range) of the first region.

arrayB - the second array (must be non-null) to compare with.

offsetB - the first index (must be in the range) of the second region.

len - the length of the regions.

Returns:

the count (non-negative) of found mismatches of the regions.

Throws:

java.lang.NullPointerException - if arrayA is null or arrayB is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offsetA is negative or is greater than length of arrayA minus len, or offsetB is negative or is greater than length of arrayB minus len).

Since:

2.0

See Also:

array(), fill(byte[], int, int, byte), reverse(byte[]), subtractFrom(byte[], byte[]), scalarMul(byte[], byte[], boolean), sumOf(byte[], int, int, boolean), countNonZero(byte[]), hashCode(byte[]), equals(byte[], byte[]), compare(byte[], int, int, byte[], int, int, boolean)

compare

public static final int compare(byte[] arrayA,
                                int offsetA,
                                int lenA,
                                byte[] arrayB,
                                int offsetB,
                                int lenB,
                                boolean isUnsigned)
                         throws java.lang.NullPointerException,
                                java.lang.ArrayIndexOutOfBoundsException

Compares two given array regions. This method returns a signed integer indicating 'less-equal-greater' relation between the specified array regions of signed or unsigned byte values (the absolute value of the result, in fact, is the distance between the first found mismatch and the end of the bigger-length region). Negative lenA is treated as zero. Negative lenB is treated as zero. Important notes: the content of array regions is compared before comparing their length.

Parameters:

arrayA - the first array (must be non-null) to be compared.

offsetA - the first index (must be in the range) of the first region.

lenA - the length of the first region.

arrayB - the second array (must be non-null) to compare with.

offsetB - the first index (must be in the range) of the second region.

lenB - the length of the second region.

isUnsigned - true if and only if array elements are (treated as) unsigned.

Returns:

a negative integer, zero, or a positive integer as arrayA region is less than, equal to, or greater than arrayB one.

Throws:

java.lang.NullPointerException - if arrayA is null or arrayB is null.

java.lang.ArrayIndexOutOfBoundsException - if lenA is positive and (offsetA is negative or is greater than length of arrayA minus lenA), or if lenB is positive and (offsetB is negative or is greater than length of arrayB minus lenB).

See Also:

array(), greaterThan(java.lang.Object), fill(byte[], int, int, byte), reverse(byte[]), scalarMul(byte[], byte[], boolean), polynome(int, byte[], boolean), sumOf(byte[], int, int, boolean), indexOf(byte, int, byte[]), lastIndexOf(byte, int, byte[]), hashCode(byte[]), equals(byte[], byte[]), mismatches(byte[], int, byte[], int, int)

counterSort

public static final void counterSort(byte[] array,
                                     int offset,
                                     int len,
                                     boolean isUnsigned)
                              throws java.lang.NullPointerException,
                                     java.lang.ArrayIndexOutOfBoundsException

Sorts the elements in the region of a given array (by counting the amount of each possible value in it). Elements in the region are sorted into ascending signed or unsigned order. A working (counter) buffer of (BYTE_MASK + 1) integer values is allocated. The algorithm cost is linear. Negative len is treated as zero. If an exception is thrown then array remains unchanged. Else the region content is altered.

Parameters:

array - the array (must be non-null) to be sorted.

offset - the first index (must be in the range) of the region to sort.

len - the length of the region to sort.

isUnsigned - true if and only if array elements are (treated as) unsigned.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

java.lang.OutOfMemoryError - if there is not enough memory.

Since:

2.0

See Also:

array(), binarySearch(byte[], int, int, byte, boolean), fill(byte[], int, int, byte)

binarySearch

public static final int binarySearch(byte[] array,
                                     int offset,
                                     int len,
                                     byte value,
                                     boolean isUnsigned)
                              throws java.lang.NullPointerException,
                                     java.lang.ArrayIndexOutOfBoundsException

Searches (fast) for value in a given sorted array. array (or its specified range) must be sorted ascending, or the result is undefined. The algorithm cost is of O(log(len)). Negative len is treated as zero. If value is not found then (-result - 1) is the offset of the insertion point for value.

Parameters:

array - the sorted array (must be non-null) to be searched in.

offset - the first index (must be in the range) of the region to search in.

len - the length of the region to search in.

value - the value to search for.

isUnsigned - true if and only if value and array elements are (treated as) unsigned.

Returns:

the index (non-negative) of the found value or (-insertionOffset - 1) (a negative integer) if not found.

Throws:

java.lang.NullPointerException - if array is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of array minus len).

See Also:

array(), indexOf(byte, int, byte[]), lastIndexOf(byte, int, byte[]), counterSort(byte[], int, int, boolean), fill(byte[], int, int, byte), toString(byte[], int, int, char, boolean)

clone

public java.lang.Object clone()

Creates and returns a copy of this object. This method creates a new instance of the class of this object and initializes its array with a copy of array of this vector.

Specified by:

clone in interface ReallyCloneable

Overrides:

clone in class java.lang.Object

Returns:

a copy (not null and != this) of this instance.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

ByteVector(), array(), getByteAt(int), equals(java.lang.Object)

hashCode

public int hashCode()

Computes and returns a hash code value for the object. This method mixes all the elements of this vector to produce a single hash code value.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

See Also:

hashCode(byte[]), array(), length(), getByteAt(int), equals(java.lang.Object)

equals

public boolean equals(java.lang.Object obj)

Indicates whether this object is equal to the specified one. This method returns true if and only if obj is instance of this vector class and all elements of this vector are equal to the corresponding elements of obj vector.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object (may be null) with which to compare.

Returns:

true if and only if this value is the same as obj value.

See Also:

ByteVector(), equals(byte[], byte[]), array(), length(), getByteAt(int), hashCode(), greaterThan(java.lang.Object)

greaterThan

public boolean greaterThan(java.lang.Object obj)

Tests for being semantically greater than the argument. The result is true if and only if obj is instance of this class and this object is greater than the specified object. Vectors are compared in the unsigned element-by-element manner, starting at index 0.

Specified by:

greaterThan in interface Sortable

Parameters:

obj - the second compared object (may be null).

Returns:

true if obj is comparable with this and this object is greater than obj, else false.

Since:

2.0

See Also:

compare(byte[], int, int, byte[], int, int, boolean), array(), length(), getByteAt(int), equals(java.lang.Object)

toString

public java.lang.String toString()

Converts this vector to its 'in-line' string representation. The decimal string representations of unsigned byte values of the wrapped array are placed into the resulting string in the direct index order, delimited by a single space.

Overrides:

toString in class java.lang.Object

Returns:

the string representation (not null) of this object.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toString(byte[], int, int, char, boolean), toHexString(byte[], int, int, boolean, char, int, boolean), toBase64String(byte[], int, int), array(), length()

integrityCheck

public void integrityCheck()

Verifies this object for its integrity. For debug purpose only.

Specified by:

integrityCheck in interface Verifiable

Throws:

java.lang.InternalError - if integrity violation is detected.

Since:

2.0

See Also:

ByteVector(byte[]), setArray(byte[]), array()