# Expressions

Expressions are used to calculate integer values or produce strings of text that can then be stored in Variables or Properties using Actions, or used in comparison operations in Restrictions.

An expression can also be embedded into the middle of text in a text box by placing it between the symbols `<#`

and `#>`

When the text is displayed on the screen the expression will be evaluated and the result inserted into the text.

## Integer Expressions

In an action a value can be calculated by an integer expression and the result stored in a 'number' variable, an element of an array variable, or an integer property of a character, object or location. The basic mathematical functions +,-,*,/ can be used to calculate a value, using integer constants, properties, variables, and the reference %number%.

- Note that multiply and divide are evaluated before addition and subtraction, so you will need to use parentheses if you want the expression to be evaluated in a different order, or if you are using boolean and/or operations on the result of a comparison.

An integer expression can also be compared with an integer variable or property in a restriction, to determine if they are equal or one is greater than or less than the other value.

x mod y Returns the modulus of x and y, i.e. the remainder when x is divided by y. 11 mod 4 = 3

- NOTE: The divide operator '/' performs a round-to-nearest-integer integer divide. If you need the truncated integer part of the division then first subtract 0.5 times the number being divided by, eg. (%IntVar%-50)/100
- Parentheses can be used to control the order of evaluation, eg. (17+4)*(9-6)
- Variable names must be delimited with '%' symbols, eg. %Score%
- Array variables use square brackets to enclose the index value, eg. %ArrayVar1[3]%
- Integer properties are accessed using Item functions.

A number of mathematical functions can also be used, including:

- min(x,y) Returns the minimum of value x and y
- max(x,y) Returns the maximum of value x and y
- either(x,y) Randomly returns either x or y
- rand(x,y) Returns a random value between x and y
- urand(x,y) Returns a unique random value between x and y. When called multiple times no value will be repeated until all of the values between x and y have been returned.
- abs(x) Returns the absolute value of x( the magnitude regardless of sign), i.e. abs(-4) = 4

## String Expressions

In an action a line of text can be calculated using a string expression and the result stored in a 'text' variable, an element of an array variable, or a text property of a character, object or location. A string expression can also be compared with a text variable or property in a restriction, to determine if they contain exactly thesame text or not.

String constants are delimited with the quote character, eg. "Some text". The '&' operator concatenates two strings together, eg. "Some text"&"ures" becomes "Some textures". Any text based property, variable, element of array variable, or the reference %text% can be used in a string expression.

The following string functions are available:

- UCase(text) Converts <text> to all upper case
- LCase(text) Converts <text> to all lower case
- PCase(text) Converts <text> to proper case. It capitalises the first letter of each sentance, with the rest remaining in its original case. "i am sam. sam IS me." becomes "I am sam. Sam IS me."
- Left(text, length) Returns the <length> leftmost characters of <text>
- Right(text, length) Returns the <length> rightmost characters of <text>
- Mid(text, start, length) returns <length> characters of <text>, starting at <start>
- Either(text1, text2) randomly returns either <text1> or <text2>
- OneOf(text1, text2, text3, text4) This function can take any number of parameters, and will return one of the parameters randomly. For example, you could embed the function into a piece of text like so:

- The top card is the Queen of <# OneOf("club", "spade", "diamond", "heart") #>s.

- Replace(SourceText, FindText, ReplaceText) This takes three parameters - the first is the piece of text to be altered, the second is the text to find, and the third is the text to replace the found text with. So for example:

- Replace("one two three", "two", "TWO") would return "one TWO three".

## Mixed Expressions

An expression can be partly an integer expression and partly a string expression. For example an integer expression can be used to calculate the index of a text variable, and the result of that used in a string expression.

The following functions can be used in mixed expressions:

- Len(text) Returns the length of <text>
- Val(text) Converts <text> to a number (or zero if it can't match)
- Str(x) Converts an integer value x to text form. Negative numbers are preceeded with "-" and positive numbers with a space.
- instr(text, search) Returns the position of the first occurance of <search> within <text> eg. instr(“hello”,”e”) = 2

- Note that this is
__not__case sensitive, so instr("hello","E") will also return 2. - This function returns zero if <search> does not exist within <text>.

## Conditional Expressions

- If(test,x,y) If "test" evaluates true, returns x, else returns y Where "test" is a=b, a==b, a<b, a<=b, a>b, a>=b, a<>b, a!=b. Conditions can be ANDed using "and", "&" or "&&" or ORed using "or", "|", "||", eg. IF(%variable1%=1,%variable2%+1,RAND(5,7))

- Always use parentheses to ensure that comparison operations occur before AND/OR, eg. IF((%var1%=3) AND (%Var2=4),10,20)

<<< General item Functions | Main Page | I |