Cadeias de caracteres de formato numérico padrão

2024-12-18

As 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 o formato [format specifier][precision specifier], em que:

O especificador de formato é um só caractere alfabético que especifica o tipo de formato de número, por exemplo, moeda ou percentual. Qualquer cadeia de caracteres de formato numérico que contém mais de um caractere alfabético, incluindo espaços em branco, é interpretada como uma cadeia de caracteres de formato numérico personalizado. Para obter mais informações, acesse Cadeias de caracteres de formato numérico personalizado.
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 caracteres de resultado, a cadeia de caracteres de resultado reflete um número arredondado para um resultado representável mais próximo do resultado infinitamente preciso.

Observação

O especificador de precisão determina o número de dígitos na cadeia de caracteres de resultado. Para adicionar uma cadeia de caracteres de resultado com espaços à esquerda ou à direita ou outros caracteres (como um 0), use as funções Text.PadStart e Text.PadEnd e use o comprimento geral count nessas funções para conter a cadeia de caracteres de resultado.

As cadeias de caracteres de formato numérico padrão são compatíveis com a função Number.ToText.

Especificadores de formato padrão

A tabela a seguir descreve os especificadores de formato numérico padrão e exibe exemplos de saídas produzidas por cada especificador de formato. Vá para a seção Anotações para obter informações adicionais sobre o uso de 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.

Observação

O resultado de uma cadeia de caracteres formatada para uma cultura específica pode ser diferente 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 do sistema que você usa podem afetar o formato.

Especificador de formato	Nome	Descrição	Exemplos
"C" ou "c"	Moeda	Resultado: um valor de moeda. Compatível com: todos os tipos numéricos. Especificador de precisão: número de casas decimais. Especificador de precisão padrão: definido pela cultura. Para saber mais: especificador de formato de moeda ("C").	123,456 ("C", en-US) -> $123.46 123,456 ("C", fr-FR) -> 123,46 € 123,456 ("C", ja-JP) -> ¥123 -123.456 ("C3", en-US) -> (US$ 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. Compatível com: somente 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 saber mais: especificador de formato decimal ("D").	1234 ("D") -> 1234 -1234 ("D6") -> -001234
"E" ou "e"	Exponencial (científica)	Resultado: notação Exponencial. Compatível com: todos os tipos numéricos. Especificador de precisão: número de casas decimais. Especificador de precisão padrão: 6. Para saber mais: especificador de formato exponencial ("E").	1052.0329112756 ("E", en-US) -> 1,052033E+003 1052.0329112756 ("e", fr-FR) -> 1,052033e+003 -1052.0329112756 ("e2", en-US) -> -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. Compatível com: todos os tipos numéricos. Especificador de precisão: número de casas decimais. Especificador de precisão padrão: definido pela cultura. Para saber mais: especificador de formato de ponto fixo ("F").	1234.567 ("F", en-US) -> 1234,57 1234.567 ("F", de-DE) -> 1234,57 1234 ("F1", en-US) -> 1234.0 1234 ("F1", de-DE) -> 1234,0 -1234,56 ("F4", en-US) -> -1234.5600 -1234,56 ("F4", de-DE) -> -1234.5600
"G" ou "g"	Geral	Resultado: a mais compacta entre notação de ponto fixo ou científica. Compatível com: 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 saber mais: especificador de formato geral ("G").	-123,456 ("G", en-US) -> -123.456 -123,456 ("G", sv-SE) -> -123.456 123,4546 ("G4", en-US) -> 123,5 123,4546 ("G4", sv-SE) -> 123,5 -1,234567890e-25 ("G", en-US) -> -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. Compatível com: todos os tipos numéricos. Especificador de precisão: número de casas decimais desejadas. Especificador de precisão padrão: definido pela cultura. Para saber mais: especificador de formato numérico ("N").	1234,567 ("N", en-US) -> 1.234,57 1234.567 ("N", ru-RU) -> 1234,57 1234 ("N1", en-US) -> 1.234,0 1234 ("N1", ru-RU) -> 1234,0 -1234,56 ("N3", en-US) -> -1.234.560 -1234,56 ("N3", ru-RU) -> -1 234.560
"P" ou "p"	Porcentagem	Resultado: número multiplicado por 100 e exibido com um sinal de porcentagem. Compatível com: todos os tipos numéricos. Especificador de precisão: número de casas decimais desejadas. Especificador de precisão padrão: definido pela cultura. Para saber mais: especificador de formato de porcentagem ("P").	1 ("P", en-US) -> 100,00 % 1 ("P", fr-FR) -> 100,00 % -0,39678 ("P1", en-US) -> -39,7 % -0,39678 ("P1", fr-FR) -> -39,7 %
"X" ou "x"	Hexadecimal	Resultado: uma cadeia de caracteres hexadecimal. Compatível com: somente tipos integrais. Especificador de precisão: número de dígitos na cadeia de caracteres de resultado. Para saber mais: especificador de formato hexadecimal ("X").	255 ("X") -> FF -1 ("x") -> ff 255 ("x4") -> 00ff -1 ("X4") -> 00FF
Qualquer outro caractere único	Especificador desconhecido	Resultado: gera 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 (nesse 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 caracteres resultante. 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 tem mais do que o número especificado ou padrão de casas decimais, o valor fracionário é arredondado na cadeia de caracteres de resultado. Se o valor à direita do número de casas decimais especificadas for 5 ou mais, o último dígito da cadeia de caracteres do resultado será arredondado para cima.

A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.

O seguinte exemplo 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 caracteres de dígitos decimais (0-9), prefixados por um sinal de negativo se o número for negativo. Esse formato é compatível apenas com tipos integrais.

O especificador de precisão indica o número mínimo de dígitos desejados na cadeia de caracteres resultante. Se necessário, o número é preenchido com zeros à esquerda para produzir o número de dígitos fornecido pelo especificador de precisão. Quando nenhum especificador de precisão é especificado, o padrão é 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 do formato do exponencial ("E") converte um número em uma cadeia de caracteres no formato "-d.ddd…E+ddd" ou "-d.ddd…e+ddd", em que cada 'd' indica um dígito (0-9). A cadeia de caracteres é iniciada com um sinal de negativo se o número é negativo. Exatamente um dígito sempre precede o ponto decimal.

O especificador de precisão indica o número desejado de dígitos após o ponto decimal. Quando o especificador de precisão é omitido, um padrão de seis dígitos após o ponto decimal é usado.

A caixa do especificador de formato indica se o expoente é prefixado com um "E" ou um "e". O expoente sempre consistem em um sinal de positivo ou negativo e um mínimo de três dígitos. O expoente é preenchido com zeros para atender a esse mínimo, se necessário.

A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.

O seguinte exemplo 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

Observação

O valor de texto em branco ("") no último parâmetro de Number.ToText no exemplo anterior refere-se à cultura invariável.

Especificador de formato de ponto fixo (F)

O especificador de formato de ponto fixo ("F") converte um número em uma cadeia de caracteres no formato "-ddd.ddd…", em que cada "d" indica um dígito (0-9). A cadeia de caracteres é iniciada com um sinal de negativo se o número é negativo.

O especificador de precisão indica o número de casas decimais desejadas. 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 a notação mais compacta entre ponto fixo ou 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 caracteres de resultado. Quando o especificador de precisão é omitido ou zero, o tipo do número determina a precisão padrão, conforme indicado na tabela a seguir.

Tipo numérico	Precisão padrão
`Byte.Type` ou `Int8.Type`	3 dígitos
`Int16.Type`	5 dígitos
`Int32.Type`	10 dígitos
`Int64.Type`	19 dígitos
`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 ao expressar o número na notação científica é maior do que -5 e menor que o especificador de precisão; caso contrário, a notação científica é usada. Se necessário, o resultado contém um ponto decimal, e os zeros à direita após o ponto decimal são omitidos. Se o especificador de precisão estiver presente e o número de dígitos significativos no resultado exceder a precisão especificada, o excesso de dígitos à direita será removido por arredondamento.

No entanto, se o número for Decimal.Type e o especificador de precisão for omitido, a notação de ponto fixo será usada sempre e os zeros à direita serão preservados.

Se a notação científica for usada, o expoente no resultado será prefixado com "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 é gerado pelo especificador de formato exponencial, o qual 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 seguinte exemplo formata valores de ponto flutuante variados 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 no formato "-d,ddd,ddd.ddd…", em que "-" indica um símbolo de número negativo, se necessário, "d" indica um dígito (0-9), "," indica um separador de grupos de número e "." indica um símbolo de ponto decimal. O especificador de precisão indica o número desejado de dígitos após o ponto decimal. Se o especificador de precisão for omitido, o número de casas decimais será definido pela cultura atual.

A cadeia de caracteres de resultado é afetada pelas informações de formatação da cultura atual.

O seguinte exemplo formata valores de ponto flutuante variados com o especificador de formato numérico:

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 percentual (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 de casas decimais desejadas. Se o especificador de precisão for omitido, a precisão numérica padrão fornecida pela cultura atual será usada.

O seguinte exemplo formata valores de ponto flutuante variados 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 caracteres de dígitos hexadecimais. A caixa do especificador de formato indica se caracteres maiúsculos ou minúsculos devem ser usados para os dígitos hexadecimais maiores que 9. Por exemplo, use "X" para produzir "ABCDEF" e "x" para produzir "abcdef". Esse formato é compatível apenas com tipos integrais.

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

Observações

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 ponto flutuante

Algumas descrições de especificadores de formato numérico padrão referem-se a tipos inteiros ou de ponto flutuante. Os tipos numéricos integrais são Byte.Type, Int8.Type, Int16.Type, Int32.Type, eInt64.Type. Os tipos numéricos de ponto flutuante são Decimal.Type, Single.Type e Double.Type.

Infinitos de ponto 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 de caracteres formatada será o valor das respectivas Number.PositiveInfinity, Number.NegativeInfinityou Number.NaN constantes 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.Typee 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

Compartilhar via

Cadeias de caracteres de formato numérico padrão

Especificadores de formato padrão

Usar cadeias de caracteres de formato numérico padrão

Especificador de formato de moeda (C)

Especificador de formato decimal (D)

Especificador de formato exponencial (E)

Especificador de formato de ponto fixo (F)

Especificador de formato geral (G)

Especificador de formato numérico (N)

Especificador de formato percentual (P)

Especificador de formato hexadecimal (X)

Observações

Tipos numéricos integrais e de ponto flutuante

Infinitos de ponto flutuante e NaN

Exemplo de código

Conteúdo relacionado

Comentários

Recursos adicionais