Meta Tags

<@CALC>

Syntax

<@CALC EXPR=expr [PRECISION=precision] [FORMAT=format][ENCODING=encoding]>

Description

Returns the result of the calculation specified in EXPR.

Basic Functionality

The expression may contain numbers (including numbers in scientific notation); any of six arithmetic operations--multiplication (*), division (/), modulo (%), power (^), addition (+), and subtraction (-); parentheses for controlling the order of operations; mathematical functions; string functions; logical operations; comparison operations; calculation variables (A-Z); and sub-expressions.

Note: Do not confuse calculation variables with configuration variables or other Tango variables. They are only applicable to <@CALC> and do not work with <@ASSIGN> or <@VAR>.

If the expression contains any spaces--except for spaces within embedded meta tags--it must be quoted.

The optional PRECISION attribute is an integer that controls the number of decimal places displayed in the result. The default precision is the maximum required for accuracy of the result.

If an error is encountered while the expression is parsed or computed, the computation is halted and the tag is substituted with relevant error information.

Examples

<@CALC EXPR="3+7">

This tag returns "10".

<@CALC EXPR="<@POSTARG NAME='calculateThis'>" PRECISION="4">

This evaluates the contents of the form field specified--calculateThis--to four decimal places of precision. If the field contained "8*9+8/2", for example, the tag would evaluate to "76.0000".

Advanced Functionality and Calculation Variables
Reference

Numbers

A valid number is a sequence of digits, optionally preceded or trailed by a currency sign (default "$", otherwise set by the configuration variable currencyChar), with any number of thousand separator characters, an optional decimal point, and an exponentiation part. As well, an empty variable or empty string evaluates to zero.

Numbers can be used with any operators and functions, even with the string specific function len, which returns the length of the number converted to a string.

When a number is used in logical expression, any non-zero number is considered true, and zero is considered false.

Logical expressions themselves return "1" if they are true or "0" if they are false.

Two symbolic constants, true and false, which evaluate to "1" and "0", respectively, are provided for convenience.

An empty string evaluates to zero for the purposes of calculation. That is, if the variable foo is empty, the following operations are valid:

<@CALC '@@foo + 1'> OK, returns 1
<@CALC '"" + 1'> OK, returns 1
<@CALC 'mean(@@foo 1)'> OK, returns 0.5

The thousand separator set to space

A special case occurs when the thousand separator is set to a space. A number containing a space can be processed if it is a result of a tag evaluation; however, a number literal must be quoted if it includes spaces.

For example:

<@ASSIGN NAME=fred VALUE="1 000 000">

<@CALC "@@fred / 100">Ok, returns 10000.0
<@CALC "@@fred > '1 000'"> Ok, returns 1.0
<@CALC "@@fred > 1 000"> Error

For more information, see "currencyChar", "decimalChar" , "DBDecimalChar" , and "thousandsChar" .

The thousands separator, currency sign, and other numerical formats are set by Tango configuration variables. They can be set in various scopes.

Array evaluation

<@CALC> treats array references using non-array-specific operators and functions as a numerical value returning the number of rows in the array.

This provides an easy way to verify whether an array is empty or contains a certain value. For example, you can test for the existence of an array variable with <@CALC EXPR="@@array_variable > 0" TRUE="Yes!" FALSE="No such variable.">.

For example:

The variable fred contains the following array:

1	2
3	4

The variable barney contains the following array:

1	2
5	6
7	8

<@CALC @@fred> returns 2.

<@CALC @@barney> returns 3.

<@IF EXPR="@@fred > @@barney" TRUE="true!" FALSE="alas"> returns "alas".

Hexadecimal, Octal and Binary Numbers

The calculator can accept hexadecimal, octal, and binary numbers. The num function converts strings representing hexadecimal, octal and binary numbers to decimal numbers, and the result of the conversion can be used anywhere where a number is used. The following table specifies the conversion rules.

Note: If a decimal number is passed to this function, it either yields an error or an incorrect result

Prefix	Valid Symbols	Converted As	Examples
0x	0123456789abcdef	Hexadecimal	num (0xff) num (0x0123f3a4)
0	01234567	Octal	num (0123456) num (0120235)
None	01	Binary	num (1011110010100) num (111)

For example, all the following expressions generate errors:

num(0x123fga) ERROR: letter g is invalid
num(012380) ERROR: digit 8 is invalid
num(123) ERROR: digits 2 and 3 are invalid

Strings

Any Tango meta tag that does not evaluate to a valid number or array reference is considered a string. No additional quoting is required. There is a single exception to this rule, further explained in "Meta Tag Evaluation" .

Strings can be used only in comparison operations, contains clauses or as arguments to the len function. A string literal--that is, a string, directly included in the expression--must be enclosed in single quotes if it contains spaces, special characters or starts with a digit.

Note:

Single letters must always be enclosed in quotes in string operations so that they are treated as letters, and not as calculation variables.

For more information, see “Calculation Variables”.

The following examples show string comparisons. If a string literal contains a single quote or a backslash, it must be escaped with a backslash.

<@ASSIGN NAME=name VALUE="John Lennon"> <@CALC EXPR="@@name=John">false
<@CALC EXPR="@@name=John Lennon"> ERROR
<@CALC EXPR="@@name='John Lennon'">true
<@CALC EXPR="@@name='John*'"> true

<@ASSIGN NAME=name VALUE="John's trousers"> <@CALC EXPR="@@name=John*"true
<@CALC EXPR="@@name='John\'s trousers'">true
<@CALC EXPR="@@name='John's'"> ERROR

<@ASSIGN NAME=dir VALUE="C:\test"> <@CALC EXPR="@@dir='C:\test'">false
<@CALC EXPR="@@dir='C:\\test'"> true

When a string is encountered on one side of the comparison operation, the other operand is forced to a string, too. For example:

2.15 <='abba' '123.456.78.12'=@@ip_address

Function len returns the length of the string, so the result of this operation can be used anywhere a number can be used. Strings can not be assigned to calculation variables.

For example, these are valid expressions:

ABBA='BLACK SABBATH' false
len(JOHN LENNON) + len(FREDDY MERCURY) - 5 > 0 true

but these are not:

a :=ABBA ERROR: cannot assign string
FREDDY < 0 ERROR: cannot compare string and number

and this tag returns true although you may expect it to return false:

<@CALC EXPR="a=b">

Note: A single letter on both sides of the comparison operator evaluates to a calculation variable, meaning a number comparison is performed.

String comparisons using <@CALC> are case insensitive.

Calculation Variables

A calculation variable is a single case-insensitive letter (A-Z) that can be assigned a numeric value and used in subsequent operations. You can write small programs inside the tag with calculation variables and statement separators, or put a program in a separate file and use <@INCLUDE> to calculate the result.

The following table shows predefined calculation variables. You may use these values in your programs, or have any of these calculation variables reassigned with any other value.

Variable	Meaning	Value
G	(3 - sqrt(5))/2, the golden ratio.	0.381966011250105
E	e, the base of natural logarithms.	2.718281828459045
L	log10(e), the ratio between natural and decimal logarithms.	0.434294481903252
P	pi, the circumference to diameter ratio of a circle.	3.141592653589793
Q	sqrt(2), the square root of 2.	1.414213562373095
I	Has a meaning only inside foreach expression.	Current row index
J	Has a meaning only inside foreach expression.	Current column index
X	Has a meaning only inside foreach expression.	Current array element index

Operators

The following table shows the operators listed in order of increasing precedence. Operators having the same precedence, for example, plus and minus, are not separated by a rule.

Note: The beginswith operator should be used instead of a trailing asterisk as a wildcard in comparisons.The use of asterisks as wildcards is deprecated and will be removed in a future release.

Operator	Meaning and Return Value	Usage
;	Sub-statement separator, returns the value of the last statement.	statement ; statement
:=	Assignment operator, assigns the value of the expression to the calculation variable, and returns that value.	variable := expression
\|\| OR	Logical OR, returns 1 if any of the expressions is evaluated to a non-zero value, or 0 otherwise.	expr \|\| expr expr OR expr
&& AND	Logical AND, returns 1 if both of the expressions are evaluated to non-zero values, or 0 otherwise.	expr && expr expr AND expr
<	Numeric or string LESS. Returns 1 if left operand is greater than right one, or 0 otherwise.	expr < expr string < string
>	Numeric or string GREATER. Returns 1 if left operand is greater than right one, or 0 otherwise.	expr > expr string > string
<=	Numeric or string LESS OR EQUAL. Returns 1 if left operand is less than or equal to right one, or 0 otherwise.	expr <= expr string <= string
>=	Numeric or string GREATER OR EQUAL. Returns 1 if left operand is greater than or equal to right one, or 0 otherwise.	expr >= expr string >= string
=	numeric or string EQUAL. Returns 1 if left operand is equal to right one, or 0 otherwise.	expr = expr string = string
!=	Numeric or string NOT EQUAL. Returns 1 if left operand is not equal to right one, or 0 otherwise.	expr != expr string != string
? :	Ternary comparison. Evaluates to expr1 if condition is true, or to expr2 otherwise.	(cond) ? expr1: expr2
contains	Containment. Returns true if specified string or number is contained in the array.	array contains string array contains number
contains	Occurrence. Returns true if specified string or number is a substring of the source string.	source_string contains string source_string contains number
beginswith	Occurrence. Returns true if specified string or number begins the source string. (Case-insensitive.)	source_string beginswith string source_string beginswith number
endswith	Occurrence. Returns true if specified string or number ends the source string. (Case-insensitive.)	source_string endswith string source_string endswith number
+	Addition. Returns the sum of the expressions.	expr + expr
-	Subtraction. Returns the difference of the expressions.	expr - expr
*	Multiplication. Returns the product of the expressions.	expr * expr
/	Division. Returns the quotient of the expr1 divided by the expr2.	expr1 / expr2
%	Modulo. Returns the remainder of expr1 divided by expr2.	expr1 % expr2
^	Power. Returns expr1 raised to expr2 power.	expr1 ^ expr2
-	Unary minus. Returns the negation of the expression.	- expr
+	Unary plus. Returns the expression itself.	+ expr
! NOT	Logical NOT. Returns 0 if the value of the expression is not 0, or 1 otherwise.	! expr NOT expr

Built-in Functions

Each built-in function expects either a single numeric argument, or a space-separated list of mixed numeric and array arguments, or a string. It is an error to specify an argument of the wrong type to a function. If an array, specified as an argument to a function, contains non-numeric elements, these elements are ignored without any error diagnostics.

The following tables list all built-in functions.

1. Numeric functions of the form func(expr)

Function	Meaning and Return Value	Arguments and Usage
abs	\|x\|, the absolute value of the expression	abs(expr)
acos	*cos*-1(x), the arccosine of the expression, returned in radians	acos(expr)
asin	*sin*-1(x), the arcsine of the expression, returned in radians	asin(expr)
atan	*tan*-1(x), the arctangent of the expression, returned in radians	atan(expr)
ceil	expression rounded to the closest integer greater than or equal to the expression	ceil(expr)
cos	*cos(x)*, the cosine of the expression, specified in radians	cos(expr)
exp	ex, the exponentiation of the expression	exp(expr)
fac	x! (or **123...x**) factorial of the expression	fac(expr)
floor	expression rounded to the closest integer less than the expression	floor(expr)
log	*In(x)* (or *log*e(x)), the natural logarithm of the expression	log(expr)
log10	*log*10(x), the decimal logarithm of the expression	log10(expr)
sin	*sin(x)*, the sine of the expression, specified in radians	sin(expr)
sqrt	*sqrt(x)* (or x1/2), the square root of the expression	sqrt(expr)
tan	*tan(x)*, the tangent of the expression, specified in radians	tan(expr)

2. String functions of the form func(string)

Function	Meaning and Return Value	Arguments and Usage
len	returns the length of the string enclosed in parentheses	len(text)
num	converts a string, representing a hexadecimal, octal, or binary number into a number	num(text)

3. Array functions of the form func(expr|array expr|array)

Function	Meaning and Return Value	Arguments and Usage
max	*max(A*1, A2,...An). returns the largest element	max(expr expr ...)
min	*min(A*1, A2,...An). returns the smallest element	min(expr expr ...)
sum	A1+A2+...+An. returns the sum of the elements	sum(expr expr...)
prod	A1A2...*An. returns the product of the elements	prod(expr expr...)
mean	Amean=(A1+A2+...+An) /n. returns the mean of the elements	mean(expr expr...)
var	Avar=((A1-Amean)2+((A2-Amean)2+...+((An-Amean)2)/(n-1) returns the (squared) variance of the elements	var(expr expr...)

Array Operators

Contains Operator

The contains operator has the following syntax:

<@VAR NAME="array"> contains number or string

This operator checks if the specified number or string is contained in the array. The string should be enclosed in quotes, if it contains any non-alphanumeric characters. The operator returns "1" if the element is found, or "0" otherwise.

For example, the following expression, which uses the <@IF> meta tag, returns "Cool" if "Queen" is found in the CDs array, and "Too Bad" if it is not.

<@IF EXPR="<@VAR NAME=CDs> contains Queen" TRUE=Cool FALSE="Too bad">

Foreach Operator

The foreach operator has the following syntax:

<@VAR array> foreach {statement; ...}

For more information, see "<@ARRAY>".

For more information, see "<@ASSIGN>".

This operator steps through the elements of an array and it assigns

the value of the elements to the variable "X"
the current row number to the variable "I"
and the current column number to the variable "J"

and it executes the statements inside the braces "{ }"for each element. All non-numeric elements are interpreted as zeroes.

The operator returns the last calculated value of the expression.

The values of "X, I, J" are restored upon the exit from the foreach operator. For example, if array CDs is initialized as follows:

<@ASSIGN NAME="CDinitValue" VALUE="AC/DC,Scorpions,Deep Purple,Black Sabbath,Queen;19.50,22.50,22.50,17.90,29.00"> <@ASSIGN NAME="CDs" VALUE="<@ARRAY ROWS='2' COLS='5' VALUE=@@CDinitValue CDELIM=',' RDELIM=';'>">

then the following program prints the name of the most expensive CD:

<@VAR NAME=CDs[1,<@CALC "t :=1; p :=0.0;

<@VAR NAME=CDs> foreach { t :=(p < x)? j: t; p :=(p < x)? x: p; }; t">]>

Meta Tag Evaluation

There are two special cases when a meta tag is not treated as a string. Consider the following two examples:

<@CALC EXPR="<@POSTARG NAME=prog>"> <@CALC EXPR="<@INCLUDE FILE=myprog>">

If the post argument prog contains an expression submitted by a user, or the file myprog contains an expression to be calculated, one would expect <@CALC> to produce the result of the calculation. The rule is, if the expression contains a single meta tag, such an expression is fully evaluated by the calculator, rather than treated as a string.

Ordering of Operation Evaluation With Parentheses

Parentheses can be used to order the evaluation of expressions that otherwise are evaluated in the order specified in the Operators table ("Operators" ). For example:

<@CALC EXPR= "7*3+2">

This example evaluates to "23".

<@CALC EXPR= "7*(3+2)">

This example evaluates to "35".

A more complex example can be constructed using different operators and nested parentheses:

<@CALC EXPR="(<@ARG _function> = 'detail') and ((len(<@ARG id>) != 0 and <@ARG mode>='abs') or (<@ARG mode>='next' or <@ARG mode>='prev'">))>

This tag evaluates to "1" (true) if the _function argument is equal to "detail" and any one of the following conditions are met:

id arg is not empty and the mode arg is "abs"
mode argument is "next"
mode argument is "prev".

<@CALC>

Syntax

Description

Basic Functionality

Examples

Advanced Functionality and Calculation Variables Reference

Numbers

The thousand separator set to space

Array evaluation

Hexadecimal, Octal and Binary Numbers

Prefix

Valid Symbols

Converted As

Examples

Strings

Calculation Variables

Variable

Meaning

Value

Operators

Operator

Meaning and Return Value

Usage

Built-in Functions

1. Numeric functions of the form func(expr)

Function

Meaning and Return Value

Arguments and Usage

2. String functions of the form func(string)

Function

Meaning and Return Value

Arguments and Usage

3. Array functions of the form func(expr|array expr|array)

Function

Meaning and Return Value

Arguments and Usage

Array Operators

Contains Operator

Foreach Operator

Meta Tag Evaluation

Ordering of Operation Evaluation With Parentheses

See Also

Advanced Functionality and Calculation Variables
Reference