Miva Script Operators

Miva Script Operators

Introduction

An operator in a Miva Script expression indicates how the data it acts on are to be processed: added, subtracted, compared, joined, bit-shifted, and so forth. In the expressions {age + 10} and {age GT 16}, '+' and 'GT' are operators. The components on each side of the operator are sometimes called operands.

Miva Script operators have a built-in precedence that determines which operator gets interpreted first if there are two or more operators in an expression. You can also override the built-in precedence by surrounding sub-expressions with parentheses, `(' and ')'.

Miva Script provides the following types of operators:

Arithmetical operators
Comparison operators
Logical operators
Text string operators
Bitwise operators
Operator precedence

Arithmetical Operators

These operators are used with numbers or numeric expressions.

Miva Script also supports a number of built-in numerical functions.

Operator

Name

Description

+

Addition

expr1 + expr2

-

Subtraction

expr1 - expr2

*

Multiplication

expr1 * expr2

/

Division

expr1 / expr2

POW

POWer

expr1 POW expr2

Raise expr1 to the power expr2

For example, 3 POW 4 is 34, or 81.

MOD

MODulu

expr1 MOD expr2

Returns the integer remainder from expr1/expr2

For example, 26 MOD 7 is 5. See also the built-in function fmod(), which returns floating point remainders.

ROUND

Number
rounding

number ROUND places

Rounds number up or down to places decimal places.

For example, 123.45676 ROUND 2 is 123.46

Note: A minus sign can precede a literal number to make it negative (for example, -3.14), but otherwise must be used strictly as a binary operator: {-x} evaluates to the literal string '-x'; to express the negative of a value, use {-1*x} or {0-x}. Using +, /, or * as a unary operator results in an expression error.

Comparison Operators

These operators are used to compare two numbers or two text strings. In text string comparisons, lowercase letters are considered to be greater than uppercase letters. Two strings are equal only if the case (upper or lower) matches letter-by-letter. These operators all give a value of 1 (true) or 0 (false).

Operator

Name

Description

GT

Greater Than

expr_a GT expr_b

Tests whether expr_a is greater than expr_b

LT

Less Than

expr_a LT expr_b

Tests whether expr_a is less than expr_b

EQ

EQual To

expr_a EQ expr_b

Tests whether expr_a is equal to expr_b

Two strings are equal only if the case (upper or lower) matches letter-by-letter.

NE

Not Equal To

expr_a NE expr_b

Tests whether expr_a is not equal to expr_b

GE

Greater Than or Equal To

expr_a GE expr_b

Tests whether expr_a is greater than or equal to expr_b

LE

Less Than or
Equal To

expr_a LE expr_b

Tests whether expr_a is less than or equal to expr_b

Note: The expression {0 EQ ''} ("does zero equal the null string?") returns 1 (true).

To check whether a string is non-null, you can use the expression {string} rather than the longer form {string NE ''}. Similarly, to test whether a number is non-zero, use {number} rather than {number NE 0}.

Tip: Strings that consist of numbers and punctuation characters, and begin with identical numeric prefixes (for example '234-1' and '234-2') are considered equal by EQ. To force Miva Script to perform a true string comparison, prepend the same letter to both sides of the EQ. For example:

{'x' $ lhs EQ 'x' $ rhs}

Logical Operators

These operators are used with 'true' or 'false' expressions. For example:

<MvIF EXPR="{age GE 17 AND age LT 80}">

This expression is true if both of the expressions '{age GE 17}' and '{age LT 80}' are true.

Operator

Name

Description

NOT

Logical NOT

NOT expr

Returns the opposite of expr (if expr is false, NOT expr is true, and vice versa). Notice that this operator is unary: it acts on one expression, not two.

AND

Logical AND

expr_a AND expr_b

This expression is true if both expr_a and expr_b are true.

OR

Logical OR

expr_a OR expr_b

This expression is true if either of expr_a and expr_b is true.

Text String Operators

These operators are used with text strings or text string expressions.

Miva Script also supports a number of built-in string functions.

Operator

Name

Description

$

Concatenate strings

expr_a $ expr_b

Concatenates (joins) the strings expr_a and expr_b together.

For example, {'fred' $ 'flintstone'} would result in 'fredflintstone'.

IN / CIN

Beginning position

expr_a IN expr_b

expr_a CIN expr_b

Returns the beginning position of expr_a contained in expr_b.

For example, {'da' IN 'canada'} returns 5, because 'da' begins at the fifth letter in 'canada'. IN is case-sensitive: it will find matches only if the matched sub-string in expr_b has the same case, letter-by-letter, as expr_a. Use the CIN operator if you want to make your comparison case-insensitive. Notice that if you use literal strings in this expression you have to surround them with single quotes.

EIN / ECIN

End position

expr_a EIN expr_b

expr_a ECIN expr_b

Returns the end position of expr_a contained in expr_b.

For example, {'dia' IN 'canadian'} returns 7, because 'dia' ends at the seventh letter in 'canadian'. EIN/ECIN returns 0 when the left operand is NULL. This fixes backward compatibility with Miva v3.57 and earlier "Htmlscript" versions. ECIN is the case-insensitive version of EIN.

SUBSTR

Substring

expr SUBSTR 'position, #chars'

Returns the substring of expr that begins at position and is #chars characters in length. For example, {'canadian' SUBSTR '3,5'} returns 'nadia', which starts at the third character in 'canadian', and is five characters long. Note that the right side of a SUBSTR expression must be a string consisting of two numbers separated by a comma, or an expression or macro that evaluates to such a string.

FMT

Format string

expr FMT pattern

The FMT operator enables you to format a string based on a pattern. This operator provides a way to enhance the search, display, and logical processing capabilities of Miva Script active documents. New users are advised to gain some experience with constructing expressions using the built-in string functions before trying FMT. See "Formatting Strings - FMT Operator" on pageÝ99 for a discussion of FMT string format patterns and modifiers.

CRYPT

Encrypt a string

plaintext CRYPT key

Performs a one-way encryption, similar to that provided with the UNIX crypt command. The string plaintext is encrypted using the string key (this string is sometimes called a 'salt'). key can be any two characters (extra characters will be ignored). Only the first eight characters of plaintext will be used in the encryption. key is used as the first two characters of the encrypted value. CRYPT always yields the same result when applied to a particular plaintext and key.

Bitwise Operators

These operators act on numbers at the binary or 'bit' level. For example, BITAND compares the bits of two numbers, and returns a third number whose bits are equal to 1 (turned on) only if the same bits are equal to 1 in both the original numbers. That is, it performs a logical AND on corresponding bits.

The expression '{27 BITAND 13}' is evaluated as follows: 27 has the binary (base 2) form '00011011'; 13 has the binary form '00001101'. The only bits that are equal to 1 in both numbers are the first and fourth (counting from the right); therefore, the result is the number that has those bits equal to one, and all others equal to 0: 00001001, or 9 in decimal form.

Operator

Name

Description

BITAND

Bitwise AND

expr_a BITAND expr_b

Perform a logical AND on the bits of expr_a and expr_b.

BITOR

Bitwise OR

expr_a BITOR expr_b

Perform a logical OR on the bits of expr_a and expr_b.

BITXOR

Bitwise Exclusive OR

expr_a BITXOR expr_b

Perform a logical exclusive OR on the bits of expr_a and expr_b (return the number whose bits are equal to 1 in either, but not both, of the original numbers).

BITOC

Bitwise ones complement

BITOC expr

Flip the bits of expr (including the 'sign bit'). Notice that this operator is unary: it acts on one number, not two. Here is an example: {BITOC 9}. 9 in binary form is '1001'; including the 'sign bit' (leftmost bit), which indicates that the number is positive, it is '01001'. Flipping these bits gives '10110'. Since the sign bit is now '1', the number is negative. According to the rules of binary arithmetic, '0110' interpreted as a negative number is '-10'.

BITSL

Bitwise shift-left

expr_a BITSL expr_b

Shift the bits of expr_a to the left by expr_b places. The leftmost bits are lost, and the rightmost bits are replaced by zeroes.'{23 BITSL 2}' is interpreted as follows: 23 is 00010111 in binary form; shifting these bits left two places gives 01011100, or 92 in decimal format.

BITSR

Bitwise shift-right

expr_a BITSR expr_b

Shift the bits of expr_a to the right by expr_b places. The rightmost bits are lost, and the leftmost bits are replaced by zeroes.

Order of Precedence for Operators

Sometimes an expression can be interpreted in more than one way, depending on which operators are executed first. For example, {2 + 3 * 4} could be evaluated as 14 or 20, depending on whether the + or the * was evaluated first. In order to make the expected results unambiguous, Miva Script follows three rules:

Sub-expressions inside parentheses, '(' and ')', are evaluated first.
Each operator is assigned a precedence, and if there is a choice of which operator to evaluate first, the operator with higher precedence is evaluated.
If two operators have the same precedence, the leftmost one is evaluated first.

The order of precedence for Miva Script operators, from highest to lowest, is as follows:

NOT
FMT, ROUND, CRYPT, MOD, SUBSTR, POW
/, *
+,-,$
IN, CIN, EIN, ECIN, EQ, NE, GE, LE, LT, GT
AND, OR

According to these rules, {2 + 3 * 4} is evaluated to 14, because '*' has a higher precedence than '+'. If you really want the '+' to be evaluated first, you can use parentheses: {(2 + 3) * 4}. In the expression {2 / 4 * 5}, both operators have the same precedence, so the leftmost one (/) is evaluated first, and the result of the whole expression is 2.5.

Operator	Name	Description
+	Addition	expr1 + expr2
-	Subtraction	expr1 - expr2
*	Multiplication	expr1 * expr2
/	Division	expr1 / expr2
POW	POWer	expr1 POW expr2 Raise expr1 to the power expr2 For example, 3 POW 4 is 34, or 81.
MOD	MODulu	expr1 MOD expr2 Returns the integer remainder from expr1/expr2 For example, 26 MOD 7 is 5. See also the built-in function fmod(), which returns floating point remainders.
ROUND	Number rounding	number ROUND places Rounds number up or down to places decimal places. For example, 123.45676 ROUND 2 is 123.46

Operator	Name	Description
GT	Greater Than	expr_a GT expr_b Tests whether expr_a is greater than expr_b
LT	Less Than	expr_a LT expr_b Tests whether expr_a is less than expr_b
EQ	EQual To	expr_a EQ expr_b Tests whether expr_a is equal to expr_b Two strings are equal only if the case (upper or lower) matches letter-by-letter.
NE	Not Equal To	expr_a NE expr_b Tests whether expr_a is not equal to expr_b
GE	Greater Than or Equal To	expr_a GE expr_b Tests whether expr_a is greater than or equal to expr_b
LE	Less Than or Equal To	expr_a LE expr_b Tests whether expr_a is less than or equal to expr_b

Operator	Name	Description
NOT	Logical NOT	NOT expr Returns the opposite of expr (if expr is false, NOT expr is true, and vice versa). Notice that this operator is unary: it acts on one expression, not two.
AND	Logical AND	expr_a AND expr_b This expression is true if both expr_a and expr_b are true.
OR	Logical OR	expr_a OR expr_b This expression is true if either of expr_a and expr_b is true.

Operator	Name	Description
$	Concatenate strings	expr_a $ expr_b Concatenates (joins) the strings expr_a and expr_b together. For example, {'fred' $ 'flintstone'} would result in 'fredflintstone'.
IN / CIN	Beginning position	expr_a IN expr_b expr_a CIN expr_b Returns the beginning position of expr_a contained in expr_b. For example, {'da' IN 'canada'} returns 5, because 'da' begins at the fifth letter in 'canada'. IN is case-sensitive: it will find matches only if the matched sub-string in expr_b has the same case, letter-by-letter, as expr_a. Use the CIN operator if you want to make your comparison case-insensitive. Notice that if you use literal strings in this expression you have to surround them with single quotes.
EIN / ECIN	End position	expr_a EIN expr_b expr_a ECIN expr_b Returns the end position of expr_a contained in expr_b. For example, {'dia' IN 'canadian'} returns 7, because 'dia' ends at the seventh letter in 'canadian'. EIN/ECIN returns 0 when the left operand is NULL. This fixes backward compatibility with Miva v3.57 and earlier "Htmlscript" versions. ECIN is the case-insensitive version of EIN.
SUBSTR	Substring	expr SUBSTR 'position, #chars' Returns the substring of expr that begins at position and is #chars characters in length. For example, {'canadian' SUBSTR '3,5'} returns 'nadia', which starts at the third character in 'canadian', and is five characters long. Note that the right side of a SUBSTR expression must be a string consisting of two numbers separated by a comma, or an expression or macro that evaluates to such a string.
FMT	Format string	expr FMT pattern The FMT operator enables you to format a string based on a pattern. This operator provides a way to enhance the search, display, and logical processing capabilities of Miva Script active documents. New users are advised to gain some experience with constructing expressions using the built-in string functions before trying FMT. See "Formatting Strings - FMT Operator" on pageÝ99 for a discussion of FMT string format patterns and modifiers.
CRYPT	Encrypt a string	plaintext CRYPT key Performs a one-way encryption, similar to that provided with the UNIX crypt command. The string plaintext is encrypted using the string key (this string is sometimes called a 'salt'). key can be any two characters (extra characters will be ignored). Only the first eight characters of plaintext will be used in the encryption. key is used as the first two characters of the encrypted value. CRYPT always yields the same result when applied to a particular plaintext and key.

Operator	Name	Description
BITAND	Bitwise AND	expr_a BITAND expr_b Perform a logical AND on the bits of expr_a and expr_b.
BITOR	Bitwise OR	expr_a BITOR expr_b Perform a logical OR on the bits of expr_a and expr_b.
BITXOR	Bitwise Exclusive OR	expr_a BITXOR expr_b Perform a logical exclusive OR on the bits of expr_a and expr_b (return the number whose bits are equal to 1 in either, but not both, of the original numbers).
BITOC	Bitwise ones complement	BITOC expr Flip the bits of expr (including the 'sign bit'). Notice that this operator is unary: it acts on one number, not two. Here is an example: {BITOC 9}. 9 in binary form is '1001'; including the 'sign bit' (leftmost bit), which indicates that the number is positive, it is '01001'. Flipping these bits gives '10110'. Since the sign bit is now '1', the number is negative. According to the rules of binary arithmetic, '0110' interpreted as a negative number is '-10'.
BITSL	Bitwise shift-left	expr_a BITSL expr_b Shift the bits of expr_a to the left by expr_b places. The leftmost bits are lost, and the rightmost bits are replaced by zeroes.'{23 BITSL 2}' is interpreted as follows: 23 is 00010111 in binary form; shifting these bits left two places gives 01011100, or 92 in decimal format.
BITSR	Bitwise shift-right	expr_a BITSR expr_b Shift the bits of expr_a to the right by expr_b places. The rightmost bits are lost, and the leftmost bits are replaced by zeroes.