Cadeias de caracteres de formato numérico personalizado

Artigo
10/24/2024

Você pode criar uma cadeia de caracteres de formato numérico personalizada, que consiste em um ou mais especificadores numéricos personalizados, para definir como formatar dados numéricos. Uma cadeia de caracteres de formato numérico personalizado é qualquer cadeia de caracteres de formato que não seja uma cadeia de caracteres de formato numérico padrão.

A tabela a seguir descreve os especificadores de formato numérico personalizados e exibe a saída de exemplo produzida por cada especificador de formato. Vá para a seção Anotações para obter informações adicionais sobre como usar cadeias de caracteres de formato numérico personalizado e a seção Exemplo para obter uma ilustração abrangente de seu uso.

Especificador de formato	Nome	Descrição	Exemplos
"0"	Espaço reservado zero	Substitui o zero pelo dígito correspondente, se houver um; caso contrário, zero aparecerá na cadeia de caracteres de resultado. Para obter mais informações: O especificador personalizado "0".	1234.5678 ("00000") -> 01235 0.45678 ("0.00", pt-BR) -> 0.46 0.45678 ("0.00", fr-FR) -> 0,46
"#"	Espaço reservado para dígitos	Substitui o símbolo "#" pelo dígito correspondente, se estiver presente; caso contrário, nenhum dígito aparecerá na cadeia de caracteres de resultado. Nenhum dígito aparece na cadeia de resultados se o dígito correspondente na cadeia de entrada for um 0 não significativo. Por exemplo, 0003 ("####") -> 3. Para obter mais informações: O especificador personalizado "#".	1234.5678 ("#####") -> 1235 0.45678 ("#.##", pt-BR) -> .46 0.45678 ("#.##", fr-FR) -> ,46
"."	Ponto decimal	Determina o local do separador decimal na cadeia de caracteres de resultado. Mais informações: O "." Especificador personalizado.	0.45678 ("0.00", pt-BR) -> 0.46 0.45678 ("0.00", fr-FR) -> 0,46
","	Separador de grupo e dimensionamento de números	Serve como um separador de grupo e um especificador de escala de número. Como um separador de grupo, ele insere um caractere separador de grupo localizado entre cada grupo. Como um especificador de escala de número, ele divide um número por 1000 para cada vírgula especificada. Para obter mais informações: O especificador personalizado "," .	Especificador separador de grupo: 2147483647 ("##,#", pt-BR) -> 2,147,483,647 2147483647 ("##,#", es-ES) -> 2.147.483.647 Especificador de escala: 2147483647 ("#,#,,", pt-BR) -> 2.147 2147483647 ("#,#,,", es-ES) -> 2.147
"%"	Espaço reservado para porcentagem	Multiplica um número por 100 e insere um símbolo de porcentagem localizada na cadeia de caracteres de resultado. Para obter mais informações: O especificador personalizado "%".	0.3697 ("%#0.00", en-US) -> %36.97 0.3697 ("%#0.00", el-GR) -> %36,97 0,3697 ("##.0 %", pt-BR) -> 37,0 % 0,3697 ("##.0 %", el-GR) -> 37,0 %
"‰"	Espaço reservado por mille	Multiplica um número por 1000 e insere um símbolo localizado por mille na cadeia de resultados. Mais informações: O especificador personalizado "‰".	0.03697 ("#0.00‰", pt-BR) -> 36.97‰ 0.03697 ("#0.00‰", ru-RU) -> 36,97‰
"E0" "E+0" "E-0" "e0" "e+0" "e-0"	Notação exponencial	Se seguido por pelo menos um 0 (zero), formata o resultado usando notação exponencial. O caso de "E" ou "e" indica o caso do símbolo expoente na cadeia de resultados. O número de zeros após o caractere "E" ou "e" determina o número mínimo de dígitos no expoente. Um sinal de adição (+) indica que um caractere de sinal sempre precede o expoente. Um sinal de menos (-) indica que um caractere de sinal precede apenas expoentes negativos. Mais informações: Os especificadores personalizados "E" e "e".	987654 ("#0.0e0") -> 98.8e4 1503.92311 ("0.0##e+00") -> 1.504e+03 1.8901385E-16 ("0.0e+00") -> 1.9e-16
"\", "''", """"	Carateres de escape	Faz com que o(s) próximo(s) caractere(s) seja(m) interpretado(s) como um literal e não como um especificador de formato personalizado. Mais informações: Personagens de fuga.	987654 ("\###00\#") -> #987654# 987654 ("'#'##00'#'") -> #987654# 987654 ("""#""##00""""") -> #987654#
'String' "Corda"	Delimitador de cadeia de caracteres literal	Indica que os caracteres incluídos devem ser copiados para a cadeia de caracteres de resultado inalterada. Mais informações: Literais de caracteres.	68 ("# 'graus'") -> 68 graus 68 ("#' graus'") -> 68 graus
;	Separador de secção	Define seções com cadeias de caracteres de formato separadas para números positivos, negativos e zero. Mais informações: O ";" Separador de seção.	12.345 ("#0.0#;( #0.0#);-\0-") -> 12.35 0 ("#0.0#;( #0.0#);-\0-") -> -0- -12.345 ("#0.0#;( #0.0#);-\0-") -> (12.35) 12.345 ("#0.0#;( #0.0#)") -> 12.35 0 ("#0.0#;( #0.0#)") -> 0.0 -12.345 ("#0.0#;( #0.0#)") -> (12.35)
Outro	Todos os outros personagens	O caractere é copiado para a cadeia de caracteres de resultado inalterada. Mais informações: Literais de caracteres.	68 ("# °") -> 68 °

As seções a seguir fornecem informações detalhadas sobre cada um dos especificadores de formato numérico personalizado.

O especificador personalizado "0"

O especificador de formato personalizado "0" serve como um símbolo de espaço reservado zero. Se o valor que está sendo formatado tiver um dígito na posição em que o zero aparece na cadeia de caracteres de formato, esse dígito será copiado para a cadeia de caracteres de resultado; caso contrário, um zero aparecerá na cadeia de caracteres de resultado. A posição do zero mais à esquerda antes do ponto decimal e do zero mais à direita após o ponto decimal determina o intervalo de dígitos que estão sempre presentes na cadeia de resultados.

O especificador "00" faz com que o valor seja arredondado para o dígito mais próximo antes do decimal, onde o arredondamento de zero é sempre usado. Por exemplo, formatar 34,5 com "00" resultaria no valor 35.

O exemplo a seguir exibe vários valores que são formatados usando cadeias de caracteres de formato personalizado que incluem espaços reservados zero.

let
    Source =
    {
        Number.ToText(123, "00000", ""),
        // Displays 00123

        Number.ToText(1.2, "0.00", ""),
        // Displays 1.20

        Number.ToText(1.2, "00.00", ""),
        // Displays 01.20

        Number.ToText(1.2, "00.00", "da-DK"),
        // Displays 01,20

        Number.ToText(.56, "0.0", ""),
        // Displays 0.6

        Number.ToText(1234567890, "0,0", ""),
        // Displays 1,234,567,890

        Number.ToText(1234567890, "0,0", "el-GR"),
        // Displays 1.234.567.890

        Number.ToText(1234567890.123456, "0,0.0", ""),
        // Displays 1,234,567,890.1

        Number.ToText(1234.567890, "0,0.00", "")
        // Displays 1,234.57
    }
in
    Source

Nota

O valor de texto em branco ("") no último parâmetro de Number.ToText na amostra anterior refere-se à cultura invariante.

Voltar à mesa

O especificador personalizado "#"

O especificador de formato personalizado "#" serve como um símbolo de espaço reservado para dígitos. Se o valor que está sendo formatado tiver um dígito na posição em que o símbolo "#" aparece na cadeia de caracteres de formato, esse dígito será copiado para a cadeia de caracteres de resultado. Caso contrário, nada é armazenado nessa posição na cadeia de caracteres de resultado.

Observe que esse especificador nunca exibe um zero que não seja um dígito significativo, mesmo que zero seja o único dígito na cadeia de caracteres. Ele exibe zero somente se for um dígito significativo no número que está sendo exibido.

A cadeia de caracteres de formato "##" faz com que o valor seja arredondado para o dígito mais próximo antes do decimal, onde o arredondamento para longe de zero é sempre usado. Por exemplo, formatar 34.5 com "##" resultaria no valor 35.

O exemplo a seguir exibe vários valores que são formatados usando cadeias de caracteres de formato personalizado que incluem espaços reservados para dígitos.

let
    Source =
    {
        Number.ToText(1.2, "#.##", ""),
        // Displays 1.2

        Number.ToText(123, "#####"),
        // Displays 123

        Number.ToText(123456, "[##-##-##]"),
        // Displays [12-34-56]

        Number.ToText(1234567890, "#"),
        // Displays 1234567890

        Number.ToText(1234567890, "(###) ###-####")
        // Displays (123) 456-7890
    }
in
    Source

Para retornar uma cadeia de caracteres de resultado na qual dígitos ausentes ou zeros à esquerda são substituídos por espaços, use o Text.PadStart e especifique uma largura de campo, como ilustra o exemplo a seguir.

let
   Source = Text.Format("The value is: '#{0}'", {Text.PadStart(Number.ToText(.324, "#.###"), 5)})
in
   Source

// The example displays the following output if the current culture
// is en-US:
//      The value is: ' .324'

Voltar à mesa

O especificador personalizado "."

O especificador de formato personalizado "." insere um separador decimal localizado na cadeia de caracteres de resultado. O primeiro período na cadeia de caracteres de formato determina a localização do separador decimal no valor formatado; quaisquer períodos adicionais são ignorados. Se o especificador de formato terminar com um "." somente os dígitos significativos serão formatados na cadeia de caracteres de resultado.

O caractere que é usado como separador decimal na cadeia de caracteres de resultado nem sempre é um ponto; é determinado pela cultura que controla a formatação.

O exemplo a seguir usa o especificador de formato "." para definir o local do ponto decimal em várias cadeias de caracteres de resultado.

let
    Source =
    {
        Number.ToText(1.2, "0.00", ""),
        // Displays 1.20

        Number.ToText(1.2, "00.00", ""),
        // Displays 01.20

        Number.ToText(1.2, "00.00", "da-DK"),
        // Displays 01,20

        Number.ToText(.086, "#0.##%", ""),
        // Displays 8.6%

        Number.ToText(Double.From(86000), "0.###E+0", "")
        // Displays 8.6E+4
    }
in
    Source

Voltar à mesa

O especificador personalizado ","

O caractere "," serve como um separador de grupo e um especificador de escala de número.

Separador de grupo: Se uma ou mais vírgulas forem especificadas entre dois espaços reservados para dígitos (0 ou #) que formatam os dígitos integrais de um número, um caractere separador de grupo será inserido entre cada grupo de números na parte integral da saída.

A cultura determina o caractere usado como separador de grupo numérico e o tamanho de cada grupo numérico. Por exemplo, se a cadeia de caracteres "#,#" e a cultura invariante forem usadas para formatar o número 1000, a saída será "1.000".
Especificador de escala numérica: Se uma ou mais vírgulas forem especificadas imediatamente à esquerda da vírgula decimal explícita ou implícita, o número a ser formatado será dividido por 1000 para cada vírgula. Por exemplo, se a cadeia de caracteres "0,," for usada para formatar o número 100 milhões, a saída será "100".

Você pode usar o separador de grupo e especificadores de escala numérica na mesma cadeia de caracteres de formato. Por exemplo, se a cadeia de caracteres "#,0,," e a cultura invariante forem usadas para formatar o número um bilhão, a saída será "1.000".

O exemplo a seguir ilustra o uso da vírgula como separador de grupo.

let
    Source =
    {
        Number.ToText(1234567890, "#,#", ""),
        // Displays 1,234,567,890

        Number.ToText(1234567890, "#,##0,,", "")
        // Displays, 1,235
    }
in
    Source

O exemplo a seguir ilustra o uso da vírgula como um especificador para dimensionamento numérico.

let
    Source =
    {
        Number.ToText(1234567890, "#,,", ""),
        // Displays 1235

        Number.ToText(1234567890, "#,,,", ""),
        // Displays 1

        Number.ToText(1234567890, "#,##0,,", "")
        // Displays 1,235
    }
in
    Source

Voltar à mesa

O especificador personalizado "%"

Um sinal de porcentagem (%) em uma cadeia de caracteres de formato faz com que um número seja multiplicado por 100 antes de ser formatado. O símbolo de porcentagem localizada é inserido no número no local onde a % aparece na cadeia de caracteres de formato. O caractere percentual usado é definido pela cultura.

O exemplo a seguir define uma cadeia de caracteres de formato personalizado que inclui o especificador personalizado "%".

let
    Source = Number.ToText(.086, "#0.##%", "")
    // Displays 8.6%
in
    Source

Voltar à mesa

O especificador personalizado "‰"

Um caractere per mille (‰ ou \u2030) em uma cadeia de caracteres de formato faz com que um número seja multiplicado por 1000 antes de ser formatado. O símbolo per mille apropriado é inserido na string retornada no local onde o símbolo ‰ aparece na string de formato. O caractere per mille usado é definido pela cultura, que fornece informações de formatação específicas da cultura.

O exemplo a seguir define uma cadeia de caracteres de formato personalizado que inclui o especificador personalizado "‰".

let
    Source = Number.ToText(.00354, "#0.##" & Character.FromNumber(0x2030), "")
    // Displays 3.54‰
in
    Source

Voltar à mesa

Os especificadores personalizados "E" e "e"

Se qualquer uma das cadeias de caracteres "E", "E+", "E-", "e", "e+" ou "e-" estiverem presentes na string de formato e forem seguidas imediatamente por pelo menos um zero, o número é formatado usando notação científica com um "E" ou "e" inserido entre o número e o expoente. O número de zeros após o indicador de notação científica determina o número mínimo de dígitos a produzir para o expoente. Os formatos "E+" e "e+" indicam que um sinal de mais ou menos deve sempre preceder o expoente. Os formatos "E", "E-", "e" ou "e-" indicam que um caractere de sinal deve preceder apenas expoentes negativos.

O exemplo a seguir formata vários valores numéricos usando os especificadores para notação científica.

let
    Source =
    {
        Number.ToText(86000, "0.###E+0", ""),
        // Displays 8.6E+4

        Number.ToText(86000, "0.###E+000", ""),
        // Displays 8.6E+004

        Number.ToText(86000, "0.###E-000", "")
        // Displays 8.6E004
    }
in
    Source

Voltar à mesa

Carateres de escape

Os símbolos "#", "0", ".", ",", "%" e "‰" em uma cadeia de caracteres de formato são interpretados como especificadores de formato em vez de caracteres literais. Dependendo de sua posição em uma cadeia de caracteres de formato personalizado, o "E" maiúsculo e minúsculo, bem como os símbolos + e - também podem ser interpretados como especificadores de formato.

Para evitar que um caractere seja interpretado como um especificador de formato, você pode:

Preceda-o com uma barra invertida.
Envolva-o com uma única citação.
Rodeie-o com duas aspas duplas.

Cada um desses personagens atua como personagens de fuga. O caractere de escape significa que o caractere a seguir é um literal de caractere que deve ser incluído na cadeia de caracteres de resultado inalterada.

Para incluir uma barra invertida em uma cadeia de caracteres de resultado, você deve escapar dela com outra barra invertida (\\).

Para incluir uma única citação em uma cadeia de caracteres de resultado, você deve escapar dela com uma barra invertida (\'). Se outra aspa única que não é escapada precede a aspa única com escape, a barra invertida é exibida em vez disso ('\' exibe \).

Para incluir aspas duplas em uma cadeia de caracteres de resultados, você deve escapar de duas delas com uma barra invertida (\"").

O exemplo a seguir usa caracteres de escape para impedir que a operação de formatação interprete os caracteres "#", "0" e "" como caracteres de escape ou especificadores de formato.

let
    Source =
    {
        Number.ToText(123, "\#\#\# ##0 dollars and \0\0 cents \#\#\#"),
        // Displays ### 123 dollars and 00 cents ###

        Number.ToText(123, "'###' ##0 dollars and '00' cents '###'"),
        // Displays ### 123 dollars and 00 cents ###

        Number.ToText(123, """###"" ##0 dollars and ""00"" cents ""###"""),
        // Displays ### 123 dollars and 00 cents ###

        Number.ToText(123, "\\\\\\ ##0 dollars and \0\0 cents \\\\\\"),
        // Displays \\\ 123 dollars and 00 cents \\\

        Number.ToText(123, "'\\\' ##0 dollars and '00' cents '\\\'"),
        // Displays \\\ 123 dollars and 00 cents \\\

        Number.ToText(123, """\\\"" ##0 dollars and ""00"" cents ""\\\""")
        // Displays \\\ 123 dollars and 00 cents \\\
    }
in
    Source

Voltar à mesa

O separador de secção ";"

O ponto-e-vírgula (;) é um especificador de formato condicional que aplica formatação diferente a um número, dependendo se seu valor é positivo, negativo ou zero. Para produzir esse comportamento, uma cadeia de caracteres de formato personalizado pode conter até três seções separadas por ponto-e-vírgula. Essas seções são descritas na tabela a seguir.

Número de secções	Descrição
Uma secção	A cadeia de caracteres de formato aplica-se a todos os valores.
Duas secções	A primeira secção aplica-se a valores positivos e zeros, e a segunda secção aplica-se a valores negativos. Se o número a ser formatado for negativo, mas se tornar zero após arredondamento de acordo com o formato na segunda seção, o zero resultante será formatado de acordo com a primeira seção.
Três secções	A primeira secção aplica-se a valores positivos, a segunda secção aplica-se a valores negativos e a terceira secção aplica-se a zeros. A segunda seção pode ser deixada vazia (por não ter nada entre os ponto-e-vírgula), caso em que a primeira seção se aplica a todos os valores diferentes de zero. Se o número a ser formatado for diferente de zero, mas se tornar zero após arredondamento de acordo com o formato na primeira ou segunda seção, o zero resultante será formatado de acordo com a terceira seção.

Os separadores de seção ignoram qualquer formatação preexistente associada a um número quando o valor final é formatado. Por exemplo, valores negativos são sempre exibidos sem um sinal de menos quando separadores de seção são usados. Se desejar que o valor formatado final tenha um sinal de subtração, inclua explicitamente o sinal de subtração como parte do especificador de formato personalizado.

O exemplo a seguir usa o especificador de formato ";" para formatar números positivos, negativos e zero de forma diferente.

let
    Source =
    {
        Number.ToText(1234, "##;(##)"),
        // Displays 1234

        Number.ToText(-1234, "##;(##)"),
        // Displays (1234)

        Number.ToText(0, "##;(##);**Zero**")
        // Displays **Zero**
    }
in
    Source

Voltar à mesa

Literais de caracteres

Os especificadores de formato que aparecem em uma cadeia de caracteres de formato numérico personalizado são sempre interpretados como caracteres de formatação e nunca como caracteres literais. Isso inclui os seguintes caracteres:

0
#
%
‰
'
\
""
.
,
E ou e, dependendo da sua posição na cadeia de formatação.

Todos os outros caracteres são sempre interpretados como literais de caracteres e, em uma operação de formatação, são incluídos na cadeia de caracteres de resultado inalterada. Em uma operação de análise, eles devem corresponder exatamente aos caracteres na cadeia de caracteres de entrada; A comparação diferencia maiúsculas de minúsculas.

O exemplo a seguir ilustra um uso comum de unidades de caracteres literais (neste caso, milhares):

let
    Source = Number.ToText(123.8, "#,##0.0K")
    // Displays 123.8K
in
    Source

Há duas maneiras de indicar que os caracteres devem ser interpretados como caracteres literais e não como caracteres de formatação, para que possam ser incluídos em uma cadeia de caracteres de resultado ou analisados com êxito em uma cadeia de caracteres de entrada:

Ao escapar de um caractere de formatação. Para obter mais informações, vá para Personagens de fuga.
Colocando toda a cadeia literal entre aspas apóstrofes.

O exemplo a seguir usa ambas as abordagens para incluir caracteres reservados em uma cadeia de caracteres de formato numérico personalizado.

let
    Source =
    {
        Number.ToText(9.3, "##.0\%"),
        // Displays 9.3%

        Number.ToText(9.3, "\'##\'"),
        // Displays '9'

        Number.ToText(9.3, "\\##\\"),
        // Displays \9\

        Number.ToText(9.3, "##.0'%'"),
        // Displays 9.3%

        Number.ToText(9.3, "'\'##'\'"),
        // Displays \9\

        Number.ToText(9.3, "##.0""%"""),
        // Displays 9.3%

        Number.ToText(9.3, "\""##\""")
        // Displays "9"
    }
in
    Source

Notas

Infinidades 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 formatada é o valor das respetivas constantes Number.PositiveInfinity, Number.NegativeInfinityou Number.NaN especificadas pela cultura atualmente aplicável.

Arredondamento e cadeias de caracteres de formato de ponto fixo

Para cadeias de caracteres de formato de ponto fixo (ou seja, cadeias de caracteres de formato que não contêm caracteres de formato de notação científica), os números são arredondados para tantas casas decimais quanto há espaços reservados para dígitos à direita da vírgula decimal. Se a cadeia de caracteres de formato não contiver um ponto decimal, o número será arredondado para o número inteiro mais próximo. Se o número tiver mais dígitos do que os espaços reservados para dígitos à esquerda da vírgula decimal, os dígitos extras serão copiados para a cadeia de caracteres de resultado imediatamente antes do primeiro espaço reservado para dígitos.

Voltar à mesa

Exemplo

O exemplo a seguir demonstra duas cadeias de caracteres de formato numérico personalizadas. Em ambos os casos, o espaço reservado para dígitos (#) exibe os dados numéricos e todos os outros caracteres são copiados para a cadeia de caracteres de resultado.

let
    Source =
    {
        Number.ToText(1234567890, "(###) ###-####"),
        // Displays (123) 456-7890

        Number.ToText(42, "My Number = #")
        // Displays My number = 42
    }
in
    Source

Voltar à mesa

Como a cultura afeta a formatação de texto
Conversão de tipo de número
Tipos de dados no Power Query
Standard Numeric Format Strings (Cadeias de Formato Numérico Padrão)

Partilhar via

Cadeias de caracteres de formato numérico personalizado

O especificador personalizado "0"

O especificador personalizado "#"

O especificador personalizado "."

O especificador personalizado ","

O especificador personalizado "%"

O especificador personalizado "‰"

Os especificadores personalizados "E" e "e"

Carateres de escape

O separador de secção ";"

Literais de caracteres

Notas

Infinidades de ponto flutuante e NaN

Arredondamento e cadeias de caracteres de formato de ponto fixo

Exemplo

Comentários

Recursos adicionais

Partilhar via

Cadeias de caracteres de formato numérico personalizado

O especificador personalizado "0"

O especificador personalizado "#"

O especificador personalizado "."

O especificador personalizado ","

O especificador personalizado "%"

O especificador personalizado "‰"

Os especificadores personalizados "E" e "e"

Carateres de escape

O separador de secção ";"

Literais de caracteres

Notas

Infinidades de ponto flutuante e NaN

Arredondamento e cadeias de caracteres de formato de ponto fixo

Exemplo

Conteúdos relacionados

Comentários

Recursos adicionais