Compartilhar via

Sequências de Caracteres de Formato Numérico Personalizado

  • Artigo

Uma sequência de caracteres numéricos personalizada, que você cria e consiste de um ou mais especificadores personalizados de formatos numéricos, define como dados numéricos são formatados.Uma sequência de caracteres de formato numérico personalizado é definida equivalentemente como qualquer sequência que é não uma sequência de caracteres formato numérico padrão.

A tabela a seguir descreve os especificadores de formato numérico personalizado.Para obter mais informações, consulte as notas que seguem a tabela.

Especificador de Formato

Nome

Descrição

0

Espaço Reservado para Zero

Se o valor que está sendo formatado tiver um dígito na posição onde o '0' aparece na sequência de caracteres de formato, então esse dígito é copiado para a sequência de resultado; caso contrário, um '0' aparece na sequência de resultado.A posição do '0' que se enconstra mais à esquerda antes do ponto decimal e o '0' mais à direita após o ponto decimal determina o intervalo de dígitos que estão sempre presentes na sequência de resultado.

O especificador "00" faz com que o valor a ser arredondado para o dígito mais próximo anterior ao decimal, onde o arredondamento para cima sempre é usado.Por exemplo, formatando 34.5 com "00" resultaria no valor 35.

O exemplo a seguir exibe vários valores formatados usando sequências de formato personalizado que incluem espaços reservados de zero.

Dim value As Double




value = 123


Console.WriteLine(value.ToString("00000"))


' Displays 00123




value = 1.2


Console.Writeline(value.ToString("0.00", CultureInfo.InvariantCulture))


' Displays 1.20


Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture))


' Displays 01.20


Console.WriteLine(value.ToString("00.00", _


                  CultureInfo.CreateSpecificCulture("da-DK")))


' Displays 01,20




value = .56


Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture))


' Displays 0.6




value = 1234567890


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture))  


' Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,#", _


                  CultureInfo.CreateSpecificCulture("el-GR")))  


' Displays 1.234.567.890      
double value;




value = 123;


Console.WriteLine(value.ToString("00000"));


// Displays 00123




value = 1.2;


Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));


// Displays 1.20


Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));


// Displays 01.20


Console.WriteLine(value.ToString("00.00", 


                  CultureInfo.CreateSpecificCulture("da-DK")));


// Displays 01,20




value = .56;


Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture));


// Displays 0.6




value = 1234567890;


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture)); 


// Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,#", 


                  CultureInfo.CreateSpecificCulture("el-GR"))); 


// Displays 1.234.567.890

#

Espaço Reservado para Dígito

Se o valor que está sendo formatado tem um dígito na posição onde aparece o '#' na sequência de caracteres de formato, então esse dígito é copiado para a sequência de resultado.Caso contrário, nada é armazenado nessa posição na sequência de resultados.

Observe que este especificador nunca exibe o caractere '0' se for não um dígito significativo, mesmo se o '0' for o único dígito na sequência de caracteres.Ele exibirá o caractere '0' se ele é um dígito significativo no número sendo exibido.

O especificador "##" faz com que o valor a ser arredondado para o dígito mais próximo anterior ao decimal, onde o arredondamento para cima sempre é usado.Por exemplo, formatando 34.5 com "##" resultaria no valor 35.

O exemplo a seguir exibe vários valores formatados usando sequências de formato personalizado que incluem espaços reservados para zero.

      Dim value As Double




      value = 1.2


      Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture))


      ' Displays 1.2




      value = 123


      Console.WriteLine(value.ToString("#####"))


      ' Displays 123




      value = 123456


      Console.WriteLine(value.ToString("[##-##-##]"))      


       ' Displays [12-34-56]




      value = 1234567890


      Console.WriteLine(value.ToString("#"))


      ' Displays 1234567890


      Console.WriteLine(value.ToString("(###) ###-####"))


      ' Displays (123) 456-7890
      double value;




      value = 1.2;


      Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture));


      // Displays 1.2




      value = 123;


      Console.WriteLine(value.ToString("#####"));


      // Displays 123




      value = 123456;


      Console.WriteLine(value.ToString("[##-##-##]"));      


       // Displays [12-34-56]




      value = 1234567890;


      Console.WriteLine(value.ToString("#"));


      // Displays 1234567890


      Console.WriteLine(value.ToString("(###) ###-####"));


      // Displays (123) 456-7890

.

Ponto Decimal

O primeiro caractere '.' na sequência de caracteres de formato determina o local do separador decimal no valor formatado; quaisquer caracteres '.' adicionais são ignorados.

O caractere real usado como o separador decimal na sequência de resultado é determinado pela propriedade NumberDecimalSeparator do objeto NumberFormatInfo que controla a formatação.

O exemplo a seguir usa o especificador de formato ponto decimal para definir a localização do ponto decimal em várias sequências de resultados.

      Dim value As Double




      value = 1.2


      Console.Writeline(value.ToString("0.00", CultureInfo.InvariantCulture))


      ' Displays 1.20


      Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture))


      ' Displays 01.20


      Console.WriteLine(value.ToString("00.00", _


                        CultureInfo.CreateSpecificCulture("da-DK")))


      ' Displays 01,20




      value = .086


      Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture)) 


      ' Displays 8.6%




      value = 86000


      Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture))


       ' Displays 8.6E+4
      double value;




      value = 1.2;


      Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));


      // Displays 1.20


      Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));


      // Displays 01.20


      Console.WriteLine(value.ToString("00.00", 


                        CultureInfo.CreateSpecificCulture("da-DK")));


      // Displays 01,20




      value = .086;


      Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture)); 


      // Displays 8.6%




      value = 86000;


      Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));


       // Displays 8.6E+4

,

Separator de milhar e Escala Numérica

O caractere ',' serve tanto como um especificador de separador de milhar e um especificador de escala numérica.

Especificador de separador de milhar: Se um ou mais caracteres ',' é especificado entre dois espaços reservados de dígito (0 ou #) que os dígitos de um número integrais de formatação, um caractere separador de agrupar é inserido entre cada agrupar de números na parte integral da saída.

As propriedades NumberGroupSeparator e NumberGroupSizes do atual objeto NumberFormatInfo determinam o caractere usado como separador de número de grupo e o tamanho de cada grupo de números.Por exemplo, se a sequência de caracteres "#, #" e a cultura invariável são usadas para formatar o número 1000, a saída será "1.000".

Dimensionamento especificador de número: Se um ou mais caracteres ',' for especificado imediatamente à esquerda da vírgula decimal explícita ou implícita, o número a ser formatada é dividido por 1000 sempre que ocorre um especificador de escala numérico.Por exemplo, se a sequência de caracteres "0,," é usada para formatar o número 100 milhões, a saída será "100".

Você pode usar separador de milhares e especificadores de escala numérica na mesma sequência de formato.Por exemplo, se a sequência de caracteres "#, 0,," e a cultura invariável são usadas para formatar o número um bilhão, a saída será "1,000".

O exemplo a seguir ilustra o uso da vírgula como um separador de milhar.

Dim value As Double = 1234567890


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture))


' Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture))


' Displays 1,235        
double value = 1234567890;


Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture));


// Displays 1,234,567,890      


Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));


// Displays 1,235

O exemplo a seguir ilustra o uso da vírgula como um especificador para escala de numérica.

      Dim value As Double = 1234567890


      Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture))    


      ' Displays 1235   


      Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture))


       ' Displays 1  


      Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture))       


       ' Displays 1,235
      double value = 1234567890;


      Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture));   


      // Displays 1235   


      Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture));


       // Displays 1  


      Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));       


       // Displays 1,235

%

Espaço reservado de Porcentaem

A presença de um caractere '%' em uma sequência de caracteres de formato faz com que um número seja multiplicado por 100 antes de ser formatado.O símbolo adequado é inserido no próprio número no local onde o '%' aparece na sequência de caracteres de formato.O caractere de porcentagem usado é dependente na atual classe NumberFormatInfo.

O exemplo a seguir define diversas sequências de formato personalizado que incluem o espaço reservado de percentual.

Dim value As Double = .086


Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture))


' Displays 8.6%      
double value = .086;


Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture));


// Displays 8.6%

‰

Por espaço reservado mille

A presença de um caractere '‰' (\u2030) em uma cadeia de formato faz com que um número a ser multiplicado por 1000 antes que ele está formatado.Por símbolo mille apropriado é inserido na string retornada no local onde o símbolo '‰' aparece na seqüência de caracteres de formato.O por mille caractere usado é definido pelo NumberFormatInfo.PerMilleSymbol propriedade do objeto que fornece informações de formatação específicas da cultura.

O exemplo a seguir define uma seqüência de caracteres de formato personalizado que inclui o por espaço reservado mille.

Dim value As Double = .00354


Dim perMilleFmt As String = "#0.## " & ChrW(&h2030)


Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture))


' Displays 3.54 ‰      
double value = .00354;


string perMilleFmt = "#0.## " + '\u2030';


Console.WriteLine(value.ToString(perMilleFmt, CultureInfo.InvariantCulture));


// Displays 3.54‰

E0

E + 0

E - 0

e0

E + 0

e - 0

Notação científica

Se qualquer uma das sequências de caracteres "E", " E + ", " E - ", "e", " e + " ou " e - " estiverem presentes na sequência de caracteres de formato e forem seguidos imediatamente por pelo menos um caracter ' 0 ', então o número é formatado usando notação científica com um 'E' ou 'e' inserido entre o número e o expoente.O número de caracteres '0' após o indicador de notação científica determina o número mínimo de dígitos à saída para o expoente.Os formatos "E+" e "e+" indicam que um caractere sinal (mais ou menos) sempre deve preceder o expoente.Os formatos "E", " E-", "e" ou "e-" indicam que um caractere sinal só deve preceder expoentes negativos.

O exemplo a seguir formata vários valores numéricos usando os especificadores para notação científica.

Dim value As Double = 86000


Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture))


' Displays 8.6E+4


Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture))


' Displays 8.6E+004


Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture))


' Displays 8.6E004
double value = 86000;


Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));


// Displays 8.6E+4


Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture));


// Displays 8.6E+004


Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture));


// Displays 8.6E004

\

Caractere de Escape

Em C# e C++, o caractere barra invertida faz com que o próximo caractere na sequência seja interpretado como uma sequência de escape.Ele é usado com sequências de formatação tradicionais, como '\n' (nova linha).

Em algumas linguagens, o próprio caractere de escape deve ser precedido por um caractere de escape quando usado como um literal.Caso contrário, o compilador interpreta os caracteres como uma sequência de escape.Use a sequência de caracteres "\\" para exibir ' \ '.

Observe que esse caractere de escape não é suportado no Visual Basic; no entanto, ControlChars fornece a mesma funcionalidade.

'ABC'

"ABC"

Sequência de caracteres literal

Caracteres entre aspas simples ou duplas são copiados para a sequência de resultados, e não afetam a formatação.

;

Separador de Seção

O caractere ';' é usado para separar seções para números positivos, negativos e zero na sequência de caracteres de formato.Se houver duas seções na sequência de formato personalizado, a seção mais à esquerda define a formatação de números positivos e zero, enquanto a seção mais à direita define a formatação dos números negativos.Se houver três seções, a seção mais à esquerda define a formatação dos números positivos, a seção intermediária define a formatação dos números negativos e a seção mais à direita define a formatação de números de zero.

O exemplo a seguir utiliza o especificador de formato para o separador de seção para formatar números positivos, negativos e zero de maneira diferente.

Dim posValue As Double = 1234


Dim negValue As Double = -1234


Dim fmt As String = "##;(##)"


Console.WriteLine(posValue.ToString(fmt))    ' Displays 1234


Console.WriteLine(negValue.ToString(fmt))    ' Displays (1234)
double posValue = 1234;


double negValue = -1234;


string fmt = "##;(##)";


Console.WriteLine(posValue.ToString(fmt));    // Displays 1234


Console.WriteLine(negValue.ToString(fmt));    // Displays (1234)

Outros

Todos outros caracteres

Qualquer outro caractere é copiado para a sequência de resultado, e não afeta a formatação.

Anotações

Pontos Flutuantes Infinitos e NaN (Não Números)

Observe que, independentemente da sequência de caracteres de formato, se o valor de um tipo ponto flutuante éSingle ou Double infinito positivo, negativo infinito ou um não número (NaN), a sequência de caracteres formatada é o valor das respectivas propriedades PositiveInfinitySymbol os respectivos, NegativeInfinitySymbol ou NaNSymbol especificada pelo objeto NumberFormatInfo aplicável no momento.

Configurações do Painel de controle

As configurações no item Opções regionais e de idioma no Painel de Controle influenciam a sequência de resultado produzida por uma operação de formatação.Essas configurações são usadas para inicializar o objeto NumberFormatInfo associado a cultura de segmento atual, que fornece valores usados para controlar a formatação.Computadores usando configurações diferentes vão gerar diferentes sequências de caracteres como resultado.

Arredondamento e Sequências de Caracteres de Formato Ponto-Fixo

Observe que para as sequências de caracteres de formato ponto-fixo (isto é, sequências 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 da ponto decimal.Se a sequência de caracteres de formato não contiver um ponto decimal, o número será arredondado para o inteiro mais próximo.Se o número tiver mais dígitos do que houver espaços reservados de dígitos à esquerda do ponto decimal, os dígitos extras são copiados para a sequência de resultado imediatamente antes do primeiro espaço reservado para dígito.

Separadores de Seção e Formatação Condicional

Uma formatação diferente pode ser aplicada a uma sequência de caracteres com base no valor ser positivo, negativo, ou zero.Para produzir esse comportamento, uma sequência de caracteres de formato personalizado pode conter até três seções separadas por ponto-e-vírgula.Essas operações são descritas na tabela a seguir.

Número de seções

Descrição

Uma seção

A sequência de caracteres de formato se aplica a todos os valores.

Duas seções

A primeira seção aplica-se a valores positivos e zeros, e a segunda seção se aplica a valores negativos.

Se o número a ser formatado for negativo, mas se torna zero após o arredondamento de acordo com o formato na segunda seção, então o zero resultante é formatado de acordo com a primeira seção.

Três seções

A primeira seção aplica-se a valores positivos, a segunda seção se aplica a valores negativos, e a terceira seção se aplica a zeros.

A segunda seção pode ser deixada vazia (por não ter nada entre os ponto-e-vírgulas), caso em que a primeira seção se aplica a todos os valores diferente de zero.

Se o número a ser formatado for diferente de zero, mas se torna zero após o arredondamento de acordo com o formato na primeira ou segunda seção, então o zero resultante é formatado de acordo com a terceira seção.

Separadores de Seção ignoram qualquer formatação preexistente associada com um número quando o valor final é formatado.Por exemplo, valores negativos sempre são exibidos sem um sinal de subtração quando os separadores de seção são usados.Se você quiser o valor final formatado para ter um sinal de subtração, você deve incluir explicitamente o sinal de menos como parte de especificador de formato personalizado.

Os fragmentos de código a seguir ilustram como separadores de seção podem ser usados para produzir sequências de caracteres formatadas.

Dim MyPos As Double = 19.95
Dim MyNeg As Double = -19.95
Dim MyZero As Double = 0

' In the U.S. English culture, MyString has the value: $19.95.
Dim MyString As String = MyPos.ToString("$#,##0.00;($#,##0.00);Zero")

' In the U.S. English culture, MyString has the value: ($19.95).
' The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero")

' In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero")

double MyPos = 19.95, MyNeg = -19.95, MyZero = 0.0;

// In the U.S. English culture, MyString has the value: $19.95.
string MyString = MyPos.ToString("$#,##0.00;($#,##0.00);Zero");

// In the U.S. English culture, MyString has the value: ($19.95).
// The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero");

// In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero");

Dois Exemplos de Formato Personalizado

Os fragmentos de código a seguir demonstram formatação numérica personalizada.Em ambos os casos o espaço reservado de dígito (#) na sequência de caracteres de formato personalizado exibe os dados numéricos, e todos os outros caracteres são copiados para a saída.

Dim myDouble As Double = 1234567890
Dim myString As String = myDouble.ToString( "(###) ### - ####" )
' The value of myString is "(123) 456 – 7890".

Dim MyInt As Integer = 42
MyString = MyInt.ToString( "My Number = #" )
' In the U.S. English culture, MyString has the value: 
' "My Number = 42".

Double myDouble = 1234567890;
String myString = myDouble.ToString( "(###) ### - ####" );
// The value of myString is "(123) 456 – 7890".

int  MyInt = 42;
MyString = MyInt.ToString( "My Number = #" );
// In the U.S. English culture, MyString has the value: 
// "My Number = 42".

Consulte também

Conceitos

Sequências de caracteres de formato numérico

Sequências de Caracteres de Formato Numérico Padrão

Referência

NumberFormatInfo

Outros recursos

Tipos de Formatação

Date

History

Motivo

Julho de 2008

Adicionado por um espaço reservado mille.

Correção de bug do conteúdo.