Instrução Function

  • Artigo

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

Sintaxe

[Público | Privada | Amigo] [Estático] Nome dafunçã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:

Sair Descrição
Public Opcional. Indica que o procedimento Function está acessível a todos os outros procedimentos em todos os módulos. Se usado em um módulo que contém uma opção Privada, o procedimento não estará disponível fora do projeto.
Private Opcional. Indica que o procedimento Function está acessível apenas a outros procedimentos no módulo em que ele é declarado.
Amigo Opcional. Usado somente em um módulo de classe. Indica que o procedimento Function está visível em todo o projeto, mas não visível para um controlador de uma instância de um objeto.
Static Opcional. Indica que as variáveis locais do procedimento function são preservadas entre chamadas. O atributo estático não afeta variáveis declaradas fora da Função, mesmo que sejam usadas no procedimento.
name Obrigatório. Nome da Função; segue convenções de nomenclatura de variável padrão.
listadeargumentos Opcional. Lista de variáveis que representam argumentos que são passados para o procedimento Function quando ele é chamado. Diversas variáveis separadas por vírgulas.
type Opcional. Tipo de dados do valor retornado pelo procedimento Function; pode ser Byte, Boolean, Integer, Long, Conversor de Moedas, Single, Double, Decimal (não compatível atualmente), Date, String (exceto comprimento fixo), Objeto, Variant ou qualquer tipo definido pelo usuário.
instruções Opcional. Qualquer grupo de instruções a serem executadas no procedimento Function .
expression Opcional. Retorno do valor da Função.

O argumento listadeargumentos tem as seguintes sintaxe e partes:

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

Sair Descrição
Opcional Opcional. Indica se um argumento não é obrigatório. Se for usado, todos os argumentos subsequentes em arglist também deverão ser opcionais e declarados usando a palavra-chave Optional. Optional não podem ser usados para um argumento se ParamArray for usado.
ByVal Opcional. Indica se o argumento será passado por valor.
ByRef Opcional. Indica se o argumento será passado por referência. ByRef é o padrão no VBA diferentemente do Visual Basic .NET.
ParamArray Opcional. Usado apenas como o último argumento no arglist para indicar que o argumento final é uma matriz opcional de elementos Variant . A palavra-chave ParamArray permite que você forneça um número aleatório de argumentos. Ele pode não ser usado com ByVal, ByRef ou Opcional.
nomedavariável Obrigatório. Nome da variável que representa o argumento passado; segue as convenções de nomenclatura de variável padrão.
tipo Opcional. Tipo de dados do argumento passado para o procedimento; pode ser Byte, Boolean, Integer, Long, Conversor de Moedas, Single, Double, Decimal (não suportado atualmente) Date, String (somente comprimento de variável), Objeto, Variant ou um tipo de objeto específico. Se o parâmetro não for Optional, um tipo definido pelo usuário também poderá ser especificado.
valorpadrão Opcional. Qualquer expressão constante ou constante. Válido somente para parâmetros Optional. Se o tipo for Object, um valor padrão explícito só poderá ser Nothing.

Comentários

Se não for especificado explicitamente usando procedimentos públicos, privados ou amigos, os procedimentos de função 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 Amigo pode ser associado tardiamente.

Os procedimentos de função podem ser recursivos; ou seja, eles podem se chamar para executar uma determinada tarefa. No entanto, a recursão pode levar a um estouro de pilha. O palavra-chave estático geralmente não é usado com procedimentos de Função recursiva.

Todo código executável deve estar em procedimentos. Você não pode definir um procedimento function dentro de outro procedimento de Função, Sub ou Propriedade .

A instrução Exit Function causa uma saída imediata de um procedimento function . A execução do programa continua com a instrução seguindo a instrução que chamou o procedimento Function . Qualquer número de instruções da 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 levar 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 você 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 em parênteses, em uma expressão. Consulte a instrução Chamada para obter informações específicas sobre como chamar procedimentos de função .

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 retorna 0, uma função de cadeia de caracteres retorna uma cadeia de caracteres de comprimento zero (") e uma função Variant retorna Vazia. Uma função que retorna uma referência de objeto retorna Nada 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 declaradas explicitamente 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 tenha o mesmo nome de outro procedimento, constante ou variável, supõe-se que seu procedimento se refere a esse nome no nível do módulo. Declare explicitamente variáveis para evitar esse tipo de conflito. Use uma instrução Opção Explícita 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 altera o valor das 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 opcionais inicializados e com tipo rígido.

' 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 do palavra-chave ParamArray permite que uma função aceite um número variável de argumentos. Na definição a seguir, ela é passada 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 e tipos padrão que não sejam 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

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.