ucParse

ucParse

Parses an expression and returns a handle for use with ucEvaluate.

ucParse(Expression [, ExprType [, tHandle]])

-or-

ucParse(Expression, tHandle [, ExprType])

Parameters

Expression

Required. Expression is a string argument such as "x ^ 2 + 3" that you want to parse. It may also be multiple expressions separated by a semi-colon (;), in which case the return value is that of the last expression. ucParse takes the expression as a string, and breaks it down into simple binary instructions for later use with ucEvaluate. Although you can evaluate an expression in one step with ucEval, the advantage of using ucParse and ucEvaluate separately is maximum speed. If you will be evaluating an expression millions of times in a speed-critical loop, you can do the more time-consuming parsing step just once with ucParse, prior to the loop, and then use ucEvaluate(), which has a much lighter load, within the loop.

ExprType

Optional. You can specify the return type of an expression. In most cases, you can omit this optional argument, and not worry about the type of the expression, since appropriate conversions will automatically take place where applicable.

ucEvaluateStr will return the result of an expression of any type, and you can use this to coerce your results to a given type as in the following example:

Expr = ucParse("1.4 + 2.4", ucLong)

Print ucEvaluateStr(Expr) ' Returns 4 instead of 3.8

tHandle

Optional. This represents the thread handle for the thread in which the expression is defined. If this argument is omitted (or has a value of 0), then the expression is placed in the default thread.

Generally, each expression that you parse should be released at some point when it is no longer needed. You can, however, parse expressions and define other items into a given thread, using this argument, and instead of releasing each item individually, you can release everything in the thread altogether by calling ucReleaseItem with the thread handle. See Thread Handling.

Remarks

The value returned by ucParse is a handle to be used with ucEvaluate, or ucEvaluateStr. Once you are finished with an expression, use this same handle with ucReleasItem to release the expression.
The second and third arguments can be swapped. That is because both are handles to items, whose properties are checked to determine which is which before proceeding. So if you will constantly be using the thread argument, and not the type handle, you can simply use the thread handle as the second argument. So, provided that tHandle is a valid thread handle:

Expr = ucParse("x+y", 0, tHandle)

is equivalent to:

Expr = ucParse("x+y", tHandle)

Example 1: Fast evaluation millions of times in a loop

The following example is an adaptation of the Summation example found in the demo program that comes with uCalc FMP. It demonstrates the speed of using ucParse() first, and then ucEvaluate() separately, inside a calculation loop that is repeated many times. It performs a summation on a user-supplied math expression, such as: x^2+5*x-10, from 1 to 2000000.

Visual Basic (classic)

Dim ExprHandle As Long, xHandle As Long

Dim x As Double, SumTotal As Double

Dim UserExpression As String

UserExpression = InputBox("Enter an expression", , "x^2+5*x-10")

xHandle = ucDefineVariable("x", VarPtr(x))

ExprHandle = ucParse(UserExpression)

For x = 1 To 2000000

SumTotal = SumTotal + ucEvaluate(ExprHandle)

MsgBox Str$(SumTotal)

ucReleaseItem ExprHandle

ucReleaseItem xHandle

Examples for other compilers

Example 2:

In this example, various expressions are parsed independently. They are placed in the same thread so that they can be released altogether with one command.

Visual Basic

Dim x As Double

TempThread = ucNewThread()

ucDefineVariable "x = 2", VarPtr(x), TempThread

Expr1 = ucParse("1 + 1", TempThread)

Expr2 = ucParse("9 / x", TempThread)

Expr3 = ucParse("'Hello ' + 'World'", TempThread)

Print ucEvaluate(Expr1) ' Returns 2

Print ucEvaluate(Expr2) ' Returns 4.5

Print ucEvaluateStr(Expr3) ' Returns Hello World

ucReleaseItem(TempThread) ' Releases all 3 expressions and the variable definition

Issues for users migrating from version 2.0

Expressions parsed with ucParse are now released with ucReleaseItem instead of ucReleaseExpr