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.
Cadeias de caracteres de formato numérico personalizado são compatíveis com algumas sobrecargas do ToString método de todos os tipos numéricos. Por exemplo, você pode fornecer uma cadeia de caracteres de formato numérico para os métodos e ToString(String) métodos ToString(String, IFormatProvider) do Int32 tipo. Cadeias de caracteres de formato numérico personalizado também são compatíveis com o recurso de formatação composta do .NET, que é usado por alguns Write e WriteLine métodos das Console classes, StreamWriter do String.Format método e do StringBuilder.AppendFormat método.
O recurso de interpolação de cadeia de caracteres também dá suporte a cadeias de caracteres de formato numérico personalizado.
Dica
Você pode baixar o Utilitário de Formatação, um aplicativo do Windows Forms do .NET Core que permite aplicar cadeias de caracteres de formato a valores numéricos ou de data e hora e exibe a cadeia de caracteres de resultado. O código-fonte está disponível para C# e Visual Basic.
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. Consulte 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 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: o especificador 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. Observe que nenhum dígito será exibido 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: o especificador 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: "". 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: o especificador 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: o especificador 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: o especificador 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 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 |
| "\" | Caractere de escape | Faz com que o próximo caractere seja interpretado como um literal e não como um especificador de formato personalizado. Mais informações: o caractere de escape "\". |
987654 ("\###00\#") -> #987654# |
| 'string' "corda" |
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. Mais informações: literais 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: 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) |
| Outros | Todos os outros caracteres | O caractere é copiado, inalterado, para a cadeia de caracteres de resultado. 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.
Observação
Alguns dos exemplos de C# neste artigo são executados no Try.NET executor de código embutido e playground. Selecione o botão Executar para executar um exemplo em uma janela interativa. Depois de executar o código, você pode modificá-lo e executar o código modificado selecionando Executar novamente. O código modificado será executado na janela interativa ou, se a compilação falhar, a janela interativa exibirá todos as mensagens de erro do compilador C#.
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.
double value;
value = 123;
Console.WriteLine(value.ToString("00000"));
Console.WriteLine(String.Format("{0:00000}", value));
// Displays 00123
value = 1.2;
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.00}", value));
// Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:00.00}", value));
// Displays 01.20
CultureInfo daDK = CultureInfo.CreateSpecificCulture("da-DK");
Console.WriteLine(value.ToString("00.00", daDK));
Console.WriteLine(String.Format(daDK, "{0:00.00}", value));
// Displays 01,20
value = .56;
Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.0}", value));
// Displays 0.6
value = 1234567890;
Console.WriteLine(value.ToString("0,0", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0,0}", value));
// Displays 1,234,567,890
CultureInfo elGR = CultureInfo.CreateSpecificCulture("el-GR");
Console.WriteLine(value.ToString("0,0", elGR));
Console.WriteLine(String.Format(elGR, "{0:0,0}", value));
// Displays 1.234.567.890
value = 1234567890.123456;
Console.WriteLine(value.ToString("0,0.0", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0,0.0}", value));
// Displays 1,234,567,890.1
value = 1234.567890;
Console.WriteLine(value.ToString("0,0.00", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0,0.00}", value));
// Displays 1,234.57
Dim value As Double
value = 123
Console.WriteLine(value.ToString("00000"))
Console.WriteLine(String.Format("{0:00000}", value))
' Displays 00123
value = 1.2
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.00}", value))
' Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:00.00}", value))
' Displays 01.20
Dim daDK As CultureInfo = CultureInfo.CreateSpecificCulture("da-DK")
Console.WriteLine(value.ToString("00.00", daDK))
Console.WriteLine(String.Format(daDK, "{0:00.00}", value))
' Displays 01,20
value = .56
Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.0}", value))
' Displays 0.6
value = 1234567890
Console.WriteLine(value.ToString("0,0", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0,0}", value))
' Displays 1,234,567,890
Dim elGR As CultureInfo = CultureInfo.CreateSpecificCulture("el-GR")
Console.WriteLine(value.ToString("0,0", elGR))
Console.WriteLine(String.Format(elGR, "{0:0,0}", value))
' Displays 1.234.567.890
value = 1234567890.123456
Console.WriteLine(value.ToString("0,0.0", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0,0.0}", value))
' Displays 1,234,567,890.1
value = 1234.567890
Console.WriteLine(value.ToString("0,0.00", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0,0.00}", value))
' Displays 1,234.57
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.
double value;
value = 1.2;
Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#.##}", value));
// Displays 1.2
value = 123;
Console.WriteLine(value.ToString("#####"));
Console.WriteLine(String.Format("{0:#####}", value));
// Displays 123
value = 123456;
Console.WriteLine(value.ToString("[##-##-##]"));
Console.WriteLine(String.Format("{0:[##-##-##]}", value));
// Displays [12-34-56]
value = 1234567890;
Console.WriteLine(value.ToString("#"));
Console.WriteLine(String.Format("{0:#}", value));
// Displays 1234567890
Console.WriteLine(value.ToString("(###) ###-####"));
Console.WriteLine(String.Format("{0:(###) ###-####}", value));
// Displays (123) 456-7890
Dim value As Double
value = 1.2
Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#.##}", value))
' Displays 1.2
value = 123
Console.WriteLine(value.ToString("#####"))
Console.WriteLine(String.Format("{0:#####}", value))
' Displays 123
value = 123456
Console.WriteLine(value.ToString("[##-##-##]"))
Console.WriteLine(String.Format("{0:[##-##-##]}", value))
' Displays [12-34-56]
value = 1234567890
Console.WriteLine(value.ToString("#"))
Console.WriteLine(String.Format("{0:#}", value))
' Displays 1234567890
Console.WriteLine(value.ToString("(###) ###-####"))
Console.WriteLine(String.Format("{0:(###) ###-####}", value))
' Displays (123) 456-7890
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 recurso de formatação composta e especifique uma largura de campo, como ilustra o exemplo a seguir.
using System;
public class SpaceOrDigit
{
public static void Main()
{
Double value = .324;
Console.WriteLine("The value is: '{0,5:#.###}'", value);
}
}
// The example displays the following output if the current culture
// is en-US:
// The value is: ' .324'
Module SpaceExample
Public Sub Main()
Dim value As Double = 0.324
Console.WriteLine("The value is: '{0,5:#.###}'", value)
End Sub
End Module
' 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 período; é determinado pela NumberDecimalSeparator propriedade do objeto que controla a NumberFormatInfo 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.
double value;
value = 1.2;
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.00}", value));
// Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:00.00}", value));
// Displays 01.20
Console.WriteLine(value.ToString("00.00",
CultureInfo.CreateSpecificCulture("da-DK")));
Console.WriteLine(String.Format(CultureInfo.CreateSpecificCulture("da-DK"),
"{0:00.00}", value));
// Displays 01,20
value = .086;
Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#0.##%}", value));
// Displays 8.6%
value = 86000;
Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E+0}", value));
// Displays 8.6E+4
Dim value As Double
value = 1.2
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.00}", value))
' Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:00.00}", value))
' Displays 01.20
Console.WriteLine(value.ToString("00.00", _
CultureInfo.CreateSpecificCulture("da-DK")))
Console.WriteLine(String.Format(CultureInfo.CreateSpecificCulture("da-DK"),
"{0:00.00}", value))
' Displays 01,20
value = .086
Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#0.##%}", value))
' Displays 8.6%
value = 86000
Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E+0}", value))
' Displays 8.6E+4
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.
As NumberGroupSeparator propriedades e NumberGroupSizes as propriedades do objeto atual NumberFormatInfo determinam o caractere usado como separador de grupo de números e o tamanho de cada grupo numérico. 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.
double value = 1234567890;
Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,#}", value));
// Displays 1,234,567,890
Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,##0,,}", value));
// Displays 1,235
Dim value As Double = 1234567890
Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,#}", value))
' Displays 1,234,567,890
Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,##0,,}", value))
' Displays 1,235
O exemplo a seguir ilustra o uso da vírgula como um especificador de escala numérica.
double value = 1234567890;
Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,,}", value));
// Displays 1235
Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,,,}", value));
// Displays 1
Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,##0,,}", value));
// Displays 1,235
Dim value As Double = 1234567890
Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture, "{0:#,,}", value))
' Displays 1235
Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,,,}", value))
' Displays 1
Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#,##0,,}", value))
' Displays 1,235
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 PercentSymbol propriedade do objeto atual NumberFormatInfo .
O exemplo a seguir define várias cadeias de caracteres de formato personalizado que incluem o especificador personalizado "%".
double value = .086;
Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#0.##%}", value));
// Displays 8.6%
Dim value As Double = .086
Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:#0.##%}", value))
' Displays 8.6%
Especificador personalizado "‰"
Um caractere por moinho (‰ 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 mille usado é definido pela NumberFormatInfo.PerMilleSymbol propriedade do objeto 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 "‰".
double value = .00354;
string perMilleFmt = "#0.## " + '\u2030';
Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:" + perMilleFmt + "}", value));
// Displays 3.54‰
Dim value As Double = .00354
Dim perMilleFmt As String = "#0.## " & ChrW(&h2030)
Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:" + perMilleFmt + "}", value))
' Displays 3.54 ‰
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.
double value = 86000;
Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E+0}", value));
// Displays 8.6E+4
Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E+000}", value));
// Displays 8.6E+004
Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture));
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E-000}", value));
// Displays 8.6E004
Dim value As Double = 86000
Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E+0}", value))
' Displays 8.6E+4
Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E+000}", value))
' Displays 8.6E+004
Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture))
Console.WriteLine(String.Format(CultureInfo.InvariantCulture,
"{0:0.###E-000}", value))
' Displays 8.6E004
O caractere 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, os símbolos "E" maiúsculas e minúsculas, 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 precedê-lo com uma barra invertida, que é o caractere 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 (\\).
Observação
Alguns compiladores, como os compiladores C++ e C#, também podem interpretar um único caractere de barra invertida como um caractere de escape. Para garantir que uma cadeia de caracteres seja interpretada corretamente quando formatada, você poderá usar o caractere literal de cadeia de caracteres textual (o caractere @) antes da cadeia de caracteres em C# ou adicionar outro caractere de barra invertida antes de cada barra invertida em C# e em C++. O exemplo de C# a seguir ilustra ambas as abordagens.
O exemplo a seguir usa o caractere de escape para impedir que a operação de formatação interprete os caracteres "#", "0" e "\" como caracteres de escape ou especificadores de formato. Os exemplos de C# usam uma barra invertida adicional para garantir que uma barra invertida seja interpretada como um caractere literal.
int value = 123;
Console.WriteLine(value.ToString("\\#\\#\\# ##0 dollars and \\0\\0 cents \\#\\#\\#"));
Console.WriteLine(String.Format("{0:\\#\\#\\# ##0 dollars and \\0\\0 cents \\#\\#\\#}",
value));
// Displays ### 123 dollars and 00 cents ###
Console.WriteLine(value.ToString(@"\#\#\# ##0 dollars and \0\0 cents \#\#\#"));
Console.WriteLine(String.Format(@"{0:\#\#\# ##0 dollars and \0\0 cents \#\#\#}",
value));
// Displays ### 123 dollars and 00 cents ###
Console.WriteLine(value.ToString("\\\\\\\\\\\\ ##0 dollars and \\0\\0 cents \\\\\\\\\\\\"));
Console.WriteLine(String.Format("{0:\\\\\\\\\\\\ ##0 dollars and \\0\\0 cents \\\\\\\\\\\\}",
value));
// Displays \\\ 123 dollars and 00 cents \\\
Console.WriteLine(value.ToString(@"\\\\\\ ##0 dollars and \0\0 cents \\\\\\"));
Console.WriteLine(String.Format(@"{0:\\\\\\ ##0 dollars and \0\0 cents \\\\\\}",
value));
// Displays \\\ 123 dollars and 00 cents \\\
Dim value As Integer = 123
Console.WriteLine(value.ToString("\#\#\# ##0 dollars and \0\0 cents \#\#\#"))
Console.WriteLine(String.Format("{0:\#\#\# ##0 dollars and \0\0 cents \#\#\#}",
value))
' Displays ### 123 dollars and 00 cents ###
Console.WriteLine(value.ToString("\\\\\\ ##0 dollars and \0\0 cents \\\\\\"))
Console.WriteLine(String.Format("{0:\\\\\\ ##0 dollars and \0\0 cents \\\\\\}",
value))
' Displays \\\ 123 dollars and 00 cents \\\
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ês 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.
double posValue = 1234;
double negValue = -1234;
double zeroValue = 0;
string fmt2 = "##;(##)";
string fmt3 = "##;(##);**Zero**";
Console.WriteLine(posValue.ToString(fmt2));
Console.WriteLine(String.Format("{0:" + fmt2 + "}", posValue));
// Displays 1234
Console.WriteLine(negValue.ToString(fmt2));
Console.WriteLine(String.Format("{0:" + fmt2 + "}", negValue));
// Displays (1234)
Console.WriteLine(zeroValue.ToString(fmt3));
Console.WriteLine(String.Format("{0:" + fmt3 + "}", zeroValue));
// Displays **Zero**
Dim posValue As Double = 1234
Dim negValue As Double = -1234
Dim zeroValue As Double = 0
Dim fmt2 As String = "##;(##)"
Dim fmt3 As String = "##;(##);**Zero**"
Console.WriteLine(posValue.ToString(fmt2))
Console.WriteLine(String.Format("{0:" + fmt2 + "}", posValue))
' Displays 1234
Console.WriteLine(negValue.ToString(fmt2))
Console.WriteLine(String.Format("{0:" + fmt2 + "}", negValue))
' Displays (1234)
Console.WriteLine(zeroValue.ToString(fmt3))
Console.WriteLine(String.Format("{0:" + fmt3 + "}", zeroValue))
' Displays **Zero**
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):
double n = 123.8;
Console.WriteLine($"{n:#,##0.0K}");
// The example displays the following output:
// 123.8K
Dim n As Double = 123.8
Console.WriteLine($"{n:#,##0.0K}")
' The example displays the following output:
' 123.8K
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, consulte o caractere 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.
double n = 9.3;
Console.WriteLine($@"{n:##.0\%}");
Console.WriteLine($@"{n:\'##\'}");
Console.WriteLine($@"{n:\\##\\}");
Console.WriteLine();
Console.WriteLine($"{n:##.0'%'}");
Console.WriteLine($@"{n:'\'##'\'}");
// The example displays the following output:
// 9.3%
// '9'
// \9\
//
// 9.3%
// \9\
Dim n As Double = 9.3
Console.WriteLine($"{n:##.0\%}")
Console.WriteLine($"{n:\'##\'}")
Console.WriteLine($"{n:\\##\\}")
Console.WriteLine()
Console.WriteLine($"{n:##.0'%'}")
Console.WriteLine($"{n:'\'##'\'}")
' The example displays the following output:
' 9.3%
' '9'
' \9\
'
' 9.3%
' \9\
Anotações
Infinitos de ponto flutuante e NaN
Independentemente da cadeia de caracteres de formato, se o valor de um HalfSingletipo de ponto flutuante ou Double de ponto flutuante for infinito positivo, infinito negativo ou não um número (NaN), a cadeia de caracteres formatada será o valor do respectivo PositiveInfinitySymbol, NegativeInfinitySymbolou NaNSymbol propriedade especificada pelo objeto atualmente aplicávelNumberFormatInfo.
Configurações do Painel de Controle
As configurações no item Opções Regionais e de Idioma no Painel de Controle influenciam a cadeia de caracteres de resultado produzida por uma operação de formatação. Essas configurações são usadas para inicializar o NumberFormatInfo objeto associado à cultura atual e a cultura atual fornece valores usados para controlar a formatação. Computadores que usam configurações diferentes geram cadeias de caracteres de resultado diferentes.
Além disso, se você usar o CultureInfo(String) construtor para instanciar um novo CultureInfo objeto que representa a mesma cultura que a cultura atual do sistema, todas as personalizações estabelecidas pelo item Opções Regionais e de Idioma no Painel de Controle serão aplicadas ao novo CultureInfo objeto. Você pode usar o CultureInfo(String, Boolean) construtor para criar um CultureInfo objeto que não reflete as personalizações de um sistema.
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 quantas casas decimais houver espaços reservados de dígito à direita do ponto decimal. Se a cadeia de caracteres de formato não contiver um ponto decimal, o número será arredondado para o 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.
double number1 = 1234567890;
string value1 = number1.ToString("(###) ###-####");
Console.WriteLine(value1);
int number2 = 42;
string value2 = number2.ToString("My Number = #");
Console.WriteLine(value2);
// The example displays the following output:
// (123) 456-7890
// My Number = 42
Dim number1 As Double = 1234567890
Dim value1 As String = number1.ToString("(###) ###-####")
Console.WriteLine(value1)
Dim number2 As Integer = 42
Dim value2 As String = number2.ToString("My Number = #")
Console.WriteLine(value2)
' The example displays the following output:
' (123) 456-7890
' My Number = 42
Consulte também
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
