nom.tam.util
Class ArrayFuncs

java.lang.Object
  extended by nom.tam.util.ArrayFuncs
All Implemented Interfaces:
PrimitiveInfo

public class ArrayFuncs
extends java.lang.Object
implements PrimitiveInfo

This is a package of static functions which perform computations on arrays. Generally these routines attempt to complete without throwing errors by ignoring data they cannot understand.


Field Summary
 
Fields inherited from interface nom.tam.util.PrimitiveInfo
BOOLEAN_INDEX, BYTE_INDEX, CHAR_INDEX, classes, DOUBLE_INDEX, FIRST_NUMERIC, FLOAT_INDEX, INT_INDEX, isNumeric, LAST_NUMERIC, LONG_INDEX, SHORT_INDEX, sizes, suffixes, types
 
Constructor Summary
ArrayFuncs()
           
 
Method Summary
static java.lang.String arrayDescription(java.lang.Object o)
          Generate a description of an array (presumed rectangular).
static boolean arrayEquals(java.lang.Object x, java.lang.Object y)
          Are two objects equal? Arrays have the standard object equals method which only returns true if the two object are the same.
static boolean arrayEquals(java.lang.Object x, java.lang.Object y, double tolf, double told)
          Are two objects equal? Arrays have the standard object equals method which only returns true if the two object are the same.
static int computeSize(java.lang.Object o)
          Compute the size of an object.
static java.lang.Object convertArray(java.lang.Object array, java.lang.Class newType)
          Convert an array to a specified type.
static java.lang.Object convertArray(java.lang.Object array, java.lang.Class newType, boolean reuse)
          Convert an array to a specified type.
static void copyArray(java.lang.Object original, java.lang.Object copy)
          Copy one array into another.
static void copyInto(java.lang.Object array, java.lang.Object mimic)
          Copy an array into an array of a different type.
static java.lang.Object curl(java.lang.Object input, int[] dimens)
          Curl an input array up into a multi-dimensional array.
static java.lang.Object deepClone(java.lang.Object o)
          Try to create a deep clone of an Array or a standard clone of a scalar.
protected static int doCurl(java.lang.Object input, java.lang.Object output, int[] dimens, int offset)
          Do the curling of the 1-d to multi-d array.
protected static int doFlatten(java.lang.Object input, java.lang.Object output, int offset)
          This routine does the actually flattening of multi-dimensional arrays.
static void examinePrimitiveArray(java.lang.Object o)
          Examine the structure of an array in detail.
static java.lang.Object flatten(java.lang.Object input)
          Given an array of arbitrary dimensionality return the array flattened into a single dimension.
static java.lang.Object generateArray(java.lang.Class baseType, int[] dims)
          Create an array and populate it with a test pattern.
static java.lang.Object genericClone(java.lang.Object o)
          Clone an Object if possible.
static java.lang.Object getBaseArray(java.lang.Object o)
          This routine returns the base array of a multi-dimensional array.
static java.lang.Class getBaseClass(java.lang.Object o)
          This routine returns the base class of an object.
static int getBaseLength(java.lang.Object o)
          This routine returns the size of the base element of an array.
static int[] getDimensions(java.lang.Object o)
          Find the dimensions of an object.
static java.lang.Object mimicArray(java.lang.Object array, java.lang.Class newType)
          Create an array of a type given by new type with the dimensionality given in array.
static int nElements(java.lang.Object o)
          Count the number of elements in an array
static java.lang.Object newInstance(java.lang.Class cl, int dim)
          Allocate an array dynamically.
static java.lang.Object newInstance(java.lang.Class cl, int[] dims)
          Allocate an array dynamically.
static byte testPattern(java.lang.Object o, byte start)
          Just create a simple pattern cycling through valid byte values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ArrayFuncs

public ArrayFuncs()
Method Detail

computeSize

public static int computeSize(java.lang.Object o)
Compute the size of an object. Note that this only handles arrays or scalars of the primitive objects and Strings. It returns 0 for any object array element it does not understand.

Parameters:
o - The object whose size is desired.

nElements

public static int nElements(java.lang.Object o)
Count the number of elements in an array


deepClone

public static java.lang.Object deepClone(java.lang.Object o)
Try to create a deep clone of an Array or a standard clone of a scalar. The object may comprise arrays of any primitive type or any Object type which implements Cloneable. However, if the Object is some kind of collection, e.g., a Vector then only a shallow copy of that object is made. I.e., deep refers only to arrays.

Parameters:
o - The object to be copied.

genericClone

public static java.lang.Object genericClone(java.lang.Object o)
Clone an Object if possible. This method returns an Object which is a clone of the input object. It checks if the method implements the Cloneable interface and then uses reflection to invoke the clone method. This can't be done directly since as far as the compiler is concerned the clone method for Object is protected and someone could implement Cloneable but leave the clone method protected. The cloning can fail in a variety of ways which are trapped so that it returns null instead. This method will generally create a shallow clone. If you wish a deep copy of an array the method deepClone should be used.

Parameters:
o - The object to be cloned.

copyArray

public static void copyArray(java.lang.Object original,
                             java.lang.Object copy)
Copy one array into another. This function copies the contents of one array into a previously allocated array. The arrays must agree in type and size.

Parameters:
original - The array to be copied.
copy - The array to be copied into. This array must already be fully allocated.

getDimensions

public static int[] getDimensions(java.lang.Object o)
Find the dimensions of an object. This method returns an integer array with the dimensions of the object o which should usually be an array. It returns an array of dimension 0 for scalar objects and it returns -1 for dimension which have not been allocated, e.g., int[][][] x = new int[100][][]; should return [100,-1,-1].

Parameters:
o - The object to get the dimensions of.

getBaseArray

public static java.lang.Object getBaseArray(java.lang.Object o)
This routine returns the base array of a multi-dimensional array. I.e., a one-d array of whatever the array is composed of. Note that arrays are not guaranteed to be rectangular, so this returns o[0][0]....


getBaseClass

public static java.lang.Class getBaseClass(java.lang.Object o)
This routine returns the base class of an object. This is just the class of the object for non-arrays.


getBaseLength

public static int getBaseLength(java.lang.Object o)
This routine returns the size of the base element of an array.

Parameters:
o - The array object whose base length is desired.
Returns:
the size of the object in bytes, 0 if null, or -1 if not a primitive array.

generateArray

public static java.lang.Object generateArray(java.lang.Class baseType,
                                             int[] dims)
Create an array and populate it with a test pattern.

Parameters:
baseType - The base type of the array. This is expected to be a numeric type, but this is not checked.
dims - The desired dimensions.
Returns:
An array object populated with a simple test pattern.

testPattern

public static byte testPattern(java.lang.Object o,
                               byte start)
Just create a simple pattern cycling through valid byte values. We use bytes because they can be cast to any other numeric type.

Parameters:
o - The array in which the test pattern is to be set.
start - The value for the first element.

arrayDescription

public static java.lang.String arrayDescription(java.lang.Object o)
Generate a description of an array (presumed rectangular).

Parameters:
o - The array to be described.

examinePrimitiveArray

public static void examinePrimitiveArray(java.lang.Object o)
Examine the structure of an array in detail.

Parameters:
o - The array to be examined.

flatten

public static java.lang.Object flatten(java.lang.Object input)
Given an array of arbitrary dimensionality return the array flattened into a single dimension.

Parameters:
input - The input array.

doFlatten

protected static int doFlatten(java.lang.Object input,
                               java.lang.Object output,
                               int offset)
This routine does the actually flattening of multi-dimensional arrays.

Parameters:
input - The input array to be flattened.
output - The flattened array.
offset - The current offset within the output array.
Returns:
The number of elements within the array.

curl

public static java.lang.Object curl(java.lang.Object input,
                                    int[] dimens)
Curl an input array up into a multi-dimensional array.

Parameters:
input - The one dimensional array to be curled.
dimens - The desired dimensions
Returns:
The curled array.

doCurl

protected static int doCurl(java.lang.Object input,
                            java.lang.Object output,
                            int[] dimens,
                            int offset)
Do the curling of the 1-d to multi-d array.

Parameters:
input - The 1-d array to be curled.
output - The multi-dimensional array to be filled.
dimens - The desired output dimensions.
offset - The current offset in the input array.
Returns:
The number of elements curled.

mimicArray

public static java.lang.Object mimicArray(java.lang.Object array,
                                          java.lang.Class newType)
Create an array of a type given by new type with the dimensionality given in array.

Parameters:
array - A possibly multidimensional array to be converted.
newType - The desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.type.

convertArray

public static java.lang.Object convertArray(java.lang.Object array,
                                            java.lang.Class newType,
                                            boolean reuse)
Convert an array to a specified type. This method supports conversions only among the primitive numeric types.

Parameters:
array - A possibly multidimensional array to be converted.
newType - The desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.type.
preserve - If set, and the requested type is the same as the original, then the original is returned.

convertArray

public static java.lang.Object convertArray(java.lang.Object array,
                                            java.lang.Class newType)
Convert an array to a specified type. This method supports conversions only among the primitive numeric types.

Parameters:
array - A possibly multidimensional array to be converted.
newType - The desired output type. This should be one of the class descriptors for primitive numeric data, e.g., double.type.

copyInto

public static void copyInto(java.lang.Object array,
                            java.lang.Object mimic)
Copy an array into an array of a different type. The dimensions and dimensionalities of the two arrays should be the same.

Parameters:
array - The original array.
mimic - The array mimicking the original.

newInstance

public static java.lang.Object newInstance(java.lang.Class cl,
                                           int dim)
Allocate an array dynamically. The Array.newInstance method does not throw an error.

Parameters:
cl - The class of the array.
dim - The dimension of the array.
Returns:
The allocated array.
Throws:
An - OutOfMemoryError if insufficient space is available.

newInstance

public static java.lang.Object newInstance(java.lang.Class cl,
                                           int[] dims)
Allocate an array dynamically. The Array.newInstance method does not throw an error.

Parameters:
cl - The class of the array.
dims - The dimensions of the array.
Returns:
The allocated array.
Throws:
An - OutOfMemoryError if insufficient space is available.

arrayEquals

public static boolean arrayEquals(java.lang.Object x,
                                  java.lang.Object y)
Are two objects equal? Arrays have the standard object equals method which only returns true if the two object are the same. This method returns true if every element of the arrays match. The inputs may be of any dimensionality. The dimensionality and dimensions of the arrays must match as well as any elements. If the elements are non-primitive. non-array objects, then the equals method is called for each element. If both elements are multi-dimensional arrays, then the method recurses.


arrayEquals

public static boolean arrayEquals(java.lang.Object x,
                                  java.lang.Object y,
                                  double tolf,
                                  double told)
Are two objects equal? Arrays have the standard object equals method which only returns true if the two object are the same. This method returns true if every element of the arrays match. The inputs may be of any dimensionality. The dimensionality and dimensions of the arrays must match as well as any elements. If the elements are non-primitive. non-array objects, then the equals method is called for each element. If both elements are multi-dimensional arrays, then the method recurses.