View source for Handles to Objects

[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs><br />

A handle is a pointer to a variable, function, module, or other object. Using a handle lets you write variables or functions that work with the object itself, for example to access its attributes — instead of just its value which is what you usually get when you mention a variable by identifier in an expression.

===Viewing handles===
In a table result, a handle in an index or content cell usually shows the title of the object. If you select '''Show by identifier''' from the [[Object menu]] (or press ''Control+y''), it toggles to show identifiers instead of titles (as it does in the node diagrams). If you double-click a cell containing a handle (title or identifier) it opens its [[Object window]] (as it does when you double-click a node in a diagram). 

===Attributes that contain handles===
The attributes, <code>inputs, outputs</code>, and <code>contains</code> (the list of objects in a module) each consist of a list of handles to objects. The attribute <code>isIn</code> is a single handle to the module that contains this object — the inverse of <code>contains</code>.

==List of variables: [v1, v2, ... vn]==
If you define a variable as a list of variables, for example,

:<code>Variable A := [X, Y, Z]</code>

the variable will have a self index that is a list of handles to those variables. In a table result view of <code>A</code> (or other variable that uses this index), the index <code>A</code> will usually show the titles of the variables. See [[Functions_that_create_indexes#List_of_variables|List of variables]] for more. In an expression, the handles in the self index can be accessed using [[IndexValue]](A). The main value of <code>A</code> (either mid value or a probabilistic view of <code>A</code>) contains the results of evaluating <code>X</code>, <code>Y</code> and <code>Z</code>.

== Handle(o) ==
Returns a handle to an Analytica object, given its identifier «o». 

:<code>Handle(Va1) &rarr;¨Va1</code>

== HandleFromIdentifier(text) ==
Returns a handle to global object (i.e., not a local variable or parameter), given its identifier as «text». See [[HandleFromIdentifier]]()

:<code>Variable B := 99</code>
:<code>HandleFromIdentifier("B") &rarr; Va1</code>

The dependency maintenance is unaware of the dependency on the object. Hence, any changes to the variable <code>B</code> above will not cause the result to recompute.

== ListOfHandles(identifiers...) ==
Returns a list of handles to the specified Analytica objects, given their «identifiers». See [[ListOfHandles]]().

:<code>ListOfHandles(Va1, Va2, Va3) &rarr;¨ [Va1, Va2, Va3]</code>

== Indexes of Handles ==

=== MetaOnly attribute ===
When an index object is defined as a list of identifiers, the <code>MetaOnly</code> attribute controls whether it is treated as a general index or a meta-index. Meta-indexes are useful when reasoning about the structure or contents of the model itself. A general index evaluates the variables appearing in its definition to obtain its mid or sample value, and the values that are recognized by Subscript (i.e., [[Subscript-Slice_Operator|a[i=x]]]), while a meta-index (having its <code>MetaOnly</code> attribute set to 1) does not evaluate the objects in the list. The following comparisons demonstrates the similarities and differences.

:<code>Constant E:= exp(1)</code>
:<code>Variable X := -1</code>

:{| class="wikitable"
! General Index
! Meta-Index
|-
| style="width:300px;" | <code>Index I0 := [E, X, Pi,True]</code>
| style="width:300px;" | <code>Index I1 := [E, X, Pi,True]</code>
|-
|style="width:300px;" | <code>MetaOnly of I0 := 0 {or not set}</code>
|style="width:300px;" | <code>MetaOnly of I1 := 1</code>
|-
|style="width:300px;" | <code>Variable A0 := Table(I0)(1, 2, 3, 4)</code>
|style="width:300px;" | <code>Variable A1 := Table(I1)(1, 2, 3, 4)</code>
|-
|style="width:300px;" | <code>IndexValue(I0) &rarr; [E, X, Pi, True]</code>
|style="width:300px;" |<code>IndexValue(I1) &rarr; [E, X ,Pi, True]</code>
|-
|style="width:300px;" |<code>Mid(I0) &rarr; 2.718, -1, 3.142,1]</code>
|style="width:300px;" |<code>Mid(I1) &rarr; [E, X, Pi,  True]</code>
|-
|style="width:300px;" |<code>A0[I0 = Handle(E)] &rarr; 1</code>
|style="width:300px;"|<code>A1[I1 = Handle(E)] &rarr; 1</code>
|-
|style="width:300px;" |<code>A0[I0 = Handle(True)] &rarr; 4</code>
|style="width:300px;" |<code>A1[I1 = Handle(True)] &rarr; 4</code>
|-
|style="width:300px;" |<code>A0[I0 = E] &rarr; 1</code>
|style="width:300px;" |<code>A1[I1 = E] &rarr; Error:-2.718 not in I1</code>
|-
|style="width:300px;" |<code>A0[I0 = -1] &rarr; 2</code>
|style="width:300px;" |<code>A1[I1 = -1] &rarr; Error:-1 not in I1</code>
|-
|style="width:300px;" |<code>A0[I0 = True] &rarr; 4</code>
|style="width:300px;" |<code>A1[I1 = True] &rarr; Error:1 not in I1</code>
|}

== LocalIndex..Do ==
The construct, <code>[[LocalIndex]] i := indexExpr</code>, declares a local meta-index (see [[Local Indexes]]). This should generally be used in lieu of the Index <code>Index i := indexExpr</code> construct when «indexExpr» evaluates to a list of handles.

:<code>[[LocalIndex]] I := [[Contains]] [[of]] Revenue_Module;</code>
:<code>[[Description]] [[of]] (I)</code>

See more at [[Local..Do]]

== IndexesOf(X) ==
Returns the indexes of an array value as a list of handles. The first element of the list is [[null]], rather than a [[handle]], when «X» has an [[implicit dimension]] (also known as a '''''null-index'''''). See also [[IndexesOf]].

== Local Variables and Handles ==
When you declare and use local variables that might hold handles, you should declare these local variables using [[Local..Do]] or [[LocalAlias..Do]], rather than [[Var..Do]] or [[For..Do]]. When local variables hold handles, there are two semantic interpretations — the local variable could either be a storage location for a handle to an object, or it could act as an alias to the object. The [[Local..Do]] or [[LocalAlias..Do]] declarations makes this distinction clear.

== Local..Do ==
The construct, <code>Local temp := expr</code>, declares a local variable named «temp» that holds an atomic value or an array of values, some of which might be handles. When the value is a handle, the handle is treated as just another entity, whose datatype happens to be a handle. If you assign another handle or value to «temp», you simply change the contents of the local variable, and do not alter the object that the handle points to. Use this construct to manage collections of handles.

:<code>[[Local]] hRevModule := [[Handle]](Revenue_module);</code>
:<code>[[Local]] hExpModule := [[Handle]](Expense_module);</code>
:<code>[[Local]] m := [hRevModule, hExpModule];</code>
:<code>...</code>

For the next example, suppose a global variable named <code>Hy</code> exists with a definition of <code>Handle(Y)</code>. 

:<code>[[Local]] a := [[Handle]](X);</code>
:<code>a := Hy</code>

Following the assignment, the local variable <code>a</code> contains a handle to <code>Y</code>. The variable <code>X</code> is unaltered. You should compare this to the same example using [[LocalAlias..Do]] in the following section.

When you need to iterate over a collection of handles, you can use, e.g.,

:<code>[[Local]] h[ ] := [[Contains]] [[Of]] Revenue_module;</code>

== LocalAlias..Do ==
The construct, <code>[[LocalAlias]] temp := expr</code>, evaluates «expr» and declares a local variable named «temp» that holds a single atomic value. When «expr» evaluates to a handle, the local variable identifier acts as an exact alias to the object pointed to by the handle.

:<code>[[LocalAlias]] r := [[Handle]](Rate_input) Do r := r * 1.1</code>

The preceding expression is functionally identical to<ref>This expression contains a side-effect to a global variable. Side-effects to global variables are only allowed in expressions or user-defined functions that are run directly from button scripts. This would cause an error if attempted from a variable’s definition.</ref>

:<code>Rate_input := Rate_input * 1.1</code>

For the next example, suppose a global variable named <code>Hy</code> exists with a definition of <code>Handle(Y)</code>.

:<code>[[LocalAlias]] a := [[Handle]](X)</code>
:<code>a := Hy</code>

This expression is functionally identical to

:<code>X := Hy</code>

The expression, if evaluated in a context where side-effects are permitted, would alter the definition of <code>X</code>. Following the assignment to <code>a</code>, the local variable <code>a</code> continues to be an alias to <code>X</code>. You should compare this to the same example for [[MetaVar..Do]] in the preceding section.

When «expr» is an array of handles, then the body expression is iterated for each alias. The following expression increases the definition of every global variable within an indicated module to a value 1.1 times its initial value.

:<code>[[LocalAlias]] x := [[Contains]] [[of]] Input_module;</code>
:<code>x := x * 1.1</code>

The rule for [[LocalAlias]] is that the result for the expressions using «temp» are identical to what you would get if you replaced every occurrence of  «temp» within those expressions with the identifier for the variable pointed to by the handle, and then evaluated the expressions<ref>Not every object in Analytica lives in the global namespace (e.g., local indexes), so this rule doesn’t literally apply for handles to objects not in the global namespace. For these, we cannot replace the local name with an identifier since no global identifier exists for the object pointed to by the handle.</ref>.

An easy mistake to make when using [[LocalAlias]] is to forget that «expr» is evaluated before the assignment. This feature allows you to compute the handle to the object that will be aliased, but it also means that you need to remember to surround an identifier with a call to [[Handle]]() when you just want a simple alias. If you write

:<code>[[LocalAlias]] x := y</code>

then this assigns to «x» the value of «y», not a handle to the object «y». If «y» happens to hold a handle to <code>z</code>, then «x» becomes an alias to <code>z</code>, not an alias to «y». To obtain an alias for «y», you must use 

:<code>[[LocalAlias]] x := Handle(y);</code>

You can assign non-handle values, such as numbers and text, to a [[LocalAlias]] variable. When you do so, the local variable identifier serves as an alias for a single value, and is the same as 

:<code>Local temp[] := expr;</code>

== Conversions between Local and LocalAlias ==
When writing expressions that manipulate handles in local variables, you may sometimes need to convert between [[Local]] and [[LocalAlias]] semantics. When a [[Local]] holds a handle, its value is an entity with the data type of handle. Since subtraction is not defined for a handle, the following expression is an error

:<code>[[Local]] hr := [[Handle]](Revenue) Do hr - Expenses { Error }</code>

The expression is attempting to subtract the value of expenses (a number) from a handle. In this example, we need the [[LocalAlias]] semantics instead, so given <code>hr</code> we can convert using

:<code>[[Local]] hr := [[Handle]](Revenue);</code>
:<code>[[LocalAlias]] r := hr;</code>
:<code>r - Expenses</code>

A [[Local]] can also be dereferenced by using the [[Evaluate]]() function: 

:<code>[[Local]] hr := [[Handle]](Revenue) Do [[Evaluate]](hr) - Expenses</code>

In the other direction, when a [[LocalAlias]], <code>r</code>, is an alias for another object and you need the handle to the object, use <code>[[Handle]](r)</code>. It is legal to use the [[Handle]]() function on a local variable declared using [[LocalAlias]], but it is an error to apply the [[Handle]]() function to a local variable defined using [[Local]]. This is because a local variable is not an object (it is just a name for a value), and since handles can only point to objects, there is no such thing as a handle to a local variable<ref>A local index is an object, so you can have a handle to a local index. The [[LocalIndex..Do]] and [[Index..Do]] constructs create an index object, along with a local variable name that has [[LocalAlias]] semantics for the index object.</ref>.

==Notes==
<references/>

== See Also ==
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Handle]]
* [[Objects and Values]]
* [[ListOfHandles]]
* [[HandleFromIdentifier]]
* [[Handle Functions]]
* [[Local Indexes]]
* [[IndexesOf]]
* [[LocalAlias]]
* [[LocalAlias..Do]]
* [[Local..Do]]
* [[LocalIndex..Do]]
</div>


<footer>References and Data Structures / {{PAGENAME}} / Dialog Functions</footer>