TOC PREV

Appendix A. Tables of Functions

In this appendix, we tabulate the functions available in the expression language. Further explanation of many of these functions is given in section section 3.7 above.
A.1 Trigonometric Functions
TABLE 4: Trigonometric functions.
function argument type(s) return type description
acos double in the range[-1.0, 1.0] or complex double in the range[0.0, pi] or NaN if out of range or complex arc cosine complex case:
asin double in the range[-1.0, 1.0] or complex double in the range[-pi/2, pi/2] or NaN if out of range or complex arc sine complex case:
atan double or complex double in the range [-pi/2, pi/2] or complex arc tangent complex case:
atan2 double, double double in the range [-pi, pi] angle of a vector (note: the arguments are (y, x), not (x, y) as one might expect).
acosh double greater than 1 or complex double or complex hyperbolic arc cosine, defined for both double and complex case by:
asinh double or complex double or complex hyperbolic arc sine complex case:
cos double or complex double in the range , or complex cosine complex case:
cosh double or complex double or complex hyperbolic cosine, defined for double or complex by:
sin double or complex double or complex sine function complex case:
sinh double or complex double or complex hyperbolic sine, defined for double or complex by:
tan double or complex double or complex tangent function, defined for double or complex by:
tanh double or complex double or complex hyperbolic tangent, defined for double or complex by:

A.2 Basic Mathematical Functions
TABLE 5: Basic mathematical functions
function argument type(s) return type description
abs double or int or long or complex double or int or long (complex returns double) absolute value complex case:
angle complex double in the range [-pi, pi] angle or argument of the complex number:
ceil double double ceiling function, which returns the smallest (closest to negative infinity) double value that is not less than the argument and is an integer.
compare double, double int compare two numbers, returning -1, 0, or 1 if the first argument is less than, equal to, or greater than the second.
conjugate complex complex complex conjugate
exp double or complex double in the range[0.0, infinity] or complex exponential function (e^argument) complex case:
floor double double floor function, which is the largest (closest to positive infinity) value not greater than the argument that is an integer.
gaussian double, double or double, double, int, or double, double, int, int double or {double} or [double] one or more Gaussian random variables with the specified mean and standard deviation (see page 112).
imag complex double imaginary part
isInfinite double boolean return true if the argument is infinite
isNaN double boolean return true if the argument is "not a number"
log double or complex double or complex natural logarithm complex case:
log10 double double log base 10
log2 double double log base 2
max double, double or int, int or long, long or unsignedByte, unsignedByte or {double} or {int} or {long} or {unsignedByte} double or int or long or unsignedByte maximum
min double, double or int, int or long, long or unsignedByte, unsignedByte or {double} or {int} or {long} or {unsignedByte} double or int or long or unsignedByte minimum
neighborhood type, type, double boolean return true if the first argument is in the neighborhood of the second, meaning that the distance is less than or equal to the third argument. The first two arguments can be any type for which such a distance is defined. For composite types, arrays, records, and matrices, then return true if the first two arguments have the same structure, and each corresponding element is in the neighborhood.
pow double, double or complex, complex double or complex first argument to the power of the second
random no arguments or int or int, int double or {double} or [double] one or more random numbers between 0.0 and 1.0 (see page 112)
real complex double real part
remainder double, double double remainder after division, according to the IEEE 754 floating-point standard (see page 113).
round double long round to the nearest long, choosing the next greater integer when exactly in between, and throwing an exception if out of range. If the argument is NaN, the result is 0L. If the argument is out of range, the result is either MaxLong or MinLong, depending on the sign.
roundToInt double int round to the nearest int, choosing the next greater integer when exactly in between, and throwing an exception if out of range. If the argument is NaN, the result is 0. If the argument is out of range, the result is either MaxInt or MinInt, depending on the sign.
sgn double int -1 if the argument is negative, 1 otherwise
sqrt double or complex double or complex square root. If the argument is double with value less than zero, then the result is NaN. complex case:
toDegrees double double convert radians to degrees
toRadians double double convert degrees to radians

A.3 Matrix, Array, and Record Functions.
TABLE 6: Functions that take or return matrices, arrays, or records.
function argument type(s) return type description
arrayToMatrix {type}, int, int [type] Create a matrix from the specified array with the specified number of rows and columns
concatenate {type}, {type} {type} Concatenate two arrays.
concatenate {{type}} {type} Concatenate arrays in an array of arrays.
conjugateTranspose [complex] [complex] Return the conjugate transpose of the specified matrix.
createSequence type, type, int {type} Create an array with values starting with the first argument, incremented by the second argument, of length given by the third argument.
crop [int], int, int, int, int or [double], int, int, int, int or [complex], int, int, int, int or [long], int, int, int, int or [int] or [double] or [complex] or [long] or Given a matrix of any type, return a submatrix starting at the specified row and column with the specified number of rows and columns.
determinant [double] or [complex] double or complex Return the determinant of the specified matrix.
diag {type} [type] Return a diagonal matrix with the values along the diagonal given by the specified array.
divideElements [type], [type] [type] Return the element-by-element division of two matrices
emptyArray type {type} Return an empty array whose element type matches the specified token.
find {type}, type {int} Return an array of the indices where elements of the specified array match the specified token.
find {boolean} {int} Return an array of the indices where elements of the specified array have value true.
hilbert int [double] Return a square Hilbert matrix, where . A Hilbert matrix is nearly, but not quite singular.
identityMatrixComplex int [complex] Return an identity matrix with the specified dimension.
identityMatrixDouble int [double] Return an identity matrix with the specified dimension.
identityMatrixInt int [int] Return an identity matrix with the specified dimension.
identityMatrixLong int [long] Return an identity matrix with the specified dimension.
intersect record, record record Return a record that contains only fields that are present in both arguments, where the value of the field is taken from the first record.
inverse [double] or [complex] [double] or [complex] Return the inverse of the specified matrix, or throw an exception if it is singular.
matrixToArray [type] {type} Create an array containing the values in the matrix
merge record, record record Merge two records, giving priority to the first one when they have matching record labels.
multiplyElements [type], [type] [type] Multiply element wise the two specified matrices.
orthogonalizeColumns [double] or [complex] [double] or [complex] Return a similar matrix with orthogonal columns.
orthogonalizeRows [double] or [complex] [double] or [complex] Return a similar matrix with orthogonal rows.
orthonormalizeColumns [double] or [complex] [double] or [complex] Return a similar matrix with orthonormal columns.
orthonormalizeRows [double] or [complex] [double] or [complex] Return a similar matrix with orthonormal rows.
repeat int, type {type} Create an array by repeating the specified token the specified number of times.
sort {string}or {realScalar} {string} or {realScalar} Return the specified array, but sorted in ascending order. realScalar is any scalar token except complex.
sortAscending {string}or {realScalar} {string} or {realScalar} Return the specified array, but sorted in ascending order. realScalar is any scalar token except complex.
sortDescending {string}or {realScalar} {string} or {realScalar} Return the specified array, but sorted in descending order. realScalar is any scalar token except complex.
subarray {type}, int, int {type} Extract a subarray starting at the specified index with the specified length.
sum {type} or [type] type Sum the elements of the specified array or matrix. This throws an exception if the elements do not support addition or if the array is empty (an empty matrix will return zero).
trace [type] type Return the trace of the specified matrix.
transpose [type] [type] Return the transpose of the specified matrix.
zeroMatrixComplex int, int [complex] Return a zero matrix with the specified number of rows and columns.
zeroMatrixDouble int, int [double] Return a zero matrix with the specified number of rows and columns.
zeroMatrixInt int, int [int] Return a zero matrix with the specified number of rows and columns.
zeroMatrixLong int, int [long] Return a zero matrix with the specified number of rows and columns.

A.4 Functions for Evaluating Expressions

TABLE 7: Utility functions for evaluating expressions
function argument type(s) return type description
eval string any type evaluate the specified expression (see page 112).
parseInt string or string, int int return an int read from a string, using the given radix if a second argument is provided.
parseLong string or string, int int return a long read from a string, using the given radix if a second argument is provided.
toBinaryString int or long string return a binary representation of the argument
toOctalString int or long string return an octal representation of the argument
toString double or int or int, int or long or long, int string return a string representation of the argument, using the given radix if a second argument is provided.
traceEvaluation string string evaluate the specified expression and report details on how it was evaluated (see page 112).

A.5 Signal Processing Functions
TABLE 8: Functions performing signal processing operations
function argument type(s) return type description
convolve {double}, {double} or {complex}, {complex} {double} or {complex} Convolve two arrays and return an array whose length is sum of the lengths of the two arguments minus one. Convolution of two arrays is the same as polynomial multiplication.
DCT {double} or {double}, int or {double}, int, int {double} Return the discrete cosine transform of the specified array, using the specified (optional) length and normalization strategy (see page 113).
downsample {double}, int or {double}, int, int {double} Return a new array with every -th element of the argument array, where is the second argument. If a third argument is given, then it must be between 0 and , and it specifies an offset into the array (by giving the index of the first output).
FFT {double} or {complex} or {double}, int {complex}, int {complex} Return the fast Fourier transform of the specified array. If the second argument is given with value , then the length of the transform is . Otherwise, the length is the next power of two greater than or equal to the length of the input array. If the input length does not match this length, then input is padded with zeros.
generateBartlettWindow int {double} Return a Bartlett (rectangular) window with the specified length. The end points have value 0.0, and if the length is odd, the center point has value 1.0. For length M + 1, the formula is:
generateBlackmanWindow int {double} Return a Blackman window with the specified length. For length M + 1, the formula is:
generateBlackmanHarrisWindow int {double} Return a Blackman-Harris window with the specified length. For length M + 1, the formula is:
generateGaussianCurve double, double, int {double} Return a Gaussian curve with the specified standard deviation, extent, and length. The extent is a multiple of the standard deviation. For instance, to get 100 samples of a Gaussian curve with standard deviation 1.0 out to four standard deviations, use generateGaussianCurve(1.0, 4.0, 100).
generateHammingWindow int {double} Return a Hamming window with the specified length. For length M + 1, the formula is:
generateHanningWindow int {double} Return a Hanning window with the specified length. For length M + 1, the formula is:
generatePolynomialCurve {double}, double, double, int {double} Return samples of a curve specified by a polynomial. The first argument is an array with the polynomial coefficients, beginning with the constant term, the linear term, the squared term, etc. The second argument is the value of the polynomial variable at which to begin, and the third argument is the increment on this variable for each successive sample. The final argument is the length of the returned array.
generateRaisedCosinePulse double, double, int {double} Return an array containing a symmetric raised-cosine pulse. This pulse is widely used in communication systems, and is called a "raised cosine pulse" because the magnitude its Fourier transform has a shape that ranges from rectangular (if the excess bandwidth is zero) to a cosine curved that has been raised to be non-negative (for excess bandwidth of 1.0). The elements of the returned array are samples of the function:
,
where x is the excess bandwidth (the first argument) and T is the number of samples from the center of the pulse to the first zero crossing (the second argument). The samples are taken with a sampling interval of 1.0, and the returned array is symmetric and has a length equal to the third argument. With an excessBandwidth of 0.0, this pulse is a sinc pulse.
generateRectangularWindow int {double} Return an array filled with 1.0 of the specified length. This is a rectangular window.
IDCT {double} or {double}, int or {double}, int, int {double} Return the inverse discrete cosine transform of the specified array, using the specified (optional) length and normalization strategy (see page 113).
IFFT {double} or {complex} or {double}, int {complex}, int {complex} Return the inverse fast Fourier transform of the specified array. If the second argument is given with value , then the length of the transform is . Otherwise, the length is the next power of two greater than or equal to the length of the input array. If the input length does not match this length, then input is padded with zeros.
nextPowerOfTwo double int Return the next power of two larger than or equal to the argument.
poleZeroToFrequency {complex}, {complex}, complex, int {complex} Given an array of pole locations, an array of zero locations, a gain term, and a size, return an array of the specified size representing the frequency response specified by these poles, zeros, and gain. This is calculated by walking around the unit circle and forming the product of the distances to the zeros, dividing by the product of the distances to the poles, and multiplying by the gain.
sinc double double Return the sinc function, , where special care is taken to ensure that 1.0 is returned if the argument is 0.0.
toDecibels double double Return , where is the argument.
unwrap {double} {double} Modify the specified array to unwrap the angles. That is, if the difference between successive values is greater than in magnitude, then the second value is modified by multiples of until the difference is less than or equal to . In addition, the first element is modified so that its difference from zero is less than or equal to in magnitude.
upsample {double}, int {double} Return a new array that is the result of inserting zeroes between each successive sample in the input array, where is the second argument. The returned array has length , where L is the length of the argument array. It is required that .

A.6 I/O Functions and Other Miscellaneous Functions
TABLE 9: Miscellaneous functions.
function argument type(s) return type description
asURL string string Return a URL representation of the argument.
cast type1, type2 type1 Return the second argument converted to the type of the first, or throw an exception if the conversion is invalid.
constants none record Return a record identifying all the globally defined constants in the expression language.
findFile string string Given a file name relative to the user directory, current directory, or classpath, return the absolute file name of the first match, or return the name unchanged if no match is found.
filter function, {type} {type} Extract a sub-array consisting of all of the elements of an array for which the given predicate function returns true.
filter function, {type}, int {type} Extract a sub-array with a limited size consisting of all of the elements of an array for which the given predicate function returns true.
freeMemory none long Return the approximate number of bytes available for future memory allocation.
iterate function, int, type {type} Return an array that results from first applying the specified function to the third argument, then applying it to the result of that application, and repeating to get an array whose length is given by the second argument.
map function, {type} {type} Return an array that results from applying the specified function to the elements of the specified array.
property string string Return a system property with the specified name from the environment, or an empty string if there is none. Some useful properties are java.version, ptolemy.ptII.dir, ptolemy.ptII.dirAsURL, and user.dir.
readFile string string Get the string text in the specified file, or throw an exception if the file cannot be found. The file can be absolute, or relative to the current working directory (user.dir), the user's home directory (user.home), or the classpath.
readResource string string Get the string text in the specified resource (which is a file found relative to the classpath), or throw an exception if the file cannot be found.
totalMemory none long Return the approximate number of bytes used by current objects plus those available for future object allocation.

TOC PREV