Mutables library

A mutable is a memory location that you can write to as a side-effect of a calculation and can later read from. It can hold any Analytica data structure. There is no dependency maintenance, unlike normal Analytica flow architecture, so values you read from it don't invalidate if the mutable later changes. Mutables can be especially useful for debugging, especially with complex data structures.

The mutables library is included with Analytica 6.4 and later. It requires Analytica 6.0 or later.

Download: Mutables library.ana.

Using mutables for debugging

Mutables can be especially useful for debugging when the data structures are too complex to use ConsolePrint effectively, or contain binary data, etc.. The code you are debugging can save intermediate values in mutables, and then you can examine these later after the entire calc finishes to figure out what was going on.

Use in this way, you will usually create a Variable node to hold the mutable:

Variable debug_val ::= MutableNew( )

The code you are debugging calls

MutableSet( debug_val, some_intermediate_val );

to save the value for examination later. Then later you view it using, say

Variable ViewDebugVal ::= MutableGet debug_val )

It is best to set the CachingMethod of ViewDebugVal to Never Cache, since there is no dependency maintenance. I.e., if you rerun your algorithm and then view this result, you'll see the first value if ViewDebugVal caches. InvalidateResult(ViewDebugVal) can also be used from a button.

You can also pass mutables to a function parameter, which is sometimes useful when you have subroutines that modify a data structure.

Mutables can also be used from imperative code, but this use is strongly discouraged. There is seldom a good reason for using them in this way -- you just inherit all the disadvantages of imperative code. Analytica explicitly prohibits side-effects of expression evaluation, which promotes referential transparency. This library provides a mechanism to get around this, but its more legitimate uses are for debugging or in-memory logging use cases.

If you have a calculation that has multiple results, instead of placing the secondary results in variables that have mutables, a better option is to define the secondary result variables with the ComputedBy function.

Function Reference

MutableNew( )

Creates a new mutable -- a storage location that can be set using

MutableSet( mutable, x )

and read using

MutableGet( mutable )

Use case 1 (common for debugging)

Create a new global variable to be your mutable. The name of the variable is the name of your mutable. Its definition is:

MutableNew()

Use case 2 (Common when passing a mutable parameter to a UDF)

Local myMutableName := MutableNew();

F( myMutableName )

where F is the called UDF. Inside F it uses MutableGet and MutableSet.

You can also have mutables within a data structure, and data structures with multiple separate mutables. The data structure itself doesn't change, just the values inside the mutable elements.

MutableSet( mutable, x )

Stores the value «x» in the «mutable».

MutableGet( mutable )

Returns the current value stored in «mutable».