ptolemy.math

Class LongArrayMath

java.lang.Object

ptolemy.math.LongArrayMath

public class LongArrayMath
extends java.lang.Object

This class provides a library for mathematical operations on long 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	LongArrayMath()

Method Summary

Modifier and Type	Method and Description
protected static int	_commonLength(long[] array1, long[] 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 long[]	add(long[] array, long z) Return a new array that is the formed by adding z to each element of the input array.
static long[]	add(long[] array1, long[] array2) Return a new array that is the element-by-element sum of the two input arrays.
static long[]	allocCopy(long[] array) Return a new array that is a copy of the array argument.
static long[]	append(long[] array1, int idx1, int length1, long[] 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 long[]	append(long[] array1, long[] array2) Return a new array that is the result of appending array2 to the end of array1.
static long[]	applyBinaryOperation(LongBinaryOperation op, long[] array, long z) Return a new array that is formed by applying an instance of a LongBinaryOperation 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 long[]	applyBinaryOperation(LongBinaryOperation op, long[] array1, long[] array2) Return a new array that is formed by applying an instance of a LongBinaryOperation 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 long[]	applyBinaryOperation(LongBinaryOperation op, long z, long[] array) Return a new array that is formed by applying an instance of a LongBinaryOperation 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 long[]	applyUnaryOperation(LongUnaryOperation op, long[] array) Return a new array that is formed by applying an instance of a LongUnaryOperation to each element in the input array (op.operate(array[i])).
static long[]	bitwiseAnd(long[] array, long z) Return a new array that is the formed by bitwise ANDing z with each element of the input array (array[i] & z).
static long[]	bitwiseAnd(long[] array1, long[] array2) Return a new array that is the element-by-element bitwise AND of the two input arrays (array1[i] & array2[i]).
static long[]	bitwiseComplement(long[] array) Return a new array that is the element-by-element bitwise complement of the input array (~array[i]).
static long[]	bitwiseOr(long[] array, long z) Return a new array that is the formed by bitwise ORing z with each element of the input array (array[i] | z).
static long[]	bitwiseOr(long[] array1, long[] array2) Return a new array that is the element-by-element bitwise OR of the two input arrays (array1[i] | array2[i]).
static long[]	bitwiseXor(long[] array, long z) Return a new array that is the formed by bitwise XORing z with each element of the input array (array[i] ^ z).
static long[]	bitwiseXor(long[] array1, long[] array2) Return a new array that is the element-by-element bitwise XOR of the two input arrays (array1[i] ^ array2[i]).
static long[]	divide(long[] array, long z) Return a new array that is the formed by dividing each element of the input array by z (array[i] / z).
static long[]	divideElements(long[] array1, long[] 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 long	dotProduct(long[] array1, long[] array2) Return the dot product of the two arrays.
static long[]	limit(long[] array, long bottom, long 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 long[]	modulo(long[] array, long 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 long[]	modulo(long[] array1, long[] array2) Return a new array that is the element-by-element modulo of the two input arrays (array1[i] % array2[i]).
static long[]	multiply(long[] array, long factor) Return a new array that is constructed from the argument by multiplying each element in the array by the second argument, which is a long.
static long[]	multiply(long[] array1, long[] array2) Return a new array that is the element-by-element multiplication of the two input arrays.
static long[]	negative(long[] array) Return a new array that is the formed by the additive inverse of each element of the input array (-array[i]).
static long[]	padMiddle(long[] array, int newLength) Return a new array of longs that is formed by padding the middle of the array with 0's.
static long[]	resize(long[] array, int newLength) Return a new array of length newLength that is formed by either truncating or padding the input array.
static long[]	resize(long[] array, int newLength, int startIdx) Return a new array of length newLength that is formed by either truncating or padding the input array.
static long[]	scale(long[] array, long scaleFactor) Return a new array of longs produced by scaling the input array elements by scaleFactor.
static long[]	shiftArithmetic(long[] 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 long[]	shiftLogical(long[] 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 long[]	subtract(long[] array1, long[] 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 long	sumOfSquares(long[] array) Return the sum of the squares of all of the elements in the array.
static Complex[]	toComplexArray(long[] array) Return a new array that is formed by converting the long numbers in the argument array to complex numbers.
static double[]	toDoubleArray(long[] array) Return a new array that is formed by converting the longs in the argument array to doubles.
static float[]	toFloatArray(long[] array) Return a new array that is formed by converting the longs in the argument array to doubles.
static int[]	toIntegerArray(long[] array) Return a new array that is formed by converting the longs in the argument array to integers.
static java.lang.String	toString(long[] array) Return a new String representing the array, formatted as in Java array initializers.
static java.lang.String	toString(long[] 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(long[] array1, long[] array2, long 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(long[] array1, long[] array2, long[] 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

LongArrayMath

protected LongArrayMath()

Method Detail

add

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

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

add

public static final long[] add(long[] array1,
                               long[] 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 long[] allocCopy(long[] 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 long[] append(long[] array1,
                                  long[] 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 long[] append(long[] array1,
                                  int idx1,
                                  int length1,
                                  long[] 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 longs.

idx1 - The starting index for array1.

length1 - The number of elements of array1 to use.

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

idx2 - The starting index for array2.

length2 - The number of elements of array2 to append.

Returns:

A new array of longs.

applyBinaryOperation

public static final long[] applyBinaryOperation(LongBinaryOperation op,
                                                long[] array,
                                                long z)

Return a new array that is formed by applying an instance of a LongBinaryOperation 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 long[] applyBinaryOperation(LongBinaryOperation op,
                                                long z,
                                                long[] array)

Return a new array that is formed by applying an instance of a LongBinaryOperation 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 long[] applyBinaryOperation(LongBinaryOperation op,
                                                long[] array1,
                                                long[] array2)

Return a new array that is formed by applying an instance of a LongBinaryOperation 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 long[] applyUnaryOperation(LongUnaryOperation op,
                                               long[] array)

Return a new array that is formed by applying an instance of a LongUnaryOperation 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 long[] bitwiseAnd(long[] array,
                                      long 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 long[] bitwiseAnd(long[] array1,
                                      long[] 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 long[] bitwiseComplement(long[] 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 long[] bitwiseOr(long[] array,
                                     long 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 long[] bitwiseOr(long[] array1,
                                     long[] 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 long[] bitwiseXor(long[] array,
                                      long 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 long[] bitwiseXor(long[] array1,
                                      long[] 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 long[] divide(long[] array,
                                  long 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 long[] divideElements(long[] array1,
                                          long[] 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 longs.

array2 - The second array of longs.

Returns:

A new array of longs.

dotProduct

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

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

limit

public static final long[] limit(long[] array,
                                 long bottom,
                                 long 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 Long.MIN_VALUE or Long.MAX_VALUE.

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

Parameters:

array - An array of longs.

bottom - The bottom limit.

top - The top limit.

Returns:

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

modulo

public static final long[] modulo(long[] array,
                                  long 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 long[] modulo(long[] array1,
                                  long[] 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 long[] multiply(long[] array1,
                                    long[] 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 long[] multiply(long[] array,
                                    long factor)

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

Parameters:

array - An array of longs.

factor - A long.

Returns:

A new array of longs.

negative

public static final long[] negative(long[] 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 long[] padMiddle(long[] array,
                                     int newLength)

Return a new array of longs 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 longs.

newLength - The desired length of the returned array.

Returns:

A new array of longs.

resize

public static final long[] resize(long[] 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 longs.

newLength - The desired length of the output array.

Returns:

A new array of longs of length newLength.

resize

public static final long[] resize(long[] 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 longs.

newLength - The desired length of the output array.

startIdx - The starting index for the input array.

Returns:

A new array of longs of length newLength.

scale

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

Return a new array of longs 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 long[] shiftArithmetic(long[] 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 longs.

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

Returns:

A new array of longs.

shiftLogical

public static final long[] shiftLogical(long[] 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 longs.

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

Returns:

A new array of longs.

subtract

public static final long[] subtract(long[] array1,
                                    long[] 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 long sumOfSquares(long[] 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 0L if the length of the array is 0.

toComplexArray

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

Return a new array that is formed by converting the long numbers 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 long numbers.

Returns:

A new array of complex numbers.

toDoubleArray

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

Return a new array that is formed by converting the longs 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 long.

Returns:

A new array of doubles.

toFloatArray

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

Return a new array that is formed by converting the longs 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 long.

Returns:

A new array of doubles.

toIntegerArray

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

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

Parameters:

array - An array of long.

Returns:

A new array of integers.

toString

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

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

toString

public static final java.lang.String toString(long[] 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(long[] array1,
                                   long[] array2,
                                   long 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(long[] array1,
                                   long[] array2,
                                   long[] 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(long[] array1,
                                         long[] 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 longs.

array2 - The second array of longs.

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

Returns:

The common length of both arrays.