Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Você pode criar uma cadeia de caracteres de formato numérico personalizado, que consiste em um ou mais especificadores numéricos personalizados, para definir a formatação de 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 personalizado 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 o uso de 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 de zero | Substitui o zero pelo dígito correspondente, se houver um presente. Caso contrário, o zero aparecerá na cadeia de caracteres de resultado. Mais informações: Especificador de formato personalizado "0". |
1234.5678 ("00000") -> 01235 0,45678 ("0,00", en-US) -> 0,46 0,45678 ("0,00", fr-FR) -> 0,46 |
| "#" | Espaço reservado de dígito | Substitui o símbolo "#" pelo dígito correspondente, se houver um presente. Caso contrário, nenhum dígito aparecerá na cadeia de caracteres de resultado. Nenhum dígito aparecerá na cadeia de caracteres de resultado se o dígito correspondente na cadeia de caracteres de entrada for um 0 não significativo. Por exemplo, 0003 ("####") -> 3. Mais informações: Especificador de formato personalizado "#". |
1234.5678 ("#####") -> 1235 0,45678 ("#.##", en-US) -> .46 0,45678 ("#.##", fr-FR) -> 46 |
| "." | Ponto decimal | Determina a posição do separador decimal na cadeia de caracteres de resultado. Mais informações: O especificador personalizado ".". |
0,45678 ("0,00", en-US) -> 0,46 0,45678 ("0,00", fr-FR) -> 0,46 |
| "," | Separador de grupo e escala numérica | Funciona tanto como um separador de grupo quanto como um especificador de escala numérica. Como separador de grupo, insere um caractere separador de grupo localizado entre cada grupo. Como especificador de escala numérica, divide um número por 1000 para cada vírgula especificada. Mais informações: Especificador de formato personalizado ",". |
Especificador de separador de grupo: 2147483647 ("##,#", en-US) -> 2.147.483.647 2147483647 ("##,#", es-ES) -> 2.147.483.647 Especificador de escala: 2147483647 ("#,#,,", en-US) -> 2.147 2147483647 ("#,#,,", es-ES) -> 2.147 |
| "%" | Espaço reservado percentual | Multiplica um número por 100 e insere um símbolo percentual localizado na cadeia de caracteres de resultado. Mais informações: Especificador de formato personalizado "%". |
0,3697 ("%#0,00", en-US) -> %36.97 0,3697 ("%#0,00", el-GR) -> %36,97 0,3697 ("##.0 %", en-US) -> 37,0 % 0,3697 ("##.0 %", el-GR) -> 37,0 % |
| "‰" | Espaço reservado por milhar | Multiplica um número por 1000 e insere um símbolo de por milhar localizado na cadeia de caracteres de resultado. Mais informações: Especificador de formato personalizado "‰". |
0,03697 ("#0.00‰", en-US) -> 36.97‰ 0,03697 ("#0,00‰", ru-RU) -> 36,97‰ |
| "E0" "E+0" "E-0" "e0" e+0 e-0 |
Notação exponencial | Se seguida por pelo menos um 0 (zero), formata o resultado usando notação exponencial. A caixa de “E” ou “e” indica a caixa do símbolo do expoente na cadeia de caracteres de resultado. O número de zero depois do caractere “E” ou “e” determina o número mínimo de dígitos do expoente. Um sinal de positivo (+) indica que um caractere de sinal sempre precede o expoente. Um sinal de negativo (-) indica que um caractere de sinal precede apenas expoentes negativos. Mais informações: Especificadores de formato personalizado "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 |
| "\", "''", """" | Caracteres de escape | Faz com que o próximo caractere ou caracteres sejam interpretados como um literal em vez de um especificador de formato personalizado. Mais informações: Caracteres de escape. |
987654 ("\###00\#") -> #987654# 987654 ("'#'##00'#'") -> #987654# 987654 ("""#""##00""#""") -> #987654# |
| 'string' "string" |
Delimitador de cadeia de caracteres literal | Indica que os caracteres delimitados devem ser copiados para a cadeia de caracteres de resultado sem sofrerem alterações. Para saber mais: Literais de cadeia de caracteres. |
68 ("# ' graus'") -> 68 graus 68 ("# ' graus'") -> 68 graus |
| ; | Separador de seção | Define seções com cadeias de caracteres de formato separadas para números positivos, negativos e zero. Mais informações: 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 caracteres | O caractere é copiado, inalterado, para a cadeia de caracteres de resultado. Para saber mais: Literais de cadeia de caracteres. |
68 ("# °") -> 68 ° |
As seções a seguir fornecem informações detalhadas sobre cada um dos especificadores de formato numérico personalizado.
Especificador personalizado "0"
O especificador de formato personalizado “0 " funciona como um símbolo de espaço reservado de 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 o zero mais à direita após o ponto decimal determina o intervalo de dígitos que estão sempre presentes na cadeia de caracteres de resultado.
O especificador "00" faz com que o valor seja arredondado para o dígito mais próximo anterior ao decimal, no qual o arredondamento para cima sempre é usado. Por exemplo, a formatação de 34,5 com "00" resultaria no valor 35.
O exemplo a seguir mostra vários valores formatados com cadeias de caracteres de formato personalizado que incluem espaços reservados de 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
Observação
O valor de texto em branco ("") no último parâmetro de Number.ToText no exemplo anterior refere-se à cultura invariável.
Especificador personalizado "#"
O especificador de formato personalizado “# " funciona como um símbolo de espaço reservado de dígito. Se o valor que está sendo formatado tem um dígito na posição onde o símbolo "#" aparece na cadeia de caracteres de formato, esse dígito é 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 exibirá 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 anterior ao decimal, no qual o arredondamento para cima sempre é usado. Por exemplo, a formatação de 34,5 com "##" resultaria no valor 35.
O exemplo a seguir mostra vários valores formatados com cadeias de caracteres de formato personalizado que incluem espaços reservados de dígito.
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'
Especificador personalizado "."
O especificador de formato personalizado "." insere um separador decimal localizado na cadeia de caracteres resultante. O primeiro caractere de ponto na cadeia de caracteres de formato determina o local do separador decimal no valor formatado; quaisquer caracteres de ponto 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 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 a posição do ponto decimal em várias cadeias de caracteres de resultados.
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
Especificador personalizado ","
O caractere "," funciona tanto como um separador de grupo quanto como um especificador de escala do número.
Separador de grupo: se uma ou mais vírgulas forem especificadas entre dois espaços reservados de dígito (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 de números e o tamanho de cada grupo de números. Por exemplo, se a cadeia de caracteres "#,#" e a cultura invariável 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 do ponto decimal explícito ou implícito, 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 os especificadores de separador de grupo e 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 um 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 de escala numérica.
let
Source =
{
Number.ToText(1234567890, "#,,", ""),
// Displays 1235
Number.ToText(1234567890, "#,,,", ""),
// Displays 1
Number.ToText(1234567890, "#,##0,,", "")
// Displays 1,235
}
in
Source
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 localizado é inserido no próprio número no local em que o % aparece na cadeia de caracteres de formato. O caractere de porcentagem 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
Especificador personalizado "‰"
Um caractere por mil caracteres (‰ 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 de por mil apropriado é inserido na cadeia de caracteres retornada no local em que o símbolo ‰ aparece na cadeia de caracteres de formato. O caractere por mil 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
Especificadores personalizados "E" e "e"
Se qualquer uma das cadeias de caracteres "E", " E + ", " E - ", "e", " e + " ou " e - " estiver presente na cadeia de caracteres de formato e for seguida imediatamente por pelo menos um caractere zero, então o número será 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 que serão enviados para o expoente. Os formatos "E+" e "e+" indicam que um caractere de positivo ou negativo sempre deve preceder o expoente. Os formatos "E", " E-", "e" ou "e-" indicam que um caractere de sinal só deve preceder os 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
Caracteres de escape
Os símbolos “#”, “0 ", “. ”, “,”, “% e "‰" em uma cadeia de caracteres de formato são interpretados como especificadores de formato e não como 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 impedir que um caractere seja interpretado como um especificador de formato, você pode:
- Preceda-o com uma barra invertida.
- Coloque-o entre aspas simples.
- Coloque-o entre aspas duplas.
Cada um desses personagens atua como caracteres de escape. O caractere de escape significa que o próximo caractere é um literal de caractere que deve ser incluído inalterado na cadeia de caracteres de resultado.
Para incluir uma barra invertida em uma cadeia de caracteres de resultado, você deve escapá-la com outra barra invertida (\\).
Para incluir aspas simples em uma cadeia de caracteres de resultado, você deve escapar dela com uma barra invertida (\'). Se outra aspa simples que não é escapada preceder as aspas simples de escape, a barra invertida será exibida ('\' exibe \).
Para incluir aspas duplas em uma cadeia de caracteres de resultado, 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
Separador de seção ";"
O ponto-e-vírgula (;) é um especificador de formato condicional que aplica formatação diferente a um número dependendo se o 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 seções | Descrição |
|---|---|
| Uma seção | A cadeia de caracteres de formato aplica-se a todos os valores. |
| Duas seções | A primeira seção aplica-se a valores positivos e zeros e a segunda seção aplica-se a valores negativos. Se o número a ser formatado for negativo, mas se tornar zero após o arredondamento de acordo com o formato na segunda seção, então o zero resultante será formatado de acordo com a primeira seção. |
| Trê seções | A primeira seção aplica-se a valores positivos, a segunda seção aplica-se a valores negativos e a terceira seção aplica-se a zeros. A segunda seção pode ser deixada em branco (ao não ter nada entre os pontos-e-vírgulas), caso em que a primeira seção se aplica a todos os valores diferentes de zero. Se o número a ser formatado for não zero, mas se tornar zero após o arredondamento de acordo com o formato na primeira ou segunda seção, então o zero resultante será formatado de acordo com a terceira seção. |
Separadores de seção ignoram qualquer formatação preexistente associada a um número quando o valor final é formatado. Por exemplo, valores negativos sempre são exibidos sem um sinal de negativ o quando os separadores de seção são usados. Se desejar que o valor final formatado contenha um sinal de negativo, você deverá incluir explicitamente o sinal de negativo como parte de especificador de formato personalizado.
O exemplo a seguir utiliza o especificador de formato ";" para formatar números positivos, negativos e zero de maneira diferente.
let
Source =
{
Number.ToText(1234, "##;(##)"),
// Displays 1234
Number.ToText(-1234, "##;(##)"),
// Displays (1234)
Number.ToText(0, "##;(##);**Zero**")
// Displays **Zero**
}
in
Source
Literais de caracteres
Os especificadores de formato que aparecem em uma cadeia de caracteres de formato numérica personalizada sempre são interpretados como caracteres de formatação e nunca como caracteres literais. Isso inclui os seguintes caracteres:
Todos os outros caracteres sempre são 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 entrada; a comparação diferencia maiúsculas de minúsculas.
O exemplo a seguir ilustra um uso comum de unidades de caractere literal (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:
Pelo escape de um caractere de formatação. Para obter mais informações, acesse Caracteres de escape.
Colocando toda a cadeia de caracteres literal entre aspas ou apóstrofos.
O exemplo a seguir usa as duas abordagem para incluir caracteres reservados em uma cadeia de caracteres de formato numérica personalizada.
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
Observações
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.
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 espaços reservados de 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 espaços reservados de dígitos à esquerda do ponto decimal, os dígitos extras serão copiados para a cadeia de caracteres de resultado imediatamente antes do primeiro espaço reservado de dígito.
Exemplo
O exemplo a seguir demonstra duas cadeias de caracteres de formato numérico personalizado. Em ambos os casos, o espaço reservado de dígito (#) 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