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.

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 numa cadeia 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

Especificador de formato de ponto fixo (F)

O especificador de formato de ponto fixo ("F") converte um número numa cadeia da forma "-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.

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 numérico ("N") converte um número numa cadeia do formato "-d,ddd,dd.ddd...", onde "-" indica um símbolo numérico 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.TypeInt16.Type, eInt32.TypeInt64.Type. Os tipos numéricos de vírgula flutuante são Decimal.Type, Single.Typee 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

Conteúdos relacionados

• Como a cultura afeta a formatação de texto
• Conversão de tipo de número
• Tipos de dados no Power Query
• Cadeias de caracteres de formato numérico personalizado