Módulo
Conteúdo
Índice 🔎︎

# Função Format

Converte um número em um string e então o formata de acordo com o especificado.

## Sintaxe:

    Format (Number [, Format As String])

## Valor de retorno:

String

## Parâmetros:

Number: qualquer expressão numérica que você deseje converter em uma cadeia de caracteres formatada.

Format: cadeia de caracteres que especifica o código do formato para o número. Se Format for omitido, a função Format se comportará como a função Str.

## Códigos de formatação

A lista a seguir descreve os códigos que você pode usar para formatar um número:

0: se Number exibir um dígito na posição do 0 no código de formato, o dígito será exibido; do contrário, será exibido 0.

Se a expressão Number tiver menos dígitos que o número de zeros no código de formato (em qualquer lado do decimal), serão exibidos zeros à esquerda ou à direita. Se o número tiver mais dígitos à esquerda do separador decimal do que o número de zeros no código do formato, os dígitos adicionais serão exibidos sem modificação.

As casas decimais no número são arredondadas de acordo com o número de zeros exibidos após o separador decimal no código Format .

#: se Number contiver um dígito na posição do espaço reservado para # no código Format, será exibido o dígito; do contrário, não será exibido nada nesta posição.

Este símbolo funciona como o 0, exceto pelo fato de que os zeros à esquerda ou à direita não serão exibidos se houver mais caracteres # no código de formato do que dígitos no número. Serão exibidos apenas os dígitos relevantes ao número.

.: o espaço reservado para decimal determina o número de casas decimais à esquerda e à direita do separador decimal.

Se o código de formato contiver somente espaços reservados para # à esquerda deste símbolo, os números menores que 1 começarão com um separador decimal. Para exibir sempre um zero à esquerda dos números fracionários, use o 0 como um espaço reservado para o primeiro dígito à esquerda do separador decimal.

%: multiplica o número por 100 e insere o sinal de porcentagem (%) na posição onde o número aparece no código de formato.

E- E+ e- e+ : Se o código de formato contiver ao menos um espaço reservado para dígito (0 ou #) à direita do símbolo E-, E+, e- ou e+, será aplicado um formato científico ou exponencial ao número. A letra E ou e será inserida entre o número e o expoente. O número de espaços reservados para dígitos à direita do símbolo determina o número de dígitos no expoente.

Se o expoente for negativo, o sinal de subtração será exibido diretamente antes de um expoente com E-, E+, e-, e+. Se o expoente for positivo, o sinal de adição só será exibido antes de expoentes com E+ ou e+.

O delimitador de milhares será exibido se o código do formato exibir o delimitador entre espaços reservados para dígito (0 ou #).

O uso do ponto como separador de milhares e de decimais é dependente das configurações regionais. Quando usar um número no código fonte Basic, sempre use um ponto como separador decimal. O caractere exibido como separador decimal depende no formato de número usado no seu sistema.

- + $ ( ) espaço : O sinal de adição (+), subtração (-), cifrão ($), espaço ou parênteses inserido diretamente no código de formato será exibido com um caractere literal.

Para exibir caracteres diferentes dos listados aqui, você deve precedê-los de uma barra invertida (\) ou colocá-los entre aspas (" ").

\ : A barra invertida exibe o próximo caractere no código de formato.

Os caracteres no código de formato que tiverem significado especial só poderão ser exibidos como caracteres literais se estiverem precedidos de uma barra invertida. A barra invertida propriamente dita não é exibida, a menos que você insira duas barras invertidas (\\) no código de formato.

Os caracteres que devem ser precedidos de uma barra invertida no código de formato para serem exibidos como caracteres literais são: caracteres de formatação de data e hora (a, c, d, h, m, n, p, q, s, t, w, y, /, :), caracteres de formatação de números (#, 0, E, %, e, vírgula, ponto) e caracteres de formatação de cadeia de caracteres (@, &, <, >, !).

Você também pode usar os formatos de número predefinidos apresentados a seguir. Com exceção de "Número Geral", todos os códigos predefinidos retornam o número como um formato decimal com duas casas.

Se você usar formatos predefinidos, o nome do formato deverá estar entre aspas.

## Formato predefinido

General Number: os números são exibidos da forma como são inseridos.

Currency: insere um sinal de cifrão na frente do número e coloca os números negativos entre parênteses.

Fixed: exibe pelo menos um dígito na frente do separador decimal.

Standard: exibe os números com um separador de milhar.

Percent: multiplica o número por 100 e acrescenta a ele um sinal de porcentagem.

Scientific: Exibe números no formato científico (por exemplo, 1.00E+03 for 1000).

Um código de formato pode ser dividido em três seções separadas por ponto e vírgula. A primeira parte define o formato como valores positivos, a segunda como valores negativos e, a terceira, como zero. Se você especificar somente um código de formato, ele será aplicado a todos os números.

Você pode definir o local utilizado para controlar o formato de números, datas e moedas no LibreOffice Basic em LibreOffice - Preferências Ferramentas - Opções
- Configurações de idioma - Idiomas. Nos códigos de formato do Basic, o ponto decimal (.) sempre será utilizado como espaço reservado para o separador decimal em seu local e será substituído pelo caractere correspondente.

O mesmo se aplica para as configurações de locale para data, hora e formatos monetários. O código de formatação do Basic será interpretado e exibido de acordo com suas configurações de locale.

## Códigos de erro:

5 Chamada de procedimento inválida

## Exemplo:

    Sub ExampleFormat

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

        ' sempre use um ponto como separador decimal quando digitar números no código fonte Basic.

        ' exibe, por exemplo, 6,328.20 em Inglês, 6.328,20 em Alemão.

    End Sub

Tópicos relacionados

Códigos de formatos numéricos