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.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.

 

 

 

 

 

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

 

 

 

 

 

 

* 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.

 

 

* 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.

 

* 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.

 

* 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.

 

* 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.

 

 

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.

 

 

 

 

Features that were removed in 2.9

 

 

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.