Operators and functions available to end-users

The first section lists functions and operators that are typically familiar, each with a quick description and example.  The subsequent section lists special functions and operators that require additional explanations.

Symbol    Description                Example

!         Factorial                  5! = 120

^         Raised to the power of     4 ^ 5 = 1024

*         Multiply by                3 * 6 = 18

/         Divide by                  9 / 2 = 4.5

\         Integer divide by          9 \ 2 = 4

mod       Modulo (remainder)         7 mod 4 = 3

+         Add                        1 + 1 = 2

-         Subtract                   9 - 5 = 4

-         Unary negation             -(5+4) = -9

+         Concatenate                'Zeb' + 'ra' = 'Zebra'

>         Greater than (numeric)     9 > 2 = -1

<         Less than (numeric)        7 < 4 = 0

==        Equal test (numeric)       5 == 4 = 0

>=        Greater or equal (numeric) 3 >= 3 = -1

<=        Less or equal (numeric)    #h3E <= 9 = 0

<>        Not equal (numeric)        #b10101 <> 20 = -1

>         Greater than (string)      'This' > 'That' = -1

<         Less than (string)         'This' < 'That' = 0

==        Equal test (string)        'A' == 'B' = 0

>=        Greater or equal (string)  'Zeb' >= 'Zebra' = 0

<=        Less or equal (string)     'Zeb' <= 'Zebra' = -1

<>        Not equal (string)         'X' <> 'Y' = -1

And       Bitwise AND                #b101 AND #h1E = 4

Or        Bitwise OR                 13 OR 6 = 15

IIF       If condition (numeric)     IIf(1+1==2, 4, 5) = 4

IIF       If condition (string)      IIf(1, 'T', 'F') = 'T'

Min       Minimum value              min(10, 3) = 3

Max       Maximum value              max(1, 9, 2) = 9

Sin       Sine                       sin(pi/2) = 1 (assuming pi is defined)

Cos       Cosine                     cos(pi) = -1

Tan       Tangent                    tan(1) = 1.5574...

Atan      Arc tangent                atan(0) = 0

Abs       Absolute value             abs(-8) = 8

Exp       e to the power of          exp(3) = 20.08...

Log       Natural log                log(16) = 2.77...

Ceil      Round up                   ceil(6.2) = 7

Int       Truncate to an integer     int(6.8) = 6

Frac      Fractional part            frac(3.125) = 0.125

Sgn       Sign (returns -1, 0, or 1) sgn(-9) = -1

Sqr       Square root                sqr(64) = 8

Functions and operators that require further explanation

Asc(StringArg [, Position])

Returns the ASCII value of a character.  If the Position argument is omitted, then the ASCII value of the first character of the string is returned, otherwise the value of the nth position (starting with 1), as supplied by the Position argument is returned.

Example:      Asc("A")        returns 65

Asc("ABC", 3)   returns 67

operand1 AndAlso operand2

AndAlso returns True (-1 or 1 depending on the default settings), if operand1 is non-zero and so is operand2.  The And operator always evaluates both operands, whereas AndAlso uses short-circuit evaluation, which means that if operand1 is false (or 0), then AndAlso will return a result without proceeding to evaluate operand2.  This is important in situations where operand2 might evaluate something like a division by 0, or might contain a routine that performs an action such as displaying a message box.  You probably would not want it to go through with evaluating operand2 in such a situation if operand1 is enough to determine the outcome.  See OrElse.

BaseConvert(Number, FromBase)

Converts from a given base to base 10.  Number is a string argument (to allow for non-numeric digits as used in hexadecimal), and FromBase is numeric.

Example:      BaseConvert("101", 2)    returns 5

Chr(Number)

Returns the character associated with the ASCII value supplied as the Number argument.

Example:      Chr(65)          returns A

Error(ErrorMessage)

See Error

Local(var1 [, var2 [, var3 [, ...]]], Expression)

See Local

Min(a, b [, ...])

Max(a, b [, ...])

These take any number of arguments and return the minimum argument (for Min), or the maximum argument (for Max).  They work with both string and numeric arguments.  Arguments must be either all strings or all numbers.  Note: In version 3.0 Min() and Max() are defined using native callbacks, making them very significantly faster than the recursive macro definitions of the previous version.

operand1 OrElse operand2

OrElse returns True (-1 or 1 depending on the default settings), if either operand1 or operand2 is non-zero.  The Or operator always evaluates both operands, whereas OrElse uses short-circuit evaluation, which means that if operand1 is a non-zero value, then OrElse will return a result without proceeding to evaluate operand2.  See AndAlso.

Precedence(Operator)

Returns the precedence level of a given operator.  The Operator argument is a string.  This is useful when defining a new operator with the same level as a preexisting one.

Example:      ucDefineOperator "Precedence('+') {x} Plus {y} := x + y"

Rand([x])

Rand(a, b)

Options

No arguments

Returns a floating point random number between 0 and 1.  The number chosen is the next in a random sequence.

x > 0

Returns a floating point random number between 0 and 1.  The number chosen is the next in a random sequence.

x = 0

Returns the same random number as the one previously generated.

x < 0

Returns the same random number each time, using the argument as seed.

a, b

Returns an integer random number between a and b.

This adds curly braces { and } around parameters in a string so that this string can be used as a syntax definition.  This allows for the definition of macros, for instance.

Params is a string argument, which contains a list of parameters.  The parameters in the string do not have to be organized in any special way.  uCalc will pick out all alphanumeric elements in the string and treat those as the parameters.  Expression is a string containing a definition that is to be parameterized.  That is, curly braces will be added around each alphanumeric occurrence in Expression that was found in Params.  Parameter names are not case sensitive.  The thread argument is optional.  A value of 0 represents the current thread.

The example below shows how you might call SetSyntaxParams.  Here uCalc picks out x, y, and z from Params as parameters.  Occurrences of x, y, and z in the second argument are surrounded by curly braces in the transformed string:

ucEvalStr("SetSyntaxParams('(x, y, z)', 'macro(x, y, z) = sin(x)*y+abc+x-z')")

returns

macro({x}, {y}, {z}) = sin({x})*{y}+abc+{x}-{z}

Here, the first argument could have equally been "x, y, z", "(x y z)", "[x+y+z]", "((x) (y) (z))", etc.

See also the Macro construct towards the end of the include file.  For an example, see the Macro definition in the ucDefine topic.

SetVar(VariableName, Value)

This assigns a value to a variable.  The variable can be of just about any data type, and can also be an array element.  However, Value must either be the same type as VariableName, or a compatible type.

uc_For(Counter, Start, Finish, Step, Expression)

This repeats the evaluation of Expression a certain number of times, as in a For/Next loop.  The Counter argument accepts a numeric variable, which will first be set to the value of Start, and then successively be incremented by the amount of Step until the Counter variable reaches the value of Finish, at which point the loop ends.

See this Example.

uc_Loop(DoCondition, Expression, LoopCondition)

This repeats the evaluation of the Expression argument until either DoCondition or LoopCondition is equal to 0.  The value of DoCondition is checked prior to the evaluation of the expression, while the value of LoopCondition is checked after the expression is evaluated.

New or enhanced in version 3.0

·   Min() and Max() are significantly faster.  They are now defined as native functions instead of recursive syntax macros.

Note: The following functions: ucHandle(), ucRename(), uCalc() and uCalcStr() are no longer available at the end-user level in version 3.0 as they are beyond the scope of the math parser.  See other uCalc products for such functionality.

New or enhanced in version 2.96

• Local() and Error() were added.
• ucDefine() is now available as an end-user function.
• The last argument of IIF is optional.
• SetVar (which was already in the DLL) is now declared and available.
• Exceptions are raised, or NaN or Inf are returned for a ^ b when a < 0, and b is a fractional number, and for sqr(x), log(x), and x!, when x < 0.
• The ^ operator, and sqr() and log() functions run faster.

New or enhanced in version 2.9+

• The IIF function now only evaluates either the True argument, or the False one, but not both.
• The IIF function can work with either numeric or string arguments.
• String relational (comparison) operators were added.
• There is no longer any ambiguity between the + operator, the & operator, and the AND operator, for strings and numbers.

Issues for users migrating from version 2.0

• Version 2.0 had alternative names for a number of functions / operators.  The following alternative names are no longer supported (the item in parenthesis is what remains):  Fact (!), ** (^), DIV (\), =< (<=), => (>=), = (==), | (OR), & (AND), & (+, referring to concatenate), ATN (ATAN), LN (LOG), SQRT (SQR).  You can easily re-instate any of these alternatives as needed.
• The following items are no longer pre-defined:  XOR, EQV, IMP, ASIN, ACOS, SEC, CSC, COT, Hyperbolic functions (SINH, COSH, TANH, etc.), EXP2, EXP10, LOG2, LOG10,  CONCATENATE, PI.
• Relational operators (<, >, <>, ==, etc.) now return a -1 instead of 1.  The True value is stored in the memory address returned by ucAddr(uc_True).  One way to change it back to 1 is: