Upgrading Issues

See Also: What's New in version 3.0?

Issues for users upgrading from 3.0 to 3.8

· The numeric value for some constants and reserved characters has changed. One should always rely on the provided constant names instead of their numeric values whenever possible.

Issues for users of version 2.96 upgrading to 3.0

In order to accelerate product development, and to make it easier to provide technical support, the interfaces for the various compilers were modified so that they are as uniform as possible. Many ways of doing things that were unique to one compiler or another were removed. Another important change is that a clearer distinction between uCalc Fast Math Parser and upcoming new uCalc products is being made. This means that special features beyond parsing and evaluating math expressions are no longer supported as part of the math parser.

· The Lite license was eliminated.

· Some previously documented features that are no longer directly supported as part of the math parser include: ucDefine() at the end-user level (it’s still supported at the source code level), ucExpand(), uCalc(), and uCalcStr().

· Support for some obscure undocumented or under-documented features was removed. This includes ucHandle(), ucRename(), ucGetCodeBlock(), ucGetNextItem(), ucInterpret() and batch evaluation.

· ucDefine(), and ucDefineSyntax() are still available. However, technical support for functionality beyond the simple examples in this help file are not covered under the uCalc FMP license.

· Some constant names have changed.

· Numeric values for some constants have changed.

· The wording of some error messages has changed.

· The numeric values for operator precedence levels have changed. Operator precedence levels remain the same relative to each other; only the numeric values themselves have changed. So for instance the numeric values for precedence levels for + and *, respectively, were 10 and 20 in version 2.96. Now, they are 50 and 60. The numeric values themselves were somewhat arbitrarily chosen; they are spaced in such a way as to allow enough new levels to be inserted between existing operators. It is generally best to define new operators relative to existing operators, using the Precedence() function, instead of hardcoding new operator definitions with literal numeric values.

· Names of DLL files have changed from ucFMP296.DLL and uCalc296.DLL to ucFMP300.DLL and uCalcLBx.DLL.

· Properties such Bootstrap were allowed at the end of a function definition. Now, such properties should always precede the rest of the definition; they should be used with ucDefine instead of ucDefineFunction or ucDefineOperator.

· ucParam, ucParamStr, ucParamCount, and ucParamHandle were renamed ucArg, ucArgStr, ucArgCount and ucArgHandle. The old names are preserved for backwards compatibility.

· ucErrSymbol, ucErrLocation, and ucErrMsg were renamed ucErrorSymbol, ucErrorLocation, and ucErrorMessage respectively. The old names are preserved for backwards compatibility.

Issues for users of versions 2.9 to 2.95 upgrading to 2.96

• Version 2.9 was completely redesigned from scratch, in order to make it possible to add powerful new features. Along with the re-design came some changes in the implementation. Unfortunately a number of apparently small changes turned out to be enough of an inconvenience for users. For instance, users missed the option of not having to place a leading 0 in fractional numbers between 0 and 1, so that .5 would be the equivalent of 0.5, for instance. The help file for 2.0 had plenty of examples for the various supported compilers, whereas in 2.9 the examples were restricted mainly to Visual Basic. And even then there weren't enough examples. The many new features in 2.9 came with a speed penalty. Speed was restored by the time 2.95 came out. However, fast native callbacks were not explained. Overall, although uCalc 2.9 introduced many new features, it was deemed more complicated by some, and required help in order to make the best use of it.

Version 2.96 was released in order to address such issues. You will find key examples for various supported compilers. Some functionality that users missed from 2.0 was restored (such as the optional leading 0 and more). ucParam, which was deemed obsolete in versions 2.9 to 2.95, was optimized and re-instated as part of native callbacks, which are faster than callbacks in 2.0. Version 2.96 was not meant to have major new features. Instead, you will find many small changes that are meant to make uCalc FMP easier for you to use.

• With the simplified syntax, new documentation, and faster speed than the previous method, native callbacks are now recommended for all callbacks where possible. Native callbacks are reserved for the Standard License.

• Those who have purchased a Standard License (or equivalent) for versions 2.9 to 2.95 will continue to be entitled to unlimited free upgrades up until (and including) 3.0, along with a free license for uCalc Language Builder when it comes out. The license was amended in version 2.96 so that new customers are entitled to at least one minor upgrade, and any upgrade (minor or major) that may be released within 6 months of their purchase; a free license for uCalc Language Builder is no longer promised.

• In version 2.96, the ucEvalStr and ucEvaluateStr output for fractional numbers between -1 and 1 now includes a leading 0 (for instance 0.5 instead of .5), while the leading 0 is now optional when such a number is part of the input.

• If you have defined multiple error handlers, then when an error or exception is raised, they will be called starting with the first one that was defined, and ending with the most recently defined one. Previously it was in that order for exceptions raised during the evaluation stage, and the reverse order during the parsing stage.

• The behavior described under Localized Variables has changed, and is subject to further change in a future version. For now, it is necessary to append "~~ Overhead" to the function definition in order for it to behave the same way as version 2.95. The added overhead slows down the function, unfortunately. There is a new feature in version 2.96 for local variables.

Issues for upgrading from 2.0 to 2.9 and above

Ignore the following if you haven't been using version 2.0. Upcoming versions are unlikely to create major incompatibilities.

An effort was made to preserve compatibility between version 2.0 of uCalc Fast Math Parser and this version where possible. In a number of cases, however, it was not possible. In order to simplify the syntax, resolve certain limitations found in 2.0, and to make this version more flexible, certain changes were required. Except for the most minimal implementations of uCalc, it might not be possible to simply re-compile your code without modification, nor is it always simply a matter of search-and-replace to make the required changes. Though you will likely not find the changes to be very drastic, it will still be important to browse through the following list to understand some of the key differences in how this version works. Many of these same items listed below can be found throughout the help file in the relevant topics.

There are two lists: 1. Things that have changed, and 2. Things that are no longer supported.

Things that have changed

• Error numbers returned by ucError, and error messages returned by ucErrorMessage have changed. See the include file for new values and messages.

• By default, relational operators (>, <, ==, etc.) now return a -1 for True instead of 1. One way to change it back to 1 is: ucDefine("Var: uc_True As Long = 1 ~~ Address: #", ucAddr(uc_True))

• Alphanumeric names by default can no longer have a period (.) in them. The period character is now reserved for member access. None of this is hard-coded, however. You can change what constitutes a valid "alphanumeric" name by doing a search for alphanumeric in the include file, and modifying the regular expression pattern you find there.

• ucDefineVariable no longer supports an optional second string parameter. The optional second parameter is now for passing the address of a variable.

• When you call ucDefineVariable with the name of a variable that was already defined, it does not replace the other variable definition, nor does it update the value of the other variable. Instead the old definition continues to co-exist with the new. The most recent definition will be the only one visible for subsequent use. If you release the newer definition, the older definition will regain its place as the visible one.

• When you re-define a function, if it has the same arguments as the previous definition, then it behaves the same way as described in the previous paragraph for variables. If the arguments are different, then they operate as overloaded definitions, meaning that the appropriate definition will be used depending on the context. For instance, if you define MyFunc(x), and MyFunc(x, y), then you can use an expression such as "MyFunc(5) + MyFunc(3, 4)".

• The following changes were made to ucDefineFunction:

* The following 2.0 way of using ucDefineFunction is no longer supported:

ucDefineFunction "FunctionName(ParamCount)", CodeAddress

Functions defined this way were faster than regular callback definitions. However, you were limited to two arguments; and they could only be numeric. Now, for even better efficiency, use Native callbacks.

* Cryptic directives, such as &, and @ are replaced with the more descriptive directives ByExpr and ByHandle.

* The special variable type argument is no longer supported. However, the new ByHandle can generally do the same thing.

* The $ directive for strings is no longer supported. Use "As String" instead. For some compilers you may need to use WideString or LPCSTR instead for your callbacks.

* For numeric types, # is not supported. Instead specify Single, Long, Double, etc. for your callbacks. If no type is specified then extended precision or double precision (depending on the compiler) is used by default.

* It is very important in this version to remember to specify data types for function arguments, as well as the function's return value; particularly for callbacks, if you are using data types other than the numeric default.

* Variable number of arguments is now denoted with three consecutive dots (...). You can have a fixed number of arguments followed by a variable number of arguments. In 2.0, you didn't have the choice of requiring some arguments if you also had a variable number of args. Also, you now have the option of restricting the data type of the variable number of args.

• ucParamCount now requires a parameter. ucParam and ucParamStr now have two arguments. See the MyAverage() function in the demo file.

• Operator definition changes:

* Operators can no longer be defined with ucDefineFunction. Now, a separate function, ucDefineOperator, is used for that purpose.

* In 2.0 when you defined an operator, it also defined a function of the same name. It is no longer done that way. When you define an operator, it will only work in the capacity of an operator.

• Changes regarding ucReleaseExpr:

* ucReleaseExpr was removed, and replaced with ucReleaseItem. IMPORTANT: You should not merely replace occurrences of ucReleaseExpr in your code with ucReleaseItem, as they work very differently. The old ucReleaseExpr was capable of releasing expressions only in sequential order. And if you supplied an argument (which was optional), it would release that number of recent expressions.

With the new ucReleaseItem, you can release individual items in any order. The argument passed to ucReleaseItem is the handle of the specific item you want to release. Anything you can define (an expression, function, variable, thread, syntax, pattern, etc.) is now an item. Each item has a handle, and can be released using this handle.

* Examples in version 2.0 showed that you could call ucReleaseExpr immediately after ucParse, even before calling ucEvaluate. That was OK in version 2.0, because ucReleaseExpr simply set a marker for the data to be overwritten later. However, now, ucReleaseItem actually releases the item from memory immediately, after which you cannot use the item any more.

* An item that is incorrectly defined is automatically released, and has a handle of 0. ucReleaseItem(0) simply does nothing. So it is always OK to release an item, without first checking to see if it has a non-0 handle.

* ucReleaseVariable was also removed and replaced with ucReleaseItem. The help file in version 2.0 mentioned an extra step to take when releasing a string variable. That step is no longer necessary.

* ucReleaseItem as defined in the include file releases an item by handle. To release an item by name, simply use uCalc(uc_ReleaseItem, "MyItem"), where MyItem is the name of your variable, function, or any other named item.

• ucReset changes. ucReset itself was removed and some of its functionality replaced. ucReset was a multipurpose routine. So each aspect will be discussed separately:

* Releasing everything. Apparently many users used ucReset in this way due to the limitations of ucReleaseExpr. In such cases, you can now use the more flexible ucReleaseItem. However, you still can release everything defined in a given thread (including its sub-threads), by invoking ucReleaseItem with the handle of the thread you want to release. Be careful when releasing the default thread, as you might need to re-define everything as found in the Initialization section of the include file (since there are no "built-in" operators, functions, syntaxes, etc.).

* Allocating definition space. This is now irrelevant, as definition space is allocated automatically as you go along. You do not have to allocate a maximum chunk of memory ahead of time and worry about whether you might reach that limit.

* Setting Relational True. The Language Builder does not have "built-in" relational operators. However, the same library from which FMP's relational operators are defined also has a provision for changing the True value. ucAddr(uc_True) contains a 32-bit memory address that contains the value for True. The default is now -1 instead of 1.

* Precedence level. Each operator can now be defined with its own precedence level at the moment it is defined. Still, you can set/retrieve the default level by calling uCalc() with uc_SetDefaultPrecedence or uc_GetDefaultPrecedence if you want. However, explicitly assigning a level in each operator definition is recommend. Even after an operator is defined, you can change its precedence level by calling uCalc() with the uc_Precedence property. Precedence levels can be any arbitrary positive integer value less than 2^31, deriving its meaning by whether this value is greater or less than the precedence levels of other given operators. In 2.0, you were limited to values between 1 and 22 (which was the level range of hard-coded built-in operators).

* Precedence levels for operators are no longer hard-coded. They are defined in the include files. You can change the levels there, or you can even change them during runtime. In version 2.0, you could only set the precedence levels for user-defined operators, and then it was one level for all user-operators.

* DecimalSeparator and ArgumentSeparator. Use ucDefineSyntax for this instead.

• Strings are handled very differently. Here are the changes:

* Technically the uCalc Language Builder (which is used by uCalc FMP) does not have "built-in" support for strings, or any kind of data type for that matter. Instead it allows you to define data types yourself. A library of common types from which to choose from is included in the DLL, some of which are declared in the header / include file for your compiler, so you don't have to start entirely from scratch. String types chosen in the include file for uCalc FMP (you can add to, remove, or rename them as needed), include: String (dynamic multi-byte ansi string; default), WideString (Unicode), LPCSTR (null-terminated), and FixedString (fixed length strings). You must specify an appropriate string type, especially for callback definitions. See the demo file for your compiler to see which kinds of string types are appropriate for your callback routines.

* The $ character no longer designates a function or argument as a string during definition. Instead, use "As String" (or As LPCSTR, etc.). If you are using the Language Builder, you can define a syntax that uses the $ in the same way as BASIC, if you prefer. (The usage of $ in version 2.0 was vaguely reminiscent of, but not consistent with the $ string notation of BASIC).

* ucSetParamStr(0, ...) is replaced with ucReturnStr.

* The single quote (') and double quote (") delimiters for string literals were hard-coded in version 2.0. Now, this syntax is defined in the include file, and can be changed either there, or during runtime.

* The & operator is no longer hard-coded as a concatenation symbol, nor is the Concatenate() function, though you are free to define them again (there are several ways of doing this).

* Passing a string argument in place of a numeric expression where a ByExpr (formerly expression type) argument is expected is no longer supported. Instead you can define a ByExpr argument As String, or as any other given numeric or other type. It would no longer make sense for uCalc to force a string arg to convert into a numeric expression if that's not your intention. You can simulate the old behavior by receiving a string and using ucEvalStr on the argument once inside the callback.

• Error handling has changed. You can still check the value of ucError after evaluating an expression, if you want. However, the new and improved way is to define one (or more) error handling callback routine(s), which can handle all errors wherever they may occur. With this, it is no longer necessary to use ucError throughout your code like before. The new method requires less code, and is also more efficient.

Also, you have full control of the FPU word, which can for instance, decide whether 1 / 0 should raise an error, or be treated as the numeric value of Inf. The demo shows one of the ways to control the FPU.

Something important to all users, even if you don't care anything about FPU control per se, is that uCalc maintains a separate FPU word from that of your host program, and both are insulated from each other. The end result is that this resolves a problem that some users reported, which was caused by their host program changing the FPU setting (without the programmer being aware), and preventing uCalc from working.

Overflow, Underflow, and other FPU exceptions can directly be controlled by uCalc.

• Some of the contact info found in the old help file is outdated. The preferred contact information can be found at www.ucalc.com/contact.html

• All of uCalc's functionality is encapsulated in an exported function named uCalc. You will notice that almost all routines in the include files are merely wrappers to this uCalc function. Advanced users can gain further functionality with direct calls to uCalc or ucDefine.

Features that were removed in 2.9

• Some user-level functions or operators were defined with several alternative names in version 2.0. For instance, both Fact and ! for factorial. The following alternative names are no longer included (the item in parenthesis is what remains): Fact (!), ** (^), DIV (\), =< (<=), => (>=), = (==), | (OR), & (AND), & (+ as in concatenation), ATN (ATAN), LN (LOG), SQRT (SQR). You can easily re-instate any of these as needed.

• The following functions, operators, or constant(s) aren't present in this version: % (percentage), XOR, EQV, IMP, ASIN, ACOS, SEC, CSC, COT, Hyperbolic functions (SINH, COSH, TANH, etc.), EXP2, EXP10, LOG2, LOG10, CONCATENATE, PI. The programmer can define some of these on his/her own if needed.

There are in fact no longer any "built-in" functions, operators, or constants at all. Some common items, such as arithmetic, trigonometric, and miscellaneous items are included in a library in the DLL, and are activated in the header / include file. You can remove, rename, or add items to the list. You can implement new items using the same kind of native callback procedures as the ones in the library, achieving the same maximum speed.

• ucAlias was removed. Its functionality can be duplicated (and is greatly superceded) with ucDefineSyntax. For the renaming aspect of ucAlias, see the RenameItem function defined in the Library.uc file that comes with the uCalc Language Builder (downloadable from www.ucalc.com).

• Implicit multiplication is only partially supported. If a number is followed by an alphanumeric word, it will be treated as a multiplication. However two consecutive alphanumeric words will not be treated as a multiplication.

• ucErrorData, along with ucGetErrorData and ucSetErrorData were removed. Use ucErrSymbol within an error handler callback in place of ucGetErrorData.

• ucReset was removed. See earlier explanation.

• ucIsString was removed. As documented, ucIsString was quite limited. Use uCalc(uc_GetItemData, ...) instead. You can now determine the data type (not just whether or not it's a string), as well as other properties of an item. See ExprType in the Library.uc file of the uCalc Language Builder for an example of how to determine the data type of an expression.

• ucSetParamStr, and ucParamStr functionality in the context of ucPreParse is no longer available, since pre-parsing itself is no longer available.

• ucPreParse is no longer supported. The main example in version 2.0 involved two alternatives of a function definition. Now, you can directly define multiple versions of a function without doing anything extra for it to work. For aspects of ucPreParse's functionality dealing with expressions, use ucDefineSyntax instead.

• ucVariableValue, ucGetVariableValue, ucVariableValueStr, ucGetVariableValueStr were removed. These are now irrelevant under the new way of doing things, as you can now attach a uCalc variable directly to the address of a variable in your source code (except in VB.NET). This results in less code, which also runs faster. See the source code for the Plot or Sum examples in the demo program.