Function Statement

See AlsoY05OGJ                 Example076Q61>Low

Declares the name, arguments, and code that form the body of a Function procedureK6LBMC.


[Static] [Private] Function functionname [(argumentlist)] [As type]


          [functionname = expression]

          [Exit Function]


          [functionname = expression]

End Function


All executable code must be in Function or Sub proceduresQDBVHN.  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 module2JU32VW 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 character4TVC9NP.  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 libraryDEFDLL [DLL]), Global variables, and Global constantsTD9WSV.  To avoid a name conflict, you can use the Private reserved word43US84 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 variable4OG2C0B, constant, or procedure name in the same module.

                        Note that the type of the name determines the data type3GYXY7 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 Variant8PHEAW3.

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 Empty1L2JEZ4.

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 arrayYPCGZO 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 type9DGMAH.  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.


See Also

Dim StatementLANDIM

Global StatementTDN897

Option Explicit StatementIJUJAQ

Static StatementCC4JTI

Sub StatementLANSUB

Function Statement Example

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