Compartilhar via


Tipos de Formatação

A formatação é o processo de converter uma instância de um valor de enumeração, estrutura ou classe em sua representação de seqüência de caracteres, com freqüência para que possa ser exibida aos usuários a seqüência resultante ou desserializada para restaurar o tipo de dados original. Esta conversão pode representar uma série de desafios:

  • A maneira que os valores são armazenados internamente não reflete necessariamente a maneira que os usuários desejam exibi-los. Por exemplo, um número de telefone pode ser armazenado no formulário 8009999999, que não é amigável. Em vez disso, ele deve ser exibido como 800-999-9999.

  • Às vezes, a conversão de um objeto em sua representação de seqüência de caracteres não é intuitiva. Por exemplo, não é claro como a representação de seqüência de caracteres de um objeto de temperatura ou uma pessoa deve aparecer.

  • Valores geralmente exigem a formatação de cultura. Por exemplo, em um aplicativo que usa números para refletir os valores monetários, seqüências de caracteres numéricas devem incluir símbolo a cultura atual, separador de grupo (que, na maioria das culturas, é milhares separador) e o símbolo decimal.

  • Um aplicativo pode ter que exibir o mesmo valor de maneiras diferentes. Por exemplo, um aplicativo pode representar um membro de enumeração, exibindo uma representação de seqüência de caracteres de seu nome ou exibindo seu valor subjacente.

Observação

Formatação converte o valor de um tipo em uma representação de seqüência de caracteres.A análise é o inverso da formatação.Uma operação de análise cria uma instância de um tipo de dados a partir de sua representação de seqüência de caracteres.Para obter informações sobre conversão de strings para outros tipos de dados, consulte Analisando sequências de caracteres.

A.NET Framework oferece suporte à formatação avançada que permite aos desenvolvedores tratar esses requisitos.

Esta visão geral contém as seções a seguir:

  • Formatação do.NET Framework

  • Padrão de formatação usando o método ToString

  • Substituindo o método ToString

  • O método ToString e seqüências de caracteres de formato

  • Provedores de formato e a Interface IFormatProvider

  • A Interface IFormattable

  • Formatação Composta

  • Formatação com ICustomFormatter personalizada

  • Tópicos relacionados

  • Referência

Formatação do.NET Framework

O mecanismo básico para a formatação é a implementação padrão da Object.ToString método, que é discutido o formatação padrão, usando o método ToString seção mais adiante neste tópico. No entanto, o.NET Framework fornece várias maneiras de modificar e estender o suporte à formatação padrão. Eles incluem o seguinte:

  • Substituindo o Object.ToString método para definir uma representação de seqüência de caracteres personalizada de valor. um objeto Para obter mais informações, consulte o substituindo o método ToString seção mais adiante neste tópico.

  • Definindo os especificadores de formato que permitem a representação de seqüência de caracteres do valor de um objeto para assumir várias formas. Por exemplo, o "X" o especificador de formato na instrução a seguir converte um número inteiro para a representação de seqüência de caracteres de um valor hexadecimal.

    Console.WriteLine(integerValue.ToString("X"))   ' Displays EB98.
    
    Console.WriteLine(integerValue.ToString("X"));   // Displays EB98.
    

    Para obter mais informações sobre especificadores de formato, consulte o método ToString e seqüências de caracteres de formato seção.

  • Usando provedores de formato para aproveitar as convenções de formatação de uma cultura específica. Por exemplo, a instrução a seguir exibe um valor monetário usando as convenções de formatação da cultura en-US.

    Console.WriteLine(cost.ToString("C", New System.Globalization.CultureInfo("en-US")))
    ' The example displays the following output:
    '       $1,632.54
    
    Console.WriteLine(cost.ToString("C", 
                      new System.Globalization.CultureInfo("en-US")));   
    // The example displays the following output:
    //       $1,632.54
    

    Para obter mais informações sobre a formatação de provedores de formato, consulte o a provedores de formato e a IFormatProvider Interface seção.

  • Implementando o IFormattable interface para oferecer suporte a ambos os conversão de seqüência de caracteres com o Convert classe e a formatação de composição. Para obter mais informações, consulte o iformattable Interface seção.

  • Usando a formatação de composição para incorporar a representação de seqüência de caracteres de um valor em uma seqüência maior. Para obter mais informações, consulte o Formatação composto seção.

  • Implementação de ICustomFormatter e IFormatProvider para fornecer uma completa personalizado formatação solução. Para obter mais informações, consulte o Formatação personalizada com ICustomFormatter seção.

As seções a seguir examinam esses métodos para converter um objeto em sua representação de seqüência de caracteres.

Voltar ao topo

Padrão de formatação usando o método ToString

Cada tipo que é derivado de System.Object herda automaticamente um sem parâmetros ToString método, que retorna o nome do tipo por padrão. O exemplo a seguir ilustra o padrão ToString método. Ele define uma classe chamada Automobile que tem nenhuma implementação. Quando a classe é instanciada e sua ToString método é chamado, ele exibe o nome de tipo.

Public Class Automobile
   ' No implementation. All members are inherited from Object.
End Class

Module Example
   Public Sub Main()
      Dim firstAuto As New Automobile()
      Console.WriteLine(firstAuto)
   End Sub
End Module
' The example displays the following output:
'       Automobile
using System;

public class Automobile
{
   // No implementation. All members are inherited from Object.
}

public class Example
{
   public static void Main()
   {
      Automobile firstAuto = new Automobile();
      Console.WriteLine(firstAuto);
   }
}
// The example displays the following output:
//       Automobile

Porque todos os tipos diferentes de interfaces é derivada de Object, essa funcionalidade é fornecida automaticamente para as classes personalizadas ou estruturas. No entanto, a funcionalidade oferecida pelo padrão ToString método, é limitado: Embora ele identifica o tipo, não fornece nenhuma informação sobre uma instância do tipo. Para fornecer uma representação de seqüência de caracteres de um objeto que fornece informações sobre o objeto, você deve substituir o ToString método.

Observação

Estruturas de herdam de ValueType, que por sua vez é derivada de Object.Embora ValueType substitui Object.ToString, sua implementação é idêntica.

Voltar ao topo

Substituindo o método ToString

Exibindo o nome de um tipo costuma ser de uso limitado e não permite que os consumidores de seus tipos para diferenciar uma instância de outro. No entanto, você pode substituir o ToString método para fornecer uma representação mais útil de valor. um objeto O exemplo a seguir define uma Temperature objeto e substitui seus ToString método para exibir a temperatura em graus Celsius.

Public Class Temperature
   Private temp As Decimal

   Public Sub New(temperature As Decimal)
      Me.temp = temperature
   End Sub

   Public Overrides Function ToString() As String
      Return Me.temp.ToString("N1") + "°C"   
   End Function
End Class

Module Example
   Public Sub Main()
      Dim currentTemperature As New Temperature(23.6d)
      Console.WriteLine("The current temperature is {0}.", currentTemperature)
   End Sub
End Module
' The example displays the following output:
'       The current temperature is 23.6°C.
using System;

public class Temperature
{
   private decimal temp;

   public Temperature(decimal temperature)
   {
      this.temp = temperature;   
   }

   public override string ToString()
   {
      return this.temp.ToString("N1") + "°C";
   }
}

public class Example
{
   public static void Main()
   {
      Temperature currentTemperature = new Temperature(23.6m);
      Console.WriteLine("The current temperature is {0}.", currentTemperature);
   }
}
// The example displays the following output:
//       The current temperature is 23.6°C.

No.NET Framework, o ToString o método de cada tipo de valor primitivo foi substituído para exibir o valor do objeto em vez do nome. A tabela a seguir mostra a substituição para cada tipo primitivo. Observe que a maioria dos métodos substituídos chama outra sobrecarga de ToString método e passá-lo "G" o especificador de formato, que define o formato geral para o seu tipo, e um IFormatProvider objeto que representa a cultura atual.

Tipo

Substituição de ToString

Boolean

Retorna um Boolean.TrueString ou Boolean.FalseString.

Byte

Chamadas Byte.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Byte valor para a cultura atual.

Char

Retorna o caractere como uma seqüência de caracteres.

DateTime

Chamadas DateTime.ToString("G", DatetimeFormatInfo.CurrentInfo) para formatar o valor de data e hora para a cultura atual.

Decimal

Chamadas Decimal.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Decimal valor para a cultura atual.

Double

Chamadas Double.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Double valor para a cultura atual.

Int16

Chamadas Int16.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Int16 valor para a cultura atual.

Int32

Chamadas Int32.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Int32 valor para a cultura atual.

Int64

Chamadas Int64.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Int64 valor para a cultura atual.

SByte

Chamadas SByte.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a SByte valor para a cultura atual.

Single

Chamadas Single.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a Single valor para a cultura atual.

UInt16

Chamadas UInt16.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a UInt16 valor para a cultura atual.

UInt32

Chamadas UInt32.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a UInt32 valor para a cultura atual.

UInt64

Chamadas UInt64.ToString("G", NumberFormatInfo.CurrentInfo) para formatar a UInt64 valor para a cultura atual.

Voltar ao topo

O método ToString e seqüências de caracteres de formato

Contando com o padrão ToString método ou substituindo ToString é apropriado quando um objeto tem uma representação de seqüência de caracteres única. No entanto, o valor de um objeto freqüentemente tem várias representações. Por exemplo, uma temperatura pode ser expressa em graus Fahrenheit, graus Celsius ou kelvins. Da mesma forma, o valor de inteiro 10 pode ser representado de diversas maneiras, incluindo 10, 10.0, 1.0e01, ou r $10,00.

Para habilitar um único valor para ter várias representações de strings, o.NET Framework usa seqüências de caracteres de formato. Uma seqüência de formato é uma seqüência de caracteres que contém um ou mais predefinidos especificadores de formato, que são caracteres únicos ou grupos de caracteres que definem como o ToString método deve formatar sua saída. A seqüência de caracteres de formato é passada como um parâmetro para o objeto ToString método e determina como a representação de seqüência de caracteres do valor do objeto deve aparecer.

Todos os tipos numéricos, data e tipos de tempo e os tipos de enumeração na.NET Framework oferecem suporte a um conjunto predefinido de especificadores de formato. Você também pode usar seqüências de caracteres de formato para definir várias representações de strings de seus tipos de dados definidos pelo aplicativo.

Cadeias de caracteres de formato padrão

Uma seqüência de caracteres de formato padrão contém um especificador de formato único, o que é um caractere alfabético que define a representação de seqüência de caracteres do objeto ao qual é aplicado, junto com um especificador de precisão opcional que afeta a quantos dígitos serão exibidos na seqüência de resultado. Se o especificador precisão for omitido ou não é suportado, um especificador de formato padrão é equivalente a uma seqüência de caracteres de formato padrão.

A.NET Framework define um conjunto de especificadores de formato padrão para todos os tipos numéricos, data de todos os tipos de tempo e todos os tipos de enumeração. Por exemplo, cada uma dessas categorias suporta um "G" especificador de formato padrão, que define uma representação de seqüência geral de um valor desse tipo.

Seqüências de caracteres de formato padrão para tipos de enumeração diretamente controlam a representação de seqüência de caracteres de um valor. As seqüências de caracteres de formato passaram para um valor de enumeração ToString método determinar se o valor é exibido usando seu nome de seqüência de caracteres ("G" e "F" especificadores de formato), seu valor integral subjacente (o "D" especificador de formato), ou seu valor hexadecimal (o "X" especificador de formato). O exemplo a seguir ilustra o uso de seqüências de caracteres de formato padrão para formatar um DayOfWeek valor de enumeração.

Dim thisDay As DayOfWeek = DayOfWeek.Monday
Dim formatStrings() As String = {"G", "F", "D", "X"}

For Each formatString As String In formatStrings
   Console.WriteLine(thisDay.ToString(formatString))
Next
' The example displays the following output:
'       Monday
'       Monday
'       1
'       00000001
DayOfWeek thisDay = DayOfWeek.Monday;
string[] formatStrings = {"G", "F", "D", "X"};

foreach (string formatString in formatStrings)
   Console.WriteLine(thisDay.ToString(formatString));
// The example displays the following output:
//       Monday
//       Monday
//       1
//       00000001

Para obter informações sobre seqüências de formato de enumeração, consulte Sequências de Caracteres de Formatação de Enumeração.

Seqüências de caracteres de formato padrão para tipos numéricos geralmente definem uma seqüência de caracteres de resultado cuja aparência precisa é controlada por um ou mais valores de propriedade. Por exemplo, "C" especificador de formato formata um número como um valor monetário. Quando você chama o ToString método com o "C" especificador de formato, como o único parâmetro, os seguintes valores de propriedade da cultura atual NumberFormatInfo objeto são usados para definir a representação de seqüência de caracteres do valor numérico:

  • O CurrencySymbol propriedade, que especifica o símbolo de moeda. a cultura atual

  • O CurrencyNegativePattern ou CurrencyPositivePattern propriedade, que retorna um número inteiro que determina o seguinte:

    • O posicionamento do símbolo da moeda.

    • Se os valores negativos são indicados por um sinal negativo à esquerda, um sinal de negativo à direita ou parênteses.

    • Se um espaço é exibida entre o valor numérico e o símbolo de moeda.

  • O CurrencyDecimalDigits propriedade, que define o número de dígitos fracionários na seqüência de resultado.

  • O CurrencyDecimalSeparator propriedade, que define o símbolo do separador decimal na seqüência de resultado.

  • O CurrencyGroupSeparator propriedade, que define o símbolo de separador de grupo.

  • O CurrencyGroupSizes propriedade, que define o número de dígitos em cada grupo para a esquerda do decimal.

  • O NegativeSign propriedade, que determina o sinal negativo é usado na seqüência de resultado se parênteses não são usados para indicar valores negativos.

Além disso, seqüências de caracteres de formato numérico podem incluir um especificador de precisão. O significado deste especificador depende da seqüência de caracteres de formato com o qual ele é usado, mas geralmente indica o número total de dígitos ou o número de dígitos de fração que deve aparecer na seqüência de resultado. Por exemplo, o exemplo a seguir usa o "X 4" seqüência numérica padrão e um especificador de precisão para criar um valor de seqüência de caracteres tem quatro dígitos hexadecimais.

Dim byteValues() As Byte = { 12, 163, 255 }
For Each byteValue As Byte In byteValues
   Console.WriteLine(byteValue.ToString("X4"))
Next
' The example displays the following output:
'       000C
'       00A3
'       00FF
byte[] byteValues = { 12, 163, 255 };
foreach (byte byteValue in byteValues)
   Console.WriteLine(byteValue.ToString("X4"));
// The example displays the following output:
//       000C
//       00A3
//       00FF

Para obter mais informações sobre o padrão numérico seqüências de caracteres de formatação, consulte Sequências de Caracteres de Formato Numérico Padrão.

Seqüências de caracteres de formato padrão para valores de data e hora são aliases para cadeias de caracteres de formato personalizado armazenadas por um determinado DateTimeFormatInfo propriedade. Por exemplo, chamando o ToString o método de um valor de data e hora com o "D" especificador de formato exibe a data e hora usando a seqüência de caracteres de formato personalizado armazenada na cultura atual DateTimeFormatInfo.LongDatePattern propriedade. (Para obter mais informações sobre seqüências de caracteres de formato personalizado, consulte o seção próxima.) O exemplo a seguir ilustra essa relação.

Imports System.Globalization

Module Example
   Public Sub Main()
      Dim date1 As Date = #6/30/2009#
      Console.WriteLine("D Format Specifier:     {0:D}", date1)
      Dim longPattern As String = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern
      Console.WriteLine("'{0}' custom format string:     {1}", _
                        longPattern, date1.ToString(longPattern))
   End Sub
End Module
' The example displays the following output when run on a system whose
' current culture is en-US:
'    D Format Specifier:     Tuesday, June 30, 2009
'    'dddd, MMMM dd, yyyy' custom format string:     Tuesday, June 30, 2009
using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2009, 6, 30);
      Console.WriteLine("D Format Specifier:     {0:D}", date1);
      string longPattern = CultureInfo.CurrentCulture.DateTimeFormat.LongDatePattern;
      Console.WriteLine("'{0}' custom format string:     {1}", 
                        longPattern, date1.ToString(longPattern));
   }
}
// The example displays the following output when run on a system whose
// current culture is en-US:
//    D Format Specifier:     Tuesday, June 30, 2009
//    'dddd, MMMM dd, yyyy' custom format string:     Tuesday, June 30, 2009

Para obter mais informações sobre a data padrão e seqüências de formato de hora, consulte Sequências de caracteres de formato padrão de data e hora.

Você também pode usar seqüências de caracteres de formato padrão para definir a representação de seqüência de caracteres de um objeto definido pelo aplicativo que é produzido pelo objeto de ToString(String) método. Você pode definir os especificadores de formato padrão específico que ofereça suporte a seu objeto e você pode determinar se elas são diferencia maiúsculas de minúsculas ou maiúsculas de minúsculas. A implementação da ToString(String) método deve suportar o seguinte:

  • UM "G" especificador de formato que representa um formato comum ou habitual do objeto. A sobrecarga sem parâmetros do seu objeto ToString deve chamar o método sua ToString(String) de sobrecarga e passá-lo "G" seqüência de caracteres de formato padrão.

  • Suporte para um especificador de formato é igual a uma referência nula (Nothing em Visual Basic). Um especificador de formato é igual a uma referência nula deve ser considerado como equivalente a "G" especificador de formato.

Por exemplo, um Temperature classe internamente pode armazenar a temperatura em graus Celsius e usar os especificadores de formato para representar o valor da Temperature o objeto em graus Celsius, graus Fahrenheit e kelvins. O exemplo a seguir fornece uma ilustração.

Public Class Temperature
   Private m_Temp As Decimal

   Public Sub New(temperature As Decimal)
      Me.m_Temp = temperature
   End Sub

   Public ReadOnly Property Celsius() As Decimal
      Get
         Return Me.m_Temp
      End Get   
   End Property

   Public ReadOnly Property Kelvin() As Decimal
      Get
         Return Me.m_Temp + 273.15d   
      End Get
   End Property

   Public ReadOnly Property Fahrenheit() As Decimal
      Get
         Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
      End Get      
   End Property

   Public Overrides Function ToString() As String
      Return Me.ToString("C")
   End Function

   Public Overloads Function ToString(format As String) As String  
      ' Handle null or empty string.
      If String.IsNullOrEmpty(format) Then format = "C"
      ' Remove spaces and convert to uppercase.
      format = format.Trim().ToUpperInvariant()      

      ' Convert temperature to Fahrenheit and return string.
      Select Case format
         Case "F"
            Return Me.Fahrenheit.ToString("N2") & " °F"
         ' Convert temperature to Kelvin and return string.
         Case "K"
            Return Me.Kelvin.ToString("N2") & " K"
         ' Return temperature in Celsius.
         Case "C"
            Return Me.Celsius.ToString("N2") & " °C"
         Case Else
            Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
      End Select      
   End Function
End Class

Public Module Example
   Public Sub Main()
      Dim temp1 As New Temperature(0d)
      Console.WriteLine(temp1.ToString())
      Console.WriteLine(temp1.ToString("C"))
      Console.WriteLine(temp1.ToString("F"))
      Console.WriteLine(temp1.ToString("K"))
      Dim temp2 As New Temperature(-40d)
      Console.WriteLine(temp2.ToString())
      Console.WriteLine(temp2.ToString("C"))
      Console.WriteLine(temp2.ToString("F"))
      Console.WriteLine(temp2.ToString("K"))
      Dim temp3 As New Temperature(16d)
      Console.WriteLine(temp3.ToString())
      Console.WriteLine(temp3.ToString("C"))
      Console.WriteLine(temp3.ToString("F"))
      Console.WriteLine(temp3.ToString("K"))

      Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3))
   End Sub
End Module
' The example displays the following output:
'       0.00 °C
'       0.00 °C
'       32.00 °F
'       273.15 K
'       -40.00 °C
'       -40.00 °C
'       -40.00 °F
'       233.15 K
'       16.00 °C
'       16.00 °C
'       60.80 °F
'       289.15 K
'       The temperature is now 16.00 °C.
public class Temperature
{
   private decimal m_Temp;

   public Temperature(decimal temperature)
   {
      this.m_Temp = temperature;
   }

   public decimal Celsius
   {
      get { return this.m_Temp; }
   }

   public decimal Kelvin
   {
      get { return this.m_Temp + 273.15m; }   
   }

   public decimal Fahrenheit
   {
      get { return Math.Round(((decimal) (this.m_Temp * 9 / 5 + 32)), 2); }
   }

   public override string ToString()
   {
      return this.ToString("C");
   }

   public string ToString(string format)
   {  
      // Handle null or empty string.
      if (String.IsNullOrEmpty(format)) format = "C";
      // Remove spaces and convert to uppercase.
      format = format.Trim().ToUpperInvariant();      

      // Convert temperature to Fahrenheit and return string.
      switch (format)
      {
         // Convert temperature to Fahrenheit and return string.
         case "F":
            return this.Fahrenheit.ToString("N2") + " °F";
         // Convert temperature to Kelvin and return string.
         case "K":
            return this.Kelvin.ToString("N2") + " K";
         // return temperature in Celsius.
         case "C":
            return this.Celsius.ToString("N2") + " °C";
         default:
            throw new FormatException(String.Format("The '{0}' format string is not supported.", format));
      }      
   }
}

public class Example
{
   public static void Main()
   {
      Temperature temp1 = new Temperature(0m);
      Console.WriteLine(temp1.ToString());
      Console.WriteLine(temp1.ToString("C"));
      Console.WriteLine(temp1.ToString("F"));
      Console.WriteLine(temp1.ToString("K"));
      Temperature temp2 = new Temperature(-40m);
      Console.WriteLine(temp2.ToString());
      Console.WriteLine(temp2.ToString("C"));
      Console.WriteLine(temp2.ToString("F"));
      Console.WriteLine(temp2.ToString("K"));
      Temperature temp3 = new Temperature(16m);
      Console.WriteLine(temp3.ToString());
      Console.WriteLine(temp3.ToString("C"));
      Console.WriteLine(temp3.ToString("F"));
      Console.WriteLine(temp3.ToString("K"));

      Console.WriteLine(String.Format("The temperature is now {0:F}.", temp3));
   }
}
// The example displays the following output:
//       0.00 °C
//       0.00 °C
//       32.00 °F
//       273.15 K
//       -40.00 °C
//       -40.00 °C
//       -40.00 °F
//       233.15 K
//       16.00 °C
//       16.00 °C
//       60.80 °F
//       289.15 K
//       The temperature is now 16.00 °C.

Voltar ao topo

Seqüências de caracteres de formato personalizado

Além de para as seqüências de caracteres de formato padrão, o.NET Framework define as seqüências de caracteres de formato personalizado para valores numéricos e de valores de data e hora. Uma seqüência de caracteres de formato personalizado consiste em um ou mais especificadores de formato personalizado que definem a representação de seqüência de caracteres de um valor. Por exemplo, a data e hora personalizadas formatar seqüência de caracteres "aaaa/mm/dd hh:mm:ss.ffff zzz de t" Converte uma data em sua representação de seqüência de caracteres no formulário "15/11/2008 07:45:00.0000 p-08: 00" para a cultura en-US. Da mesma forma, a seqüência de formato personalizado "0000" Converte o valor de inteiro 12 para "0012". Para obter uma lista completa de seqüências de caracteres de formato personalizado, consulte Sequências de Caracteres de Formato Personalizado de Data e Hora e Sequências de Caracteres de Formato Numérico Personalizado.

Se uma seqüência de caracteres de formato consiste em um especificador de formato personalizado simples, o especificador de formato deve ser precedido pelo símbolo de porcentagem (%) para evitar confusão com um especificador de formato padrão. O exemplo a seguir usa o "M" especificador de formato personalizado para exibir um número um ou dois dígitos do mês de uma determinada data.

Dim date1 As Date = #09/08/2009#
Console.WriteLine(date1.ToString("%M"))      ' Displays 9
DateTime date1 = new DateTime(2009, 9, 8);
Console.WriteLine(date1.ToString("%M"));       // Displays 9

Muitas cadeias de caracteres de formato padrão para valores de data e hora são aliases para cadeias de caracteres de formato personalizado que são definidas por propriedades de DateTimeFormatInfo objeto. Seqüências de caracteres de formato personalizado também oferecem flexibilidade considerável fornecendo definido pela aplicação de formatação para valores numéricos ou valores de data e hora. Você pode definir suas próprias seqüências de resultados personalizados para valores numéricos e de valores de data e hora, combinando várias especificadores de formato personalizado em uma seqüência única de formato personalizado. O exemplo a seguir define uma seqüência de caracteres de formato personalizado que exibe o dia da semana entre parênteses após o nome do mês, dia e ano.

Dim customFormat As String = "MMMM dd, yyyy (dddd)"
Dim date1 As Date = #8/28/2009#
Console.WriteLine(date1.ToString(customFormat))   
' The example displays the following output if run on a system
' whose language is English:
'       August 28, 2009 (Friday)      
string customFormat = "MMMM dd, yyyy (dddd)";
DateTime date1 = new DateTime(2009, 8, 28);
Console.WriteLine(date1.ToString(customFormat));   
// The example displays the following output if run on a system
// whose language is English:
//       August 28, 2009 (Friday)      

Embora as seqüências de caracteres de formato padrão geralmente podem tratar a maioria das necessidades de formatação para seus tipos definidos pelo aplicativo, você também pode definir especificadores de formato personalizado para formatar seus tipos.

Voltar ao topo

Provedores de formato e a Interface IFormatProvider

Embora os especificadores de formato permitem personalizar a formatação de objetos, produzir uma representação de seqüência significativo de objetos normalmente requer informações adicionais de formatação. Por exemplo, formatação de um número como um valor monetário usando o "C" seqüência de caracteres de formato padrão ou uma seqüência de caracteres de formato personalizado, como "$ #, #. 00" requer, no mínimo, informações sobre o correto de moeda, o separador de grupo e o separador decimal estejam disponíveis para incluir na seqüência de caracteres formatada. No.NET Framework, essas informações adicionais de formatação são disponibilizadas por meio de IFormatProvider interface, que é fornecido como um parâmetro para um ou mais métodos sobrecarregados da ToString método de tipos numéricos e tipos de data e hora. O exemplo a seguir ilustra como a representação de seqüência de caracteres de um objeto muda quando ele é formatado com três diferentes IFormatProvider objetos.

Imports System.Globalization

Public Module Example
   Public Sub Main()
      Dim value As Decimal = 1603.42d
      Console.WriteLine(value.ToString("C3", New CultureInfo("en-US")))
      Console.WriteLine(value.ToString("C3", New CultureInfo("fr-FR")))
      Console.WriteLine(value.ToString("C3", New CultureInfo("de-DE")))
   End Sub
End Module
' The example displays the following output:
'       $1,603.420
'       1 603,420 €
'       1.603,420 €
using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      decimal value = 1603.42m;
      Console.WriteLine(value.ToString("C3", new CultureInfo("en-US")));
      Console.WriteLine(value.ToString("C3", new CultureInfo("fr-FR")));
      Console.WriteLine(value.ToString("C3", new CultureInfo("de-DE")));
   }
}
// The example displays the following output:
//       $1,603.420
//       1 603,420 €
//       1.603,420 €

O IFormatProvider interface inclui um método, GetFormat(Type), que tem um único parâmetro que especifica o tipo de objeto que fornece informações de formatação. Se o método pode fornecer um objeto desse tipo, ele retorna. Caso contrário, ele retorna uma referência nula (Nothing em Visual Basic).

IFormatProvider.GetFormaté um método de retorno de chamada. Quando você chama um ToString sobrecarga de método que inclui um IFormatProvider parâmetro, ele chama o GetFormat método do que IFormatProvider objeto. O GetFormat método é responsável por retornar um objeto que fornece informações de formatação necessárias, conforme especificado pelo seu formatType parâmetro, para o ToString método.

Um número de métodos de conversão de formatação ou seqüência incluir um parâmetro do tipo IFormatProvider, mas em muitos casos o valor do parâmetro é ignorado quando o método for chamado. A tabela a seguir lista alguns dos métodos de formatação que usam o parâmetro e o tipo da Type o objeto que eles passam para o IFormatProvider.GetFormat método.

Método

Tipo de formatType parâmetro

ToStringmétodo de tipos numéricos

System.Globalization.NumberFormatInfo

ToStringmétodo dos tipos de data e hora

System.Globalization.DateTimeFormatInfo

String.Format

System.ICustomFormatter

StringBuilder.AppendFormat

System.ICustomFormatter

Observação

O ToString métodos para os tipos numéricos e os tipos de data e hora estão sobrecarregados e apenas algumas das sobrecargas incluem um IFormatProvider parâmetro.Se um método não tem um parâmetro do tipo IFormatProvider, o objeto retornado pelo CultureInfo.CurrentCulture propriedade é passada em vez disso.Por exemplo, uma chamada para o padrão Int32.ToString() método finalmente resulta em uma chamada de método, como a seguir: Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture).

A.NET Framework fornece três classes que implementam IFormatProvider:

Você também pode implementar seu próprio provedor de formato para substituir qualquer uma dessas classes. No entanto, sua implementação GetFormat método deve retornar um objeto do tipo listado na tabela anterior, se ele tiver que fornecer informações de formatação para o ToString método.

Voltar ao topo

A Interface IFormattable

Normalmente, tipos de sobrecarga de que o ToString método com uma seqüência de caracteres de formato e um IFormatProvider parâmetro também implementar a IFormattable interface. Essa interface possui um único membro, IFormattable.ToString(String, IFormatProvider), que inclui uma seqüência de caracteres de formato e de um provedor de formato como parâmetros.

Implementando o IFormattable interface para sua classe definida pelo aplicativo oferece duas vantagens:

  • Suporte para conversão de seqüência de caracteres, o Convert classe. Chama o Convert.ToString(Object) e Convert.ToString(Object, IFormatProvider) a chamada de métodos seu IFormattable implementação automaticamente.

  • Suporte para formatação de composição. Se um item do formato que inclui uma seqüência de caracteres de formato é usada para formatar o seu tipo personalizado, o common language runtime automaticamente chama o IFormattable implementação e passa a cadeia de caracteres de formato. Para obter mais informações sobre formatação composto com métodos como String.Format ou Console.WriteLine, consulte a Formatação composto seção.

O exemplo a seguir define uma Temperature classe que implementa o IFormattable interface. Ele oferece suporte a "C" ou "G" especificadores de formato para exibir a temperatura em Celsius, "F" Formatar o especificador para exibir a temperatura em Fahrenheit e o "K" especificador de formato para exibir a temperatura em Kelvin.

Imports System.Globalization

Public Class Temperature : Implements IFormattable
   Private m_Temp As Decimal

   Public Sub New(temperature As Decimal)
      Me.m_Temp = temperature
   End Sub

   Public ReadOnly Property Celsius() As Decimal
      Get
         Return Me.m_Temp
      End Get   
   End Property

   Public ReadOnly Property Kelvin() As Decimal
      Get
         Return Me.m_Temp + 273.15d   
      End Get
   End Property

   Public ReadOnly Property Fahrenheit() As Decimal
      Get
         Return Math.Round(CDec(Me.m_Temp * 9 / 5 + 32), 2)
      End Get      
   End Property

   Public Overrides Function ToString() As String
      Return Me.ToString("G", Nothing)
   End Function

   Public Overloads Function ToString(format As String) As String
      Return Me.ToString(format, Nothing)
   End Function

   Public Overloads Function ToString(format As String, provider As IFormatProvider) As String _  
      Implements IFormattable.ToString

      ' Handle null or empty arguments.
      If String.IsNullOrEmpty(format) Then format = "G"
      ' Remove any white space and convert to uppercase.
      format = format.Trim().ToUpperInvariant()

      If provider Is Nothing Then provider = NumberFormatInfo.CurrentInfo

      Select Case format
         ' Convert temperature to Fahrenheit and return string.
         Case "F"
            Return Me.Fahrenheit.ToString("N2", provider) & "°F"
         ' Convert temperature to Kelvin and return string.
         Case "K"
            Return Me.Kelvin.ToString("N2", provider) & "K"
         ' Return temperature in Celsius.
         Case "C", "G"
            Return Me.Celsius.ToString("N2", provider) & "°C"
         Case Else
            Throw New FormatException(String.Format("The '{0}' format string is not supported.", format))
      End Select      
   End Function
End Class
using System;
using System.Globalization;

public class Temperature : IFormattable
{
   private decimal m_Temp;

   public Temperature(decimal temperature)
   {
      this.m_Temp = temperature;
   }

   public decimal Celsius
   {
      get { return this.m_Temp; }
   }

   public decimal Kelvin
   {
      get { return this.m_Temp + 273.15m; }   
   }

   public decimal Fahrenheit
   {
      get { return Math.Round((decimal) this.m_Temp * 9 / 5 + 32, 2); }
   }

   public override string ToString()
   {
      return this.ToString("G", null);
   }

   public string ToString(string format)
   {
      return this.ToString(format, null);
   }

   public string ToString(string format, IFormatProvider provider)  
   {
      // Handle null or empty arguments.
      if (String.IsNullOrEmpty(format)) format = "G";
      // Remove any white space and convert to uppercase.
      format = format.Trim().ToUpperInvariant();

      if (provider == null) provider = NumberFormatInfo.CurrentInfo;

      switch (format)
      {
         // Convert temperature to Fahrenheit and return string.
         case "F":
            return this.Fahrenheit.ToString("N2", provider) + "°F";
         // Convert temperature to Kelvin and return string.
         case "K":
            return this.Kelvin.ToString("N2", provider) + "K";
         // Return temperature in Celsius.
         case "C":
         case "G":
            return this.Celsius.ToString("N2", provider) + "°C";
         default:
            throw new FormatException(String.Format("The '{0}' format string is not supported.", format));
      }      
   }
}

O exemplo a seguir instancia um Temperature objeto. Em seguida, chama o ToString método e usa a seqüência de várias cadeias de caracteres de formato composto para obter diferentes representações de um Temperature objeto. Cada uma dessas chamadas de método, por sua vez, chama o IFormattable implementação de Temperature classe.

Public Module Example
   Public Sub Main()
      Dim temp1 As New Temperature(22d)
      Console.WriteLine(Convert.ToString(temp1, New CultureInfo("ja-JP")))
      Console.WriteLine("Temperature: {0:K}", temp1)
      Console.WriteLine("Temperature: {0:F}", temp1)
      Console.WriteLine(String.Format(New CultureInfo("fr-FR"), "Temperature: {0:F}", temp1)) 
   End Sub
End Module
' The example displays the following output:
'       22.00°C
'       Temperature: 295.15°K
'       Temperature: 71.60°F
'       Temperature: 71,60°F
public class Example
{
   public static void Main()
   {
      Temperature temp1 = new Temperature(22m);
      Console.WriteLine(Convert.ToString(temp1, new CultureInfo("ja-JP")));
      Console.WriteLine("Temperature: {0:K}", temp1);
      Console.WriteLine("Temperature: {0:F}", temp1);
      Console.WriteLine(String.Format(new CultureInfo("fr-FR"), "Temperature: {0:F}", temp1));
   }
}
// The example displays the following output:
//       22.00°C
//       Temperature: 295.15°K
//       Temperature: 71.60°F
//       Temperature: 71,60°F

Voltar ao topo

Formatação Composta

Alguns métodos, como String.Format e StringBuilder.AppendFormat, suporte a formatação de composição. Uma seqüência de formato composto é um tipo de modelo que retorna uma seqüência de caracteres única que incorpora a representação de seqüência de zero, um ou mais objetos. Cada objeto é representado na seqüência de formato composto por um item de formato indexado. O índice do item de formato corresponde à posição do objeto que ela representa, na lista de parâmetros do método. Os índices são baseada em zero. Por exemplo, a seguinte chamada para o String.Format método, o primeiro item do formato, {0:D}, é substituído pela representação de seqüência de caracteres de thatDate; o segundo item de formato, {1}, é substituído pela representação de seqüência de caracteres de item1; e o terceiro item de formato, {2:C2}, é substituído pela representação de seqüência de caracteres de item1.Value.

result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.", _
                       thatDate, item1, item1.Value)
Console.WriteLine(result)                            
' The example displays output like the following if run on a system
' whose current culture is en-US:
'       On 5/1/2009, the inventory of WidgetA was worth $107.44.
result = String.Format("On {0:d}, the inventory of {1} was worth {2:C2}.", 
                       thatDate, item1, item1.Value);
Console.WriteLine(result);                            
// The example displays output like the following if run on a system
// whose current culture is en-US:
//       On 5/1/2009, the inventory of WidgetA was worth $107.44.

Para obter mais informações sobre a formatação de composição, consulte Formatação Composta.

Voltar ao topo

Formatação com ICustomFormatter personalizada

Alguns composição formatação métodos, como String.Format(IFormatProvider, String, Object[]) e StringBuilder.AppendFormat(IFormatProvider, String, Object[]), incluir um parâmetro do provedor de formato que ofereça suporte a formatação personalizada. Quando o método de formatação é chamado, ele passa uma Type objeto representando um ICustomFormatter interface para o provedor de formato GetFormat método. O GetFormat , em seguida, o método é responsável por retornar a ICustomFormatter implementação que fornece a formatação personalizada.

O ICustomFormatter interface possui um método único, Format(String, Object, IFormatProvider), que é chamado automaticamente por uma composição de formatação de método, uma vez para cada item do formato em uma seqüência de caracteres de formato composto. O Format(String, Object, IFormatProvider) método tem três parâmetros: uma seqüência de caracteres de formato, o que representa o formatString argumento em um item de formato, um objeto para formatar e um IFormatProvider objeto que fornece serviços de formatação. Normalmente, a classe que implementa ICustomFormatter também implementa IFormatProvider, portanto, este último parâmetro é uma referência para a formatação personalizada própria classe. O método retorna uma representação de seqüência de caracteres formatada personalizada do objeto a ser formatado. Se o método não é possível formatar o objeto, ele deve retornar uma referência nula (Nothing em Visual Basic).

O exemplo a seguir fornece uma ICustomFormatter implementação chamado ByteByByteFormatter que exibe os valores inteiros como uma seqüência de valores hexadecimais de dois dígitos seguidos por um espaço.

Public Class ByteByByteFormatter : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(formatType As Type) As Object _
                   Implements IFormatProvider.GetFormat
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function

   Public Function Format(fmt As String, arg As Object, 
                          formatProvider As IFormatProvider) As String _
                          Implements ICustomFormatter.Format

      If Not formatProvider.Equals(Me) Then Return Nothing

      ' Handle only hexadecimal format string.
      If Not fmt.StartsWith("X") Then 
            Return Nothing
      End If

      ' Handle only integral types.
      If Not typeof arg Is Byte AndAlso
         Not typeof arg Is Int16 AndAlso
         Not typeof arg Is Int32 AndAlso
         Not typeof arg Is Int64 AndAlso
         Not typeof arg Is SByte AndAlso
         Not typeof arg Is UInt16 AndAlso
         Not typeof arg Is UInt32 AndAlso
         Not typeof arg Is UInt64 Then _
            Return Nothing

      Dim bytes() As Byte = BitConverter.GetBytes(arg)
      Dim output As String = Nothing

      For ctr As Integer = bytes.Length - 1 To 0 Step -1
         output += String.Format("{0:X2} ", bytes(ctr))   
      Next

      Return output.Trim()
   End Function
End Class
public class ByteByByteFormatter : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType)
   { 
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }

   public string Format(string format, object arg, 
                          IFormatProvider formatProvider)
   {   
      if (! formatProvider.Equals(this)) return null;

      // Handle only hexadecimal format string.
      if (! format.StartsWith("X")) return null;

      byte[] bytes;
      string output = null;

      // Handle only integral types.
      if (arg is Byte) 
         bytes = BitConverter.GetBytes((Byte) arg);
      else if (arg is Int16)
         bytes = BitConverter.GetBytes((Int16) arg);
      else if (arg is Int32)
         bytes = BitConverter.GetBytes((Int32) arg);
      else if (arg is Int64)   
         bytes = BitConverter.GetBytes((Int64) arg);
      else if (arg is SByte)
         bytes = BitConverter.GetBytes((SByte) arg);
      else if (arg is UInt16)
         bytes = BitConverter.GetBytes((UInt16) arg);
      else if (arg is UInt32)
         bytes = BitConverter.GetBytes((UInt32) arg);
      else if (arg is UInt64)
         bytes = BitConverter.GetBytes((UInt64) arg);
      else
         return null;

      for (int ctr = bytes.Length - 1; ctr >= 0; ctr--)
         output += String.Format("{0:X2} ", bytes[ctr]);   

      return output.Trim();
   }
}

O exemplo a seguir usa a ByteByByteFormatter classe para formatar valores de inteiro. Observe que o ICustomFormatter.Format método é chamado mais de uma vez na segunda String.Format(IFormatProvider, String, Object[]) chamada de método e que o padrão NumberFormatInfo provedor é usado na chamada do método terceira porque a.ByteByByteFormatter.Format método não reconhece "n0" Formatar seqüência de caracteres e retorna uma referência nula (Nothing em Visual Basic).

Public Module Example
   Public Sub Main()
      Dim value As Long = 3210662321 
      Dim value1 As Byte = 214
      Dim value2 As Byte = 19

      Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X}", value)))
      Console.WriteLine((String.Format(New ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})", 
                                      value1, value2, value1 And value2)))                                
      Console.WriteLine(String.Format(New ByteByByteFormatter(), "{0,10:N0}", value))
   End Sub
End Module
' The example displays the following output:
'       00 00 00 00 BF 5E D1 B1
'       00 D6 And 00 13 = 00 12 (018)
'       3,210,662,321
public class Example
{
   public static void Main()
   {
      long value = 3210662321; 
      byte value1 = 214;
      byte value2 = 19;

      Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0:X}", value));
      Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0:X} And {1:X} = {2:X} ({2:000})", 
                                      value1, value2, value1 & value2));                                
      Console.WriteLine(String.Format(new ByteByByteFormatter(), "{0,10:N0}", value));
   }
}
// The example displays the following output:
//       00 00 00 00 BF 5E D1 B1
//       00 D6 And 00 13 = 00 12 (018)
//       3,210,662,321

Voltar ao topo

Tópicos relacionados

Título

Definição

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

Descreve as cadeias de caracteres de formato padrão que criar representações de seqüência de caracteres usados com freqüência de valores numéricos.

Sequências de Caracteres de Formato Numérico Personalizado

Descreve as cadeias de caracteres de formato personalizado que criar formatos de aplicativos específicos para valores numéricos.

Sequências de caracteres de formato padrão de data e hora

Descreve as cadeias de caracteres de formato padrão que criar representações de seqüência de caracteres usados com freqüência de DateTime valores.

Sequências de Caracteres de Formato Personalizado de Data e Hora

Descreve as cadeias de caracteres de formato personalizado que criar formatos de aplicativos específicos para DateTime valores.

Cadeias de caracteres de formato TimeSpan padrão

Descreve as cadeias de caracteres de formato padrão que criar representações de seqüência de caracteres usados com freqüência dos intervalos de tempo.

Cadeias de caracteres de formato TimeSpan personalizadas

Descreve as cadeias de caracteres de formato personalizado que criar formatos específicos de aplicativo para intervalos de tempo.

Sequências de Caracteres de Formatação de Enumeração

Descreve as cadeias de caracteres de formato padrão que são usadas para criar representações de seqüência de caracteres dos valores de enumeração.

Formatação Composta

Descreve como incorporar um ou mais valores formatados em uma sequência de caracteres. A sequência de caracteres posteriormente pode ser exibida no console ou gravada em um fluxo.

Executar operações de formatação

Os tópicos a seguir fornecem instruções passo a passo para executar operações específicas de formatação.

Analisando sequências de caracteres

Descreve como inicializar objetos para os valores descritos pelas representações de sequência de caracteres desses objetos. Análise é a operação inversa da formatação.

Voltar ao topo

Referência

System.IFormattable

System.IFormatProvider

System.ICustomFormatter