Function Statement (Visual Basic)

Declares the name, parameters, and code that define a Function procedure.

[ <attributelist> ] [ accessmodifier ] [ proceduremodifiers ] [ Shared ] [ Shadows ] [ Async | Iterator ]
Function name [ (Of typeparamlist) ] [ (parameterlist) ] [ As returntype ] [ Implements implementslist | Handles eventlist ]
    [ statements ]
    [ Exit Function ]
    [ statements ]
End Function

Parts

Term	Definition
attributelist	Optional. See Attribute List.
accessmodifier	Optional. Can be one of the following: Public Protected Friend Private Protected Friend See Access Levels in Visual Basic.
proceduremodifiers	Optional. Can be one of the following: Overloads Overrides Overridable NotOverridable MustOverride MustOverride Overrides NotOverridable Overrides
Shared	Optional. See Shared.
Shadows	Optional. See Shadows.
Async	Optional. See Async.
Iterator	Optional. See Iterator.
name	Required. Name of the procedure. See Declared Element Names (Visual Basic).
typeparamlist	Optional. List of type parameters for a generic procedure. See Type List.
parameterlist	Optional. List of local variable names representing the parameters of this procedure. See Parameter List (Visual Basic).
returntype	Required if Option Strict is On. Data type of the value returned by this procedure.
Implements	Optional. Indicates that this procedure implements one or more Function procedures, each one defined in an interface implemented by this procedure's containing class or structure. See Implements Statement.
implementslist	Required if Implements is supplied. List of Function procedures being implemented. implementedprocedure [ , implementedprocedure ... ] Each implementedprocedure has the following syntax and parts: interface.definedname Part Description interface Required. Name of an interface implemented by this procedure's containing class or structure. definedname Required. Name by which the procedure is defined in interface.
Handles	Optional. Indicates that this procedure can handle one or more specific events. See Handles Clause (Visual Basic).
eventlist	Required if Handles is supplied. List of events this procedure handles. eventspecifier [ , eventspecifier ... ] Each eventspecifier has the following syntax and parts: eventvariable.event Part Description eventvariable Required. Object variable declared with the data type of the class or structure that raises the event. event Required. Name of the event this procedure handles.
statements	Optional. Block of statements to be executed within this procedure.
EndFunction	Terminates the definition of this procedure.

Remarks

All executable code must be inside a procedure. Each procedure, in turn, is declared within a class, a structure, or a module that is referred to as the containing class, structure, or module.

To return a value to the calling code, use a Function procedure; otherwise, use a Sub procedure.

Defining a Function

You can define a Function procedure only at the module level. Therefore, the declaration context for a function must be a class, a structure, a module, or an interface and can't be a source file, a namespace, a procedure, or a block. For more information, see Declaration Contexts and Default Access Levels (Visual Basic).

Function procedures default to public access. You can adjust their access levels with the access modifiers.

A Function procedure can declare the data type of the value that the procedure returns. You can specify any data type or the name of an enumeration, a structure, a class, or an interface. If you don't specify the returntype parameter, the procedure returns Object.

If this procedure uses the Implements keyword, the containing class or structure must also have an Implements statement that immediately follows its Class or Structure statement. The Implements statement must include each interface that's specified in implementslist. However, the name by which an interface defines the Function (in definedname) doesn't need to match the name of this procedure (in name).

Note

You can use lambda expressions to define function expressions inline. For more information, see Function Expression (Visual Basic) and Lambda Expressions (Visual Basic).

Returning from a Function

When the Function procedure returns to the calling code, execution continues with the statement that follows the statement that called the procedure.

To return a value from a function, you can either assign the value to the function name or include it in a Return statement.

The Return statement simultaneously assigns the return value and exits the function, as the following example shows.

Function myFunction(ByVal j As Integer) As Double 
    Return 3.87 * j
End Function

The following example assigns the return value to the function name myFunction and then uses the Exit Function statement to return.

Function myFunction(ByVal j As Integer) As Double
    myFunction = 3.87 * j
    Exit Function 
End Function

The Exit Function and Return statements cause an immediate exit from a Function procedure. Any number of Exit Function and Return statements can appear anywhere in the procedure, and you can mix Exit Function and Return statements.

If you use Exit Function without assigning a value to name, the procedure returns the default value for the data type that's specified in returntype. If returntype isn't specified, the procedure returns Nothing, which is the default value for Object.

Calling a Function

You call a Function procedure by using the procedure name, followed by the argument list in parentheses, in an expression. You can omit the parentheses only if you aren't supplying any arguments. However, your code is more readable if you always include the parentheses.

You call a Function procedure the same way that you call any library function such as Sqrt, Cos, or ChrW.

You can also call a function by using the Call keyword. In that case, the return value is ignored. Use of the Call keyword isn't recommended in most cases. For more information, see Call Statement (Visual Basic).

Visual Basic sometimes rearranges arithmetic expressions to increase internal efficiency. For that reason, you shouldn't use a Function procedure in an arithmetic expression when the function changes the value of variables in the same expression.

Async Functions

The Async feature allows you to invoke asynchronous functions without using explicit callbacks or manually splitting your code across multiple functions or lambda expressions.

If you mark a function with the Async modifier, you can use the Await operator in the function. When control reaches an Await expression in the Async function, control returns to the caller, and progress in the function is suspended until the awaited task completes. When the task is complete, execution can resume in the function.

Note

An Async procedure returns to the caller when either it encounters the first awaited object that’s not yet complete, or it gets to the end of the Async procedure, whichever occurs first.

An Async function can have a return type of Task<TResult> or Task. An example of an Async function that has a return type of Task<TResult> is provided below.

An Async function cannot declare any ByRef parameters.

A Sub Statement (Visual Basic) can also be marked with the Async modifier. This is primarily used for event handlers, where a value cannot be returned. An AsyncSub procedure can't be awaited, and the caller of an AsyncSub procedure can't catch exceptions that are thrown by the Sub procedure.

For more information about Async functions, see Asynchronous Programming with Async and Await (C# and Visual Basic), Control Flow in Async Programs (C# and Visual Basic), and Async Return Types (C# and Visual Basic).

Iterator Functions

An iterator function performs a custom iteration over a collection, such as a list or array. An iterator function uses the Yield statement to return each element one at a time. When a Yield statement is reached, the current location in code is remembered. Execution is restarted from that location the next time the iterator function is called.

You call an iterator from client code by using a For Each…Next statement.

The return type of an iterator function can be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

For more information, see Iterators (C# and Visual Basic).

Example

The following example uses the Function statement to declare the name, parameters, and code that form the body of a Function procedure. The ParamArray modifier enables the function to accept a variable number of arguments.

Public Function calcSum(ByVal ParamArray args() As Double) As Double
    calcSum = 0
    If args.Length <= 0 Then Exit Function 
    For i As Integer = 0 To UBound(args, 1)
        calcSum += args(i)
    Next i
End Function

The following example invokes the function declared in the preceding example.

Module Module1

    Sub Main()
        ' In the following function call, calcSum's local variables  
        ' are assigned the following values: args(0) = 4, args(1) = 3,  
        ' and so on. The displayed sum is 10. 
        Dim returnedValue As Double = calcSum(4, 3, 2, 1)
        Console.WriteLine("Sum: " & returnedValue)
        ' Parameter args accepts zero or more arguments. The sum  
        ' displayed by the following statements is 0.
        returnedValue = calcSum()
        Console.WriteLine("Sum: " & returnedValue)
    End Sub 

    Public Function calcSum(ByVal ParamArray args() As Double) As Double
        calcSum = 0
        If args.Length <= 0 Then Exit Function 
        For i As Integer = 0 To UBound(args, 1)
            calcSum += args(i)
        Next i
    End Function 

End Module

In the following example, DelayAsync is an AsyncFunction that has a return type of Task<TResult>. DelayAsync has a Return statement that returns an integer. Therefore the function declaration of DelayAsync needs to have a return type of Task(Of Integer). Because the return type is Task(Of Integer), the evaluation of the Await expression in DoSomethingAsync produces an integer. This is demonstrated in this statement: Dim result As Integer = Await delayTask.

The startButton_Click procedure is an example of an Async Sub procedure. Because DoSomethingAsync is an Async function, the task for the call to DoSomethingAsync must be awaited, as the following statement demonstrates: Await DoSomethingAsync(). The startButton_ClickSub procedure must be defined with the Async modifier because it has an Await expression.

' Imports System.Diagnostics 
' Imports System.Threading.Tasks 

' This Click event is marked with the Async modifier. 
Private Async Sub startButton_Click(sender As Object, e As RoutedEventArgs) Handles startButton.Click
    Await DoSomethingAsync()
End Sub 

Private Async Function DoSomethingAsync() As Task
    Dim delayTask As Task(Of Integer) = DelayAsync()
    Dim result As Integer = Await delayTask

    ' The previous two statements may be combined into 
    ' the following statement. 
    ' Dim result As Integer = Await DelayAsync()

    Debug.WriteLine("Result: " & result)
End Function 

Private Async Function DelayAsync() As Task(Of Integer)
    Await Task.Delay(100)
    Return 5
End Function 

'  Output: 
'   Result: 5

See Also

Tasks

How to: Use a Generic Class (Visual Basic)

Troubleshooting Procedures (Visual Basic)

Reference

Sub Statement (Visual Basic)

Parameter List (Visual Basic)

Dim Statement (Visual Basic)

Call Statement (Visual Basic)

Of Clause (Visual Basic)

Function Expression (Visual Basic)

Concepts

Function Procedures (Visual Basic)

Parameter Arrays (Visual Basic)

Lambda Expressions (Visual Basic)