Functions

Extended Functions and Methods may use :Long and :Double parameters and return types without narrowing. See Long and Double.

A Function is a named block of reusable code. It can receive values through parameters and return one value to its caller.

Declaration

Function FunctionName[ReturnType]( [parameter [, parameter ...]] )
    statements
    [Return expression]
End Function

FunctionName must be a valid identifier. A Function declaration may appear only at program scope; Functions cannot be nested. Two Functions cannot share the same name, and Function overloading is not supported.

Function Add%(left%, right%)
    Return left + right
End Function

The return type follows the Function name. Parameters are comma-separated declarations inside the parentheses. If a return type or parameter type is omitted, it defaults to Integer.

Return types

Return type	Traditional declaration	Modern declaration	Default return value
Integer	`Function Count%()` or `Function Count()`	`Function Count:Int()`	`0`
Float	`Function Distance#()`	`Function Distance:Float()`	`0.0`
String	`Function Name$()`	`Function Name:Str()`	`""`
Custom Type	`Function Create.Player()`	`Function Create:Player()`	`Null`

The Modern forms require Dialect "modern", or Extended mode in a file with no Dialect line. Extended mode also permits Interface and typed List return types; see Interfaces and Type Lists.

Parameters

Each parameter is a local variable initialised from the corresponding call argument. Traditional tags and Modern annotations use the same forms as other variable declarations:

Function FormatScore$(name$, score%, scale#)
    Return name + ": " + Str(Int(score * scale))
End Function

Dialect "modern"

Function FormatScore:Str(name:Str, score:Int, scale:Float)
    Return name + ": " + Str(Int(score * scale))
End Function

Basic values are copied into their parameters, so assigning a new value to a parameter does not change the caller's variable. A custom-Type, Interface, or List parameter receives a copy of the reference; both references still identify the same object or List.

Default arguments

A parameter may specify a compile-time constant default. Calls may omit trailing arguments that have defaults:

Function Clamp#(value#, minimum# = 0.0, maximum# = 1.0)
    If value < minimum Then Return minimum
    If value > maximum Then Return maximum
    Return value
End Function

Print Clamp(1.5)             ; uses 0.0 and 1.0
Print Clamp(1.5, 0.0, 2.0)   ; supplies every argument

Place required parameters before defaulted parameters. A default must be a constant expression, and a call cannot skip an argument in the middle of the list.

Calling Functions

Use parentheses when the returned value forms part of an expression:

total% = Add(20, 22)
Print Add(5, 7)

A Function may also be called as a statement when its return value is not needed. Statement calls accept either command-style arguments or parentheses:

ShowMessage "Ready"
ShowMessage("Ready")

The number of arguments is checked at compile time. Each argument is converted to its declared parameter type when that conversion is permitted. Argument expressions are evaluated from left to right.

Returning a value

Return expression immediately leaves the Function and converts the expression to the declared return type:

Function Sign%(value#)
    If value < 0.0 Then Return -1
    If value > 0.0 Then Return 1
    Return 0
End Function

A bare Return, or reaching End Function, returns the default value shown in the return-type table. A custom-Type Function can return an object reference:

Type Player
    Field name$
End Type

Function CreatePlayer.Player(name$)
    Local player.Player = New Player
    player\name = name
    Return player
End Function

Scope and lifetime

Parameters and variables declared with Local exist only inside the current Function call.
A Function may read and write variables declared with Global.
Local variables in the main program are not visible inside Functions.
Dim arrays declared in the main program may be accessed or resized by Functions, as described in Arrays.

Leaving a Function releases its local String and reference variables, but it does not automatically call Delete on custom-Type objects or typed Lists. Their explicit lifetime rules still apply.

Forward calls and recursion

Function signatures are resolved before executable statements and Function bodies. A Function can therefore be called before its declaration, call itself, or participate in mutual recursion:

Print IsEven(10)

Function IsEven%(value%)
    If value = 0 Then Return True
    Return IsOdd(value - 1)
End Function

Function IsOdd%(value%)
    If value = 0 Then Return False
    Return IsEven(value - 1)
End Function

Related features

Type Methods use the same parameter, default-argument, return, local-variable, and recursion rules, but attach the code to a custom Type and provide a Self reference. See Variables for general declaration and scope rules and Custom Types for object lifetime.