ucReleaseItem

See Also: ucDefine, ucDefineFunction, ucDefineSyntax, ucDefineVariable, ucParse, ucNewThread

Releases a uCalc item.

ucReleaseItem(ItemHandle)

Parameter

ItemHandle

Required. ItemHandle is the handle of an item that was defined using either uCalc, ucDefine, ucDefineFunction, ucDefineOperator, ucDefineSyntax, ucDefineVariable, ucParse, or ucNewThread.

Remarks

Virtually everything that can be defined in uCalc is given a handle. You can use this handle to release the item.

Items that are re-defined many times on a temporary basis should generally be released when the temporary definition is no longer needed.

If ItemHandle is the handle of a thread, then all items defined under that thread are released together, sparing you the need to explicitly release each individual item.

Each item is assigned a handle that is unique across the current process, regardless of which thread it belongs to. When you define an item, you tell uCalc which thread you want the definition to be associated with. uCalc keeps track of the thread an item belongs to. Thus a thread handle is not required when releasing an item (unless the item you are releasing is itself a thread).

It is possible to hide a given definition, by defining a new item with the same name and/or attributes. You can revert back to a previous definition by releasing the latest definitions. This allows you to temporarily localize a definition.

Examples:

See ucParse -- for releasing an expression and a variable

See ucDefineVariable -- for temporary localization

See ucNewThread -- for releasing a thread

New or Enhanced

• Items can be released in any order.
• You can release everything in a thread by releasing the thread itself.
• Instead of a different ucRelease method for releasing each different kind of item, this same ucReleaseItem method releases any kind of item.

Issues for users migrating from version 2.0

• In 2.0, the argument for ucReleaseExpr represented the number of expressions to release. Now, the argument for ucReleaseItem represents the handle of a the given item you would like to release. Therefore, the two are not directly interchangeable. IMPORTANT: Do not merely replace occurences of ucReleaseExpr with ucReleaseItem.
• Examples in version 2.0 showed that you could call ucReleaseExpr immediately after ucParse, even before calling ucEvaluate. This 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, 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.
• Strings are released automatically just like all other items. You do not have to perform an extra step before releasing a string.