Cadeias de caracteres de formato numérico personalizado
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.
Cadeias de caracteres de formato numérico personalizado são suportadas por algumas sobrecargas do método de ToString todos os tipos numéricos. Por exemplo, você pode fornecer uma cadeia de caracteres de formato numérico para os ToString(String) métodos e ToString(String, IFormatProvider) do Int32 tipo. Cadeias de caracteres de formato numérico personalizado também são suportadas pelo recurso de formatação composta do .NET, que é usado por alguns Write e métodos das Console classes e , o método e StreamWriterWriteLine o StringBuilder.AppendFormatString.Format método. O recurso de interpolação de cadeias de caracteres também suporta cadeias de caracteres de formato numérico personalizadas.
Gorjeta
Você pode baixar o Utilitário de Formatação, um aplicativo .NET Core Windows Forms 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 personalizados e exibe a saída de exemplo produzida por cada especificador de formato. Consulte a seção Notas 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 | Name | Description | 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. Observe que nenhum dígito aparece 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. 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> |
| "\" | Personagem de fuga | Faz com que o próximo caractere seja interpretado como um literal em vez de um especificador de formato personalizado. Mais informações: O caractere de fuga "\". |
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.
Nota
Alguns dos exemplos de C# neste artigo são executados no Try.NET corredor 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 é executado na janela interativa ou, se a compilação falhar, a janela interativa exibe todas as mensagens de erro do compilador C#.
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.
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
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
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 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 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.
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
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 namespace System;
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'
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'
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 resultados nem sempre é um ponto; ele é determinado pela propriedade do objeto que controla a NumberDecimalSeparatorNumberFormatInfo 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.
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
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
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.
As NumberGroupSeparator propriedades e do objeto atual NumberFormatInfo determinam o caractere usado como separador de grupo de números e NumberGroupSizes o tamanho de cada grupo de números. 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 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 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.
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
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 para dimensionamento numérico.
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
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
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 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%
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%
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 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‰
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 ‰
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.
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
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 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 precedê-lo com uma barra invertida, que é o caractere de escape. 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 (\\).
Nota
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 durante a formatação, você pode usar o caractere literal de cadeia de caracteres literal (o caractere @) antes da cadeia de caracteres em C# ou adicionar outro caractere de barra invertida antes de cada barra invertida em C# e C++. O exemplo 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 \\\
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 \\\
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.
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**
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érico personalizado são sempre interpretados como caracteres de formatação e nunca como caracteres literais. Isso inclui os seguintes caracteres:
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):
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:
Ao escapar de um caractere de formatação. Para obter mais informações, consulte O caractere de escape "\".
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.
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\
Notas
Infinidades de ponto flutuante e NaN
Independentemente da cadeia de caracteres de formato, se o valor de um , , ou tipo de ponto flutuante for infinito positivo, infinito negativo ou não um HalfSinglenúmero (NaN), a cadeia de caracteres formatada será o valor da respetiva NegativeInfinitySymbolPositiveInfinitySymbol, ou DoubleNaNSymbol 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 governar a formatação. Computadores que usam configurações diferentes geram cadeias de resultados diferentes.
Além disso, se você usar o CultureInfo(String) construtor para instanciar um novo objeto que representa a mesma cultura que a cultura do sistema atual, todas as personalizações estabelecidas pelo item Opções Regionais e de Idioma no Painel de Controle serão aplicadas ao novo CultureInfoCultureInfo objeto. Você pode usar o CultureInfo(String, Boolean) construtor para criar um objeto que não reflete as personalizações de um CultureInfo 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 tantas casas decimais quantos os 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.
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.
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
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
