Função Format

Converte um número numa cadeia e formata-o de acordo com o formato que o utilizador especificar.

Sintaxe:

Format (Número [, Format As String])

Valor de retorno:

Cadeia

Parâmetros:

Número: expressão numérica que deseje converter para uma cadeia formatada.

Format: cadeia que especifica o código de formato para o número. Se Format for omitida, a função Format funciona como a função Str.

Códigos de formatação

A lista seguinte descreve os códigos que pode utilizar para formatar um número:

0: se Number tem um dígito na posição do 0 no código do formato, o dígito é mostrado, senão é mostrado um zero.

Se Number tiver menos dígitos que o número de zeros no código do formato (em qualquer um dos lados da casa decimal), são mostrados os zeros à esquerda ou à direita. Se o número tiver mais dígitos à esquerda do separador decimal do que zeros no código do formato, os dígitos adicionais são mostrados sem formatação.

As casas decimais são arredondadas de acordo com o número de zeros que surgem depois do separador decimal no código do Formato.

#: se Number contém um dígito na posição do marcador de posição # no código doFormato, o dígito é mostrado, caso contrário nada é mostrado nesta posição.

Este símbolo funciona como o 0, exceto no facto de que os zeros à esquerda ou à direita não são mostrados se existirem mais caracteres # no código de formato do que dígitos no número. Só são mostrados os dígitos relevantes do número.

.: O marcador de posição decimal determina o número de casas decimais à esquerda e direita do separador decimal.

Se o código do formato só tiver marcadores de posição # à esquerda deste símbolo, os números inferiores a 1 começam com um separador decimal. Para mostrar sempre um zero à esquerda nos números fracionários, utilize 0 como marcador de posição para o primeiro dígito à esquerda do separador decimal.

%: multiplica o número por 100 e insere o sinal de percentagem (%), em que o número surge no código do formato.

E- E+ e- e+ : se o código do formato contém pelo menos um marcador de posição de dígitos (0 ou #) à direita do símbolo E-, E+, e-, ou e+, o número é formatado de acordo com o formato científico ou exponencial. A letra E ou e é inserida entre o número e o expoente. O número de marcadores de posição de dígitos à direita do símbolo determina o número de dígitos no expoente.

Se o expoente for negativo, é mostrado um sinal negativo antes de um expoente com E-, E+, e-, e+. Se o expoente for positivo, só é mostrado o sinal de mais antes dos expoentes com E+ ou e+.

O separador de milhares é mostrado se o código do formato contiver o separador entre os marcadores de posição de dígitos (0 ou #).

A utilização do ponto como separador de milhares e decimal depende da configuração regional. Ao introduzir um número no código fonte do Basic, utilize sempre um ponto como separador decimal. O carácter mostrado como separador decimal depende do formato numérico nas definições do sistema.

- + $ ( ) espaço: o sinal de adição (+), de subtração (-), dólar ($), espaço ou parênteses inserido no código do formato é mostrado como um carácter literal.

Para mostrar diferentes dos que aqui estão listados, terá de precedê-los com uma barra invertida (\) ou colocá-los entre aspas (" ").

\ : A barra invertida mostra o carácter seguinte no código do formato.

Os caracteres no código do formato que tenham um significado especial só podem ser mostrados como caracteres literais se forem precedidos por uma barra invertida. A barra invertida não é mostrada, a menos que introduza uma barra invertida dupla (\\) no código do formato.

Os caracteres que têm de ser precedidos por uma barra invertida no código do formato para serem mostrados como caracteres literais são os caracteres de formatação da data e hora (a, c, d, h, m, n, p, q, s, t, w, y, /, :), caracteres de formatação numérica (#, 0, %, E, e, vírgula, ponto final) e os caracteres de formatação de cadeias (@, &, <, >, !).

Também pode utilizar os seguintes formatos numéricos. Com exceção do "Número geral", todos os códigos de formato pré-definido devolvem o número com duas casas decimais.

Se utilizar formatos pré-definidos, o nome do formato terá de estar entre aspas.

Formato pré-definido

Geral: os números são mostrados tal como inseridos.

Moeda: insere um símbolo à frente do número e coloca os números negativos entre parênteses.

Fixa: mostra, pelo menos, um dígito à frente do separador decimal.

Padrão: mostra os números com o separador de milhares.

Percentagem: multiplica o número por 100 e anexa um sinal de percentagem ao número.

Científico: mostra os números em notação cientifica (por exemplo, 1,00E+03 para 1000).

Um código de formato pode ser dividido em três secções separadas por ponto e vírgula. A primeira parte define o formato dos valores positivos, a segunda dos negativos e a terceira do zero. Se só especificar um código do formato, este aplica-se a todos os números.

Pode definir a configuração regional utilizada para controlar o formato de números, datas e moedas no LibreOffice Basic em - Definições de idioma - Idiomas. Nos códigos de formato do Basic, o ponto decimal (.) é sempre utilizado como marcador de posição para o separador decimal definido na sua localização e será substituído pelo carácter correspondente.

O mesmo é aplicável às configurações regionais para data, hora e moeda. O código de formatação do Basic será interpretado e mostrado de acordo com a configuração regional do utilizador.

Códigos de erro

5 Chamada de procedimento inválido

Exemplo:

Sub ExampleFormat

    MsgBox Format(6328.2, "##,##0.00")

    ' utilize sempre um ponto como delimitador decimal ao introduzir números no código fonte Basic.

    ' mostra 6,328.20 na configuração regional inglesa e 6.328,20 na configuração regional alemã.

End Sub