Instrução Function

  • Artigo

Declara o nome, argumentos e código que formam o corpo de um procedimento de Função.

Sintaxe

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

A sintaxe da instrução função tem as seguintes partes:

Sair Descrição
Public Opcional. Indica que o procedimento de Função está acessível a todos os outros procedimentos em todos os módulos. Se for utilizado num módulo que contém uma Opção Privada, o procedimento não está disponível fora do projeto.
Private Opcional. Indica que o procedimento da Função está acessível apenas a outros procedimentos no módulo onde é declarado.
Amigo Opcional. Usado somente em um módulo de classe. Indica que o procedimento de Função 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 da Função são preservadas entre chamadas. O atributo Estático não afeta as variáveis declaradas fora da Função, mesmo que sejam utilizadas no procedimento.
name Obrigatório. Nome da Função; segue as convenções de nomenclatura de variáveis padrão.
listadeargumentos Opcional. Lista de variáveis que representam argumentos que são transmitidos ao procedimento de Função quando é chamado. Diversas variáveis separadas por vírgulas.
type Opcional. Tipo de dados do valor devolvido pelo procedimento de Função; podem ser Byte, Booleano, Número Inteiro, Longo, Conversor de Moedas, Único, Duplo, Decimal (não suportado atualmente), Data, Cadeia (exceto comprimento fixo), Objeto, Variante ou qualquer tipo definido pelo utilizador.
instruções Opcional. Qualquer grupo de instruções a executar no procedimento da Função .
expression Opcional. Valor devolvido 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 é a predefinição no VBA, ao contrário do Visual Basic .NET.
ParamArray Opcional. Utilizado apenas como o último argumento em arglist para indicar que o argumento final é uma matriz Opcional de elementos Variante . A palavra-chave ParamArray permite que você forneça um número aleatório de argumentos. Não pode ser utilizado 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 transmitido ao procedimento; podem ser Byte, Booleano, Número Inteiro, Longo, Conversor de Moedas, Único, Duplo, Decimal (não suportado atualmente) Data, Cadeia (apenas comprimento variável), Objeto, Variante 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 especificar explicitamente utilizando Público, Privado ou Amigo, os procedimentos de função são públicos por predefiniçã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 da respetiva classe principal, nem um procedimento Friend pode estar atrasado.

Os procedimentos de função podem ser recursivos; ou seja, podem chamar-se a si próprios para realizar uma determinada tarefa. No entanto, a recursão pode levar a um estouro de pilha. Normalmente, a palavra-chave Estática não é utilizada com procedimentos de Função recursiva.

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

A instrução Exit Function (Sair da Função ) provoca uma saída imediata de um procedimento de Função . A execução do programa continua com a instrução a seguir à instrução que chamou o procedimento de Função . Qualquer número de instruções da Função de Saída pode aparecer em qualquer lugar num procedimento de Função .

Tal como um procedimento Sub , um procedimento de Função é um procedimento separado que pode utilizar argumentos, executar uma série de instruções e alterar os valores dos respetivos argumentos. No entanto, ao contrário de um procedimento Sub , pode utilizar um procedimento de Função no lado direito de uma expressão da mesma forma que utiliza qualquer função intrínseca, como Sqr, Cos ou Chr, quando quiser utilizar o valor devolvido pela função.

Pode chamar um procedimento de Função com o nome da função, seguido da lista de argumentos entre parênteses, numa expressão. Consulte a instrução Chamar para obter informações específicas sobre como chamar procedimentos de Função .

Para devolver um valor de uma função, atribua o valor ao nome da função. Qualquer número dessas atribuições pode aparecer em qualquer parte do procedimento. Se não for atribuído nenhum valor ao nome, o procedimento devolve um valor predefinido: uma função numérica devolve 0, uma função de cadeia devolve uma cadeia de comprimento zero ("") e uma função Variant devolve Vazio. Uma função que devolve uma referência de objeto devolve Nada se não for atribuída nenhuma referência de objeto ao nome (utilizando Definir) na Função.

O exemplo seguinte mostra como atribuir um valor devolvido a uma função. Neste caso, Falso é 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 utilizadas nos procedimentos de Função enquadram-se em duas categorias: as que são explicitamente declaradas no procedimento e as 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 seu procedimento se referir a uma variável não declarada que tenha o mesmo nome que outro procedimento, constante ou variável, presume-se que o procedimento se refere a esse nome ao nível do módulo. Declare explicitamente variáveis para evitar este tipo de conflito. Utilize 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 utilizar um procedimento de Função numa expressão aritmética quando a função alterar o valor das variáveis na mesma expressão. Para obter mais informações sobre operadores aritméticos, veja Operadores.

Exemplo

Este exemplo utiliza a instrução Função para declarar o nome, argumentos e código que formam o corpo de um procedimento de Função . O último exemplo utiliza argumentos Opcionais de tipo rígido inicializado.

' 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

A utilização da palavra-chave ParamArray permite que uma função aceite um número variável de argumentos. Na seguinte definição, é transmitida 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 predefinidos que não Variante.

' 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.