Important note: all examples follow aTbRef naming conventions.
Returning function values
return
The return statement returns a value from a function to the calling action code object (which can even be another function). The return operator is used only inside a function. Execution of the function's code stops once an expression containing a return (i.e. up to the next semi-colon) is processed. Thus if function fTest returns a string:
function fTest(){
return "Hello";
}
The returned value is passed back to the calling code:
$MyString = fTest();
with the result that $MyString would be "Hello", i.e. the value of the function's return statement. By contrast, simply calling the function without a left-side recipient:
fTest();
would still cause the fTest() function to be run. However, the function's returned value would be inaccessible to the calling code context.
Using the return operator in a function
Thus, when return is inserted in a function, the code/expression to the end of the line (or first semi-colon) is evaluated and returned. Note that as the return statement is closed by a semicolon, it is essentially a single line of code/expression started by the word 'return' (case-sensitive), a space, and then following action code code. For example:
return "Process complete";
returns a single literal string
return true;
returns a boolean value
return $MyNumber;
returns an attribute's value
return vMyValue;
returns a variable's value
However, if the to-be-returned value is not coded a single term, but rather as an expression whose output is returned, it may be enclosed in parentheses but does not require to be so. The use of parentheses helps indicate, if only to the user, that some evaluation is required before the single result is used as the return value
The first example shows an evaluated result without parentheses, the other with parentheses:
return 2 + 2;
return ("Hello " + vName");
return (iPrice * $Tax);
Can return occur anywhere in the function?
In theory Yes, but in practice, No. This is because the function process completes after the return value is evaluated and passed back out. So extra code may occur after the return but is not evaluated.
One possible use for content in a function after a return statement is to add comments about a function placed at the end, after code so available for user reference but not pushing the actual code down the (viewable) screen so aiding usability.
Can there be a multi-value return?
No, a single value is returned but that value may be of a multi-item data type. Thus, if it is desired to pass multiple discrete values in the same return event, make the returned object a list or dictionary (or a variable of List, Set or Dictionary type).
Does there have to be a return statement?
No, it is not a requirement. For instance a logging function might take an input string and append it to the end of a specific note. In such a circumstance there is nothing for the function to return to the calling code.
Can there be more than one return statement in a function?
Yes. The function ceases running when a return statement is encountered but if the function has conditional branching code, each branch that represents a final result can have its own return statement. In such a case, the intent is to allow a different returned value depending on the result of conditional tests.
So, whilst multiple return statements may exist overall, the code evaluates so only one return is ever processed (as the function stops at that point). For instance, for those unused to programming, initially this may be more easily understood using a single return statement to pass back one of 3 possible values:
function fTestLength(iString){
var:string vOutput = "";
if(iString){
if(iString.size<=5){
vOutput = "Small string";
}else{
vOutput = "Large string";
}
}
if(vOutput=="")
vOutput = "No string";
}
return vOutput
}
However, the above example can also be written as:
function fTestLength(iString){
if(iString){
if(iString.size<=5){
return "Small string";
}else{
return "Large string";
}
return "No string";
}
In this case, there are three discrete possible return values but each closes and returns for a different single branch of the code. As in the first example, the logic could as easily set a single variable in each branch and then use a single return at the end of the function.
As the function quits once a return is reached, using multiple return statements can avoid the function having to evaluate unnecessary extra code. Such efficiency measure are unlikely to affect most Tinderbox use but can act as way to help understand use of functions with conditional outcomes. Both examples evaluate to a similar outcome; use whichever form makes the most sense.
If using multiple return statements, take care to avoid exiting the function too early, i.e. that each return statement is truly a final point in the function's logic.
Next: Calling functions
See also—notes linking to here: