{ Analytica Model Mutables_library, encoding="UTF-8" }
SoftwareVersion 6.3.6

{!-60000|Attribute AcpStyles}


LinkLibrary Mutables_library
Title: Mutables library
Description: 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, so values you read from it don't invalidate if the mutable later changes. ~
~
Mutables can be especially useful for debugging certain types of things. 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. They are nice when the data structures are too complex to use ConsolePrint effectively, or contain binary data, etc.~
~
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.~
~
Mutables can also be passed 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.~
~
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.
Author: Lonnie Chrisman, Ph.D.~
Lumina Decision Systems
Date: Thu, Aug 17, 2023 3:51 PM
NodeSize: 64,24
DiagState: 2,0,0,927,200,17,10
WindState: 2,98,82,875,619
FontStyle: Arial,15
FileInfo: 0,LinkLibrary Mutables_library,2,2,1,0,Mutables library.ana
{!40600|Att_WikiHelpURL: [wiki]}

Index Struct_Mutable
Title: Struct_Mutable
Description: This defines a mutable record. A mutable consists of two methods: get and set.
Definition: ['get','set']
NodeLocation: 160,80,1
NodeSize: 72,24

Function MutableNew( )
Title: MutableNew
Description: Creates a new mutable -- a storage location that can be set using ~
	MutableSet( mutable, x )~
and read using~
	MutableGet( mutable )~
~
To use: ~
• Use case 1: Common for debugging.~
	Create a new global Variable node to be your mutable. The name of that variable is the name of your mutable.~
• Use case 2: Common when passing a mutable parameter to a UDF.~
	Used when the called UDF will change the value.~
~
		Local myMutableName := NewMutable();~
		F( myMutableName )~
~
	The called UDF, F, calls MutableGet and MutableSet.~

Definition: Local val := null;~
Array(Struct_Mutable, [~
	Function get( ) : val Do get,~
	Function set( x ) : (val := x) Do set~
])
NodeLocation: 360,80,1
NodeSize: 64,24
WindState: 2,840,38,720,600

Function MutableGet( mutable : [Struct_Mutable] )
Title: MutableGet
Description: Returns the current value stored in «mutable».
Definition: If not HasIndex(mutable, Struct_Mutable) Then~
	Error( "The parameter to MutableGet is not a mutable. " +~
		    "You need to pass a value created by MutableNew()" );~
~
Function get( ) := mutable[Struct_Mutable='get'] Do get()
NodeLocation: 520,80,1
NodeSize: 64,24
WindState: 2,826,255,720,350

Function MutableSet( mutable : [Struct_Mutable] ; x )
Title: MutableSet
Description: Stores the value «x» in the «mutable».
Definition: If not HasIndex(mutable, Struct_Mutable) Then~
	Error( "The parameter to MutableSet is not a mutable. " +~
		    "You need to pass a value created by MutableNew()" );~
~
Function set( x ) := mutable[Struct_Mutable='set'] Do set(x)
NodeLocation: 680,80,1
NodeSize: 64,24
WindState: 2,826,255,720,350

Close Mutables_library