This documentation is archived and is not being maintained.

Function Procedures

A Function procedure is a series of Visual Basic statements enclosed by the Function and End Function statements. Each time the procedure is called, its statements are executed, starting with the first executable statement after the Function statement and ending with the first End Function, Exit Function, or Return statement encountered.

A Function procedure is similar to a Sub procedure, but it also returns a value to the calling program. A Function procedure can take arguments passed to it by the calling code, such as constants, variables, or expressions.

The syntax for declaring a Function procedure is as follows:

[accessibility] Function functionname[(argumentlist)] As datatype
   ' Statements of the Function procedure.
End Function

The accessibility can be Public, Protected, Friend, Protected Friend, or Private.

You can define Function procedures in modules, classes, and structures. They are Public by default, which means you can call them from anywhere in your application.

You declare each argument the same as you do for a Sub procedure.

Return Values

The value a Function procedure sends back to the calling program is called its return value. The function returns the value in one of two ways:

  • It assigns a value to its own function name in one or more statements of the procedure. Control is not returned to the calling program until an Exit Function or End Function statement is executed, as in the following example:
    Function functionname[(argumentlist)] As datatype
       ' ...
       functionname = expression   'Control remains within the function.
       ' ...
    End Function
  • It uses the Return statement to specify the return value, and returns control immediately to the calling program, as in the following example:
    Function functionname[(argumentlist)] As datatype
       ' ...
       Return expression   'Control is returned immediately.
       ' ...
    End Function

The advantage of assigning the return value to the function name is that control does not return from the function until the program encounters an Exit Function or End Function statement. This allows you to assign a preliminary value and adjust it later if necessary.

If the function returns an array data type, you cannot access the individual elements of the array within the function. If you attempt to do this, the compiler interprets it as a call to the function. The following example generates compiler errors:

Function AllOnes(ByVal N As Integer) As Integer()
   Dim I As Integer   ' Singleton Integer, not Integer array.
   For I = 1 To N - 1   ' Assume N has a valid value.
      AllOnes(I) = 1   ' Compiler error: call with wrong data type.
   Next I
   Return AllOnes()   ' Compiler error: call with no argument.
End Function

Every Function procedure has a data type, just as every variable does. This data type is specified by the As clause in the Function statement, and it determines the type of the return value. The following sample declarations illustrate this:

Function Yesterday As Date
   ' ...
End Function
Function FindSqrt(ByVal Number As Single) As Single
   ' ...
End Function

Calling Syntax

You call a Function procedure by including its name and arguments either on the right side of an assignment statement or in an expression. The following sample calls illustrate this:

lvalue = functionname[(argumentlist)]
If ((functionname[(argumentlist)] / 3) <= expression) Then ...

The following Function procedure calculates the longest side, or hypotenuse, of a right triangle, given the values for the other two sides:

Function Hypotenuse (ByVal Side1 As Single, ByVal Side2 As Single) As Single
   Return Math.Sqrt((Side1 ^ 2) + (Side2 ^ 2))
End Function

Typical calls to Hypotenuse are as follows:

Dim TestLength, TestHypotenuse, X, Y, Area As Single
TestHypotenuse = Hypotenuse(TestLength, 10.7)
' Assume TriangleArea is a defined Function procedure — the 
' returned value from Hypotenuse is used as an argument to TriangleArea.
Area = TriangleArea(X, Y, Hypotenuse(X, Y))

The common language runtime provides many functions, located in the Microsoft.VisualBasic namespace. These include such common functions as Beep, MsgBox, and StrComp. You call these functions the same way you call your own Function procedures.

When you call a Function procedure, you do not have to use its return value. If you do not, all the actions of the function are performed, but the return value is ignored. MsgBox is often called in this manner.

See Also

Function Statement | Procedures | Sub Procedures | Property Procedures | Procedure Arguments