Conteúdo

# Função Format

Converte uma expressão numérica numa cadeia de caracteres e, em seguida, formata-a de acordo com o formato que especificar.

### Sintaxe:

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

### Parâmetros:

expressão: Expressão numérica que pretende converter numa cadeia de caracteres formatada.

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

### Tipo de retorno:

Sequência de 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 o zero. Se especificar apenas um código format, este aplica-se a todos os números.

Pode definir a localização utilizada para controlar a formatação de números, datas e moedas no LibreOffice Basic em LibreOffice - PreferênciasFerramentas - Opções - Idiomas e configurações regionais - Geral. Nos códigos de formatação do Basic, o ponto decimal (.) é sempre utilizado como marcador de posição para o separador decimal definido na sua configuração regional e será substituído pelo caractere 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.

A lista seguinte descreve os códigos que pode utilizar para formatar uma expressão numérica:

Código | Descrição
--- | ---
0 | Se a expressão tiver um algarismo na posição do 0 no código formato, esse algarismo é apresentado; caso contrário, é apresentado um zero. Se a expressão tiver menos dígitos do que o número de zeros no código de formato (em ambos os lados da vírgula decimal), são apresentados 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 formato, os dígitos adicionais são apresentados sem formatação. As casas decimais na expressão são arredondadas de acordo com o número de zeros que aparecem após o separador decimal no código formato.
# | Se a expressão contiver um algarismo na posição do marcador de lugar # no código formato, esse algarismo é apresentado; caso contrário, nada é apresentado nessa posição. Este símbolo funciona como o 0, com a diferença de que os zeros à esquerda ou à direita não são apresentados se houver mais caracteres # no código formato do que dígitos na expressão. Apenas os dígitos relevantes da expressão são apresentados.
. (period) | O marcador decimal determina o número de casas decimais à esquerda e à direita do separador decimal. Se o código format contiver apenas marcadores de posição # à esquerda deste símbolo, os números inferiores a 1 começam com um separador decimal. Para apresentar 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. 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.
% | Multiplica a expressão por 100 e insere o símbolo de percentagem (%) no local onde a expressão aparece no código formato.
E- E+ e- e+ | Se o código format contiver pelo menos um marcador de posição para dígitos (0 ou #) à direita do símbolo E-, E+, e- ou e+, a expressão é formatada no 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 para 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+.
- + $ ( ) space | Um sinal de mais (+), de menos (-), o símbolo do dólar ($), um espaço ou parênteses introduzidos diretamente no código format são apresentados como caracteres literais.
\ | 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 exibe o caractere seguinte no código formato. Os caracteres no código formato que têm um significado especial só podem ser apresentados como caracteres literais se forem precedidos por uma barra invertida. A própria barra invertida não é apresentada, a menos que se introduza uma barra invertida dupla (\\) no código de 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 (@, &, <, >, !).

## Formatos predefinidos

Também pode utilizar os seguintes formatos numéricos predefinidos. Com exceção de «Número geral», todos os códigos de formato predefinidos apresentam o número como um número decimal com duas casas decimais.

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

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

### 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ã.
    msgbox Format("ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890", "<") ' devolve abcdefghijklmnopqrstuvwxyz1234567890, os dígitos não são afetados.
    msgbox Format("abcdefghijklmnopqrstuvwxyz1234567890", ">") ' devolve ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890, os dígitos não são afetados.
    msgBox Format(12345.6, "c") ' devolve o número no formato de data 18/10/33 2:24:00 PM, de acordo com as configurações regionais alemãs.
    msgBox Format(12345.6, "Data geral") ' Equivalente a "c".
    msgbox format(12345.004,"n") ' devolve 5
    msgbox format(12345.004,"nn") ' devolve 05
    msgbox format(12345.6, "w") ' devolve 4 (quarta-feira).
    msgbox format(log(123), "Número geral") ' devolve 4,812184355372 na configuração regional alemã
    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, "Sim/Não") ' devolve "Sim" localizado
    msgbox format(0, "Sim/Não") ' devolve "Não" localizado
    msgbox format(-1, "True/False") ' devolve "True" localizado
    msgbox format(123, "On/Off") ' devolve "On" localizado
    msgbox format(45756.73, "Data longa") ' apresenta «Quarta-feira, 9 de abril de 2025» na sua localização
    End Sub

Tópicos relacionados

Códigos de formatos numéricos

Funções de cadeia de caracteres

Necessitamos da sua ajuda!