Additional examples

Important note: all examples follow aTbRef naming conventions.

---

If you are starting here for cut-'n-paste samples, do take time to read this whole section. If new to action code functions, it will help to have a baasic understanding of what fu ctions do.

Basic example

A simple function might be written to return a number with an 18% tax uplift applied to the input number:

function fAddTax(iPrice){return(1.18*iPrice);}; 

or, split out only lines for clarity:

	function fAddTax(iPrice){
		return(1.18*iPrice);
	};
	

Arguments arrive as String type data and Tinderbox coerces them as best it can. So here iPrice is a string value containing a number. however Tinderbox knows that if a number, e.g. 1.18 is multiplied by a String (containing a number) the String-type should be coerced to a Number-type before use and the resulting value will be Number data type.

Though more verbose, a safer approach—especially if unclear as to Tinderbox's coercion logic—is to be more specific, and insert comments, as shown below :

	function fAddTax(iPrice){
		// Arguments: iPrice - a number, the starting price
		//
		// make a variable (expected type of Number) and set it to argument #1
		var:number vNum = iPrice;
		// multiply variable by tax rate
		vNum = 1.18 * vNum;
		//return the tax-adjusted price
		return vNum;
	};

This defines a new function named 'fAddTax' that can be used in any action or expression (including ^action()^ in templates) to apply 18% tax to to the input figure, i.e. $1.00 → $1.18. It has one input argument, and returns a single value. Thus:

$MyNumber = fAddTax(500); 

would set MyNumber's value to 1.18*500, i.e. 590. If we assume this is money, a $500.00 input becomes $590.00 including tax (be it US Dollars or any currency).

But hard-coding (i.e. 1.18) values like tax rates is generally considered bad practice as values can (will!) change. A better function might be this, comments, line breaks for for clarity:

	function fAddTax(iPrice){
		// Arguments: iPrice - a number, the starting price
		//
		// var:number vTaxRate = 1.18;
		// make a variable (expected type of Number) and set it to argument #1
		var:number vNum = iPrice;
		// multiply variable by tax rate
		vNum = vTaxRate * vNum;
		//return the tax-adjusted price
		return vNum;
	};

But, supposedly fixed values like tax rates can change when governments change. So…

Adding an additional function argument

What if the tax rate changes? This can be accommodated by adding a second argument for the tax rate. Extra comments, line breaks for for clarity:

	function fAddVarTax(iPrice,iTaxRate){
		// Arguments: 
		//   iPrice - a number, the starting price
		//   iTaxRate - tax rate percentage as a number (15 not 0.15)
		// --------------
		
		// make a variable (expected type of Number) and set it to argument #1
		var:number vNum = iPrice;
		// multiply variable by tax rate, assuming the tax rate input is a decimal percent, e.g. '0.18' for 18%
		var:number vTax = iTaxRate;
		vNum = (1 + vTax) * vNum;
		//return the tax-adjusted price
		return vNum;
	};

Thus:

$MyNumber = fAddVarTax(500,20); 

would pass a 20% tax rate, set MyNumber's value to 1.20*500, i.e. 600.

Further examples:

	function fAnswer() {
		return 42;
	}

always returns 42. Or:

	function fFibonacci(iNum){
		if(iNum<2){
			return (iNum);
		};
		return fFibonacci(iNum-1)+fFibonacci(iNum-2);
	}

returns the iNum^th Fibonacci number. This is a more advanced example showing the concept of recursion, whereby a function calls itself.

Using more concise code

For the experts who understand the flow of the code, the function defined above could equally well be defined in a terser form:

	function fVarTax2(N,T){
		return ((1+(T/100))*N);
	};

Those with coding expertise my prefer this form. However, aTbRef code examples here are written assuming a reader with little or no coding expertise, thus the use of a more explicit and verbose format.

---

Next: Comments in functions