ucParse

See Also: ucEvaluate, ucReleaseItem

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. An expression may also consist of multiple statements separated by a semi-colon (;). 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 more straightforwardly with ucEval, the advantage of using ucParse and ucEvaluate separately is a question of 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 an expression, since appropriate conversions will automatically take place where applicable. Numeric expressions default to Extended precession, which is what ucEvaluate returns. In some compilers the return value of ucEvaluate is first converted to Double. Advanced users may create a version of ucEvaluate that is optimized for a given type other than Extended.

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. 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, who's 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:

' Note: use Extended precision instead of Double

' for better speed if your compiler supports it

Dim ExprPtr As Long, xPtr As Long

Dim x As Double, SumTotal As Double

Dim MyExpression As String

MyExpression = InputBox("Enter an expression", "Example", "x^2 + 5")

xPtr = ucDefineVariable("x As Double", VarPtr(x))

ExprPtr = ucParse(MyExpression)

For x = 1 To 5000000

SumTotal = SumTotal + ucEvaluate(ExprPtr)

Next

' Display SumTotal

ucReleaseItem ExprPtr

ucReleaseItem xPtr

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.

tHandle = ucNewThread()

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

Expr2 = ucParse("9 / 3", tHandle)

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

Print ucEvaluate(Expr1) ' Returns 2

Print ucEvaluate(Expr2) ' Returns 3

Print ucEvaluateStr(Expr3) ' Returns Hello World

ucReleaseItem(tHandle) ' Releases all 3 expressions

New or Enhanced

• You should notice speed improvements.
• You can specify a return type.
• You can specify a thread handle

Issues for users migrating from version 2.0

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