Instrução Function

Declara o nome, os argumentos e o código que formam o corpo de um procedimentoFunction.

Sintaxe

[Público | Privado | Amigo] [ Estático ] Nome da função [ ( arglist ) ] [ Comotipo ]
[instruções]
[ nome=expressão ]
[ Função de saída ]
[instruções]
[ nome=expressão ]
End Function

A sintaxe da instrução Function tem estas partes:

O argumento listadeargumentos tem as seguintes sintaxe e partes:

[ Optional ] [ ByVal | ByRef ] [ ParamArray ] varname [()] [ Comotype ] [ =defaultValue ]

Comentários

Se não forem especificados explicitamente usando Public, Private ou Friend, os procedimentos Function serão públicos por padrão.

Se Static não for usado, o valor de variáveis locais não será preservado entre chamadas.

A palavra-chave Friend só pode ser usada em módulos de classe. No entanto, procedimentos Friend podem ser acessados por procedimentos em qualquer módulo de um projeto. Um procedimento Friend não aparece na biblioteca de tipos de sua classe pai, nem um procedimento Friend pode ser associado tardiamente.

Os procedimentos de função podem ser recursivos; ou seja, eles podem chamar a si mesmos para realizar uma determinada tarefa. No entanto, a recursão pode levar a um estouro de pilha. A palavra-chave Static geralmente não é usada com procedimentos de função recursiva.

Todo código executável deve estar em procedimentos. Não é possível definir um procedimento Function dentro de outro procedimento Function, Sub ou Property .

A instrução Exit Function causa uma saída imediata de um procedimento Function . A execução do programa continua com a instrução após a instrução que chamou o procedimento Function . Qualquer número de instruções de Função de Saída pode aparecer em qualquer lugar em um procedimento de Função .

Como um procedimento Sub , um procedimento Function é um procedimento separado que pode receber argumentos, executar uma série de instruções e alterar os valores de seus argumentos. No entanto, ao contrário de um procedimento Sub , você pode usar um procedimento Function no lado direito de uma expressão da mesma forma que usa qualquer função intrínseca, como Sqr, Cos ou Chr, quando quiser usar o valor retornado pela função.

Você chama um procedimento Function usando o nome da função, seguido pela lista de argumentos entre parênteses, em uma expressão. Consulte a instrução Call para obter informações específicas sobre como chamar procedimentos de Function .

Para retornar um valor de uma função, atribua o valor ao nome da função. Qualquer número dessas atribuições pode aparecer em qualquer lugar dentro do procedimento. Se nenhum valor for atribuído ao nome, o procedimento retornará um valor padrão: uma função numérica retornará 0, uma função de cadeia de caracteres retornará uma cadeia de comprimento zero ("") e uma função Variant retornará Empty. Uma função que retorna uma referência de objeto retorna Nothing se nenhuma referência de objeto for atribuída ao nome (usando Set) dentro da função.

O exemplo a seguir mostra como atribuir um valor retornado a uma função. Nesse caso, False é atribuído ao nome para indicar que algum valor não foi encontrado.

Function BinarySearch(. . .) As Boolean 
'. . . 
 ' Value not found. Return a value of False. 
 If lower > upper Then 
  BinarySearch = False 
  Exit Function 
 End If 
'. . . 
End Function

As variáveis usadas em procedimentos de Função se enquadram em duas categorias: aquelas que são explicitamente declaradas dentro do procedimento e aquelas que não são.

As variáveis que são declaradas explicitamente em um procedimento (usando Dim ou o equivalente) são sempre locais para o procedimento. As variáveis que são usadas, mas não declaradas explicitamente em um procedimento, também são locais, a menos que sejam declaradas explicitamente em algum nível superior fora do procedimento.

Um procedimento pode usar uma variável que não é declarada explicitamente no procedimento, mas um conflito de nomenclatura poderá ocorrer se algo que você definiu no nível de módulo tiver o mesmo nome. Se o procedimento se referir a uma variável não declarada que tem o mesmo nome de outro procedimento, constante ou variável, supõe-se que o procedimento se refira a esse nome no nível do módulo. Declare variáveis explicitamente para evitar esse tipo de conflito. Use uma instrução Option Explicit para forçar a declaração explícita de variáveis.

O Visual Basic pode reorganizar expressões aritméticas para aumentar a eficiência interna. Evite usar um procedimento Function em uma expressão aritmética quando a função alterar o valor de variáveis na mesma expressão. Para obter mais informações sobre operadores aritméticos, consulte Operadores.

Exemplo

Este exemplo usa a instrução Function para declarar o nome, os argumentos e o código que formam o corpo de um procedimento Function . O último exemplo usa argumentos Optional inicializados e digitados de forma embutida.

' The following user-defined function returns the square root of the 
' argument passed to it. 
Function CalculateSquareRoot(NumberArg As Double) As Double 
 If NumberArg < 0 Then ' Evaluate argument. 
  Exit Function ' Exit to calling procedure. 
 Else 
  CalculateSquareRoot = Sqr(NumberArg) ' Return square root. 
 End If 
End Function

O uso da palavra-chave ParamArray permite que uma função aceite um número variável de argumentos. Na definição a seguir, ele é passado por valor.

Function CalcSum(ByVal FirstArg As Integer, ParamArray OtherArgs()) 
Dim ReturnValue 
' If the function is invoked as follows: 
ReturnValue = CalcSum(4, 3, 2, 1) 
' Local variables are assigned the following values: FirstArg = 4, 
' OtherArgs(1) = 3, OtherArgs(2) = 2, and so on, assuming default 
' lower bound for arrays = 1. 

Os argumentos opcionais podem ter valores padrão e tipos diferentes de Variant.

' If a function's arguments are defined as follows: 
Function MyFunc(MyStr As String,Optional MyArg1 As _
 Integer = 5,Optional MyArg2 = "Dolly") 
Dim RetVal 
' The function can be invoked as follows: 
RetVal = MyFunc("Hello", 2, "World") ' All 3 arguments supplied. 
RetVal = MyFunc("Test", , 5) ' Second argument omitted. 
' Arguments one and three using named-arguments. 
RetVal = MyFunc(MyStr:="Hello ", MyArg1:=7) 

Confira também

• Chamando os procedimentos Sub e Função
• Noções básicas sobre argumentos nomeados e argumentos opcionais
• Escrevendo um procedimento de função
• Tipos de dados
• Instruções

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.