ptolemy.math

Class IntegerArrayMath

java.lang.Object

ptolemy.math.IntegerArrayMath

public class IntegerArrayMath
extends java.lang.Object

This class provides a library for mathematical operations on int arrays. Unless explicitly noted otherwise, all array arguments are assumed to be non-null. If a null array is passed to a method, a NullPointerException will be thrown in the method or called methods.

Since:

Ptolemy II 1.0

Version:

$Id$

Author:

Albert Chen, William Wu, Edward A. Lee, Jeff Tsay

Pt.AcceptedRating:

Yellow (ctsay)

Pt.ProposedRating:

Yellow (ctsay)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IntegerArrayMath()

Method Summary

Modifier and Type	Method and Description
protected static int	_commonLength(int[] array1, int[] array2, java.lang.String methodName) Throw an exception if the two arrays are not of the same length, or if either array is null.
static int[]	add(int[] array, int z) Return a new array that is the formed by adding z to each element of the input array.
static int[]	add(int[] array1, int[] array2) Return a new array that is the element-by-element sum of the two input arrays.
static int[]	allocCopy(int[] array) Return a new array that is a copy of the array argument.
static int[]	append(int[] array1, int[] array2) Return a new array that is the result of appending array2 to the end of array1.
static int[]	append(int[] array1, int idx1, int length1, int[] array2, int idx2, int length2) Return a new array that is the result of appending length2 elements of array2, starting from the array1[idx2] to length1 elements of array1, starting from array1[idx1].
static int[]	applyBinaryOperation(IntegerBinaryOperation op, int[] array, int z) Return a new array that is formed by applying an instance of a IntegerBinaryOperation to each element in the input array and z, using the array elements as the left operands and z as the right operand in all cases.
static int[]	applyBinaryOperation(IntegerBinaryOperation op, int[] array1, int[] array2) Return a new array that is formed by applying an instance of a IntegerBinaryOperation to the two arrays, element by element, using the elements of the first array as the left operands and the elements of the second array as the right operands.
static int[]	applyBinaryOperation(IntegerBinaryOperation op, int z, int[] array) Return a new array that is formed by applying an instance of a IntegerBinaryOperation to each element in the input array, using z as the left operand in all cases and the array elements as the right operands (op.operate(z, array[i])).
static int[]	applyUnaryOperation(IntegerUnaryOperation op, int[] array) Return a new array that is formed by applying an instance of a IntegerUnaryOperation to each element in the input array (op.operate(array[i])).
static int[]	bitwiseAnd(int[] array, int z) Return a new array that is the formed by bitwise ANDing z with each element of the input array (array[i] & z).
static int[]	bitwiseAnd(int[] array1, int[] array2) Return a new array that is the element-by-element bitwise AND of the two input arrays (array1[i] & array2[i]).
static int[]	bitwiseComplement(int[] array) Return a new array that is the element-by-element bitwise complement of the input array (~array[i]).
static int[]	bitwiseOr(int[] array, int z) Return a new array that is the formed by bitwise ORing z with each element of the input array (array[i] | z).
static int[]	bitwiseOr(int[] array1, int[] array2) Return a new array that is the element-by-element bitwise OR of the two input arrays (array1[i] | array2[i]).
static int[]	bitwiseXor(int[] array, int z) Return a new array that is the formed by bitwise XORing z with each element of the input array (array[i] ^ z).
static int[]	bitwiseXor(int[] array1, int[] array2) Return a new array that is the element-by-element bitwise XOR of the two input arrays (array1[i] ^ array2[i]).
static int[]	divide(int[] array, int z) Return a new array that is the formed by dividing each element of the input array by z (array[i] / z).
static int[]	divideElements(int[] array1, int[] array2) Return a new array that is the element-by-element division of the first array by the second array (array1[i] / array2[i]).
static int	dotProduct(int[] array1, int[] array2) Return the dot product of the two arrays.
static int[]	limit(int[] array, int bottom, int top) Return a new array that is a copy of the argument except that the elements are limited to lie within the specified range.
static int[]	modulo(int[] array, int z) Return a new array that is the formed by the modulo of each element of the input array and z (array[i] % z).
static int[]	modulo(int[] array1, int[] array2) Return a new array that is the element-by-element modulo of the two input arrays (array1[i] % array2[i]).
static int[]	multiply(int[] array, int factor) Return a new array that is constructed from the argument by multiplying each element in the array by the second argument, which is an int.
static int[]	multiply(int[] array1, int[] array2) Return a new array that is the element-by-element multiplication of the two input arrays.
static int[]	negative(int[] array) Return a new array that is the formed by the additive inverse of each element of the input array (-array[i]).
static int[]	padMiddle(int[] array, int newLength) Return a new array of ints that is formed by padding the middle of the array with 0's.
static int[]	resize(int[] array, int newLength) Return a new array of length newLength that is formed by either truncating or padding the input array.
static int[]	resize(int[] array, int newLength, int startIdx) Return a new array of length newLength that is formed by either truncating or padding the input array.
static int[]	scale(int[] array, int scaleFactor) Return a new array of ints produced by scaling the input array elements by scaleFactor.
static int[]	shiftArithmetic(int[] array, int shiftAmount) Return a new array that is constructed from the argument by arithmetically shifting the elements in the array by the second argument.
static int[]	shiftLogical(int[] array, int shiftAmount) Return a new array that is constructed from the argument by logically shifting the elements in the array by the second argument.
static int[]	subtract(int[] array1, int[] array2) Return a new array that is the element-by-element difference of the two input arrays, i.e. the first array minus the second array (array1[i] - array2[i]).
static int	sumOfSquares(int[] array) Return the sum of the squares of all of the elements in the array.
static Complex[]	toComplexArray(int[] array) Return a new array that is formed by converting the integers in the argument array to complex numbers.
static double[]	toDoubleArray(int[] array) Return a new array that is formed by converting the ints in the argument array to doubles.
static float[]	toFloatArray(int[] array) Return a new array that is formed by converting the ints in the argument array to doubles.
static long[]	toLongArray(int[] array) Return a new array that is formed by converting the ints in the argument array to longs.
static java.lang.String	toString(int[] array) Return a new String representing the array, formatted as in Java array initializers.
static java.lang.String	toString(int[] array, java.lang.String elementDelimiter, java.lang.String vectorBegin, java.lang.String vectorEnd) Return a new String representing the array, formatted as specified by the ArrayStringFormat argument.
static boolean	within(int[] array1, int[] array2, int maxError) Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.
static boolean	within(int[] array1, int[] array2, int[] maxError) Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.

Methods inherited from class java.lang.Object

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

Constructor Detail

IntegerArrayMath

protected IntegerArrayMath()

Method Detail

add

public static final int[] add(int[] array,
                              int z)

Return a new array that is the formed by adding z to each element of the input array.

add

public static final int[] add(int[] array1,
                              int[] array2)

Return a new array that is the element-by-element sum of the two input arrays. If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

allocCopy

public static final int[] allocCopy(int[] array)

Return a new array that is a copy of the array argument.

Parameters:

array - An array of ints.

Returns:

A new array of ints.

append

public static final int[] append(int[] array1,
                                 int[] array2)

Return a new array that is the result of appending array2 to the end of array1. This method simply calls append(array1, 0, array1.length, array2, 0, array2.length)

append

public static final int[] append(int[] array1,
                                 int idx1,
                                 int length1,
                                 int[] array2,
                                 int idx2,
                                 int length2)

Return a new array that is the result of appending length2 elements of array2, starting from the array1[idx2] to length1 elements of array1, starting from array1[idx1]. Appending empty arrays is supported. In that case, the corresponding idx may be any number. Allow System.arraycopy() to throw array access exceptions if idx .. idx + length - 1 are not all valid array indices, for both of the arrays.

Parameters:

array1 - The first array of ints.

idx1 - The starting index for array1.

length1 - The number of elements of array1 to use.

array2 - The second array of ints, which is appended.

idx2 - The starting index for array2.

length2 - The number of elements of array2 to append.

Returns:

A new array of ints.

applyBinaryOperation

public static final int[] applyBinaryOperation(IntegerBinaryOperation op,
                                               int[] array,
                                               int z)

Return a new array that is formed by applying an instance of a IntegerBinaryOperation to each element in the input array and z, using the array elements as the left operands and z as the right operand in all cases. (op.operate(array[i], z)). If the length of the array is 0, return a new array of length 0.

applyBinaryOperation

public static final int[] applyBinaryOperation(IntegerBinaryOperation op,
                                               int z,
                                               int[] array)

Return a new array that is formed by applying an instance of a IntegerBinaryOperation to each element in the input array, using z as the left operand in all cases and the array elements as the right operands (op.operate(z, array[i])). If the length of the array is 0, return a new array of length 0.

applyBinaryOperation

public static final int[] applyBinaryOperation(IntegerBinaryOperation op,
                                               int[] array1,
                                               int[] array2)

Return a new array that is formed by applying an instance of a IntegerBinaryOperation to the two arrays, element by element, using the elements of the first array as the left operands and the elements of the second array as the right operands. (op.operate(array[i], array2[i])). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

applyUnaryOperation

public static final int[] applyUnaryOperation(IntegerUnaryOperation op,
                                              int[] array)

Return a new array that is formed by applying an instance of a IntegerUnaryOperation to each element in the input array (op.operate(array[i])). If the length of the array is 0, return a new array of length 0.

bitwiseAnd

public static final int[] bitwiseAnd(int[] array,
                                     int z)

Return a new array that is the formed by bitwise ANDing z with each element of the input array (array[i] & z). If the length of the array is 0, return a new array of length 0.

bitwiseAnd

public static final int[] bitwiseAnd(int[] array1,
                                     int[] array2)

Return a new array that is the element-by-element bitwise AND of the two input arrays (array1[i] & array2[i]). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

bitwiseComplement

public static final int[] bitwiseComplement(int[] array)

Return a new array that is the element-by-element bitwise complement of the input array (~array[i]). If the length of the array is 0, return a new array of length 0.

bitwiseOr

public static final int[] bitwiseOr(int[] array,
                                    int z)

Return a new array that is the formed by bitwise ORing z with each element of the input array (array[i] | z). If the length of the array is 0, return a new array of length 0.

bitwiseOr

public static final int[] bitwiseOr(int[] array1,
                                    int[] array2)

Return a new array that is the element-by-element bitwise OR of the two input arrays (array1[i] | array2[i]). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

bitwiseXor

public static final int[] bitwiseXor(int[] array,
                                     int z)

Return a new array that is the formed by bitwise XORing z with each element of the input array (array[i] ^ z). If the length of the array is 0, return a new array of length 0.

bitwiseXor

public static final int[] bitwiseXor(int[] array1,
                                     int[] array2)

Return a new array that is the element-by-element bitwise XOR of the two input arrays (array1[i] ^ array2[i]). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

divide

public static final int[] divide(int[] array,
                                 int z)

Return a new array that is the formed by dividing each element of the input array by z (array[i] / z). If the length of the array is 0, return a new array of length 0.

divideElements

public static final int[] divideElements(int[] array1,
                                         int[] array2)

Return a new array that is the element-by-element division of the first array by the second array (array1[i] / array2[i]). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

Parameters:

array1 - The first array of ints.

array2 - The second array of ints.

Returns:

A new array of ints.

dotProduct

public static final int dotProduct(int[] array1,
                                   int[] array2)

Return the dot product of the two arrays. If the lengths of the array are both 0, return 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

limit

public static final int[] limit(int[] array,
                                int bottom,
                                int top)

Return a new array that is a copy of the argument except that the elements are limited to lie within the specified range.

If any value is MAX_VALUE or MIN_VALUE, then it is replaced by either the top or the bottom, depending on its sign. To leave either the bottom or the top unconstrained, specify Integer.MIN_VALUE or Integer.MAX_VALUE.

If the length of the array is 0, return a new array of length 0.

Parameters:

array - An array of ints.

bottom - The bottom limit.

top - The top limit.

Returns:

A new array with values in the range [bottom, top].

modulo

public static final int[] modulo(int[] array,
                                 int z)

Return a new array that is the formed by the modulo of each element of the input array and z (array[i] % z).

modulo

public static final int[] modulo(int[] array1,
                                 int[] array2)

Return a new array that is the element-by-element modulo of the two input arrays (array1[i] % array2[i]). If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

multiply

public static final int[] multiply(int[] array1,
                                   int[] array2)

Return a new array that is the element-by-element multiplication of the two input arrays. If the lengths of both arrays are 0, return a new array of length 0. If the two arrays do not have the same length, throw an IllegalArgumentException.

multiply

public static final int[] multiply(int[] array,
                                   int factor)

Return a new array that is constructed from the argument by multiplying each element in the array by the second argument, which is an int. If the sizes of the array is 0, return a new array of size 0.

Parameters:

array - An array of ints.

factor - An int.

Returns:

A new array of ints.

negative

public static final int[] negative(int[] array)

Return a new array that is the formed by the additive inverse of each element of the input array (-array[i]).

padMiddle

public static final int[] padMiddle(int[] array,
                                    int newLength)

Return a new array of ints that is formed by padding the middle of the array with 0's. If either the length of the input array is odd, the sample with index ceil(L/2) will be repeated in the output array, where L is the length of the input array. If the length of the input and output arrays are equal, return a copy of the input array. This method is useful for preparing data for an IFFT.

Parameters:

array - An array of ints.

newLength - The desired length of the returned array.

Returns:

A new array of ints.

resize

public static final int[] resize(int[] array,
                                 int newLength)

Return a new array of length newLength that is formed by either truncating or padding the input array. This method simply calls : resize(array, newLength, 0)

Parameters:

array - An array of ints.

newLength - The desired length of the output array.

Returns:

A new array of ints of length newLength.

resize

public static final int[] resize(int[] array,
                                 int newLength,
                                 int startIdx)

Return a new array of length newLength that is formed by either truncating or padding the input array. Elements from the input array are copied to the output array, starting from array[startIdx] until one of the following conditions is met : 1) The input array has no more elements to copy. 2) The output array has been completely filled. startIdx must index a valid entry in array unless the input array is of zero length or the output array is of zero length. If case 1) is met, the remainder of the output array is filled with zero's, implicitly by Java (padding).

Parameters:

array - An array of ints.

newLength - The desired length of the output array.

startIdx - The starting index for the input array.

Returns:

A new array of ints of length newLength.

scale

public static final int[] scale(int[] array,
                                int scaleFactor)

Return a new array of ints produced by scaling the input array elements by scaleFactor. If the length of the array is 0, return a new array of length 0.

shiftArithmetic

public static final int[] shiftArithmetic(int[] array,
                                          int shiftAmount)

Return a new array that is constructed from the argument by arithmetically shifting the elements in the array by the second argument. If the second argument is positive, the elements are shifted left by the second argument. If the second argument is negative, the elements are shifted right (arithmetically, with the >>> operator) by the absolute value of the second argument. If the second argument is 0, no operation is performed (the array is just copied).

Parameters:

array - A first array of ints.

shiftAmount - The amount to shift by, positive for left shift, negative for right shift.

Returns:

A new array of ints.

shiftLogical

public static final int[] shiftLogical(int[] array,
                                       int shiftAmount)

Return a new array that is constructed from the argument by logically shifting the elements in the array by the second argument. If the second argument is positive, the elements are shifted left by the second argument. If the second argument is negative, the elements are shifted right (logically, with the >>> operator) by the absolute value of the second argument. If the second argument is 0, no operation is performed (the array is just copied).

Parameters:

array - A first array of ints.

shiftAmount - The amount to shift by, positive for left shift, negative for right shift.

Returns:

A new array of ints.

subtract

public static final int[] subtract(int[] array1,
                                   int[] array2)

Return a new array that is the element-by-element difference of the two input arrays, i.e. the first array minus the second array (array1[i] - array2[i]). If the lengths of both arrays are 0, return a new array of length 0.

sumOfSquares

public static final int sumOfSquares(int[] array)

Return the sum of the squares of all of the elements in the array. This is equivalent to the square of the L2-norm of the array. Return 0 if the length of the array is 0.

toComplexArray

public static final Complex[] toComplexArray(int[] array)

Return a new array that is formed by converting the integers in the argument array to complex numbers. Each complex number has real part equal to the value in the argument array and a zero imaginary part.

Parameters:

array - An array of integers.

Returns:

A new array of complex numbers.

toDoubleArray

public static final double[] toDoubleArray(int[] array)

Return a new array that is formed by converting the ints in the argument array to doubles. If the length of the argument array is 0, return a new array of length 0.

Parameters:

array - An array of int.

Returns:

A new array of doubles.

toFloatArray

public static final float[] toFloatArray(int[] array)

Return a new array that is formed by converting the ints in the argument array to doubles. If the length of the argument array is 0, return a new array of length 0.

Parameters:

array - An array of int.

Returns:

A new array of doubles.

toLongArray

public static final long[] toLongArray(int[] array)

Return a new array that is formed by converting the ints in the argument array to longs. If the length of the argument array is 0, return a new array of length 0.

Parameters:

array - An array of int.

Returns:

A new array of longs.

toString

public static final java.lang.String toString(int[] array)

Return a new String representing the array, formatted as in Java array initializers.

toString

public static final java.lang.String toString(int[] array,
                                              java.lang.String elementDelimiter,
                                              java.lang.String vectorBegin,
                                              java.lang.String vectorEnd)

Return a new String representing the array, formatted as specified by the ArrayStringFormat argument. To get a String in the Ptolemy expression language format, call this method with ArrayStringFormat.exprASFormat as the format argument.

within

public static final boolean within(int[] array1,
                                   int[] array2,
                                   int maxError)

Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError. If both arrays are empty, return true. If maxError is negative, return false.

Parameters:

array1 - The first array.

array2 - The second array.

maxError - The threshold for the magnitude of the difference.

Returns:

True if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.

Throws:

java.lang.IllegalArgumentException - If the arrays are not of the same length.

within

public static final boolean within(int[] array1,
                                   int[] array2,
                                   int[] maxError)

Return true if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError. If both arrays are empty, return true. If any element of maxError is negative return false.

Parameters:

array1 - The first array.

array2 - The second array.

maxError - The array of thresholds for the magnitudes of the difference.

Returns:

True if all the distances between corresponding elements array1 and array2 are all less than or equal to the corresponding elements in maxError.

Throws:

java.lang.IllegalArgumentException - If the arrays are not of the same length.

_commonLength

protected static final int _commonLength(int[] array1,
                                         int[] array2,
                                         java.lang.String methodName)

Throw an exception if the two arrays are not of the same length, or if either array is null. An exception is NOT thrown if both arrays are of length 0. If no exception is thrown, return the common length of the arrays.

Parameters:

array1 - The first array of ints.

array2 - The second array of ints.

methodName - A String representing the method name of the caller, without parentheses.

Returns:

The common length of both arrays.