Cadeias de caracteres de formato numérico padrão
Cadeias de caracteres de formato numérico padrão são usadas para formatar tipos numéricos comuns. Uma cadeia de caracteres de formato numérico padrão assume a forma [format specifier][precision specifier]
, onde:
O especificador de formato é um único caractere alfabético que especifica o tipo de formato de número, por exemplo, moeda ou porcentagem. Qualquer cadeia de caracteres de formato numérico que contenha mais de um caractere alfabético, incluindo espaço em branco, é interpretada como uma cadeia de caracteres de formato numérico personalizada. Para obter mais informações, vá para Cadeias de caracteres de formato numérico personalizadas.
O especificador de precisão é um inteiro opcional que afeta o número de dígitos na cadeia de caracteres resultante. O especificador de precisão controla o número de dígitos na representação de cadeia de caracteres de um número.
Quando o especificador de precisão controla o número de dígitos fracionários na cadeia de resultados, a cadeia de resultados reflete um número que é arredondado para um resultado representável mais próximo do resultado infinitamente preciso.
Nota
O especificador de precisão determina o número de dígitos na cadeia de resultados. Para preencher uma cadeia de caracteres de resultado com espaços à esquerda ou à direita ou outros caracteres (como 0), use as funções Text.PadStart e Text.PadEnd e use o comprimento total
count
nessas funções para preencher a cadeia de caracteres de resultado.
Cadeias de caracteres de formato numérico padrão são suportadas pela função Number.ToText.
Especificadores de formato padrão
A tabela a seguir descreve os especificadores de formato numérico padrão e exibe a saída de amostra produzida por cada especificador de formato. Vá para a seção Notas para obter informações adicionais sobre como usar cadeias de caracteres de formato numérico padrão e a seção Exemplo de código para obter uma ilustração abrangente de seu uso.
Nota
O resultado de uma cadeia de caracteres formatada para uma cultura específica pode diferir dos exemplos a seguir. As configurações do sistema operacional, as configurações do usuário, as variáveis de ambiente e outras configurações no sistema que você usa podem afetar o formato.
Especificador de formato | Nome | Descrição | Exemplos |
---|---|---|---|
"C" ou "c" | Moeda | Resultado: um valor de moeda. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos decimais. Especificador de precisão padrão: definido pela cultura. Para obter mais informações: O especificador de formato de moeda ("C"). |
123.456 ("C", pt-BR) -> \$123,46 123.456 ("C", fr-FR) -> 123,46 € 123.456 ("C", ja-JP) -> ¥123 -123.456 ("C3", pt-BR) -> (\$123.456) -123.456 ("C3", fr-FR) -> -123.456 € -123.456 ("C3", ja-JP) -> -¥123.456 |
"D" ou "d" | Decimal | Resultado: dígitos inteiros com sinal negativo opcional. Suportado por: Apenas tipos integrais. Especificador de precisão: Número mínimo de dígitos. Especificador de precisão padrão: número mínimo de dígitos necessários. Para obter mais informações: O especificador de formato decimal("D"). |
1234 ("D") -> 1234 -1234 ("D6") -> -001234 |
"E" ou "e" | Exponencial (científico) | Resultado: Notação exponencial. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos decimais. Especificador de precisão padrão: 6. Mais informações: O especificador de formato exponencial ("E"). |
1052.0329112756 ("E", pt-BR) -> 1.052033E+003 1052.0329112756 ("e", fr-FR) -> 1,052033e+003 -1052.0329112756 ("e2", pt-BR) -> -1.05e+003 -1052.0329112756 ("E2", fr-FR) -> -1,05E+003 |
"F" ou "f" | Ponto fixo | Resultado: Dígitos integrais e decimais com sinal negativo opcional. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos decimais. Especificador de precisão padrão: definido pela cultura. Para obter mais informações: O especificador de formato de ponto fixo ("F"). |
1234.567 ("F", pt-BR) -> 1234.57 1234.567 ("F", de-DE) -> 1234,57 1234 ("F1", pt-BR) -> 1234,0 1234 ("F1", de-DE) -> 1234,0 -1234.56 ("F4", pt-BR) -> -1234.5600 -1234.56 ("F4", de-DE) -> -1234,5600 |
"G" ou "g" | Geral | Resultado: O mais compacto de notação de ponto fixo ou científica. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos significativos. Especificador de precisão padrão: depende do tipo numérico. Para obter mais informações: O especificador de formato geral ("G"). |
-123.456 ("G", pt-BR) -> -123.456 -123.456 ("G", sv-SE) -> -123.456 123.4546 ("G4", pt-BR) -> 123,5 123.4546 ("G4", SV-SE) -> 123,5 -1.234567890e-25 ("G", pt-BR) -> -1.23456789E-25 -1.234567890e-25 ("G", sv-SE) -> -1,23456789E-25 |
"N" ou "n" | Número | Resultado: dígitos integrais e decimais, separadores de grupo e um separador decimal com sinal negativo opcional. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número desejado de casas decimais. Especificador de precisão padrão: definido pela cultura. Para obter mais informações: O especificador de formato numérico ("N"). |
1234.567 ("N", pt-BR) -> 1.234,57 1234.567 ("N", ru-RU) -> 1 234,57 1234 ("N1", pt-BR) -> 1.234,0 1234 ("N1", ru-RU) -> 1 234,0 -1234.56 ("N3", pt-BR) -> -1.234,560 -1234.56 ("N3", ru-RU) -> -1 234.560 |
"P" ou "p" | Percentagem | Resultado: Número multiplicado por 100 e exibido com um símbolo de porcentagem. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número desejado de casas decimais. Especificador de precisão padrão: definido pela cultura. Para obter mais informações: O especificador de formato de porcentagem ("P"). |
1 ("P", pt-BR) -> 100,00 % 1 ("P", fr-FR) -> 100,00 % -0.39678 ("P1", pt-BR) -> -39,7% -0.39678 ("P1", fr-FR) -> -39,7 % |
"X" ou "x" | Hexadecimal | Resultado: Uma cadeia de caracteres hexadecimal. Suportado por: Apenas tipos integrais. Especificador de precisão: Número de dígitos na cadeia de resultados. Para obter mais informações: O especificador de formato hexadecimal ("X"). |
255 ("X") -> FF -1 ("x") -> ff 255 ("x4") -> 00ff -1 ("X4") -> 00FF |
Qualquer outro caractere único | Especificador desconhecido | Resultado: Lança um erro de expressão em tempo de execução. |
Usar cadeias de caracteres de formato numérico padrão
Uma cadeia de caracteres de formato numérico padrão pode ser usada para definir a formatação de um valor numérico. Ele pode ser passado para o parâmetro Number.ToTextformat
. O exemplo a seguir formata um valor numérico como uma cadeia de caracteres de moeda na cultura atual (neste caso, a cultura en-US).
Number.ToText(123.456, "C2")
// Displays $123.46
Opcionalmente, você pode fornecer um argumento count
nas funções Text.PadStart e Text.PadEnd para especificar a largura do campo numérico e se seu valor está alinhado à direita ou à esquerda. Por exemplo, o exemplo a seguir alinha à esquerda um valor de moeda em um campo de 28 caracteres e alinha à direita um valor de moeda em um campo de 14 caracteres (ao usar uma fonte monoespaçada).
let
amounts = {16305.32, 18794.16},
result = Text.Format(" Beginning Balance Ending Balance#(cr,lf) #{0}#{1}",
{
Text.PadEnd(Number.ToText(amounts{0}, "C2"), 28),
Text.PadStart(Number.ToText(amounts{1}, "C2"), 14)
})
in
result
// Displays:
// Beginning Balance Ending Balance
// $16,305.32 $18,794.16
As seções a seguir fornecem informações detalhadas sobre cada uma das cadeias de caracteres de formato numérico padrão.
Especificador de formato de moeda (C)
O especificador de formato "C" (ou moeda) converte um número em uma cadeia de caracteres que representa um valor de moeda. O especificador de precisão indica o número desejado de casas decimais na cadeia de resultados. Se o especificador de precisão for omitido, o número padrão de casas decimais a serem usadas em valores de moeda será 2.
Se o valor a ser formatado tiver mais do que o número especificado ou padrão de casas decimais, o valor fracionário será arredondado na cadeia de caracteres de resultado. Se o valor à direita do número de casas decimais especificadas for 5 ou superior, o último dígito na cadeia de resultados será arredondado para longe de zero.
A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata um valor com o especificador de formato de moeda:
let
Source =
{
Number.ToText(12345.6789, "C"),
Number.ToText(12345.6789, "C3"),
Number.ToText(12345.6789, "C3", "da-DK")
}
in
Source
// The example displays the following list on a system whose
// current culture is English (United States):
// $12,345.68
// $12,345.679
// 12.345,679 kr.
Especificador de formato decimal (D)
O especificador de formato "D" (ou decimal) converte um número em uma cadeia de dígitos decimais (0-9), prefixada por um sinal de menos se o número for negativo. Este formato é suportado apenas para tipos integrais.
O especificador de precisão indica o número mínimo de dígitos desejados na cadeia resultante. Se necessário, o número é acolchoado com zeros à esquerda para produzir o número de dígitos dado pelo especificador de precisão. Se nenhum especificador de precisão for especificado, o padrão será o valor mínimo necessário para representar o inteiro sem zeros à esquerda.
A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata um valor com o especificador de formato decimal.
let
Source =
{
Number.ToText(12345, "D"),
// Displays 12345
Number.ToText(12345, "D8"),
// Displays 00012345
Number.ToText(-12345, "D"),
// Displays -12345
Number.ToText(-12345, "D8")
// Displays -00012345
}
in
Source
Especificador de formato exponencial (E)
O especificador de formato exponencial ("E") converte um número em uma cadeia de caracteres da forma "-d.ddd... E+ddd" ou "-d.ddd... e+ddd", onde cada "d" indica um dígito (0-9). A cadeia de caracteres começa com um sinal de menos se o número for negativo. Exatamente um dígito sempre precede a vírgula decimal.
O especificador de precisão indica o número desejado de dígitos após a vírgula decimal. Se o especificador de precisão for omitido, será usado um padrão de seis dígitos após a vírgula decimal.
O caso do especificador de formato indica se o expoente deve prefixar com um "E" ou um "e". O expoente consiste sempre num sinal de mais ou menos e num mínimo de três dígitos. O expoente é acolchoado com zeros para cumprir este mínimo, se necessário.
A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata um valor com o especificador de formato exponencial:
let
Source =
{
Number.ToText(12345.6789, "E", ""),
// Displays 1.234568E+004
Number.ToText(12345.6789, "E10", ""),
// Displays 1.2345678900E+004
Number.ToText(12345.6789, "e4", ""),
// 1.2346e+004
Number.ToText(12345.6789, "E", "fr-FR")
// Displays 1,234568E+004
}
in
Source
Nota
O valor de texto em branco ("") no último parâmetro de Number.ToText na amostra anterior refere-se à cultura invariante.
Especificador de formato de ponto fixo (F)
O especificador de formato de ponto fixo ("F") converte um número em uma cadeia de caracteres do formato "-ddd.ddd..." onde cada "d" indica um dígito (0-9). A cadeia de caracteres começa com um sinal de menos se o número for negativo.
O especificador de precisão indica o número desejado de casas decimais. Se o especificador de precisão for omitido, o número padrão de casas decimais a serem usadas em valores numéricos será 2.
A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata um valor duplo e um inteiro com o especificador de formato de ponto fixo:
let
Source =
{
Number.ToText(17843, "F", ""),
// Displays 17843.00
Number.ToText(-29541, "F3", ""),
// Displays -29541.000
Number.ToText(18934.1879, "F", ""),
// Displays 18934.19
Number.ToText(18934.1879, "F0", ""),
// Displays 18934
Number.ToText(-1898300.1987, "F1", ""),
// Displays -1898300.2
Number.ToText(-1898300.1987, "F3", "es-ES")
// Displays -1898300,199
}
in
Source
Especificador de formato geral (G)
O especificador de formato geral ("G") converte um número para o mais compacto de ponto fixo ou notação científica, dependendo do tipo do número e se um especificador de precisão está presente. O especificador de precisão define o número máximo de dígitos significativos que podem aparecer na cadeia de resultados. Se o especificador de precisão for omitido ou zero, o tipo do número determinará a precisão padrão, conforme indicado na tabela a seguir.
Tipo numérico | Precisão padrão |
---|---|
Byte.Type ou Int8.Type |
3 algarismos |
Int16.Type |
5 dígitos |
Int32.Type |
10 dígitos |
Int64.Type |
19 algarismos |
Single.Type |
9 dígitos |
Double.Type |
17 dígitos |
Decimal.Type |
15 dígitos |
A notação de ponto fixo é usada se o expoente que resultaria da expressão do número em notação científica for maior que -5 e menor que o especificador de precisão; caso contrário, utiliza-se a notação científica. O resultado contém um ponto decimal, se necessário, e zeros à direita após o ponto decimal são omitidos. Se o especificador de precisão estiver presente e o número de algarismos significativos no resultado exceder a precisão especificada, os algarismos à direita em excesso são removidos por arredondamento.
No entanto, se o número for a Decimal.Type
e o especificador de precisão for omitido, a notação de ponto fixo será sempre usada e os zeros à direita serão preservados.
Se for utilizada notação científica, o expoente no resultado é precedido de "E" se o especificador de formato for "G", ou "e" se o especificador de formato for "g". O expoente contém um mínimo de dois dígitos. Isso difere do formato de notação científica que é produzido pelo especificador de formato exponencial, que inclui um mínimo de três dígitos no expoente.
A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata valores de vírgula flutuante sortidos com o especificador de formato geral:
let
Source =
{
Number.ToText(12345.6789, "G", ""),
// Displays 12345.6789
Number.ToText(12345.6789, "G", "fr-FR"),
// Displays 12345,6789
Number.ToText(12345.6789, "G7", ""),
// Displays 12345.68
Number.ToText(.0000023, "G", ""),
// Displays 2.3E-06
Number.ToText(.0000023, "G", "fr-FR"),
// Displays 2,3E-06
Number.ToText(.0023, "G", ""),
// Displays 0.0023
Number.ToText(1234, "G2", ""),
// Displays 1.2E+03
Number.ToText(Number.PI, "G5", "")
// Displays 3.1416
}
in
Source
Especificador de formato numérico (N)
O especificador de formato numérico ("N") converte um número em uma cadeia de caracteres da forma "-d,ddd,ddd.ddd...", onde "-" indica um símbolo de número negativo, se necessário, "d" indica um dígito (0-9), "," indica um separador de grupo e "." indica um símbolo de ponto decimal. O especificador de precisão indica o número desejado de dígitos após a vírgula decimal. Se o especificador de precisão for omitido, o número de casas decimais é definido pela cultura atual.
A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata valores de vírgula flutuante sortidos com o especificador de formato de número:
let
Source =
{
Number.ToText(-12445.6789, "N", ""),
// Displays -12,445.68
Number.ToText(-12445.6789, "N1", "sv-SE"),
// Displays -12 445,7
Number.ToText(123456789, "N1", "")
// Displays 123,456,789.0
}
in
Source
Especificador de formato de porcentagem (P)
O especificador de formato de porcentagem ("P") multiplica um número por 100 e o converte em uma cadeia de caracteres que representa uma porcentagem. O especificador de precisão indica o número desejado de casas decimais. Se o especificador de precisão for omitido, a precisão numérica padrão fornecida pela cultura atual será usada.
O exemplo a seguir formata valores de ponto flutuante com o especificador de formato de porcentagem:
let
Source =
{
Number.ToText(.2468013, "P", ""),
// Displays 24.68 %
Number.ToText(.2468013, "P", "hr-HR"),
// Displays 24,68 %
Number.ToText(.2468013, "P1", "en-US")
// Displays 24.7%
}
in
Source
Especificador de formato hexadecimal (X)
O especificador de formato hexadecimal ("X") converte um número em uma cadeia de dígitos hexadecimais. O maiúsculo do especificador de formato indica se deve ser usado caracteres maiúsculos ou minúsculos para dígitos hexadecimais maiores que 9. Por exemplo, use "X" para produzir "ABCDEF" e "x" para produzir "abcdef". Este formato é suportado apenas para tipos integrais.
O especificador de precisão indica o número mínimo de dígitos desejados na cadeia resultante. Se necessário, o número é acolchoado com zeros à esquerda para produzir o número de dígitos dado pelo especificador de precisão.
A cadeia de caracteres de resultado não é afetada pelas informações de formatação da cultura atual.
O exemplo a seguir formata valores com o especificador de formato hexadecimal.
let
Source =
{
Number.ToText(0x2045e, "x"),
// Displays 2045e
Number.ToText(0x2045e, "X"),
// Displays 2045E
Number.ToText(0x2045e, "X8"),
// Displays 0002045E
Number.ToText(123456789, "X"),
// Displays 75BCD15
Number.ToText(123456789, "X2")
// Displays 75BCD15
}
in
Source
Notas
Esta seção contém informações adicionais sobre como usar cadeias de caracteres de formato numérico padrão.
Tipos numéricos integrais e de vírgula flutuante
Algumas descrições de especificadores de formato numérico padrão referem-se a tipos numéricos integrais ou de vírgula flutuante. Os tipos numéricos integrais são Byte.Type
, , , Int8.Type
Int16.Type
, eInt32.Type
Int64.Type
. Os tipos numéricos de vírgula flutuante são Decimal.Type
, Single.Type
e Double.Type
.
Infinidades de vírgula flutuante e NaN
Independentemente da cadeia de caracteres de formato, se o valor de um Decimal.Type
, Single.Type
ou Double.Type
tipo de ponto flutuante for infinito positivo, infinito negativo ou não um número (NaN), a cadeia formatada é o valor das respetivas constantes Number.PositiveInfinity, Number.NegativeInfinityou Number.NaN especificadas pela cultura atualmente aplicável.
Exemplo de código
O exemplo a seguir formata um ponto flutuante e um valor numérico integral usando a cultura en-US e todos os especificadores de formato numérico padrão. Este exemplo usa dois tipos numéricos específicos (Double.Type
e Int32.Type
), mas produziria resultados semelhantes para qualquer um dos outros tipos de base numérica (Byte.Type
, Decimal.Type
, Int8.Type
, Int16.Type
, Int64.Type
, e Single.Type
).
let
// Display text representations of numbers for en-US culture
culture = "en-US",
// Output floating point values
floating = Double.From(10761.937554),
#"Floating results" =
{
Text.Format("C: #{0}", {Number.ToText(floating, "C", culture)}), // Displays "C: $10,761.94"
Text.Format("E: #{0}", {Number.ToText(floating, "E03", culture)}), // Displays "E: 1.076E+004"
Text.Format("F: #{0}", {Number.ToText(floating, "F04", culture)}), // Displays "F: 10761.9376"
Text.Format("G: #{0}", {Number.ToText(floating, "G", culture)}), // Displays "G: 10761.937554"
Text.Format("N: #{0}", {Number.ToText(floating, "N03", culture)}), // Displays "N: 10,761.938"
Text.Format("P: #{0}", {Number.ToText(floating/10000, "P02", culture)}) // Displays "P: 107.62%"
},
// Output integral values
integral = Int32.From(8395),
#"Integral results" =
{
Text.Format("C: #{0}", {Number.ToText(integral, "C", culture)}), // Displays "C: $8,395.00"
Text.Format("D: #{0}", {Number.ToText(integral, "D6", culture)}), // Displays "D: 008395"
Text.Format("E: #{0}", {Number.ToText(integral, "E03", culture)}), // Displays "E: 8.395E+003"
Text.Format("F: #{0}", {Number.ToText(integral, "F01", culture)}), // Displays "F: 8395.0"
Text.Format("G: #{0}", {Number.ToText(integral, "G", culture)}), // Displays "G: 8395"
Text.Format("N: #{0}", {Number.ToText(integral, "N01", culture)}), // Displays "N: 8,395.0"
Text.Format("P: #{0}", {Number.ToText(integral/10000, "P02", culture)}), // Displays "P: 83.95%"
Text.Format("X: 0x#{0}", {Number.ToText(integral, "X", culture)}) // Displays "X: 0x20CB"
},
results = #"Floating results" & #"Integral results"
in
results