ewe.util
Class Utils

java.lang.Object
  ewe.util.Utils

public class Utils

extends Object

This class provides a variety of programmer utility functions.

Constructor Summary

Utils()

Method Summary

static Object	appendArray(Object original, Object toAppend) Join two arrays together to form a new array which contains the elements of the first followed by the elements of the second.
static int	compare(Object one, Object two) This attempts to compare two objects which may or may not implement the Comparable interface.
static void	copy(Object source, Object dest) This copies data from the source to the destination.
static void	copyField(String field, Object source, Object dest, Reflect theClass) This copies one field from the source object to the destination object using the provided Reflect Object as the class specifier.
static String	decodeJavaUtf8String(byte[] bytes, int start, int length) Decode a String encoded as Java Utf8 bytes.
static char[]	decodeJavaUtf8String(byte[] data, int start, int numberOfBytes, char[] chars, int offset) Convert a Java Utf8 byte encoded string into a string of characters.
static int	encodeJavaUtf8String(char[] toEncode, int offset, int length, byte[] destination, int destOffset) Encode a String of characters a Java Utf8 encoded bytes.
static byte[]	encodeJavaUtf8String(String str) Encodes a String as Java Utf8 bytes.
static String	fileLengthDisplay(int len)
static int	findCRLF(byte[] data, int start, int length) Find the index of a CRLF sequence or LF character in byte data.
static Object	getCopy(Object toCopy) This attempts to get a copy of an object.
static void	getIntSequence(int[] sequence, int first) This fills the int array with an increasing sequence of integers starting with first.
static void	getIntSequence(int[] sequence, int destOffset, int first, int step, int length) This puts a sequence of integers into a int array.
static int	indexOf(Object array, long lookingFor, int minIndex, int maxIndex, boolean backwards) Find the index of a value within an array.
static int	makeHashCode(byte[] data, int start, int length) Creates a hashCode from a sequence of bytes.
static int	makeHashCode(char[] data, int start, int length) Creates a hashCode from a sequence of chars.
protected static boolean	merge(Handle h, int[] source, int sourceLength, int one, int two, int length, int[] dest, boolean descending, CompareInts comparer)
static void	primitiveArrayFromString(Object obj, String data) Decode an array of primitive values, encoded as a String.
static String	primitiveArrayToString(Object obj) Encode the array of primitive Java values as a String.
static int	readInt(byte[] source, int offset, int numBytes) This reads an integer value from a byte array with the specified number of bytes.
static long	readLong(byte[] source, int offset) This reads a long value from a byte array as an 8 byte sequence - high byte first.
static int	sizeofJavaUtf8String(byte[] data, int start, int numberOfBytes) Returns the number of characters needed to store a string which has been encoded in the Java UTF8 format.
static int	sizeofJavaUtf8String(char[] toEncode, int start, int length) Returns the number of bytes needed to encode a String in the Java UTF8 format.
static boolean	sort(Handle h, int[] what, int length, CompareInts comparer, boolean descending) This sorts the array in place.
static boolean	sort(Handle h, Object[] values, Comparer comparer, boolean descending) This sorts the objects in place.
static void	sort(int[] values, int length, CompareInts comparer, boolean descending) This sorts a set of integers in place using the provided CompareInts object.
static void	sort(Object[] values, Comparer comparer, boolean descending) This sorts the objects in place.
static Object	subArray(Object original, int start, int length) Get a sub-array containing a set of elements from an existing array.
static void	textDecode(Encodable obj, String data) Encode the fields of the Encodable object.
static String	textEncode(Encodable obj) Encode the fields of the Encodable object.
static void	writeInt(int val, byte[] dest, int offset, int numBytes) This writes an integer value to a byte array with the specified number of bytes.
static void	writeLong(long value, byte[] dest, int offset) This writes a long value to a byte array as an 8 byte sequence - high byte first.
static void	zeroArrayRegion(Object array, int offset, int length)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Constructor Detail

Utils

public Utils()

Method Detail

compare

public static int compare(Object one,
                          Object two)

This attempts to compare two objects which may or may not implement the Comparable interface. If they do, then it is used, otherwise the equals method is used.

Parameters:

one - The first object.

two - The second object

Returns:

less than 1 if one is considered less than two, greater than 1 if one is considered greater than two, 0 if they are considered equal.

getCopy

public static Object getCopy(Object toCopy)

This attempts to get a copy of an object. If the object implements Copyable then a copy of that object is returned, otherwise the object itself is returned.

Parameters:

toCopy - The object to copy.

copyField

public static void copyField(String field,
                             Object source,
                             Object dest,
                             Reflect theClass)

This copies one field from the source object to the destination object using the provided Reflect Object as the class specifier. If the field value being copied implements the Copyable interface, then getCopy() is called on the Object and the copy is assigned to the destination field. Otherwise the destination field is made equal to the source field.

In order for this to work the Class AND the Field must be public.

Parameters:

field - The field name.

source - The source object.

dest - The destination object.

theClass - A Reflect object representing the exact class which is having its field copied.

copy

public static void copy(Object source,
                        Object dest)

This copies data from the source to the destination. Copying is done as follows. The class of the source is determined using the Reflection API. If that class DECLARES a "_fields" String variable (which must be public to work under Java) then a copyField() is done on each of the fields listed in the "_fields" variable. The value of this variable should be a comma separated list of fields. This process is repeated for each successive superclass of the source object.

getIntSequence

public static void getIntSequence(int[] sequence,
                                  int destOffset,
                                  int first,
                                  int step,
                                  int length)

This puts a sequence of integers into a int array.

Parameters:

sequence - The destination for the integers.

destOffset - The index in the destination to start placing the values.

first - The first value.

step - The value to add to each value to get the next value.

length - The number of values to place.

getIntSequence

public static void getIntSequence(int[] sequence,
                                  int first)

This fills the int array with an increasing sequence of integers starting with first. This calls: getIntSequence(sequence,0,first,1,sequence.length);

sort

public static void sort(int[] values,
                        int length,
                        CompareInts comparer,
                        boolean descending)

This sorts a set of integers in place using the provided CompareInts object.

Parameters:

values - the sequence of integers to sort.

length - The length of the sequence.

comparer - This compares two integer values together. Note that this does not imply a numerical comparison. The integers may represent indexes into an object array or they may represent locations for data in a file. Therefore comparing the two integers may involve comparing the data they refer to rather than their numeric values.

descending - Set this true if you want to sort in descending order. Note that this is a blocking call - while this sort is going on all other threads are stopped.

merge

protected static boolean merge(Handle h,
                               int[] source,
                               int sourceLength,
                               int one,
                               int two,
                               int length,
                               int[] dest,
                               boolean descending,
                               CompareInts comparer)

sort

public static boolean sort(Handle h,
                           int[] what,
                           int length,
                           CompareInts comparer,
                           boolean descending)

This sorts the array in place. If the handle is not null then the sort will yield occasionally to let other threads operate. The handle will be updated to show the progress but the handle Handle.Stopped bit will never be set. If this returns false this indicates that stop() was called on the handle.

sort

public static boolean sort(Handle h,
                           Object[] values,
                           Comparer comparer,
                           boolean descending)

This sorts the objects in place. If the handle is not null then the sort will yield occasionally to let other threads operate. The handle will be updated to show the progress but the handle Handle.Stopped bit will never be set.

sort

public static void sort(Object[] values,
                        Comparer comparer,
                        boolean descending)

This sorts the objects in place. If the Comparer is null then it is assumed that all of the objects implements Comparable and so are able to compare themselves.

Parameters:

values - The Object values to sort.

comparer - An object that will compare the Objects.

descending - Set this true if you want to sort in descending order. Note that this is a blocking call - while this sort is going on all other threads are stopped.

writeInt

public static final void writeInt(int val,
                                  byte[] dest,
                                  int offset,
                                  int numBytes)

This writes an integer value to a byte array with the specified number of bytes. It always writes out the high byte first.

Parameters:

val - The byte, short or integer value to write.

dest - The destination array.

offset - The location in the destination to write to.

numBytes - The number of bytes 1, 2 or 4 to write out.

readInt

public static final int readInt(byte[] source,
                                int offset,
                                int numBytes)

This reads an integer value from a byte array with the specified number of bytes. It always reads in the high byte first.

Parameters:

source - The source of the bytes.

offset - The location in the source.

numBytes - The number of bytes 1, 2 or 4 to read in.

Returns:

the integer value read in.

readLong

public static final long readLong(byte[] source,
                                  int offset)

This reads a long value from a byte array as an 8 byte sequence - high byte first.

Parameters:

source - The source of the bytes.

offset - The location in the source.

Returns:

The long value read in.

writeLong

public static final void writeLong(long value,
                                   byte[] dest,
                                   int offset)

This writes a long value to a byte array as an 8 byte sequence - high byte first.

Parameters:

value - The long value to write.

dest - The destination for the bytes.

offset - The location in the destination to write to.

sizeofJavaUtf8String

public static final int sizeofJavaUtf8String(byte[] data,
                                             int start,
                                             int numberOfBytes)

Returns the number of characters needed to store a string which has been encoded in the Java UTF8 format.

Parameters:

data - the encoded data.

start - the start location in the data.

numberOfBytes - the number of bytes of encoded data.

Returns:

the number of characters for the String.

sizeofJavaUtf8String

public static final int sizeofJavaUtf8String(char[] toEncode,
                                             int start,
                                             int length)

Returns the number of bytes needed to encode a String in the Java UTF8 format.

Parameters:

toEncode - The characters to encode.

start - The start index of the character.

length - The number of characters to encode.

Returns:

the number of bytes needed to encode a String in the Java UTF8 format.

decodeJavaUtf8String

public static final char[] decodeJavaUtf8String(byte[] data,
                                                int start,
                                                int numberOfBytes,
                                                char[] chars,
                                                int offset)

Convert a Java Utf8 byte encoded string into a string of characters.

Parameters:

data - The encoded data bytes.

start - The start index of the data bytes.

numberOfBytes - The number of bytes of encoded data.

chars - The destination array.

offset - The start index of the destination to place the characters.

Returns:

The destination array.

encodeJavaUtf8String

public static int encodeJavaUtf8String(char[] toEncode,
                                       int offset,
                                       int length,
                                       byte[] destination,
                                       int destOffset)

Encode a String of characters a Java Utf8 encoded bytes.

Parameters:

toEncode - The characters to encode.

offset - The start index of the character.

length - The number of characters to encode.

destination - The destination for the bytes.

destOffset - The offset for the destination bytes

Returns:

the number of bytes used to encode the String.

encodeJavaUtf8String

public static byte[] encodeJavaUtf8String(String str)

Encodes a String as Java Utf8 bytes.

Parameters:

str - the String to encode.

Returns:

the encoded bytes.

decodeJavaUtf8String

public static String decodeJavaUtf8String(byte[] bytes,
                                          int start,
                                          int length)

Decode a String encoded as Java Utf8 bytes.

Parameters:

bytes - The encoded bytes.

start - The start index of the encoded bytes.

length - The number of encoded bytes.

Returns:

The decoded String.

primitiveArrayToString

public static String primitiveArrayToString(Object obj)

Encode the array of primitive Java values as a String. The length of the array is not encoded along with this data, nor is the type of the data. You will have to store these yourself.

See the TextEncoder/TextDecoder objects for how to do this.

Parameters:

obj - An array of any Java type except Object or array.

Returns:

The String encoded data.

primitiveArrayFromString

public static void primitiveArrayFromString(Object obj,
                                            String data)

Decode an array of primitive values, encoded as a String.

Parameters:

obj - The array of the correct type and length.

data - The encoded data.

indexOf

public static int indexOf(Object array,
                          long lookingFor,
                          int minIndex,
                          int maxIndex,
                          boolean backwards)

Find the index of a value within an array. The value should be converted to an appropriate integer/long value and passed to the method. The type of the array will determine the how the lookingFor value will be used.

Searching is done within the range of index from minIndex up to maxIndex-1. If backwards is true searching goes from maxIndex-1 to minIndex (inclusive). Otherwise searching goes from minIndex to maxIndex-1. A return value of -1 indicates that the value was not found.

findCRLF

public static int findCRLF(byte[] data,
                           int start,
                           int length)

Find the index of a CRLF sequence or LF character in byte data.

Parameters:

data - The byte data.

start - The start index of the data.

length - The number of data bytes.

Returns:

the index of the CRLF sequence or LF character.

makeHashCode

public static int makeHashCode(byte[] data,
                               int start,
                               int length)

Creates a hashCode from a sequence of bytes.

makeHashCode

public static int makeHashCode(char[] data,
                               int start,
                               int length)

Creates a hashCode from a sequence of chars.

textEncode

public static String textEncode(Encodable obj)

Encode the fields of the Encodable object.

Parameters:

obj - The object to encode.

Returns:

A simple encoded string for the object.

textDecode

public static void textDecode(Encodable obj,
                              String data)

Encode the fields of the Encodable object.

Parameters:

obj - The object to encode.

Returns:

A simple encoded string for the object.

subArray

public static Object subArray(Object original,
                              int start,
                              int length)

Get a sub-array containing a set of elements from an existing array.

Parameters:

original - The original array.

start - The first element to copy.

length - The number of elements to copy.

Returns:

a new array containing the selected elements.

appendArray

public static Object appendArray(Object original,
                                 Object toAppend)

Join two arrays together to form a new array which contains the elements of the first followed by the elements of the second.

Parameters:

original - The first array. Can be null, in which case only the elements of toAdd will go into the new array.

toAppend - The second array. Can be null, in which case only the elements of original will go into the new array.

Returns:

a new array representing original + toAppend. If both original and toAppend are null, this will return null.

zeroArrayRegion

public static void zeroArrayRegion(Object array,
                                   int offset,
                                   int length)

fileLengthDisplay

public static String fileLengthDisplay(int len)