Functions/Subs

Functions and Subs are the same in thinBasic, so here use the two terms as synonymies.

Subs are just functions not returning any value.

Function Procedures

A Function procedure is a series of thinBasic statements enclosed by the FUNCTION and END FUNCTION statements.

A Function procedure is similar to a Sub procedure in other languages, but can also return a value.

A Function procedure can take arguments (constants, variables, or expressions that are passed to it by a calling procedure). If a Function procedure has no arguments, its Function statement must include an empty set of parentheses.

A Function returns a value by assigning a value to FUNCTION keyword in one or more statements of the procedure. The return type of a Function is always automatically converted to the function return type.

Function declaration:

Function FunctionName [([arguments])] [As Type [PTR]]

[Local variable list]

[Dim variable list]

{statements}

[Function = ReturnValue]

{statements}

[Exit Function]

{statements}

End Function

In the following example, the Celsius function calculates degrees Celsius from degrees Fahrenheit. When the function is called from the ConvertTemp Sub procedure, a variable containing the argument value is passed to the function. The result of the calculation is returned to the calling procedure and displayed in a message box.

Function Celsius(fDegrees As Number) As Number

Function = (fDegrees - 32) * 5 / 9

End Function

If a function is specified without any AS clause (so no indication about what type of data the function is returning), AS LONG is assumed by default.

Getting data into a function: parameters

Data is passed to functions using parameters.

Parameters serve as placeholders for the data you want to pass into your procedure. You can name your parameters anything that is valid as a variable name.

When you create a procedure, parentheses must be included after the name of the procedure. Any parameter is placed inside these parentheses, separated by commas.

In the following example, InVal is a placeholder for the value being passed into the Factorial function for factorial calculation:

Function Factorial(InVal As Number) As Number

Dim Count As Long

Dim RetVal As Long

RetVal = 1

For Count = 2 To InVal

RetVal = RetVal * i

Function = RetVal

End Function

Normally, thinBasic passes parameters to a Function by copy (BYCOPY). It means that a copy of the passed data will be created locally inside the function and any change to the local data will not effect the original data.

Parameters can also be passed by reference (BYREF). In this way, the address of the variable is passed and the function has to look at that address to get the value of the parameter. Passing parameters by reference will not make a copy of the original data but a reference to the original data will be created and any change to local function parameter will effect also original variable.

The passing parameter method is specified by appending a clause in front of the parameter name. For example:

FUNCTION Test(A AS INTEGER) '---Integer passed by copy, default one

FUNCTION Test(BYREF A AS INTEGER) '---Integer passed by reference

Parameters can be declared OPTIONAL. This will instruct thinBasic that, when the function will be called one or more parameters may be missed.

Parameters declared as OPTIONAL will be in any case created inside the function but if missed during function calling, default data will be assigned.

OPTIONAL keyword can be used for every parameter. Once used, all parameter following the first declared as OPTIONAL will be OPTIONAL by default.

'---First parameter if not optional

'---Second parameter is optional

FUNCTION Test(MyFirstVar AS INTEGER, OPTIONAL MySecondVar AS LONG)

'---First parameter if not optional

'---Second parameter is optional

'---Third parameter will be optional by default

FUNCTION Test(MyFirstVar AS INTEGER, OPTIONAL MySecondVar AS LONG, MyThirdVar AS EXT)

Parameters type can be omitted. In this case BYVAL VARIANT will be assumed.

For example:

Function AddMessage( _

hDlg As Long , _

Message As String, _

lObject As String, _

Optional Details As String, _

P1, P2, P3)

Variable type for parameters P1, P2, P3 is not defined. thinBasic will assume BYVAL VARIANT. This assumption give great freedom on possible passing values.

Up to 32 parameters can be passed to functions.

Getting data out of a function

To get data out of a function, you have direct or indirect way. Here they are.

Direct way

There are 3 possible direct ways to return a value from a function:

1.	assign your value or expression to the Function keyword before function ends

2.	assign your value or expression to the name of the function you are inside before function ends

3.	use Return followed by the value or expression you want to return before function ends

For example, the following function calculates the total number of bytes of all files inside a directory. To return the total number of bytes, the calculated value is assigned to Function keyword before function ends.

USES "FILE" 'Tell thinBasic you want to use "FILE" module

USES "LL" 'Tell thinBasic you want to use "LL" module (Linked List module)

Function TotalFileSize(lDir As String) As Quad

Local Count As Long

Local FileName As String

Local pList As Long

Local nItems As Long

Local TotSize As Quad

pList = Dir_List(lDir, "*.*", %FILE_NORMAL Or %FILE_HIDDEN Or _

%FILE_SYSTEM Or %FILE_ADDPATH)

nItems = LL_Count(pList)

If nItems > 0 Then

For Count = 1 To nItems

FileName = LL_GetItem(pList, Count)

TotSize = TotSize + File_Size(FileName)

End If

'---Here the 3 possible ways to return the value

Function = TotSize '---Method 1

TotalFileSize = TotSize '---Method 2

Return TotSize '---Method 3

End Function

Indirect way

An indirect way to return data from a function is to pass one or more parameter using BYREF option in from of parameter name.

BYREF means you want to pass a reference of a variable instead of the value of the variables.

Changes made inside a function to parameters passed BYREF will change the value of the referenced variable.