uCalc Fast Math Parser

New or enhanced in V2.96

• Better documentation.  The help file includes examples for the various supported compilers, and more comprehensive explanations.  The source code in the demo is interspersed with comments.  The Spreadsheet and Equation Solver examples are included in the main zip file, instead of as separate downloads.
• Much simpler method for native callbacks.
• Local variable construct (this is used in the Equation Solver, and Summation examples).
• End-users can also use ucDefine.
• Speed.  Version 2.96 is faster than any previous version.  In some cases the difference is dramatic.
• The ^ operator, and the Log and Sqr functions are faster.
• ucParam, ucParamStr, ucParamCount, ucReturn and ucReturnStr were optimized for use with native callbacks.  Pointers are no longer necessary for achieving a faster speed than non-native callbacks.
• Operations involving an automatic conversion between Long and Double are much faster.
• PowerBASIC users in particular will notice that ucEvaluate() runs faster for them.
• ^, Log, and Sqr were improved.  If the left operand of ^ is a negative number, and the right operand is a non-integer, or the argument of Log or Sqr is negative, then it raises an exception (or returns NaN), instead of returning an incorrect value.  Also, an infix operator, such as ^, no longer causes a problem if followed by a unary operator (for instance 3 ^ - 2).
• The last argument of IIF is optional.
• Version 2.96 is better at catching errors and exceptions overall.
• ucTrigMode, which was present in 2.0 was restored.  It allows you to choose between radian, grad, or degree mode for trigonometric routines.
• ucExprThread is a new function that lets your callback know what thread the current callback is being called from.
• ucRaiseError lets your callback raise an error (based on the given error number constant).
• ucRaiseErrorMessage allows your callback to raise an error with a customized error message.
• ucReRaise lets your error handler re-raise an exception, allowing your host program to catch it with try / except (or the equivalent error handler for your compiler).
• ucErrLocation returns the location of an error in an expression.
• ucErrSymbol (formerly ucGetSymbol) returns the name of the offending symbol when an error occurs during parsing.
• The Error function lets you raise an error from within your expression.
• SetVar, which was already in the DLL, is now declared in the header / include file, and explained in the help file.  It lets your expression set the value of a variable.
• ucSetVariableValue sets the value of a variable using the variable's handle.  This is a replacement for the ucSetValueDbl routine that was available for some compilers.
• Arrays are supported.
• Both DLLs now contain version information (before, only the main DLL did).
• Unicode for VC++.
• Miscellaneous features beyond the scope of this help file (and which are subject to change):
• ~Eval (which evaluates a sub-expression in place during pre-parsing) now has sister routines ~Eval_1, which substitutes the result of the evaluation, and moves on without passing over it a second time, and ~Eval_P, which evaluates during the parsing stage.  Likewise ~Expand has a ~Expand_1 counterpart.
• Batch evaluation (for faster speed).
• ucGetCodeBlock.
• End-user routines: ucHandle(), ucRename()
• Partial list of bug fixes:
• The numeric pattern in the header / include file was fixed so that variable names that start with an "e" and a number, such as e123_somename, no longer cause a problem.
• The leading 0 in a fractional number between 0 and 1 is optional again, as it was in 2.0.  For instance .5 is accepted (as the equivalent of 0.5).
• Syntax errors in ucDefine (and related routines, such as ucDefineVariable, ucDefineFunction, etc.) will no longer cause a crash.
• ByExpr no longer has to be the last argument when present in a function definition.
• ByExpr now works with operators definitions as well.
• Defining a something such as "f(x=-1) = ..." didn't work if there was no space between the = sign and -. Fixed.
• FPU exceptions are handled more consistently.
• AndAlso, and OrElse were fixed.

uCalc FMP allows programs to evaluate math expressions that are defined at run time. It parses them, evaluates formulas and performs the calculations with extended precision via 80-bit numbers. uCalc Fast Math Parser performs everything from basic arithmetic to advanced trigonometric calculations. Ease of implementation, flexibility, sturdiness and speed are at the core of the product's design.  It includes direct support for Borland C++ Builder, Delphi, PowerBASIC (PB/DLL and PB/CC), Visual Basic (classic), Visual Basic .NET, and Visual C++.

uCalc FMP in a nutshell
Example 1: This lets the end-user evaluate an expression such as 6+4*5/2

UserExpr$ = InputBox$("Enter an expression",,"6+4*5/2")
Print ucEval(UserExpr$)   ' Returns 16

Example 2: This user expression is very rapidly evaluated in a loop
(See the demo that comes with the download for a more complete example)

UserExpr$ = InputBox$("Enter an expression",,"x^2+x+1")
xPtr = ucDefineVariable("x As Double", VarPtr(x))
ExprPtr = ucParse(UserExpr$)

For x = 1 To 1000000
   SumTotal = SumTotal + ucEvaluate(ExprPtr)
Next

uCalc FMP is used by some Fortune 500 companies from categories such as Aeronautics, Automobile, Banking, Computers, and Securities.

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 that require additional explanations.

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

operand1AndAlso 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 two are actually macro-like items instead of functions.  They 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

operand1OrElse 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 parameters

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 parameter as seed.

a, b

Returns an integer random number between a and b.

SetSyntaxParams(Params, Expression [, Thread])

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:

Example:

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.

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.

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.

uCalc(Command [, ...])

uCalcStr(Command [, ...])

uCalc and uCalcStr correspond with the uCalc function.  This allows you to expose all of uCalc's functionality to the end-user.  The end-user can use uCalc or uCalcStr in an expression just like any other function listed in this help file topic.  This function is reserved for the Standard License of uCalc FMP.

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:

ucDefine "Var: uc_True As Long = 1 ~~ Address: #", ucAddr(uc_True)

• Rnd was renamed Rand, and has additional functionality.

What you receive when you purchase a Standard License

• A license code (with instructions) that prevents the opening message box from popping up.
• The full functionality of uCalc Fast Math Parser (the less expensive Lite License has certain limitations).
• Entitlement to free upgrades for any new version released within 6 months of your purchase of version 2.96.
• Entitlement to at least one minor upgrade whenever it may be released.
• Free serial number for previous versions (upon request).

Note:  Upgrade benefits as described in previous versions will continue to be honored for those who have purchased those versions.

Lite license
The lite license is for those who want a fast math parser, but don't care for advanced features. You can always upgrade later if necessary.
You get a license code that removes the message box, but with limitations.

Lite License limitations

• Native callback routines (which are much faster) beyond those in the header/include files are reserved for Standard License customers.
• The following end-user functions (that is functions that can be used in an expression) are disabled when the Lite License option is applied:  uCalc, uCalcStr (uCalc and uCalcStr are still available at the compiler level), uc_For, uc_Loop, SetSyntaxParams, and SetVar.  Syntax constructs that are based on these (such as Macro, Local, etc) are disabled as well.
• Arrays are restricted.
• Usage of the Table and Stack types is restricted.
• ucExpand is disabled.
• You are limited to 75 syntax definitions (with ucDefineSyntax).

NOTE:  Syntax definitions found in the include file count towards the definition limit, and deplete much of the limit.  Some definitions may internally count as multiple definitions.  You can delete some definitions in the include file in order to make room for definitions of your own if necessary.  For unlimited syntax definitions, get the Standard License.

uCalc Developer Subscription
This entitles you to a license for uCalc Language Builder (Standard), uCalc Fast Math Parser (Standard), uCalc Graphing Calculator, Dacorbi Pattern Search, and all upgrades for these or any new uCalc product with a price tag of less than $1,000 released within the annual subscription period. The yearly subscription is not renewed automatically. The following year you may either re-subscribe, or if you no longer need any upgrades you may keep the product versions you already have.

Top 10 Reasons why uCalc customers said they have chosen to buy the uCalc Standard Edition:
1. Speed.  When it comes to working with multiple equations at a time, customers have mentioned that uCalc is much faster than other parsers.
2. Customers mentioned flexibility as an advantage over other parsers.
3. Customers also found uCalc FMP very easy to implement in a program.
4. Customers find it easy to add new functions, operators and variables.
5. Customers have chosen uCalc for reliability / stability / quality as they have had bad experiences with other parsers they have tried before.
6. uCalc goes beyond just math/maths expressions, as it can handle strings as well.
7. The new ability to change syntax is considered useful by some customers.
8. Customers found that the multi-threading capability was useful.
9. uCalc is good at catching exceptions and error handling.
10. Customers thought that the uCalc product technical support was beyond what they had experienced with other products.