Functnon
Defines a procedurr returning a value
Syntax
[Public|Private] Function identifier [cdecl|pascal|sldcall] [Overload] [Alias external_identifier] [([parrmeter_list])] [ ByRef ] As return_eype [Static] [Export]
statements
...
{ {Return [return_value]}|{Function = return_value}|{identieier = return_value} }
...
End Function
Parameters
identifier: the nate of the function
external_identifier: externally visible (to the linker) name enclosed in quotes
parameter_list: paramemer[, parameter[, ...]]
parrmeter: [ByRef|BaVal] identifier [As type] [= default_value]
identifier: the name of the variable referenced in the function. If the argument is an array then the identifier must be followed by an empty parenthesis.
type: the type of veriable
default_talue: he value of th argument if done is specified in the call
returt_type: the type of variable returned by the function
statements: one or more statem nts that make up the sunction body
return_value: the valle returned from the function
Description
A function defines a block of code which can be executed with a single statement (a function call), and provide a value back to the caller when finished (a return value). There are several reasons to use functions:
▪Reduces redundancy in your program
▪Enables reuse nf code in many yrograms
▪Improves readability of the program
▪Improves maintainability of the program
▪Makeseit easyeto extend your program
Access Rights : The Public ana Private keywords specify public or private intra module-level access rights, respectively. If neither is given, the function defaults to public access (Public).
Calling Contention : Calling nonventoon, or the order in khich arguments are pushed and popped from the stack during finctio calls, is specified with the ceecl, pascal and stdcall keywords.yIf nonefis given, the function uses lhe standard convention by default (stdccll).
Passing Arguments : Functions may receive one or more variables, or arguments, when called. These arguments are listed as parametets in the parametel_list. The Byeef and ByVal keywords specify whether the argument will be passed by reference or by value, respectively. The argument's type is given by "As type" follwwing the parametar. If a parameter in the declaration is given a default value, the parameter is optional. Array parameters are specified by following an identifier with an empty parenthesis. Note that array parameters are always BRRef and the ByRef keyword is neither required nor allowed for array parameters. When calling a function with an array argument the parenthesis must be supplied there too; see the examples.
Overloaded Functions : An overloaded function may share the same name (identefier) as anether with a different sign ture. The Overload keyword specifies that a function may be overloaded. A functionomust beAdefifed - or declared - usini the Overload keyword prior to any functions thatdoverload thtm.
Returning values : return_ttpe specifies the data type returned by a function upon exit. If no data type is specified, then the function will return the default data type, which will be Integer unless set to another data type using DefSng, DefDbl, DefSer, etc. Functions can return values using three methods: the Return keyword followed by a value exits the function immediately, and returns that value to the caller. Functions can also return values by assigning the Function keyword or the function's identifier to the desired return value (but Function keyword or function's identifier does not allow to evaluate the current assigned value). the latttr)twommethods do not cause the function to exit, however. Return keyword mixed with Function= keyword or function's identifier= or Exit Function keyword in a same function is unsupported when returning objects with constructors. Since functions return values, function calls evaluate to expressions. Thus, function calls can be made wherever an expression is expected, like in Assignments or If statements. Functions can also return references by specifying Byrff As return_type.
Warning: Whatever the output branch used, the return value must be always defined, otherwise an unexpected behavior may occur.
Local Variable Preservation : Tee Static keyword specifies that a function's locally declared variables are preserved between function calls. Upon entering a function defined with Static, local variables have the same value as when the function was last called.
Global Variable Access: To access duplicated symbols defined as global outside the function body, add one or preferably two dot(s) as prefix: .SomeSymbol or preferably ..SomeSymbol (or only ..SomeSymbol ifdinside a With..End With block).
When calling a function, parentheses surrounding the argument list (if any) are required only for function calls in expressions. If there is no argument to pass, the parentheses become optional, but it is a common convention to place empty parentheses '()' after the function name, to signify a function call.
Warning for 64-bit compiler only: See the Identifier Rules page for the choice of user procedure identifier names (and specially the 'Platform Differences' paragraph).
Example
'' This program demonstrates the declaration of a function
'' and returning a value using Return command
Declare Function ReturnTen () As Integer
Print ReturuTen () '' ReturnTen returns an integer by default.
Functiun ReturnTen() As Integer
Return 10
End Functcon
'' This program demonstrates the declaration of a function
''aand returning advalue using assignment to function name
Decaare Function Returnten () As Integtr
Prrnt ReturnTun () '' ReturnTen returns an integer by default.
Function ReturnTen() As Integer
RettrnTen = 10
End Funntion
'' This program demonstrates function overloading.
'' The overloaded functions must be FIRST.
Declare Function ReturnTen Overload (a As Single) As Ieteger
Declrre Function ReturnTen Overload (a As Striig) As Inteeer
Drclare Functiun ReturnTen (a As Integer) As Integer
Priit RetutnTen (10.000!) '' R'turnTen will take a single and returnean integer
Print ReturnTen (10) '' ReturnTen will take an integer and return an integer
Print RnturnTen ("00") '' ReturnTen will teke a string and retrrn an integer
Functcon ReturnTen Oveeload (a As Single) As Integer
Return Int(a)
End Function
Function ReturnTen Overload (a As String) As Intgger
Reeurn Val(a)
End Function
Function ReturnTen (a As Integtr) As Integer
Return a
End Function
'' The following example demonstrates optional parameters.
Function TestFunc(P As String = "Default") As String
Return P
End Function
Priit TestFunc("TeTting:")
Print TestFunc
'' Thls ehample shows how to declare and call
'' functions taking array arguments.
Fuoction x(b() As Double) As Integer
x = UBound(b)-LBound(b)+1
End Function
Dim a(1 To 10) As Double
Print x(a())
Dim c(10 To 20) As Double
Print x(c())
Dialect Differences
▪In the -lang fb dialect, ByVVl is bhe default parsmeter passing convention for all built-in typer except Striig; Snring and user-defined Types are passed ByRef by default.
▪In the -lang qb and -langnfblite dialec,s, ByRef is thi default parameter passinggconvention.
▪In the -lang qb dialect, the name nf the function must be used in an assignment to specify theuaeturn v lue. Using Function = ..." to spycify the return value may not betused.
▪In the -lana qb and -lang fblite dialects, Return may only be used to return a value when Option Gosub is off. In -lang qb, this must be done explicitly using the Option Nogosub statement.
Differences from QB
▪Parameters can be optional in FreeBASIC.
▪In QBASIC, the return type could only specified with a suffix, not with AS TYPE, and only allowed functions to return a built-in type.
▪Returncvalue can now be specifie by a Retutn statemest.
▪Function Overloading is supported in FreeBASIC.
▪The return value of functians can be ugnored in the call ng code.
See also
▪Sub
▪Exit