See Also Example
Declares the name, arguments, and code that form the body of a Function procedure.
Syntax
[Static] [Private] Function functionname [(argumentlist)] [As type]
[statementblock]
[functionname = expression]
[Exit Function]
[statementblock]
[functionname = expression]
End Function
Remarks
All executable code must be in Function or Sub procedures. You can't define a Function procedure inside another Function or Sub procedure.
The Function statement has these parts:
Part Description
Static Indicates that the Function procedure's local variables are preserved between calls. The Static attribute doesn't affect variables that are declared outside the Function procedure, even if they are used in the procedure.
Private Indicates that the Function procedure is accessible only to other procedures in the module in which it exists. No other procedure in any other module has access. The Private keyword has no effect when declaring Function procedures in a form since they are not available outside the form anyway.
Function Marks the beginning of a Function procedure.
functionname Name of the function. Function procedure names follow the same rules that constrain the names of other variables and can include a type-declaration character. Because Function names are recognized by all procedures in all modules, functionname cannot be the same as any other globally recognized name in the program. Such names include the names of procedures (in Visual Basic or a dynamic-link library [DLL]), Global variables, and Global constants. To avoid a name conflict, you can use the Private reserved word to make the Function procedure local to the module in which it appears, but access to it will not be available from any procedure in any other module. Even if you use the Private reserved word, functionname still cannot be the same as any other module-level variable, constant, or procedure name in the same module.
Note that the type of the name determines the data type returned by the Function procedure. To specify the return data type of the Function procedure, either use an As clause following argumentlist or include a type-declaration character in the Function name. For example, to create a Function procedure that returns a string, you can include a dollar sign in the name, use an As String clause, or give it a name defined as a string name with a DefStr statement.
argumentlist List of variables, representing arguments, that are passed to the Function procedure when it is called. Multiple variables are separated by commas. Unless identified with the ByVal reserved word, individual arguments are passed by reference, so changing an argument's value inside the Function procedure changes its value in the calling procedure. If an argument passed to a function is an expression, it is treated as if it used the ByVal reserved word: no part of the expression is altered by the function.
As type Reserved word used to declare the data type of the value returned by the Function procedure; type can be Integer, Long, Single, Double, Currency, String, or Variant.
statementblock Any group of statements that are to be executed within the body of the Function procedure.
expression Return value of the function. A Function procedure returns a value by assigning that value to the function functionname. Any number of such assignments can appear anywhere within the procedure. If no value is assigned to functionname, the procedure returns a default value: A numeric function returns 0, a String function returns a zero-length string (""), and a Variant function returns Empty.
Exit Function Causes an immediate exit from a Function procedure. Program execution continues with the statement following the statement that called the Function procedure. Any number of Exit Function statements can appear anywhere in a Function procedure.
End Function Marks the end of a Function procedure.
The argument argumentlist has the following syntax:
[ByVal]variable[( )] [As type] [, [ByVal]variable[( )] [ As type] ] . . .
It has these parts.
Part Description
ByVal Indicates that the argument is passed by value rather than by reference. The ByVal reserved word cannot be used with a variable of a user-defined type, an object type, or a variable that is an array.
variable Name of the variable representing the argument. For array variables, use the parentheses but omit the number of dimensions.
As type Declares the data type of variable. The type may be Integer, Long, Single, Double, Currency, String (variable-length strings only), Variant, a user-defined type, or an object type. Use a separate As type clause for each argument.
Like a Sub procedure, a Function procedure is a separate procedure that can take arguments, perform a series of statements, and change the values of its arguments. However, unlike a Sub procedure, a Function procedure can be used in an expression in the same manner as any intrinsic function, such as Sqr, Cos, or Chr.
You can call a Function procedure by using the function name, followed by the argument list in parentheses, in an expression. If the function has no arguments, you still must include the parentheses.
Caution Function procedures can be recursive; that is, they can call themselves to perform a given task. However, recursion can lead to stack overflow. The Static reserved word is usually not used with recursive Function procedures.
To return a value from a function, assign the value to the function name. For example, in a function named BinarySearch, you might assign the value of the constant False to the name to indicate that the value was not found.
Function BinarySearch(...)
...
' Value not found. Return a value of False.
If lower > upper Then
BinarySearch = False
Exit Function
End If
...
End Function
Variables used in Function procedures fall into two categories: those that are explicitly declared within the procedure and those that are not. Variables that are explicitly declared in a procedure (using Dim or the equivalent) are always local to the procedure. Other variables used but not explicitly declared in a procedure are also local unless they are explicitly declared at some higher level outside the procedure.
Caution A procedure can use a variable that is not explicitly declared in the procedure, but a name conflict can occur if anything you have defined in the Declarations section has the same name. If your procedure refers to an undeclared variable that has the same name as another procedure, a Global or module-level constant or variable, or an object, Visual Basic assumes that your procedure is referring to that module-level name. Explicitly declare variables to avoid this kind of conflict. You can use an Option Explicit statement to force explicit declaration of variables.
Caution Visual Basic may rearrange arithmetic expressions to increase internal efficiency. Avoid using a Function procedure in an arithmetic expression when the function changes the value of variables in the same expression.
Dim Statement
Global Statement
Option Explicit Statement
Static Statement
Sub Statement
The example uses the Function statement to declare the name of a Function procedure. Exit Function is used to exit the procedure before the End Function statement is encountered. To try this example, paste the code into the Declarations section of a form. Then press F5 and click the form.
Sub Form_Click ()
Dim Msg, SqrN ' Declare variables.
Dim N As Double
N = InputBox("Calculate the square root of what number? ")
Msg = "The square root of " & N
SqrN = SquareRoot(N) ' Call user-defined function.
Select Case SqrN
Case 0: Msg = Msg & " is zero."
Case -1: Msg = Msg & " is an imaginary number."
Case Else: Msg = Msg & " is" & SqrN
End Select
MsgBox Msg ' Display message.
End Sub
Function SquareRoot (X As Double) As Double
Select Case Sgn(X) ' Evaluate sign of argument.
Case 1 ' OK if positive.
SquareRoot = Sqr(X)
Exit Function
Case 0 ' Notify user if 0.
SquareRoot = 0
Case -1 ' Notify user if negative.
SquareRoot = -1
End Select
End Function