Handle Functions

What's new in Analytica 4.0? >

About Handles (varTerms)

A handle (sometimes known as varTerm) is a reference or pointer to a variable, index, module or other Analytica object. Using a handle lets you write variables or functions that works with the object itself rather than the value of the object. Usually, if you refer to variable X in an expression, say as:

Variable X := 100
Variable A := X

The value of A will be equal to the value of X, namely 100. But if you write:

Variable B := Handle(X)

Using a Handle lets you find or change the Title, Description, Inputs or Outputs. You can also create and use lists of handles to objects. For example, the list of indexes of an array, or the inputs or outputs of a variable.

The title acts as a link. Double-click on it and it will open an Object view of C.

If you define a variable:

Variable A := [X, Y, Z]

where X, Y, and Z are variables. The value of A will be the result of evaluating X, Y, and Z. But the index value of A is a list of handles to X, Y, and Z. This index will usually show the titles of X, Y, and Z. If you double-click any of the titles in the index, it will open the Object view for that object. If "Show By Identifier" is on (from the Object menu, or if you toggle it with control-Y), they will show the identifier rather than title. But either way a double click will open the object view.

Some attributes consist of lists of handles, notably Inputs, Outputs, and Contains (the objects in a module). You can use these to write functions to find the ancestors, descendants, or contents of an object.

Function VarTerm

The VarTerm function returns a varTerm (a handle to an object) from an identifier.

Function VarTerm( X : VariableType ; AsIndex : optional boolean atomic )

If you want to create a user-defined function that returns a varTerm, in most cases the return value needs to involve a call to the VarTerm function. If you simply place the identifier of a local variable (even if it declared as VariableType) as the return value, it will be evaluated. For example, consider these two functions:

Function Fu1( X : VariableType ) := X
Function Fu2( X : VariableType ) := VarTerm(X)
Variable Va1 := 5

Suppose you evaluate Fu1(Va1) and Fu2(Va1). Fu1 returns the value of Va1, that is 5. Fu2 returns a handle to the Va1 object. Hence, to return a varTerm, a call to Function VarTerm was necessary.

You can declare a local variable to be a varTerm using, for example,

var a := VarTerm(Va1) do ...

where Va1 is the identifier of an object. In the scope of this var declaration, a then becomes an alias for Va1. In other words, anywhere you might use the identifier Va1 in an expression, you could equivalently use a.

To create an alias to an index, use

var I := VarTerm( In1, AsIndex:True ) do ...

The local variable I will then serve as an alias to the original index In1 inside the scope of this var statement. The AsIndex parameter causes I's index values to be used when I appears in a value context (this is relevant when the original object is a self-indexed array, having both a value and an index value).

When an index contains varTerms, and you wish to subscript across that index, the recommended syntax is:

 A[ I = VarTerm(x) ]

In this example, x would be the identifier appearing as one of the elements of I.

Function GetVariableByName

GetVariableByName( varName : atmoic text )

Finds an object in the global namespace having the indicated name and returns a varTerm (i.e., object handle) to that object. If no such object exists, returns Null (use IsUndef to test for null if you worry about backward compatibility).

One danger with using this function is that Analytica has no dependency influence information. For example, the following expression

 var x := GetVariableByName("Va1") do x

evaluates Va1 and returns that value; however, if Va1 were to change, Analytica would have no way of knowing that this result needs to be invalidated. Obviously, in this example, it would better to use just the identifier Va1 in the expression, but as a basis of comparison, note that Analytica would be aware of the dependency influence if this variation were used:

 var x:= VarTerm(Va1) do x

If the value of Va1 changes, it would know that this value needs to be re-computed.

Function IndexesOf

IndexesOf( A : Array )

Returns a list of varTerms, each one serving as a handle to the indexes of array A.

This is similar to IndexNames(A), except that IndexesOf returns actual varTerms, while IndexNames returns the index identifiers (as text strings).

It is possible for an array to have more than one local index having identical names. Obviously, this is not recommended, but in the unusual case where this occurs, the index handles returned by IndexesOf are unambiguous.