Programmer Guide/Command Reference/EVAL

Introduction

The EVAL command can be used to evaluate numerical expressions. These expressions may be built up from numerical constants, from scalar, vector, and matrix variables, and from a large number of functions and operators.

Syntax

An EVAL command uses the following general syntax:

result := eval expression

or

result := evalcheck expression

result

This is the target to be assigned with the result of the evaluation of the numerical expression. The result can be a shell variable, a Programmer_Guide/Shell_Items or a numerical object

expression

The numerical expression to be evaluated. The expression consists of numerical objects, functions and operators.

Examples:

• result := eval (5 * 10) % 3
• result := eval init(10,1,1)
• result := eval 5+max(fill(6,1,1))

If the expression is syntactically ill-formed an error (EVAL) or warning (EVALCHECK) is reported and the assignment is not performed (content of result is not changed). See the example script expression_check.sts for details.

Numerical objects

The following numerical objects are known to the EVAL command. The fields of the table item table are all numeric (extended table or parameter table). The value item value can contain numbers, vectors or matrices. The wave item wave is any wave item.

numerical objects

Syntax	Description	Data type
constant	a scalar constant. E.g. 4.5 or 4	scalar
table	the content of the whole table	vector, matrix
table[i,*] or table[i,]	the i-th row of the table	scalar, vector
table[*,j] or table[,j]	the j-th column of the table	scalar, vector
table[i,j]	the value of the i-th row and j-th column of the table	scalar
value	the content of the value item	scalar, vector, matrix
value[i,*] or value[i,]	the i-th row of the value item	scalar, vector
value[*,j] or value[,j]	the j-th column of the value item	scalar, vector
value[i,j]	the value of the i-th row and j-th column of the value item	scalar
wave[!signal,*] or wave[!signal,]	the signal from all channels	vector, matrix
wave[!signal,ch]	the signal from channel ch (=1,2,...)	vector
wave[!signal,*,b,l]	the signal from all channels from sample b (0 <= b < wave[!length]) to sample b+l-1 (l > 0)	vector, matrix
wave[!signal,ch,b,l]	the signal from channel ch from sample b to sample b+l-1	vector

Notes:

• wave: If b is lower than 0 or b+l is greater than wave[!length] zero padding is applied to the result

Operators

numerical operators

Symbol	Syntax	Description	Datatype of Result
-	-x	Negate all elements of x.	same as x
+	y+xS or xS+y	Add the scalar xS to all elements of y.	same as y
+	x+y	Add elements of x to the elements of y. Both operands must be of the same type.	same as x and y
-	y-xS	Subtract the scalar xS from each element in y.	same as y
-	xS–y	Subtract all elements of y from the scalar xS.	same as y
-	x-y	Subtract elements of x from the elements of y. Both operands must be of the same type.	same as x and y
*	y*xS or xS*y	Multiply all elements of y with the scalar xS.	same as y
*	xV*yV	The inner (or dot) product of the vectors xV and yV. The length of both vectors must be the same.	scalar
*	xM*yV	The product of the matrix xM and the vector yV. The length of the vector yV must be the same as the number of columns in the matrix xM.	vector with nrow(xM) elements
*	xM*yM	The product of the matrix xM and yM. The number of rows in yM must be equal to the number of columns in xM.	matrix with nrow(xM) rows and ncol(yM)) columns
/	y/xS	Divide all elements of y through the scalar xS. The value of xM may not be 0.	same as y
/	xS/yM	Multiply all elements of the inverse matrix of yM with the scalar xS. The matrix yMmust be a square matrix.The special case 1/yM returns the inverse matrix. Note that the function inv(y) can also be used to invert scalars and matrices.	same as yM
%	y%xS	The rest of the division of every element in y through the scalar xS (modulo)	same as y
^	y^xS	Raise every element of y to the power of the scalar xS. Special cases: y^-1 is calculated like 1/y and y^2 is calculated like this y*y	same as y

Notes:

• If one of the binary operands has the prefix ? (e.g. ?*) then the operation is carried out element per element.

numerical comparison operators

Symbol	Syntax	Description
<	x<y	x less than y
>	x>y	x greater than y
<=	x<=y	x less than or equal' to y
>=	x>=y	x greater than or equal to y
==	x==y	x equal to y.
!=	x!=y	x not equal to y.

Notes:

• The result of a comparison is true (1), if the condition is fulfilled, otherwise it is false (0)
• equal: Two numerical expressions are considered equal if (and only if) their dimensions are the same and all pairs of elements (x_i,j,y_i,j) are numerically equal.
• not equal: Two numerical expressions are considered not equal if their dimensions are different or at least one element pair (x_i,j,y_i,j) is numerically not equal.

It is also possible to use logical operators and logical expressions.

The numerical result of a logical expression is the value ...

1 if the logical expression is true, and

0 if the logical expression is false

• The logical value of a numerical object is true (1) if one of its elements is not equal to zero.
• The logical value of a numerical object is true (1) if one of its elements is not equal to zero.

• In most cases it make no sense to mix numerical and logical expressions.
• The logical value of a numerical object is true

logical operators

Symbol	Syntax	Description
||	x||y	logical or
&&	x&&y	logical and
!	!x	unary not

A C-like '? :' selection operator is also supported:

result := eval 1 < 2 ? 1+2 : 1-2 // result is 3

Note that unlike C, nested uses of this operator must be surrounded by brackets, e.g.:

result := eval 1 > 2 ? (5 == 5 ? 5 : 0) : (4 == 5 ? 3 : 4) // result is 4

Functions=

abs · absmax · absmin · absv · acos · aseg1 · asin · asp2osp · atan · avr · cepstrum · complex arithmetic · corr · corrfun · cos · cvphase · dct · density · dev · dft · dist · em · exp · f0ac · f0sp · fft · fill · fir1 · floor · formants · grand · haclust · hcomb · hist · hth · hz2bark · hz2cent · hz2erb · hz2mel · ifft · iir1 · imax · imin · init · int · interp · inv · ipeak · limit · log · log2lin · lpc · map2map · mapmind · max · median · min · modclust · mul · ncol · npow2 · nrow · optmm · otrack1 · pgget · pghull · pgiline · pginit · pgitest · pgsplit · pgtrans · pgxgrid · pztf · qdet · qinterp · rand · rleqs · round · rpoly · rpolyreg · sample · select · shuffle · sig2osp · sign · sin · sinc · smooth · sort · sqrt · sum · svd · tan · ticks2f1 · trn · var · vmcol · vmrow · vsubc · vsubn · vv · vvcat · vvget · vvset · wconvert · window · wsum · ydiff · yint · zcross

Examples

For an extensive list of examples, see the script eval_examples.sts: Programmer Guide/Command Reference/EVAL Examples/EVAL Examples

History

The EVAL command was added to the S_TOOLS-STx language in version 3.7.0. The EVAL command replaces and extends the EVALUATE command. If the EVAL command is not assigning to an existing item, a table is assigned. Note that the current maximum number of arguments is 64 (S_TOOLS-STx version 3.8.0). As of version 3.7.0, S_TOOLS-STx has more numerical objects than just the scalars INT and NUM.