Return

(Engine-Level Function)

Description:	Sets the return value for the module in which it is executed.
Returns:	Nothing
Usage:	Script or steady state.
Function Groups:	Basic Module
Related to:	GetReturnValue \| Launch \| Slay \| SetReturnValue
Format:	Return(X[, Resettable])
Parameters:

Optional. Any variable, expression, constant or object value. It can be of any type.

Resettable

Optional Boolean. Defaults to TRUE. If present and set to FALSE, the return value will not reset to INVALID until another Return statement specifies otherwise. See comments.

Comments:

If a Return statement appears anywhere in the code of a launched module (i.e. one that is executed inside of a script or using the Launch statement), even if that portion of the code is not executed, the module will be considered to be a called module, and will block execution of all other modules in the same thread while it is executing. Execution of the Return statement in a subroutine results in the module being slain without having to use the Slay statement.

If the Return statement is used in a called module (i.e. one that appears as a statement in a state), execution of the Return statement will not stop the execution of the module.
The return value for the module is set equal to the first parameter, and is the same type as the expected value of the module call. The type of the return value is set every time Return is executed, which allows modules to return different types of values during execution if they are called (rather than launched).

This statement may appear inside or outside of a script, and like other statements that may be called from a state, if multiple calls are active simultaneously in a module, the return value will be invalid.

WARNING: Latching Behavior and If statements

If the Return statement is placed within a script block of a called module, and if that module is called by an If statement, then the return value will be reset to Invalid after the If statement executes. This is similar to the behavior of latching functions such as AbsTime() and Watch(). See example 2.

This behavior is not desirable for some called modules. The same goes for some modules that set their return value from script using SetReturnValue. For these, set the parameter Resettable to FALSE.

Return(); is equivalent to Return(Invalid);

Example 1:

Main [ { State in Module Graphics }
  ZText(500, 100, test , 15, 0);
]
< { Submodule of Module Graphics }
Test
State1
[
  Return("example of return function");
]
>

This sets the return value of the module Test to "example of return function" which is displayed by the ZText statement in state Main of the Graphics module.

Example 2:

[
  Count = 0;
  XorYPressed Module;
]

Main [
  If XorYPressed();
  [
     { When this script executes, the return value of XorYPressed resets to Invalid }
    Count++;
  ]
  ZText(100, 100, Concat("X or Y was pressed ", Count, " times"), 12, 0);
]

< 
XorYPressed

Main [
  If MatchKeys(1, "x") || MatchKeys(1, "y");
  [
    Return(TRUE);
  ]
]
>