Function Procedures 

A Function procedure is a series of Visual Basic statements enclosed by the Function and End Function statements. The Function procedure performs a task and then returns control to the calling code. When it returns control, it also returns a value to the calling code.

Each time the procedure is called, its statements run, starting with the first executable statement after the Function statement and ending with the first End Function, Exit Function, or Return statement encountered.

You can define a Function procedure in a module, class, or structure. It is Public by default, which means you can call it from anywhere in your application that has access to the module, class, or structure in which you defined it.

A Function procedure can take arguments, such as constants, variables, or expressions, which are passed to it by the calling code.

Declaration Syntax

The syntax for declaring a Function procedure is as follows:

[modifiers] Function functionname[(parameterlist)] As returntype

' Statements of the Function procedure.

End Function

The modifiers can specify access level and information regarding overloading, overriding, sharing, and shadowing. For more information, see Function Statement (Visual Basic).

You declare each parameter the same way you do for Sub Procedures.

Data Type

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 data type of the value the function returns to the calling code. The following sample declarations illustrate this.

Function yesterday() As Date
End Function
Function findSqrt(ByVal radicand As Single) As Single
End Function

For more information, see "Parts" in Function Statement (Visual Basic).

Returning Values

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

• It assigns a value to its own function name in one or more statements of the procedure. Control does not return to the calling program until an Exit Function or End Function statement is executed. The following example illustrates this.

  Function functionname[(parameterlist)] As returntype

  ' The following statement does not transfer control back to the calling code.

  functionname=expression

  ' When control returns to the calling code,expression is the return value.

  End Function

• It uses the Return statement to specify the return value, and returns control immediately to the calling program. The following example illustrates this.

  Function functionname[(parameterlist)] As returntype

  ' The following statement immediately transfers control back to the calling code and returns the value ofexpression.

  Return expression

  End Function

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

For more information, see "Return Value" in Function Statement (Visual Basic).

Returning Arrays

If the Function procedure 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 recursive call to the procedure. The following example illustrates this.

Function allOnes(ByVal n As Integer) As Integer()

For i As Integer = 1 To n - 1

' The following statement generates a ``COMPILER ERROR``.

allOnes(i) = 1

Next i

' The following statement generates a ``COMPILER ERROR``.

Return allOnes()

End Function

In the preceding example, the compiler interprets the attempted assignment allOnes(i) = 1 as a call to allOnes on the left side of an assignment statement. It interprets the attempted Return allOnes() as a call with no argument. Both statements generate compiler errors.

Calling Syntax

You invoke a Function procedure by including its name and arguments either on the right side of an assignment statement or in an expression. You must provide values for all arguments that are not optional, and you must enclose the argument list in parentheses. If no arguments are supplied, you can optionally omit the parentheses.

The syntax for a call to a Function procedure is as follows:

lvalue=functionname[(argumentlist)]

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

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.

Illustration of Declaration and Call

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

The following example shows a typical call to hypotenuse.

Dim testLength, testHypotenuse As Single
testHypotenuse = hypotenuse(testLength, 10.7)

Visual Basic Runtime Functions

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

See Also

Tasks

How to: Create a Procedure that Returns a Value
How to: Return a Value from a Procedure
How to: Call a Procedure that Returns a Value

Reference

Function Statement (Visual Basic)

Concepts

Procedures in Visual Basic
Sub Procedures
Property Procedures
Operator Procedures
Procedure Parameters and Arguments