# Evaluate Expression

The supplied mathematical expression is evaluated and returned in the specified track or named variable. The text strings may contain any of the escape sequences described in Escape Sequences. When using track variables in the expression use the \i or \f forms as opposed to \v as they guarantee a properly formatted integer or number.

The result can be forced to be an integer value by specifying the Return integers only option.

Specify numbers with decimal points and at least one fractional digit if you do not want only integer results. ie. 3.0 not 3 or 3. (which is considered invalid). Hexadecimal numbers can be used as long as they start with a 0x sequence. eg. 0xF5

The expression parser supports parenthesis and the standard + (add), - (subtract), * (multiply), / (divide) and ** (raise to power) operators. It also supports the ~ (ones complement), & (and), | (or), ^ (xor), << (shift left) and >> (shift right) operators.

Example: (-3 + \i1) * 5

The expression parser contains a number of functions which may be of use. Prior to Yate v6.7 some of the functions were only documented in a function(...) form. These are included as they will still work but where possible a simpler (and less distasteful) form is now provided.

abs(#)
  The absolute value of #
  abs(-2) ---> 2
  abs(2) ---> 2
average({#1, #2, ...})
  The average of the specified values
  average({2,3,3,5,8,11}) ---> 6
ceiling(#)
  The smallest integer greater than or equal to #
  ceiling(1.2) ---> 2
  ceiling(-1.2) ---> -1
count({#1, #2, ...})
  The number of specified values.
  count({1,2,3}) ---> 3
floor(#)
  The largest integer less than or equal to #
  floor(1.2) ---> 1
  floor(-1.2) ---> -2
function(#1, 'div:', #2)
  The integer division of expression #1 and expression #2, regardless of the presence of fractions. As an alternative use the trunc function and the / operator.
  function(-5, 'div:', 2.1) --> -2
  function(5, 'div:', 2.1) --> 2
  trunc(-5 / 2.1) --> -2
  trunc(5 / 2.1) --> 2
max({#1, #2, ...})
function(#1, 'max:', #2)
  The maximum of the supplied expressions. Note that the function form only allows two expressions.
  max({1,2,3}) --> 3
  function(-5, 'max:', 2) --> 2
median({#1, #2, ...})
  The median of the specified values
  median({2,3,3,5,8,11}) ---> 5
min({#1, #2, ...})
function(#1, 'min:', #2)
  The maximum of the supplied expressions. Note that the function form only allows two expressions.
  min(1,2,3) --> 1
  function(-5, 'min:', 2) --> -5
modulus:by:(#1,#2)
function(#1, 'mod:', #2)
  The integer remainder of dividing expression #1 by expression #2.
  modulus:by:(5, 2) --> 1
  function(-5, 'mod:', 2) --> -1
random()
  A random number between 0 and 1.
  random()
randomn(#1)
  A random integer between 0 and the specified number (exclusive).
  randomn(10)
sqrt(#)
  The square root of the specified value.
  sum({1,2,3}) ---> 6
sum({#1, #2, ...})
  The sum of the specified values.
  sum({1,2,3}) ---> 6
trunc(#)
  The value of # with any fractional part removed
  trunc(1.2) ---> 1
  trunc(-1.2) ---> -1

If the expression cannot be compiled a message will be posted and the action will be terminated.

If the expression results in an invalid number or in the case of division by zero, the result will be set to zero and the action test state will be set to false. Otherwise, the action test state will be set to true. When running in stepwise mode, the action test state will only be set to true if the evaluation succeeded for every track.

When running in stepwise mode, the expression is only evaluated once if the destination is a named variable.

Expressions can also be evaluated inline anywhere escape sequences are permitted.

\x(expression\x.)
  expression can be any expression as defined in the Evaluate Expression statement and may contain escape sequences. Note that the terminating sequence has a leading \ character. If the expression cannot be compiled a message will be posted and the action will be terminated at the start of the next statement or earlier. If the expression results in an invalid number or in the case of division by zero, nothing is inserted. If the expression evaluation works, the inserted text may or may not contain a fractional component.
\x(expression\x)
  Same as above but on success the inserted text will always be an integer value.

Example:

> The integer sum of variable 0 and variable 1 is \x( \v0+\v1 \x)