Cadeias de caracteres de formato numérico personalizadoCustom numeric format strings

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.You can create a custom numeric format string, which consists of one or more custom numeric specifiers, to define how to format numeric data. Uma cadeia de caracteres de formato numérico personalizado é qualquer cadeia de caracteres que é não uma cadeia de caracteres de formato numérico padrão.A custom numeric format string is any format string that is not a standard numeric format string.

As cadeias de caracteres de formato numérico personalizado têm suporte de algumas sobrecargas do método ToString de todos os tipos numéricos.Custom numeric format strings are supported by some overloads of the ToString method of all numeric types. Por exemplo, você pode fornecer uma cadeia de caracteres de formato numérico para os métodos ToString(String) e ToString(String, IFormatProvider) do tipo Int32.For example, you can supply a numeric format string to the ToString(String) and ToString(String, IFormatProvider) methods of the Int32 type. Cadeias de caracteres de formato numérico personalizado também têm suporte no recurso de formatação composta do .NET Framework, o qual é usado por alguns métodos Write e WriteLine das classes Console e StreamWriter, o método String.Format e o método StringBuilder.AppendFormat.Custom numeric format strings are also supported by the .NET composite formatting feature, which is used by some Write and WriteLine methods of the Console and StreamWriter classes, the String.Format method, and the StringBuilder.AppendFormat method. O recurso de Interpolação de cadeia de caracteres também é compatível com cadeias de caracteres de formato numérico personalizado.String interpolation feature also supports custom numeric format strings.

Dica

É possível baixar o Utilitário de Formatação, um aplicativo que permite aplicar cadeias de caracteres de formato a valores numéricos ou de data e hora e exibir a cadeia de caracteres de resultado.You can download the Formatting Utility, an application that enables you to apply format strings to either numeric or date and time values and displays the result string.

A tabela a seguir descreve os especificadores de formato numérico personalizado e exibe amostras de saída produzidas por cada especificador de formato.The following table describes the custom numeric format specifiers and displays sample output produced by each format specifier. 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.See the Notes section for additional information about using custom numeric format strings, and the Example section for a comprehensive illustration of their use.

Especificador de formatoFormat specifier NomeName DESCRIÇÃODescription ExemplosExamples
"0""0" Espaço reservado de zeroZero placeholder Substitui o zero pelo dígito correspondente, se houver um presente. Caso contrário, o zero aparecerá na cadeia de caracteres de resultado.Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result string.

Para saber mais: O especificador personalizado "0".More information: The "0" Custom Specifier.
1234.5678 ("00000") -> 012351234.5678 ("00000") -> 01235

0.45678 (en-US "0,00") -> 0.460.45678 ("0.00", en-US) -> 0.46

0.45678 ("0.00", fr-FR) -> 0,460.45678 ("0.00", fr-FR) -> 0,46
"#""#" Espaço reservado de dígitoDigit placeholder 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.Replaces the "#" symbol with the corresponding digit if one is present; otherwise, no digit appears in the result string.

Observe que nenhum dígito aparece na cadeia de caracteres de resultado se o dígito na cadeia de entrada correspondente for um 0 não significativo.Note that no digit appears in the result string if the corresponding digit in the input string is a non-significant 0. Por exemplo, 0003 ("####") -> 3.For example, 0003 ("####") -> 3.

Para saber mais: O especificador personalizado "#".More information: The "#" Custom Specifier.
1234.5678 ("#####") -> 12351234.5678 ("#####") -> 1235

0.45678 ("#.##", en-US) -> .460.45678 ("#.##", en-US) -> .46

0.45678 ("#.##", fr-FR) -> ,460.45678 ("#.##", fr-FR) -> ,46
".""." Ponto decimalDecimal point Determina a posição do separador decimal na cadeia de caracteres de resultado.Determines the location of the decimal separator in the result string.

Para saber mais: O especificador personalizado ".".More information: The "." Custom Specifier.
0.45678 (en-US "0,00") -> 0.460.45678 ("0.00", en-US) -> 0.46

0.45678 ("0.00", fr-FR) -> 0,460.45678 ("0.00", fr-FR) -> 0,46
","",""," Separador de grupo e escala numéricaGroup separator and number scaling Funciona tanto como um separador de grupo quanto como um especificador de escala numérica.Serves as both a group separator and a number scaling specifier. Como separador de grupo, insere um caractere separador de grupo localizado entre cada grupo.As a group separator, it inserts a localized group separator character between each group. Como especificador de escala numérica, divide um número por 1000 para cada vírgula especificada.As a number scaling specifier, it divides a number by 1000 for each comma specified.

Para saber mais: O especificador personalizado ",".More information: The "," Custom Specifier.
Especificador de separador de grupo:Group separator specifier:

2147483647 ("##,#", en-US) -> 2,147,483,6472147483647 ("##,#", en-US) -> 2,147,483,647

2147483647 ("##,#", es-ES) -> 2.147.483.6472147483647 ("##,#", es-ES) -> 2.147.483.647

Especificador de escala:Scaling specifier:

2147483647 ("#,#,,", en-US) -> 2,1472147483647 ("#,#,,", en-US) -> 2,147

2147483647 ("#,#,,", es-ES) -> 2.1472147483647 ("#,#,,", es-ES) -> 2.147
"%""%" Espaço reservado percentualPercentage placeholder Multiplica um número por 100 e insere um símbolo percentual localizado na cadeia de caracteres de resultado.Multiplies a number by 100 and inserts a localized percentage symbol in the result string.

Para saber mais: O especificador personalizado "%".More information: The "%" Custom Specifier.
0.3697 ("%#0.00", en-US) -> %36.970.3697 ("%#0.00", en-US) -> %36.97

0.3697 ("%#0.00", el-GR) -> %36,970.3697 ("%#0.00", el-GR) -> %36,97

0.3697 ("##.0 %", en-US) -> 37.0 %0.3697 ("##.0 %", en-US) -> 37.0 %

0.3697 ("##.0 %", el-GR) -> 37,0 %0.3697 ("##.0 %", el-GR) -> 37,0 %
"‰""‰" Espaço reservado por milharPer mille placeholder Multiplica um número por 1000 e insere um símbolo de por milhar localizado na cadeia de caracteres de resultado.Multiplies a number by 1000 and inserts a localized per mille symbol in the result string.

Para saber mais: O especificador personalizado "‰".More information: The "‰" Custom Specifier.
0.03697 ("#0.00‰", en-US) -> 36.97‰0.03697 ("#0.00‰", en-US) -> 36.97‰

0.03697 ("#0.00‰", ru-RU) -> 36,97‰0.03697 ("#0.00‰", ru-RU) -> 36,97‰
"E0""E0"

"E+0""E+0"

"E-0""E-0"

"e0""e0"

"e+0""e+0"

"e-0""e-0"
Notação exponencialExponential notation Se seguida por pelo menos um 0 (zero), formata o resultado usando notação exponencial.If followed by at least one 0 (zero), formats the result using exponential notation. A caixa de “E” ou “e” indica a caixa do símbolo do expoente na cadeia de caracteres de resultado.The case of "E" or "e" indicates the case of the exponent symbol in the result string. O número de zero depois do caractere “E” ou “e” determina o número mínimo de dígitos do expoente.The number of zeros following the "E" or "e" character determines the minimum number of digits in the exponent. Um sinal de positivo (+) indica que um caractere de sinal sempre precede o expoente.A plus sign (+) indicates that a sign character always precedes the exponent. Um sinal de negativo (-) indica que um caractere de sinal precede apenas expoentes negativos.A minus sign (-) indicates that a sign character precedes only negative exponents.

Para saber mais: Os especificadores personalizados "E" e "e".More information: The "E" and "e" Custom Specifiers.
987654 ("#0.0e0") -> 98.8e4987654 ("#0.0e0") -> 98.8e4

1503.92311 ("0.0##e+00") -> 1.504e+031503.92311 ("0.0##e+00") -> 1.504e+03

1.8901385E-16 ("0.0e+00") -> 1.9e-161.8901385E-16 ("0.0e+00") -> 1.9e-16
"\""\" Caractere de escapeEscape character Faz com que o próximo caractere seja interpretado como um literal em vez de como um especificador de formato personalizado.Causes the next character to be interpreted as a literal rather than as a custom format specifier.

Para saber mais: O caractere de escape "\".More information: The "\" Escape Character.
987654 ("\###00\#") -> #987654#987654 ("\###00\#") -> #987654#
'string''string'

"string""string"
Delimitador de cadeia de caracteres literalLiteral string delimiter Indica que os caracteres delimitados devem ser copiados para a cadeia de caracteres de resultado sem sofrerem alterações.Indicates that the enclosed characters should be copied to the result string unchanged.

Para saber mais: Literais de caracteres.More information: Character literals.
68 ("# ' graus'") -> 68 graus68 ("# 'degrees'") -> 68 degrees

68 ("# ' graus'") -> 68 graus68 ("#' degrees'") -> 68 degrees
;; Separador de seçãoSection separator Define seções com cadeias de caracteres de formato separadas para números positivos, negativos e zero.Defines sections with separate format strings for positive, negative, and zero numbers.

Para saber mais: O separador de seção ";".More information: The ";" Section Separator.
12.345 ("#0.0#;(#0.0#);-\0-") -> 12.3512.345 ("#0.0#;(#0.0#);-\0-") -> 12.35

0 ("#0.0#;(#0.0#);-\0-") -> -0-0 ("#0.0#;(#0.0#);-\0-") -> -0-

-12.345 ("#0.0#;(#0.0#);-\0-") -> (12.35)-12.345 ("#0.0#;(#0.0#);-\0-") -> (12.35)

12.345 ("#0.0#;(#0.0#)") -> 12.3512.345 ("#0.0#;(#0.0#)") -> 12.35

0 ("#0.0#;(#0.0#)") -> 0.00 ("#0.0#;(#0.0#)") -> 0.0

-12.345 ("#0.0#;(#0.0#)") -> (12.35)-12.345 ("#0.0#;(#0.0#)") -> (12.35)
OutrosOther Todos os outros caracteresAll other characters O caractere é copiado, inalterado, para a cadeia de caracteres de resultado.The character is copied to the result string unchanged.

Para saber mais: Literais de caracteres.More information: Character literals.
68 ("# °") -> 68 °68 ("# °") -> 68 °

As seções a seguir fornecem informações detalhadas sobre cada um dos especificadores de formato numérico personalizado.The following sections provide detailed information about each of the custom numeric format specifiers.

Observação

Alguns dos exemplos de C# neste artigo são executados no executador de código embutido Try.NET e no playground.Some of the C# examples in this article run in the Try.NET inline code runner and playground. Clique no botão Executar para executar um exemplo em uma janela interativa.Select the Run button to run an example in an interactive window. Ao executar o código, é possível modificá-lo e executar o código modificado clicando em Executar novamente.Once you execute the code, you can modify it and run the modified code by selecting Run again. 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#.The modified code either runs in the interactive window or, if compilation fails, the interactive window displays all C# compiler error messages.

Especificador personalizado "0"The "0" custom specifier

O especificador de formato personalizado “0 " funciona como um símbolo de espaço reservado de zero.The "0" custom format specifier serves as a zero-placeholder symbol. 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.If the value that is being formatted has a digit in the position where the zero appears in the format string, that digit is copied to the result string; otherwise, a zero appears in the result string. 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.The position of the leftmost zero before the decimal point and the rightmost zero after the decimal point determines the range of digits that are always present in the result string.

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.The "00" specifier causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. Por exemplo, a formatação de 34,5 com "00" resultaria no valor 35.For example, formatting 34.5 with "00" would result in the value 35.

O exemplo a seguir mostra vários valores formatados com cadeias de caracteres de formato personalizado que incluem espaços reservados de zero.The following example displays several values that are formatted by using custom format strings that include zero placeholders.

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 

Voltar à tabelaBack to table

Especificador personalizado "#"The "#" custom specifier

O especificador de formato personalizado “# " funciona como um símbolo de espaço reservado de dígito.The "#" custom format specifier serves as a digit-placeholder symbol. 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.If the value that is being formatted has a digit in the position where the "#" symbol appears in the format string, that digit is copied to the result string. Caso contrário, nada é armazenado nessa posição na cadeia de caracteres de resultado.Otherwise, nothing is stored in that position in the result string.

Observe que esse especificador nunca exibe um zero que não seja um dígito significativo, mesmo se o zero é o único dígito na cadeia de caracteres.Note that this specifier never displays a zero that is not a significant digit, even if zero is the only digit in the string. Ele exibirá zero somente se ele for um dígito significativo no número que está sendo exibido.It will display zero only if it is a significant digit in the number that is being displayed.

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.The "##" format string causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. Por exemplo, a formatação de 34,5 com "##" resultaria no valor 35.For example, formatting 34.5 with "##" would result in the value 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.The following example displays several values that are formatted by using custom format strings that include digit placeholders.

 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 em que dígitos ausentes ou zeros à esquerda são substituídos por espaços, use o recurso de formatação de composição e especifique uma largura de campo, como mostra o exemplo a seguir.To return a result string in which absent digits or leading zeroes are replaced by spaces, use the composite formatting feature and specify a field width, as the following example illustrates.

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 Example
{
   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 Example
   Public Sub Main()
      Dim value As Double = .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'

Voltar à tabelaBack to table

Especificador personalizado "."The "." custom specifier

O especificador de formato personalizado "." insere um separador decimal localizado na cadeia de caracteres resultante.The "." custom format specifier inserts a localized decimal separator into the result string. 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.The first period in the format string determines the location of the decimal separator in the formatted value; any additional periods are ignored.

O caractere que é usado como separador decimal na cadeia de caracteres de resultado é determinado pela propriedade NumberDecimalSeparator do objeto NumberFormatInfo que controla a formatação.The character that is used as the decimal separator in the result string is not always a period; it is determined by the NumberDecimalSeparator property of the NumberFormatInfo object that controls formatting.

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.The following example uses the "." format specifier to define the location of the decimal point in several result strings.

 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

Voltar à tabelaBack to table

Especificador personalizado ","The "," custom specifier

O caractere "," funciona tanto como um separador de grupo quanto como um especificador de escala do número.The "," character serves as both a group separator and a number scaling specifier.

  • 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.Group separator: If one or more commas are specified between two digit placeholders (0 or #) that format the integral digits of a number, a group separator character is inserted between each number group in the integral part of the output.

    As propriedades NumberGroupSeparator e NumberGroupSizes do objeto NumberFormatInfo atual determinam o caractere usado como separador de número de grupo e o tamanho de cada grupo de números.The NumberGroupSeparator and NumberGroupSizes properties of the current NumberFormatInfo object determine the character used as the number group separator and the size of each number group. 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".For example, if the string "#,#" and the invariant culture are used to format the number 1000, the output is "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 1.000 para cada vírgula.Number scaling specifier: If one or more commas are specified immediately to the left of the explicit or implicit decimal point, the number to be formatted is divided by 1000 for each comma. Por exemplo, se a cadeia de caracteres "0,," for usada para formatar o número 100 milhões, a saída será "100".For example, if the string "0,," is used to format the number 100 million, the output is "100".

Você pode usar os especificadores de separador de grupo e escala numérica na mesma cadeia de caracteres de formato.You can use group separator and number scaling specifiers in the same format string. 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".For example, if the string "#,0,," and the invariant culture are used to format the number one billion, the output is "1,000".

O exemplo a seguir ilustra o uso da vírgula como um separador de grupo.The following example illustrates the use of the comma as a group separator.

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 de escala numérica.The following example illustrates the use of the comma as a specifier for number scaling.

  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

Voltar à tabelaBack to table

Especificador personalizado "%"The "%" custom specifier

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.A percent sign (%) in a format string causes a number to be multiplied by 100 before it is formatted. O símbolo de porcentagem localizado é inserido no próprio número no local em que o % aparece na cadeia de caracteres de formato.The localized percent symbol is inserted in the number at the location where the % appears in the format string. O caractere de porcentagem usado é definido pela propriedade PercentSymbol do objeto NumberFormatInfo atual.The percent character used is defined by the PercentSymbol property of the current NumberFormatInfo object.

O exemplo a seguir define várias cadeias de caracteres de formato personalizado que incluem o especificador personalizado "%".The following example defines several custom format strings that include the "%" custom specifier.

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%      

Voltar à tabelaBack to table

Especificador personalizado "‰"The "‰" custom specifier

Um caractere de por mil sinal (‰ ou \u2030) em uma cadeia de caracteres de formato faz com que um número seja multiplicado por 1000 antes de ser formatado.A per mille character (‰ or \u2030) in a format string causes a number to be multiplied by 1000 before it is formatted. 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.The appropriate per mille symbol is inserted in the returned string at the location where the ‰ symbol appears in the format string. O caractere de por mil usado é definido pela propriedade NumberFormatInfo.PerMilleSymbol do objeto que fornece informações de formatação específicas da cultura.The per mille character used is defined by the NumberFormatInfo.PerMilleSymbol property of the object that provides culture-specific formatting information.

O exemplo a seguir define uma cadeia de caracteres de formato personalizado que inclui o especificador personalizado "‰".The following example defines a custom format string that includes the "‰" custom specifier.

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 ‰      

Voltar à tabelaBack to table

Especificadores personalizados "E" e "e"The "E" and "e" custom specifiers

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.If any of the strings "E", "E+", "E-", "e", "e+", or "e-" are present in the format string and are followed immediately by at least one zero, the number is formatted by using scientific notation with an "E" or "e" inserted between the number and the exponent. 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.The number of zeros following the scientific notation indicator determines the minimum number of digits to output for the exponent. Os formatos "E+" e "e+" indicam que um caractere de positivo ou negativo sempre deve preceder o expoente.The "E+" and "e+" formats indicate that a plus sign or minus sign should always precede the exponent. Os formatos "E", " E-", "e" ou "e-" indicam que um caractere de sinal só deve preceder os expoentes negativos.The "E", "E-", "e", or "e-" formats indicate that a sign character should precede only negative exponents.

O exemplo a seguir formata vários valores numéricos usando os especificadores para notação científica.The following example formats several numeric values using the specifiers for scientific notation.

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

Voltar à tabelaBack to table

Caractere de escape "\"The "\" escape character

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.The "#", "0", ".", ",", "%", and "‰" symbols in a format string are interpreted as format specifiers rather than as literal characters. Dependendo da sua posição em uma cadeia de caracteres de formato personalizado, o "E" em maiúscula e minúscula, bem como os símbolos + e -, também podem ser interpretados como especificadores de formato.Depending on their position in a custom format string, the uppercase and lowercase "E" as well as the + and - symbols may also be interpreted as format specifiers.

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.To prevent a character from being interpreted as a format specifier, you can precede it with a backslash, which is the escape character. 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.The escape character signifies that the following character is a character literal that should be included in the result string unchanged.

Para incluir uma barra invertida em uma cadeia de caracteres de resultado, você deve escapá-la com outra barra invertida (\\).To include a backslash in a result string, you must escape it with another backslash (\\).

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.Some compilers, such as the C++ and C# compilers, may also interpret a single backslash character as an escape character. 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++.To ensure that a string is interpreted correctly when formatting, you can use the verbatim string literal character (the @ character) before the string in C#, or add another backslash character before each backslash in C# and C++. O exemplo de C# a seguir ilustra ambas as abordagens.The following C# example illustrates both approaches.

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.The following example uses the escape character to prevent the formatting operation from interpreting the "#", "0", and "\" characters as either escape characters or format specifiers. Os exemplos em C# usam uma barra invertida adicional para garantir que uma barra invertida seja interpretada como um caractere literal.The C# examples uses an additional backslash to ensure that a backslash is interpreted as a literal character.

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 \\\

Voltar à tabelaBack to table

Separador de seção ";"The ";" section separator

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.The semicolon (;) is a conditional format specifier that applies different formatting to a number depending on whether its value is positive, negative, or 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.To produce this behavior, a custom format string can contain up to three sections separated by semicolons. Essas seções são descritas na tabela a seguir.These sections are described in the following table.

Número de seçõesNumber of sections DESCRIÇÃODescription
Uma seçãoOne section A cadeia de caracteres de formato aplica-se a todos os valores.The format string applies to all values.
Duas seçõesTwo sections A primeira seção aplica-se a valores positivos e zeros e a segunda seção aplica-se a valores negativos.The first section applies to positive values and zeros, and the second section applies to negative values.

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.If the number to be formatted is negative, but becomes zero after rounding according to the format in the second section, the resulting zero is formatted according to the first section.
Trê seçõesThree sections 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.The first section applies to positive values, the second section applies to negative values, and the third section applies to 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.The second section can be left empty (by having nothing between the semicolons), in which case the first section applies to all nonzero values.

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.If the number to be formatted is nonzero, but becomes zero after rounding according to the format in the first or second section, the resulting zero is formatted according to the third section.

Separadores de seção ignoram qualquer formatação preexistente associada a um número quando o valor final é formatado.Section separators ignore any preexisting formatting associated with a number when the final value is formatted. Por exemplo, valores negativos sempre são exibidos sem um sinal de negativ o quando os separadores de seção são usados.For example, negative values are always displayed without a minus sign when section separators are used. 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.If you want the final formatted value to have a minus sign, you should explicitly include the minus sign as part of the custom format specifier.

O exemplo a seguir utiliza o especificador de formato ";" para formatar números positivos, negativos e zero de maneira diferente.The following example uses the ";" format specifier to format positive, negative, and zero numbers differently.

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**

Voltar à tabelaBack to table

Literais de caracteresCharacter literals

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.Format specifiers that appear in a custom numeric format string are always interpreted as formatting characters and never as literal characters. Isso inclui os seguintes caracteres:This includes the following characters:

  • 00
  • #
  • %
  • ''
  • \
  • ..
  • ,,
  • E ou e, de acordo com a posição na cadeia de caracteres de formato.E or e, depending on its position in the format string.

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.All other characters are always interpreted as character literals and, in a formatting operation, are included in the result string unchanged. 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.In a parsing operation, they must match the characters in the input string exactly; the comparison is case-sensitive.

O exemplo a seguir ilustra um uso comum de unidades de caractere literal (neste caso, milhares):The following example illustrates one common use of literal character units (in this case, thousands):

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:There are two ways to indicate that characters are to be interpreted as literal characters and not as formatting characters, so that they can be included in a result string or successfully parsed in an input string:

  • Pelo escape de um caractere de formatação.By escaping a formatting character. Para saber mais, confira O caractere de escape "\".For more information, see The "\" escape character.

  • Colocando toda a cadeia de caracteres literal entre aspas ou apóstrofos.By enclosing the entire literal string in quotation apostrophes.

O exemplo a seguir usa as duas abordagem para incluir caracteres reservados em uma cadeia de caracteres de formato numérica personalizada.The following example uses both approaches to include reserved characters in a custom numeric format string.

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\

ObservaçõesNotes

Infinitos de ponto flutuante e NaNFloating-Point infinities and NaN

Independentemente da cadeia de caracteres de formato, se o valor de um tipo de ponto flutuante Single ou Double é infinito positivo, infinito negativo ou um não é um número (NaN), a cadeia de caracteres formatada é o valor das respectivas propriedades PositiveInfinitySymbol, NegativeInfinitySymbol ou NaNSymbol especificadas pelo objeto NumberFormatInfo aplicável no momento.Regardless of the format string, if the value of a Single or Double floating-point type is positive infinity, negative infinity, or not a number (NaN), the formatted string is the value of the respective PositiveInfinitySymbol, NegativeInfinitySymbol, or NaNSymbol property specified by the currently applicable NumberFormatInfo object.

Configurações do Painel de ControleControl Panel settings

As configurações no item Opções Regionais e de Idioma do Painel de Controle influenciam a cadeia de caracteres de resultado produzida por uma operação de formatação.The settings in the Regional and Language Options item in Control Panel influence the result string produced by a formatting operation. Essas configurações são usadas para inicializar o objeto NumberFormatInfo associado à cultura de thread atual, a qual fornece valores usados para controlar a formatação.Those settings are used to initialize the NumberFormatInfo object associated with the current thread culture, and the current thread culture provides values used to govern formatting. Computadores que usam configurações diferentes geram cadeias de caracteres de resultado diferentes.Computers that use different settings generate different result strings.

Além disso, se o constructo CultureInfo.CultureInfo(String) for usado para criar uma instância de um novo objeto CultureInfo que representa a mesma cultura que a cultura atual do sistema, quaisquer personalizações estabelecidas pelo item Opções Regionais e de Idioma no Painel de Controle serão aplicadas ao novo objeto CultureInfo.In addition, if you use the CultureInfo.CultureInfo(String) constructor to instantiate a new CultureInfo object that represents the same culture as the current system culture, any customizations established by the Regional and Language Options item in Control Panel will be applied to the new CultureInfo object. Você pode usar o construtor CultureInfo.CultureInfo(String, Boolean) para criar um objeto CultureInfo que não reflita as personalizações de um sistema.You can use the CultureInfo.CultureInfo(String, Boolean) constructor to create a CultureInfo object that does not reflect a system's customizations.

Arredondamento e cadeias de caracteres de formato de ponto fixoRounding and fixed-point format strings

Para cadeias de caracteres de formato de ponto fixo (isto é, cadeias de caracteres de formato que não contêm caracteres de formato de notação científica), os números são arredondados para tantas casas decimais quanto houver espaços reservados de dígitos à direita do ponto decimal.For fixed-point format strings (that is, format strings that do not contain scientific notation format characters), numbers are rounded to as many decimal places as there are digit placeholders to the right of the decimal point. Se a cadeia de caracteres de formato não contiver um ponto decimal, o número será arredondado para o inteiro mais próximo.If the format string does not contain a decimal point, the number is rounded to the nearest integer. 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.If the number has more digits than there are digit placeholders to the left of the decimal point, the extra digits are copied to the result string immediately before the first digit placeholder.

Voltar à tabelaBack to table

ExemploExample

O exemplo a seguir demonstra duas cadeias de caracteres de formato numérico personalizado.The following example demonstrates two custom numeric format strings. 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.In both cases, the digit placeholder (#) displays the numeric data, and all other characters are copied to the result string.

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

Voltar à tabelaBack to table

Consulte tambémSee also