Variable use in functions

Important note: all examples follow aTbRef naming conventions.

Uses of variables in functions

There are three ways that a variable are used in functions:

as a local variable, just like any other use of variables in Action code;
as an "argument" variables used to receive the data passed from the calling code;
as "loop" variables that will be local to the loop code, just like any other use of loop variables.

Defining a variable in a function

A function variable is defined exactly the same way as in other action code:

var vThing;

As the basic assumed data type, if not set, is a String, it can be more helpful to use explicit typing, whether or not a value is applied straightway. The point is that the variable has a notified data type from the outset, rather than one coerced by Tinderbox based on context of use:

	var:string vThing;
	var:number vCount;
	var:date vNow = date("today");
	var:boolean vBoolean = true;

A variable needs to be defined before first use, as with attributes. It makes good sense to define variables at the start of the function, noting that loop variables are defined in the loop operator. Do consider also adding comments about the variable's purpose, as once written the code may only be re-read occasionally and the code's intent may get forgotten over time.)

Using variables to set data type of inputs

The data type of input arguments can be specified making the usage below obsolete. See Function arguments.

Legacy. Previously, as from v9.1.0, the function's arguments when accessed from within the function supply String-type data (this is regardless of the data type supplied in the action calling the function). Thus, to avoid unexpected type coercion, e.g. Date being misread as a String, it can be useful to pass an argument into a typed variable before using the argument value in the functions action code:

	function fMakeTable(iSomeList){
		var:list vList = iSomeList;
		vList.each(anItem){
			// ..tc.
	}

Variable duration

Variables created in a function are destroyed when the function execution completes. If a variables value is needed, other than as a return value, the value will need to be passed to an attribute for more persistent storage.

Variables only exist while the function is being executed after having been called. Whilst variables are most often used to temporarily keep intermediate results while the function is executing, if a variable holds some value that is needed elsewhere, it should either be passed back to the calling code via the return operator or an attribute should be assigned to the variable's value. Some examples of assigning attributes to function variables are:

	// ...
	$MyString = vString;
	$SomeNumber ("config-note") = vCount;
	// ...

In the first case, $MyString in the calling note is set. In the latter case, $SomeNumber in note "config-note" is set. The choice of where a stored value is saved is dependent on the wider context of use, i.e. there is no single 'correct' choice.

A variable may be used as an input argument for a call to another function:

	// ...
	var:string vString = "Testing!";
	fAnotherFunction(vString){
	 // ...

Variable scope

A variable created in a function is only accessible from within that same function. For experienced programmers this may seem unexpected (see more) and may change in the future. At present, a variable should only be used within the function in which it is defined.

Next: Attributes vs. variables in functions

See also—notes linking to here:

Function arguments