Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Cadeias de caracteres de formato numérico padrão são usadas para formatar tipos numéricos comuns. Uma cadeia de caracteres de formato numérico padrão assume a forma [format specifier][precision specifier], onde:
O especificador de formato é um único caractere alfabético que especifica o tipo de formato de número, por exemplo, moeda ou porcentagem. Qualquer cadeia de caracteres de formato numérico que contenha mais de um caractere alfabético, incluindo espaço em branco, é interpretada como uma cadeia de caracteres de formato numérico personalizada. Para obter mais informações, consulte Cadeias de caracteres de formato numérico personalizadas.
O especificador de precisão é um inteiro opcional que afeta o número de dígitos na cadeia de caracteres resultante. No .NET 7 e versões posteriores, o valor máximo de precisão é 999.999.999. No .NET 6, o valor de precisão máxima é Int32.MaxValue. Em versões anteriores do .NET, a precisão pode variar de 0 a 99. O especificador de precisão controla o número de dígitos na representação de cadeia de caracteres de um número. Não arredonda o número em si. Para executar uma operação de arredondamento, use o Math.Ceilingmétodo , Math.Floorou Math.Round .
Quando o especificador de precisão controla o número de dígitos fracionários na cadeia de resultados, a cadeia de resultados reflete um número que é arredondado para um resultado representável mais próximo do resultado infinitamente preciso. Se houver dois resultados igualmente quase representáveis:
- No .NET Framework e no .NET Core até o .NET Core 2.0, o tempo de execução seleciona o resultado com o maior dígito menos significativo (ou seja, usando MidpointRounding.AwayFromZero).
- No .NET Core 2.1 e posterior, o tempo de execução seleciona o resultado com um dígito ainda menos significativo (ou seja, usando MidpointRounding.ToEven).
Observação
O especificador de precisão determina o número de dígitos na cadeia de resultados. Para preencher uma cadeia de caracteres de resultado com espaços à esquerda ou à direita, use o recurso de formatação composta e defina um componente de largura no item de formato.
As cadeias de caracteres de formato numérico padrão são suportadas por:
Algumas sobrecargas do
ToStringmétodo de todos os tipos numéricos. Por exemplo, você pode fornecer uma cadeia de caracteres de formato numérico para os Int32.ToString(String) métodos e Int32.ToString(String, IFormatProvider) .O
TryFormatmétodo de todos os tipos numéricos, por exemplo, Int32.TryFormat(Span<Char>, Int32, ReadOnlySpan<Char>, IFormatProvider) e Single.TryFormat(Span<Char>, Int32, ReadOnlySpan<Char>, IFormatProvider).O recurso de formatação composta do .NET, que é usado por alguns
WriteeWriteLinemétodos das Console classes e StreamWriter , o String.Format método e o StringBuilder.AppendFormat método. O recurso de formato composto permite incluir a representação de cadeia de caracteres de vários itens de dados em uma única cadeia de caracteres, especificar a largura do campo e alinhar números em um campo. Para obter mais informações, consulte Formatação composta.Cadeias de caracteres interpoladas em C# e Visual Basic, que fornecem uma sintaxe simplificada quando comparada a cadeias de caracteres de formato composto.
Sugestão
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.
Especificadores de formato padrão
A tabela a seguir descreve os especificadores de formato numérico padrão e exibe a saída de amostra produzida por cada especificador de formato. Consulte a seção Notas para obter informações adicionais sobre como usar cadeias de caracteres de formato numérico padrão e a seção Exemplo de código para obter uma ilustração abrangente de seu uso.
O resultado de uma cadeia de caracteres formatada para uma cultura específica pode diferir dos exemplos a seguir. As configurações do sistema operacional, as configurações do usuário, as variáveis de ambiente e a versão do .NET que você está usando podem afetar o formato. Por exemplo, começando com o .NET 5, o .NET tenta unificar formatos culturais entre plataformas. Para obter mais informações, consulte Globalização e UTI do .NET.
| Especificador de formato | Nome | Descrição | Exemplos |
|---|---|---|---|
| "B" ou "b" | Binário | Resultado: Uma cadeia binária. Suportado por: Somente tipos integrais (.NET 8+). Especificador de precisão: Número de dígitos na cadeia de resultados. Para obter mais informações: O especificador de formato binário ("B"). |
42 ("B") -> 101010 255.º ("B16") -> 0000000011111111 |
| "C" ou "c" | Moeda | Resultado: um valor de moeda. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos decimais. Especificador de precisão padrão: definido por NumberFormatInfo.CurrencyDecimalDigits. Para obter mais informações: O especificador de formato de moeda ("C"). |
123.456 ("C", en-US) -> \$123,46 123.456 ("C", fr-FR) -> 123,46 € 123.456 ("C", ja-JP) -> ¥123 -123.456 ("C3", en-US) -> (\$123.456) -123.456 ("C3", fr-FR) -> -123.456 € -123.456 ("C3", ja-JP) -> -¥123.456 |
| "D" ou "d" | Decimal | Resultado: dígitos inteiros com sinal negativo opcional. Suportado por: Apenas tipos integrais. Especificador de precisão: Número mínimo de dígitos. Especificador de precisão padrão: número mínimo de dígitos necessários. Para obter mais informações: O especificador de formato decimal("D"). |
1234 ("D") -> 1234 -1234 ("D6") -> -001234 |
| "E" ou "e" | Exponencial (científico) | Resultado: Notação exponencial. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos decimais. Especificador de precisão padrão: 6. Mais informações: O especificador de formato exponencial ("E"). |
1052.0329112756 ("E", en-US) -> 1.052033E+003 1052.0329112756 ("e", fr-FR) -> 1,052033e+003 -1052.0329112756 ("e2", en-US) -> -1.05e+003 -1052.0329112756 ("E2", fr-FR) -> -1,05E+003 |
| "F" ou "f" | Ponto fixo | Resultado: Dígitos integrais e decimais com sinal negativo opcional. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos decimais. Especificador de precisão padrão: definido por NumberFormatInfo.NumberDecimalDigits. Para obter mais informações: O especificador de formato Fixed-Point ("F"). |
1234.567 ("F", en-US) -> 1234.57 1234.567 ("F", de-DE) -> 1234,57 1234 ("F1", en-US) -> 1234,0 1234 ("F1", de-DE) -> 1234,0 -1234.56 ("F4", en-US) -> -1234.5600 -1234.56 ("F4", de-DE) -> -1234,5600 |
| "G" ou "g" | Geral | Resultado: O mais compacto de notação de ponto fixo ou científica. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número de dígitos significativos. Especificador de precisão padrão: depende do tipo numérico. Para obter mais informações: O especificador de formato geral ("G"). |
-123.456 ("G", en-US) -> -123.456 -123.456 ("G", sv-SE) -> -123.456 123.4546 ("G4", en-US) -> 123,5 123.4546 ("G4", sv-SE) -> 123,5 -1.234567890E-25 ("G", en-US) -> -1.23456789E-25 -1.234567890E-25 ("G", sv-SE) -> -1,23456789E-25 |
| "N" ou "n" | Número | Resultado: dígitos integrais e decimais, separadores de grupo e um separador decimal com sinal negativo opcional. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número desejado de casas decimais. Especificador de precisão padrão: definido por NumberFormatInfo.NumberDecimalDigits. Para obter mais informações: O especificador de formato numérico ("N"). |
1234.567 ("N", en-US) -> 1.234,57 1234.567 ("N", ru-RU) -> 1 234,57 1234 ("N1", en-US) -> 1.234,0 1234 ("N1", ru-RU) -> 1 234,0 -1234.56 ("N3", en-US) -> -1.234,560 -1234.56 ("N3", ru-RU) -> -1 234.560 |
| "P" ou "p" | Percentagem | Resultado: Número multiplicado por 100 e exibido com um símbolo de porcentagem. Suportado por: Todos os tipos numéricos. Especificador de precisão: Número desejado de casas decimais. Especificador de precisão padrão: definido por NumberFormatInfo.PercentDecimalDigits. Para obter mais informações: O especificador de formato de porcentagem ("P"). |
1 ("P", en-US) -> 100.00 % 1 ("P", fr-FR) -> 100,00 % -0,39678 ("P1", en-US) -> -39,7 % -0,39678 ("P1", fr-FR) -> -39,7 % |
| "R" ou "r" | Ida e volta | Resultado: uma cadeia de caracteres que pode ir de ida e volta para um número idêntico. Apoiado por: Single, Double, e BigInteger. Nota: Recomendado apenas para o BigInteger tipo. Para Double tipos, use "G17", para Single tipos, use "G9". Especificador de precisão: ignorado. Para obter mais informações: O especificador de formato de ida e volta ("R"). |
123456789.12345678 ("R") -> 123456789.12345678 -1234567890.12345678 ("R") -> -1234567890.1234567 |
| "X" ou "x" | Hexadecimal | Resultado: Uma cadeia de caracteres hexadecimal. Suportado por: Apenas tipos integrais. Especificador de precisão: Número de dígitos na cadeia de resultados. Para obter mais informações: O especificador de formato hexadecimal ("X"). |
255 ("X") -> FF -1 ("x") -> ff 255 ("x4") -> 00ff -1 ("X4") -> 00FF |
| Qualquer outro caractere único | Especificador desconhecido | Resultado: lança um FormatException em tempo de execução. |
Usar cadeias de caracteres de formato numérico padrão
Observação
Os 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#.
Uma cadeia de caracteres de formato numérico padrão pode ser usada para definir a formatação de um valor numérico de uma das seguintes maneiras:
Ele pode ser passado para o
TryFormatmétodo ou uma sobrecarga doToStringmétodo que tem umformatparâmetro. O exemplo a seguir formata um valor numérico como uma cadeia de caracteres de moeda na cultura atual (neste caso, a cultura en-US).decimal value = 123.456m; Console.WriteLine(value.ToString("C2")); // Displays $123.46Dim value As Decimal = 123.456d Console.WriteLine(value.ToString("C2")) ' Displays $123.46Ele pode ser fornecido como o
formatStringargumento em um item de formato usado com métodos como String.Format, Console.WriteLinee StringBuilder.AppendFormat. Para obter mais informações, consulte Formatação composta. O exemplo a seguir usa um item de formato para inserir um valor de moeda em uma cadeia de caracteres.decimal value = 123.456m; Console.WriteLine($"Your account balance is {value:C2}."); // Displays "Your account balance is $123.46."Dim value As Decimal = 123.456d Console.WriteLine("Your account balance is {0:C2}.", value) ' Displays "Your account balance is $123.46."Opcionalmente, você pode fornecer um
alignmentargumento para especificar a largura do campo numérico e se seu valor está alinhado à direita ou à esquerda. O exemplo a seguir alinha à esquerda um valor de moeda em um campo de 28 caracteres e alinha à direita um valor de moeda em um campo de 14 caracteres.decimal[] amounts = { 16305.32m, 18794.16m }; Console.WriteLine(" Beginning Balance Ending Balance"); Console.WriteLine(" {0,-28:C2}{1,14:C2}", amounts[0], amounts[1]); // Displays: // Beginning Balance Ending Balance // $16,305.32 $18,794.16Dim amounts() As Decimal = {16305.32d, 18794.16d} Console.WriteLine(" Beginning Balance Ending Balance") Console.WriteLine(" {0,-28:C2}{1,14:C2}", amounts(0), amounts(1)) ' Displays: ' Beginning Balance Ending Balance ' $16,305.32 $18,794.16Ele pode ser fornecido como o
formatStringargumento em um item de expressão interpolado de uma cadeia de caracteres interpolada. Para obter mais informações, consulte o artigo Interpolação de cadeia de caracteres na referência C# ou o artigo Cadeias de caracteres interpoladas na referência do Visual Basic.
As seções a seguir fornecem informações detalhadas sobre cada uma das cadeias de caracteres de formato numérico padrão.
Especificador de formato binário (B)
O especificador de formato binário ("B") converte um número em uma cadeia de dígitos binários. Este formato é suportado apenas para tipos integrais e apenas no .NET 8+.
O especificador de precisão indica o número mínimo de dígitos desejados na cadeia resultante. Se necessário, o número é acolchoado com zeros à esquerda para produzir o número de dígitos dado pelo especificador de precisão.
A cadeia de caracteres de resultado não é afetada pelas informações de formatação do objeto atual NumberFormatInfo .
Especificador de formato de moeda (C)
O especificador de formato "C" (ou moeda) converte um número em uma cadeia de caracteres que representa um valor de moeda. O especificador de precisão indica o número desejado de casas decimais na cadeia de resultados. Se o especificador de precisão for omitido, a precisão padrão será definida pela NumberFormatInfo.CurrencyDecimalDigits propriedade.
Se o valor a ser formatado tiver mais do que o número especificado ou padrão de casas decimais, o valor fracionário será arredondado na cadeia de caracteres de resultado. Se o valor à direita do número de casas decimais especificadas for 5 ou superior, o último dígito na cadeia de resultados será arredondado para longe de zero.
A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . A tabela a seguir lista as NumberFormatInfo propriedades que controlam a formatação da cadeia de caracteres retornada.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| CurrencyPositivePattern | Define o posicionamento do símbolo de moeda para valores positivos. |
| CurrencyNegativePattern | Define o posicionamento do símbolo de moeda para valores negativos e especifica se o sinal negativo é representado por parênteses ou pela NegativeSign propriedade. |
| NegativeSign | Define o sinal negativo usado se CurrencyNegativePattern indicar que parênteses não são usados. |
| CurrencySymbol | Define o símbolo da moeda. |
| CurrencyDecimalDigits | Define o número padrão de dígitos decimais em um valor de moeda. Esse valor pode ser substituído usando o especificador de precisão. |
| CurrencyDecimalSeparator | Define a cadeia de caracteres que separa dígitos integrais e decimais. |
| CurrencyGroupSeparator | Define a cadeia de caracteres que separa grupos de números integrais. |
| CurrencyGroupSizes | Define o número de dígitos inteiros que aparecem em um grupo. |
O exemplo a seguir formata um Double valor com o especificador de formato de moeda:
double value = 12345.6789;
Console.WriteLine(value.ToString("C", CultureInfo.CurrentCulture));
Console.WriteLine(value.ToString("C3", CultureInfo.CurrentCulture));
Console.WriteLine(value.ToString("C3",
CultureInfo.CreateSpecificCulture("da-DK")));
// The example displays the following output on a system whose
// current culture is English (United States):
// $12,345.68
// $12,345.679
// 12.345,679 kr
Dim value As Double = 12345.6789
Console.WriteLine(value.ToString("C", CultureInfo.CurrentCulture))
Console.WriteLine(value.ToString("C3", CultureInfo.CurrentCulture))
Console.WriteLine(value.ToString("C3", _
CultureInfo.CreateSpecificCulture("da-DK")))
' The example displays the following output on a system whose
' current culture is English (United States):
' $12,345.68
' $12,345.679
' kr 12.345,679
Especificador de formato decimal (D)
O especificador de formato "D" (ou decimal) converte um número em uma cadeia de dígitos decimais (0-9), prefixada por um sinal de menos se o número for negativo. Este formato é suportado apenas para tipos integrais.
O especificador de precisão indica o número mínimo de dígitos desejados na cadeia resultante. Se necessário, o número é acolchoado com zeros à esquerda para produzir o número de dígitos dado pelo especificador de precisão. Se nenhum especificador de precisão for especificado, o padrão será o valor mínimo necessário para representar o inteiro sem zeros à esquerda.
A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . Como mostra a tabela a seguir, uma única propriedade afeta a formatação da cadeia de caracteres de resultado.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo. |
O exemplo a seguir formata um Int32 valor com o especificador de formato decimal.
int value;
value = 12345;
Console.WriteLine(value.ToString("D"));
// Displays 12345
Console.WriteLine(value.ToString("D8"));
// Displays 00012345
value = -12345;
Console.WriteLine(value.ToString("D"));
// Displays -12345
Console.WriteLine(value.ToString("D8"));
// Displays -00012345
Dim value As Integer
value = 12345
Console.WriteLine(value.ToString("D"))
' Displays 12345
Console.WriteLine(value.ToString("D8"))
' Displays 00012345
value = -12345
Console.WriteLine(value.ToString("D"))
' Displays -12345
Console.WriteLine(value.ToString("D8"))
' Displays -00012345
Especificador de formato exponencial (E)
O especificador de formato exponencial ("E") converte um número em uma cadeia de caracteres da forma "-d.ddd... E+ddd" ou "-d.ddd... e+ddd", onde cada "d" indica um dígito (0-9). A cadeia de caracteres começa com um sinal de menos se o número for negativo. Exatamente um dígito sempre precede a vírgula decimal.
O especificador de precisão indica o número desejado de dígitos após a vírgula decimal. Se o especificador de precisão for omitido, será usado um padrão de seis dígitos após a vírgula decimal.
O caso do especificador de formato indica se o expoente deve prefixar com um "E" ou um "e". O expoente consiste sempre num sinal de mais ou menos e num mínimo de três dígitos. O expoente é acolchoado com zeros para cumprir este mínimo, se necessário.
A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . A tabela a seguir lista as NumberFormatInfo propriedades que controlam a formatação da cadeia de caracteres retornada.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo para o coeficiente e o expoente. |
| NumberDecimalSeparator | Define a cadeia de caracteres que separa o dígito integral dos dígitos decimais no coeficiente. |
| PositiveSign | Define a cadeia de caracteres que indica que um expoente é positivo. |
O exemplo a seguir formata um Double valor com o especificador de formato exponencial:
double value = 12345.6789;
Console.WriteLine(value.ToString("E", CultureInfo.InvariantCulture));
// Displays 1.234568E+004
Console.WriteLine(value.ToString("E10", CultureInfo.InvariantCulture));
// Displays 1.2345678900E+004
Console.WriteLine(value.ToString("e4", CultureInfo.InvariantCulture));
// Displays 1.2346e+004
Console.WriteLine(value.ToString("E",
CultureInfo.CreateSpecificCulture("fr-FR")));
// Displays 1,234568E+004
Dim value As Double = 12345.6789
Console.WriteLine(value.ToString("E", CultureInfo.InvariantCulture))
' Displays 1.234568E+004
Console.WriteLine(value.ToString("E10", CultureInfo.InvariantCulture))
' Displays 1.2345678900E+004
Console.WriteLine(value.ToString("e4", CultureInfo.InvariantCulture))
' Displays 1.2346e+004
Console.WriteLine(value.ToString("E", _
CultureInfo.CreateSpecificCulture("fr-FR")))
' Displays 1,234568E+004
Especificador de formato de ponto fixo (F)
O especificador de formato de ponto fixo ("F") converte um número em uma cadeia de caracteres do formato "-ddd.ddd..." onde cada "d" indica um dígito (0-9). A cadeia de caracteres começa com um sinal de menos se o número for negativo.
O especificador de precisão indica o número desejado de casas decimais. Se o especificador de precisão for omitido, a propriedade current NumberFormatInfo.NumberDecimalDigits fornecerá a precisão numérica.
A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . A tabela a seguir lista as NumberFormatInfo propriedades do objeto que controlam a formatação da cadeia de caracteres de resultado.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo. |
| NumberDecimalSeparator | Define a cadeia de caracteres que separa dígitos integrais de dígitos decimais. |
| NumberDecimalDigits | Define o número padrão de dígitos decimais. Esse valor pode ser substituído usando o especificador de precisão. |
O exemplo a seguir formata um Double e um Int32 valor com o especificador de formato de ponto fixo:
int integerNumber;
integerNumber = 17843;
Console.WriteLine(integerNumber.ToString("F",
CultureInfo.InvariantCulture));
// Displays 17843.00
integerNumber = -29541;
Console.WriteLine(integerNumber.ToString("F3",
CultureInfo.InvariantCulture));
// Displays -29541.000
double doubleNumber;
doubleNumber = 18934.1879;
Console.WriteLine(doubleNumber.ToString("F", CultureInfo.InvariantCulture));
// Displays 18934.19
Console.WriteLine(doubleNumber.ToString("F0", CultureInfo.InvariantCulture));
// Displays 18934
doubleNumber = -1898300.1987;
Console.WriteLine(doubleNumber.ToString("F1", CultureInfo.InvariantCulture));
// Displays -1898300.2
Console.WriteLine(doubleNumber.ToString("F3",
CultureInfo.CreateSpecificCulture("es-ES")));
// Displays -1898300,199
Dim integerNumber As Integer
integerNumber = 17843
Console.WriteLine(integerNumber.ToString("F", CultureInfo.InvariantCulture))
' Displays 17843.00
integerNumber = -29541
Console.WriteLine(integerNumber.ToString("F3", CultureInfo.InvariantCulture))
' Displays -29541.000
Dim doubleNumber As Double
doubleNumber = 18934.1879
Console.WriteLine(doubleNumber.ToString("F", CultureInfo.InvariantCulture))
' Displays 18934.19
Console.WriteLine(doubleNumber.ToString("F0", CultureInfo.InvariantCulture))
' Displays 18934
doubleNumber = -1898300.1987
Console.WriteLine(doubleNumber.ToString("F1", CultureInfo.InvariantCulture))
' Displays -1898300.2
Console.WriteLine(doubleNumber.ToString("F3", _
CultureInfo.CreateSpecificCulture("es-ES")))
' Displays -1898300,199
Especificador de formato geral (G)
O especificador de formato geral ("G") converte um número para o mais compacto de ponto fixo ou notação científica, dependendo do tipo do número e se um especificador de precisão está presente. O especificador de precisão define o número máximo de dígitos significativos que podem aparecer na cadeia de resultados. Se o especificador de precisão for omitido ou zero, o tipo do número determinará a precisão padrão, conforme indicado na tabela a seguir.
| Tipo numérico | Precisão padrão |
|---|---|
| Byte ou SByte | 3 algarismos |
| Int16 ou UInt16 | 5 dígitos |
| Int32 ou UInt32 | 10 dígitos |
| Int64 | 19 algarismos |
| UInt64 | 20 dígitos |
| BigInteger | Ilimitado (igual a "R") |
| Half | Menor número triplo de dígitos para representar o número |
| Single | Menor número triplicável de dígitos para representar o número (no .NET Framework, G7 é o padrão) |
| Double | Menor número de dígitos triplicáveis para representar o número (no .NET Framework, G15 é o padrão) |
| Decimal | Menor número triplo de dígitos para representar o número |
A notação de ponto fixo é usada se o expoente que resultaria da expressão do número em notação científica for maior que -5 e menor que o especificador de precisão; caso contrário, utiliza-se a notação científica. O resultado contém um ponto decimal, se necessário, e zeros à direita após o ponto decimal são omitidos. Se o especificador de precisão estiver presente e o número de algarismos significativos no resultado exceder a precisão especificada, os algarismos à direita em excesso são removidos por arredondamento.
No entanto, se o número for a Decimal e o especificador de precisão for omitido, a notação de ponto fixo será sempre usada e os zeros à direita serão preservados.
Se for utilizada notação científica, o expoente no resultado é precedido de "E" se o especificador de formato for "G", ou "e" se o especificador de formato for "g". O expoente contém um mínimo de dois dígitos. Isso difere do formato de notação científica que é produzido pelo especificador de formato exponencial, que inclui um mínimo de três dígitos no expoente.
Quando usado com um Double valor, o especificador de formato "G17" garante que o valor original Double seja bem-sucedido de ida e volta. Isso ocorre porque Double é um número de ponto flutuante de precisão dupla (binary64) compatível com IEEE 754-2008 que dá até 17 dígitos significativos de precisão. No .NET Framework, recomendamos seu uso em vez do especificador de formato "R", já que em alguns casos "R" não consegue obter com êxito valores de ponto flutuante de precisão dupla de ida e volta.
Quando usado com um Single valor, o especificador de formato "G9" garante que o valor original Single seja bem-sucedido em viagens de ida e volta. Isso ocorre porque Single é um número de ponto flutuante de precisão única (binary32) compatível com IEEE 754-2008 que fornece até nove dígitos significativos de precisão. Por razões de desempenho, recomendamos o seu uso em vez do especificador de formato "R".
A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . A tabela a seguir lista as NumberFormatInfo propriedades que controlam a formatação da cadeia de caracteres de resultado.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo. |
| NumberDecimalSeparator | Define a cadeia de caracteres que separa dígitos integrais de dígitos decimais. |
| PositiveSign | Define a cadeia de caracteres que indica que um expoente é positivo. |
O exemplo a seguir formata valores de vírgula flutuante sortidos com o especificador de formato geral:
double number;
number = 12345.6789;
Console.WriteLine(number.ToString("G", CultureInfo.InvariantCulture));
// Displays 12345.6789
Console.WriteLine(number.ToString("G",
CultureInfo.CreateSpecificCulture("fr-FR")));
// Displays 12345,6789
Console.WriteLine(number.ToString("G7", CultureInfo.InvariantCulture));
// Displays 12345.68
number = .0000023;
Console.WriteLine(number.ToString("G", CultureInfo.InvariantCulture));
// Displays 2.3E-06
Console.WriteLine(number.ToString("G",
CultureInfo.CreateSpecificCulture("fr-FR")));
// Displays 2,3E-06
number = .0023;
Console.WriteLine(number.ToString("G", CultureInfo.InvariantCulture));
// Displays 0.0023
number = 1234;
Console.WriteLine(number.ToString("G2", CultureInfo.InvariantCulture));
// Displays 1.2E+03
number = Math.PI;
Console.WriteLine(number.ToString("G5", CultureInfo.InvariantCulture));
// Displays 3.1416
Dim number As Double
number = 12345.6789
Console.WriteLine(number.ToString("G", CultureInfo.InvariantCulture))
' Displays 12345.6789
Console.WriteLine(number.ToString("G", _
CultureInfo.CreateSpecificCulture("fr-FR")))
' Displays 12345,6789
Console.WriteLine(number.ToString("G7", CultureInfo.InvariantCulture))
' Displays 12345.68
number = .0000023
Console.WriteLine(number.ToString("G", CultureInfo.InvariantCulture))
' Displays 2.3E-06
Console.WriteLine(number.ToString("G", _
CultureInfo.CreateSpecificCulture("fr-FR")))
' Displays 2,3E-06
number = .0023
Console.WriteLine(number.ToString("G", CultureInfo.InvariantCulture))
' Displays 0.0023
number = 1234
Console.WriteLine(number.ToString("G2", CultureInfo.InvariantCulture))
' Displays 1.2E+03
number = Math.Pi
Console.WriteLine(number.ToString("G5", CultureInfo.InvariantCulture))
' Displays 3.1416
Especificador de formato numérico (N)
O especificador de formato numérico ("N") converte um número em uma cadeia de caracteres da forma "-d,ddd,ddd.ddd...", onde "-" indica um símbolo de número negativo, se necessário, "d" indica um dígito (0-9), "," indica um separador de grupo e "." indica um símbolo de ponto decimal. O especificador de precisão indica o número desejado de dígitos após a vírgula decimal. Se o especificador de precisão for omitido, o número de casas decimais será definido pela propriedade atual NumberFormatInfo.NumberDecimalDigits .
A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . A tabela a seguir lista as NumberFormatInfo propriedades que controlam a formatação da cadeia de caracteres de resultado.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo. |
| NumberNegativePattern | Define o formato de valores negativos e especifica se o sinal negativo é representado por parênteses ou pela NegativeSign propriedade. |
| NumberGroupSizes | Define o número de dígitos integrais que aparecem entre separadores de grupo. |
| NumberGroupSeparator | Define a cadeia de caracteres que separa grupos de números integrais. |
| NumberDecimalSeparator | Define a cadeia de caracteres que separa dígitos integrais e decimais. |
| NumberDecimalDigits | Define o número padrão de dígitos decimais. Esse valor pode ser substituído usando um especificador de precisão. |
O exemplo a seguir formata valores de vírgula flutuante sortidos com o especificador de formato de número:
double dblValue = -12445.6789;
Console.WriteLine(dblValue.ToString("N", CultureInfo.InvariantCulture));
// Displays -12,445.68
Console.WriteLine(dblValue.ToString("N1",
CultureInfo.CreateSpecificCulture("sv-SE")));
// Displays -12 445,7
int intValue = 123456789;
Console.WriteLine(intValue.ToString("N1", CultureInfo.InvariantCulture));
// Displays 123,456,789.0
Dim dblValue As Double = -12445.6789
Console.WriteLine(dblValue.ToString("N", CultureInfo.InvariantCulture))
' Displays -12,445.68
Console.WriteLine(dblValue.ToString("N1", _
CultureInfo.CreateSpecificCulture("sv-SE")))
' Displays -12 445,7
Dim intValue As Integer = 123456789
Console.WriteLine(intValue.ToString("N1", CultureInfo.InvariantCulture))
' Displays 123,456,789.0
Especificador de formato de porcentagem (P)
O especificador de formato de porcentagem ("P") multiplica um número por 100 e o converte em uma cadeia de caracteres que representa uma porcentagem. O especificador de precisão indica o número desejado de casas decimais. Se o especificador de precisão for omitido, a precisão numérica padrão fornecida pela propriedade atual PercentDecimalDigits será usada.
A tabela a seguir lista as NumberFormatInfo propriedades que controlam a formatação da cadeia de caracteres retornada.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| PercentPositivePattern | Define o posicionamento do símbolo de porcentagem para valores positivos. |
| PercentNegativePattern | Define o posicionamento do símbolo de porcentagem e o símbolo negativo para valores negativos. |
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo. |
| PercentSymbol | Define o símbolo de porcentagem. |
| PercentDecimalDigits | Define o número padrão de dígitos decimais em um valor percentual. Esse valor pode ser substituído usando o especificador de precisão. |
| PercentDecimalSeparator | Define a cadeia de caracteres que separa dígitos integrais e decimais. |
| PercentGroupSeparator | Define a cadeia de caracteres que separa grupos de números integrais. |
| PercentGroupSizes | Define o número de dígitos inteiros que aparecem em um grupo. |
O exemplo a seguir formata valores de ponto flutuante com o especificador de formato de porcentagem:
double number = .2468013;
Console.WriteLine(number.ToString("P", CultureInfo.InvariantCulture));
// Displays 24.68 %
Console.WriteLine(number.ToString("P",
CultureInfo.CreateSpecificCulture("hr-HR")));
// Displays 24,68%
Console.WriteLine(number.ToString("P1", CultureInfo.InvariantCulture));
// Displays 24.7 %
Dim number As Double = .2468013
Console.WriteLine(number.ToString("P", CultureInfo.InvariantCulture))
' Displays 24.68 %
Console.WriteLine(number.ToString("P", _
CultureInfo.CreateSpecificCulture("hr-HR")))
' Displays 24,68%
Console.WriteLine(number.ToString("P1", CultureInfo.InvariantCulture))
' Displays 24.7 %
Especificador de formato de ida e volta (R)
O especificador de formato de ida e volta ("R") tenta garantir que um valor numérico convertido em uma cadeia de caracteres seja analisado novamente no mesmo valor numérico. Este formato é suportado apenas para os Halftipos , Single, Doublee BigInteger .
No .NET Framework e em versões do .NET Core anteriores à 3.0, o especificador de formato "R" falha ao obter valores de ida e volta Double com êxito em alguns casos. Para ambos os Double valores e Single para ambos, o especificador de formato "R" oferece um desempenho relativamente fraco. Em vez disso, recomendamos que você use o especificador de formato "G17" para Double valores e o especificador de formato "G9" para valores de ida e volta Single com êxito.
Quando um BigInteger valor é formatado usando esse especificador, sua representação de cadeia de caracteres contém todos os dígitos significativos no BigInteger valor.
Embora você possa incluir um especificador de precisão, ele é ignorado. As viagens de ida e volta têm precedência sobre a precisão quando se utiliza este especificador. A cadeia de caracteres de resultado é afetada pelas informações de formatação do objeto atual NumberFormatInfo . A tabela a seguir lista as NumberFormatInfo propriedades que controlam a formatação da cadeia de caracteres de resultado.
| NumberFormatInfo propriedade | Descrição |
|---|---|
| NegativeSign | Define a cadeia de caracteres que indica que um número é negativo. |
| NumberDecimalSeparator | Define a cadeia de caracteres que separa dígitos integrais de dígitos decimais. |
| PositiveSign | Define a cadeia de caracteres que indica que um expoente é positivo. |
O exemplo a seguir formata um BigInteger valor com o especificador de formato de ida e volta.
using System;
using System.Numerics;
public class Example
{
public static void Main()
{
var value = BigInteger.Pow(Int64.MaxValue, 2);
Console.WriteLine(value.ToString("R"));
}
}
// The example displays the following output:
// 85070591730234615847396907784232501249
Imports System.Numerics
Module Example
Public Sub Main()
Dim value = BigInteger.Pow(Int64.MaxValue, 2)
Console.WriteLine(value.ToString("R"))
End Sub
End Module
' The example displays the following output:
' 85070591730234615847396907784232501249
Importante
Em alguns casos, Double os valores formatados com a cadeia de caracteres de formato numérico padrão "R" não são bem-sucedidos de ida e volta se compilados usando as /platform:x64 opções ou /platform:anycpu e executados em sistemas de 64 bits. Consulte o parágrafo a seguir para obter mais informações.
Para contornar o problema de valores formatados com a cadeia de caracteres de formato numérico padrão "R" não triplicar com êxito se compilados usando as /platform:x64 opções ou /platform:anycpu e executados em sistemas de 64 bits, você pode formatar Double valores usando a cadeia de Double caracteres de formato numérico padrão "G17". O exemplo a seguir usa a cadeia de caracteres de formato "R" com um Double valor que não é de ida e volta com êxito e também usa a cadeia de caracteres de formato "G17" para percorrer com êxito o valor original:
Console.WriteLine("Attempting to round-trip a Double with 'R':");
double initialValue = 0.6822871999174;
string valueString = initialValue.ToString("R",
CultureInfo.InvariantCulture);
double roundTripped = double.Parse(valueString,
CultureInfo.InvariantCulture);
Console.WriteLine($"{initialValue:R} = {roundTripped:R}: {initialValue.Equals(roundTripped)}\n");
Console.WriteLine("Attempting to round-trip a Double with 'G17':");
string valueString17 = initialValue.ToString("G17",
CultureInfo.InvariantCulture);
double roundTripped17 = double.Parse(valueString17,
CultureInfo.InvariantCulture);
Console.WriteLine($"{initialValue:R} = {roundTripped17:R}: {initialValue.Equals(roundTripped17)}\n");
// If compiled to an application that targets anycpu or x64 and run on an x64 system,
// the example displays the following output:
// Attempting to round-trip a Double with 'R':
// .NET Framework:
// 0.6822871999174 = 0.68228719991740006: False
// .NET:
// 0.6822871999174 = 0.6822871999174: True
//
// Attempting to round-trip a Double with 'G17':
// 0.6822871999174 = 0.6822871999174: True
Imports System.Globalization
Module Example
Public Sub Main()
Console.WriteLine("Attempting to round-trip a Double with 'R':")
Dim initialValue As Double = 0.6822871999174
Dim valueString As String = initialValue.ToString("R",
CultureInfo.InvariantCulture)
Dim roundTripped As Double = Double.Parse(valueString,
CultureInfo.InvariantCulture)
Console.WriteLine("{0:R} = {1:R}: {2}",
initialValue, roundTripped, initialValue.Equals(roundTripped))
Console.WriteLine()
Console.WriteLine("Attempting to round-trip a Double with 'G17':")
Dim valueString17 As String = initialValue.ToString("G17",
CultureInfo.InvariantCulture)
Dim roundTripped17 As Double = double.Parse(valueString17,
CultureInfo.InvariantCulture)
Console.WriteLine("{0:R} = {1:R}: {2}",
initialValue, roundTripped17, initialValue.Equals(roundTripped17))
End Sub
End Module
' If compiled to an application that targets anycpu or x64 and run on an x64 system,
' the example displays the following output:
' Attempting to round-trip a Double with 'R':
' .NET Framework:
' 0.6822871999174 = 0.68228719991740006: False
' .NET:
' 0.6822871999174 = 0.6822871999174: True
'
' Attempting to round-trip a Double with 'G17':
' 0.6822871999174 = 0.6822871999174: True
Especificador de formato hexadecimal (X)
O especificador de formato hexadecimal ("X") converte um número em uma cadeia de dígitos hexadecimais. O maiúsculo do especificador de formato indica se deve ser usado caracteres maiúsculos ou minúsculos para dígitos hexadecimais maiores que 9. Por exemplo, use "X" para produzir "ABCDEF" e "x" para produzir "abcdef". Este formato é suportado apenas para tipos integrais.
O especificador de precisão indica o número mínimo de dígitos desejados na cadeia resultante. Se necessário, o número é acolchoado com zeros à esquerda para produzir o número de dígitos dado pelo especificador de precisão.
A cadeia de caracteres de resultado não é afetada pelas informações de formatação do objeto atual NumberFormatInfo .
O exemplo a seguir formata Int32 valores com o especificador de formato hexadecimal.
int value;
value = 0x2045e;
Console.WriteLine(value.ToString("x"));
// Displays 2045e
Console.WriteLine(value.ToString("X"));
// Displays 2045E
Console.WriteLine(value.ToString("X8"));
// Displays 0002045E
value = 123456789;
Console.WriteLine(value.ToString("X"));
// Displays 75BCD15
Console.WriteLine(value.ToString("X2"));
// Displays 75BCD15
Dim value As Integer
value = &h2045e
Console.WriteLine(value.ToString("x"))
' Displays 2045e
Console.WriteLine(value.ToString("X"))
' Displays 2045E
Console.WriteLine(value.ToString("X8"))
' Displays 0002045E
value = 123456789
Console.WriteLine(value.ToString("X"))
' Displays 75BCD15
Console.WriteLine(value.ToString("X2"))
' Displays 75BCD15
Observações
Esta seção contém informações adicionais sobre como usar cadeias de caracteres de formato numérico padrão.
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, que fornece valores usados para controlar a formatação. Computadores que usam configurações diferentes geram cadeias de resultados diferentes.
Além disso, se o CultureInfo(String) construtor for usado para instanciar um novo CultureInfo 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 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.
NumberFormatInfo propriedades
A formatação é influenciada pelas propriedades do objeto atual NumberFormatInfo , que é fornecido implicitamente pela cultura atual ou explicitamente pelo parâmetro do método que invoca a IFormatProvider formatação. Especifique um NumberFormatInfo ou CultureInfo objeto para esse parâmetro.
Observação
Para obter informações sobre como personalizar os padrões ou cadeias de caracteres usados na formatação de valores numéricos, consulte o tópico da NumberFormatInfo classe.
Tipos numéricos integrais e de vírgula flutuante
Algumas descrições de especificadores de formato numérico padrão referem-se a tipos numéricos integrais ou de vírgula flutuante. Os tipos numéricos integrais são Byte, , , Int16, Int32, UInt16Int64, UInt32, UInt64, e BigIntegerSByte. Os tipos numéricos de vírgula flutuante são Decimal, Half, Single, e Double.
Infinidades de vírgula flutuante e NaN
Independentemente da cadeia de caracteres de formato, se o valor de um HalfSingle, ou Double tipo de ponto flutuante for infinito positivo, infinito negativo ou não um número (NaN), a cadeia de caracteres formatada será o valor da respetiva NegativeInfinitySymbolPositiveInfinitySymbol, ou NaNSymbol propriedade especificada pelo objeto atualmente aplicávelNumberFormatInfo.
Exemplo de código
O exemplo a seguir formata uma integral e um valor numérico de vírgula flutuante usando a cultura en-US e todos os especificadores de formato numérico padrão. Este exemplo usa dois tipos numéricos específicos (Double e ), mas produziria resultados semelhantes para qualquer um dos outros tipos de base numérica (Byte, SByte, Int16, Int32, Int64, UInt32UInt16, , UInt64, DecimalBigIntegerHalfe Single).Int32
// Display string representations of numbers for en-us culture
CultureInfo ci = new CultureInfo("en-us");
// Output floating point values
double floating = 10761.937554;
Console.WriteLine($"C: {floating.ToString("C", ci)}"); // Displays "C: $10,761.94"
Console.WriteLine($"E: {floating.ToString("E03", ci)}"); // Displays "E: 1.076E+004"
Console.WriteLine($"F: {floating.ToString("F04", ci)}"); // Displays "F: 10761.9376"
Console.WriteLine($"G: {floating.ToString("G", ci)}"); // Displays "G: 10761.937554"
Console.WriteLine($"N: {floating.ToString("N03", ci)}"); // Displays "N: 10,761.938"
Console.WriteLine($"P: {(floating/10000).ToString("P02", ci)}"); // Displays "P: 107.62 %"
Console.WriteLine($"R: {floating.ToString("R", ci)}"); // Displays "R: 10761.937554"
Console.WriteLine();
// Output integral values
int integral = 8395;
Console.WriteLine($"C: {integral.ToString("C", ci)}"); // Displays "C: $8,395.00"
Console.WriteLine($"D: {integral.ToString("D6", ci)}"); // Displays "D: 008395"
Console.WriteLine($"E: {integral.ToString("E03", ci)}"); // Displays "E: 8.395E+003"
Console.WriteLine($"F: {integral.ToString("F01", ci)}"); // Displays "F: 8395.0"
Console.WriteLine($"G: {integral.ToString("G", ci)}"); // Displays "G: 8395"
Console.WriteLine($"N: {integral.ToString("N01", ci)}"); // Displays "N: 8,395.0"
Console.WriteLine($"P: {(integral/10000.0).ToString("P02", ci)}"); // Displays "P: 83.95 %"
Console.WriteLine($"X: 0x{integral.ToString("X", ci)}"); // Displays "X: 0x20CB"
Console.WriteLine();
Option Strict On
Imports System.Globalization
Imports System.Threading
Module NumericFormats
Public Sub Main()
' Display string representations of numbers for en-us culture
Dim ci As New CultureInfo("en-us")
' Output floating point values
Dim floating As Double = 10761.937554
Console.WriteLine("C: {0}", _
floating.ToString("C", ci)) ' Displays "C: $10,761.94"
Console.WriteLine("E: {0}", _
floating.ToString("E03", ci)) ' Displays "E: 1.076E+004"
Console.WriteLine("F: {0}", _
floating.ToString("F04", ci)) ' Displays "F: 10761.9376"
Console.WriteLine("G: {0}", _
floating.ToString("G", ci)) ' Displays "G: 10761.937554"
Console.WriteLine("N: {0}", _
floating.ToString("N03", ci)) ' Displays "N: 10,761.938"
Console.WriteLine("P: {0}", _
(floating / 10000).ToString("P02", ci)) ' Displays "P: 107.62 %"
Console.WriteLine("R: {0}", _
floating.ToString("R", ci)) ' Displays "R: 10761.937554"
Console.WriteLine()
' Output integral values
Dim integral As Integer = 8395
Console.WriteLine("C: {0}", _
integral.ToString("C", ci)) ' Displays "C: $8,395.00"
Console.WriteLine("D: {0}", _
integral.ToString("D6")) ' Displays "D: 008395"
Console.WriteLine("E: {0}", _
integral.ToString("E03", ci)) ' Displays "E: 8.395E+003"
Console.WriteLine("F: {0}", _
integral.ToString("F01", ci)) ' Displays "F: 8395.0"
Console.WriteLine("G: {0}", _
integral.ToString("G", ci)) ' Displays "G: 8395"
Console.WriteLine("N: {0}", _
integral.ToString("N01", ci)) ' Displays "N: 8,395.0"
Console.WriteLine("P: {0}", _
(integral / 10000).ToString("P02", ci)) ' Displays "P: 83.95 %"
Console.WriteLine("X: 0x{0}", _
integral.ToString("X", ci)) ' Displays "X: 0x20CB"
Console.WriteLine()
End Sub
End Module
Ver também
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
