[TOC] [Prev] [Next] [Bottom]


<@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.

For more information, see Calculation Variables.

! Note: Single letters must always be enclosed in quotes in string operations so that they are treated as letters, and not as 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.

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

For more information, see beginswith.

<@CALC EXPR="Henry beginswith 'H'"> evaluates the string "Henry" to see if it begins with the string "H" (case-insensitive).

<@CALC EXPR="1234 beginswith H"> evaluates "1234" to see if it begins with the value specified in the calculation variable H (number-to-string conversions are performed).

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 1*2*3*...*x) factorial of the expression

fac(expr)

floor

expression rounded to the closest integer less than the expression

floor(expr)

log

In(x) (or loge(x)), the natural logarithm of the expression

log(expr)

log10

log10(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(A1, A2,...An). returns the largest element

max(expr expr ...)

min

min(A1, A2,...An). returns the smallest element

min(expr expr ...)

sum

A1+A2+...+An. returns the sum of the elements

sum(expr expr...)

prod

A1*A2*...*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

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:

See Also

<@ARRAY>
<@IF>, <@ELSEIF>, <@ELSEIFEMPTY>, <@ELSEIFEQUAL>, </@IF>
Encoding Attribute
<@FORMAT>
Format Attribute
<@VAR>


[TOC] [Prev] [Next] [Bottom]


docs@pervasive.com

Copyright © 1999, Pervasive Software. All rights reserved.