Sumário

# Função Format

Converte uma expressão numérica em uma string e a formata de acordo com o formato que você especificar.

### Sintaxe:

    Formatar(expressão [, format As String]) As String

### Parâmetros:

expression: Expressão numérica que você deseja converter em uma string formatada.

formato: String que especifica o código de formato para o número. Se formato for omitido, a função Formato funciona como a função LibreOffice Basic Str().

### Tipo de retorno:

Caractere texto.

## Códigos de formatação

Em BASIC, um código format pode ser dividido em três secções separadas por ponto e vírgula. A primeira parte define o formato para valores positivos, a segunda parte para valores negativos e a terceira parte para zero. Se especificar apenas um código format, 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 - Idiomas e localidades - Geral. 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 localidade 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 localidade.

A lista a seguir descreve os códigos que você pode usar para formatar uma expressão numérica:

Código | Descrição
--- | ---

0

Se expressão tiver um dígito na posição do 0 no código formato, o dígito é exibido; caso contrário, é exibido um zero.

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

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

# | Se expressão contiver um dígito na posição do espaço reservado # no código formato, o dígito será exibido; caso contrário, nada será exibido nessa 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 Format do que dígitos na Expressão. Serão exibidos apenas os dígitos relevantes do Expressão.

. (period)

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

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

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.

% | Multiplica a expressão por 100 e insere o sinal de percentagem (%) onde a expressão aparece no código formato.

E- E+ e- e+

Se o código format contiver pelo menos um espaço reservado para dígitos (0 ou #) à direita do símbolo E-, E+, e- ou e+, a expressão será formatada no formato científico ou exponencial. A letra E ou e é 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+.

- + $ ( ) space | : Um sinal de mais (+), menos (-), dólar ($), espaço ou parênteses inseridos diretamente no código format são exibidos como caracteres literais.

\

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

Os caracteres no código Format que tem um significado reservado só podem ser mostrados como caracteres literais se estiverem precedidos de uma barra invertida. A barra invertida não é exibida, a menos que você digite duas barras invertidas (\\) no código de formatação.

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 (@, &, <, >, !).

## Formatos predefinidos

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

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

Código | Descrição
--- | ---
"<" | Converter expressão para minúsculas
">" | Converta expressão para maiúsculas.
"c" or "General Date" | Retorna a expressão numérica no formato de data curta, opcionalmente com "H:MM:SS AM/PM". Se expressão for uma string, retorna a string.
"n" | Retorna os minutos da expressão numérica, com 1 ou 2 dígitos.
"nn" | Retorna os minutos da expressão numérica com dois dígitos.
"w" | Retorna o dia da semana da expressão numérica. 1 é domingo e 7 é sábado.
"General Number" | Retorna a expressão numérica com 12 dígitos (0.############).
"Currency" | Retorna a expressão numérica na moeda da localidade.
"Fixed" | Retorna a expressão numérica com 2 casas decimais (0,00).
"Standard" | Retorna a expressão numérica com separadores de milhares e 2 casas decimais (@0,00).
"Percent" | Retorna a expressão numérica como valor percentual (0,00%).
"Scientific" | Retorna a expressão numérica em notação científica (#.00E+00);
"Yes/No" | Retorna “Sim” se a expressão numérica não for igual a zero, “Não” caso contrário. “Sim” e “Não” são localizados.
"True/False" | Retorna “Verdadeiro” se a expressão numérica não for igual a zero, “Falso” caso contrário. “Verdadeiro” e “Falso” são localizados.
"On/Off" | Retorna "On" se a expressão numérica não for igual a zero, "Off" caso contrário. "On" e "Off" são localizados.
"Long Date" or "dddddd" | Retorna a expressão numérica no formato longo de data do sistema e depende da linguagem.
"Medium Date" | Retorna a expressão numérica no formato de data DD-MMM-AA, dependendo da linguagem.
"Short Date" or "ddddd" | Retorna a expressão numérica no formato de data curta do sistema, dependendo da linguagem.
"Long Time" or "ttttt" | Retorna a expressão numérica no formato de hora longo do sistema e depende da localidade ("H:MM:SS AM/PM").
"Medium Time" | Retorna a expressão numérica no formato de hora médio do sistema, dependendo da localidade (HH:MM AM/PM)
"Short Time" | Retorna a expressão numérica no formato de hora curto do sistema, dependendo da linguagem (HH:MM).

### 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.
    msgbox Format("ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890", "<") ' retorna abcdefghijklmnopqrstuvwxyz1234567890, os dígitos não são afetados.
    msgbox Format("abcdefghijklmnopqrstuvwxyz1234567890", ">") ' retorna ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890, os dígitos não são afetados.
    msgBox Format(12345.6,"c") ' retorna o número no formato de data 18/10/33 2:24:00 PM da localidade Alemanha.
    msgBox Format(12345.6,"General Date") ' O mesmo que "c".
    msgbox format(12345.004,"n") ' retorna 5
    msgbox format(12345.004,"nn") ' retorna 05
    msgbox format(12345.6,"w") ' retorna 4 (Quarta-feira).
    msgbox format(log(123),"General Number") ' retorna 4,812184355372 na localidade Alemanha
    msgbox format(123456.7890,"Fixed") ' 123456.79
    msgbox format(123456.1234,"Fixed") ' 123456.12
    msgbox format(123456.7890,"Standard") '123,456.79
    msgbox format(123456.1234,"Standard") '123,456.12
    msgbox format(12.3456,"Percent") ' 1234.56%
    msgbox format(0.123456,"Percent") '12.35%
    msgbox format(123,"Yes/No") ' retorna a palavra "Yes" traduzida ("Sim")
    msgbox format(0,"Yes/No") ' retorna "No" traduzido
    msgbox format(-1,"True/False") ' retorna "True" traduzido
    msgbox format(123,"On/Off") ' retorna "On" traduzido
    msgbox format(45756.73,"Long Date") ' retorna Quarta-feira 9 de abril de 2025
    End Sub

Tópicos relacionados

Códigos de formatos numéricos

Funções de String