Este artigo foi traduzido por máquina. Para visualizar o arquivo em inglês, marque a caixa de seleção Inglês. Você também pode exibir o texto Em inglês em uma janela pop-up, movendo o ponteiro do mouse sobre o texto.
Tradução
Inglês

Formatando tipos no .NET Framework

 

Formatação é o processo de conversão de uma instância de classe, estrutura ou valor de enumeração em sua representação de cadeia de caracteres, de forma que a cadeia de caracteres resultante possa ser exibida aos usuários ou desserializada para restaurar o tipo de dados original. Essa conversão pode apresentar uma série de desafios:

  • A maneira que os valores são armazenados internamente não necessariamente reflete 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 é fácil de usar. Em vez disso, ele deve ser exibido como 800-999-9999. Consulte o cadeias de caracteres de formato personalizado seção para obter um exemplo que formata um número dessa maneira.

  • Às vezes, a conversão de um objeto para sua representação de cadeia de caracteres não é intuitiva. Por exemplo, ele não é claro como a representação de cadeia de caracteres de um objeto de temperatura ou um objeto Person deve aparecer. Para obter um exemplo que formata um objeto de temperatura em uma variedade de formas, consulte o cadeias de caracteres de formato padrão seção.

  • Muitas vezes, os valores exigem formatação que leva em conta a cultura. Por exemplo, em um aplicativo que usa números para refletir os valores monetários, cadeias de caracteres numéricas devem incluir o símbolo da moeda da cultura atual, o separador de grupo (que, na maioria das culturas, é o separador de milhar) e o símbolo decimal. Para obter um exemplo, consulte o formatação sensível à cultura com provedores de formato e a IFormatProvider Interface seção.

  • Um aplicativo pode ter que exibir o mesmo valor de maneiras diferentes. Por exemplo, um aplicativo pode representar um membro de enumeração ao exibindo uma representação de cadeia de caracteres de seu nome ou exibindo seu valor subjacente. Para obter um exemplo que formata um membro do DayOfWeek enumeração de maneiras diferentes, consulte o cadeias de caracteres de formato padrão seção.

System_CAPS_noteObservação

A formatação converte o valor de um tipo em uma representação de cadeia 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 com base em na representação de sua cadeia de caracteres. Para obter informações sobre como converter cadeias de caracteres em outros tipos de dados, consulte Analisando cadeias de caracteres no .NET Framework.

O .NET Framework oferece suporte à formatação avançada que permite aos desenvolvedores atender a esses requisitos.

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

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

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

  • A definição dos especificadores de formato que permitem que a representação de cadeia de caracteres do valor de um objeto assuma várias formas. Por exemplo, o especificador de formato "X" na instrução a seguir converte um inteiro na representação de cadeia de caracteres de um valor hexadecimal.

    int integerValue = 60312;
    Console.WriteLine(integerValue.ToString("X"));   // Displays EB98.
    

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

  • O uso de 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 de moeda usando as convenções de formatação da cultura en-US.

    double cost = 1632.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 com provedores de formato, consulte o provedores de formato e a IFormatProvider Interface seção.

  • Implementando o IFormattable interface para oferecer suporte a ambas as conversão de cadeia de caracteres com o Convert classe e formatação composta. Para obter mais informações, consulte o IFormattable Interface seção.

  • O uso da formatação de composição para inserir a representação de cadeia de caracteres de um valor em uma cadeia de caracteres maior. Para obter mais informações, consulte o formatação composta seção.

  • Implementando ICustomFormatter e IFormatProvider para fornecer uma solução completa de formatação personalizada. 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 cadeia de caracteres.

Voltar ao início

Cada tipo é 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 não tem nenhuma implementação. Quando a classe é instanciada e sua ToString método é chamado, ele exibe o nome do tipo. Observe que o ToString método não for chamado explicitamente no exemplo. O Console.WriteLine(Object) método chama implicitamente o ToString método do objeto é passado para ele como um argumento.

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
System_CAPS_warningAviso

Começando com Windows 8.1, o Tempo de Execução do Windows inclui um IStringable interface com um único método, IStringable.ToString, que fornece suporte de formatação padrão. No entanto, recomendamos que não implementam tipos gerenciados a IStringable interface. Para obter mais informações, consulte "o Tempo de Execução do Windows e o IStringable Interface" seção o Object.ToString página de referência.

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

System_CAPS_noteObservação

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

Voltar ao início

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

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 " +
                        currentTemperature.ToString());
   }
}
// The example displays the following output:
//       The current temperature is 23.6°C.

No .NET Framework, o ToString método de cada tipo de valor primitivo foi substituído para exibir o valor do objeto, em vez de seu nome. A tabela a seguir mostra a substituição de cada tipo primitivo. Observe que a maioria dos métodos substituídos chama outra sobrecarga de ToString método e passe o especificador de formato "G", que define o formato geral de 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 o Byte valor para a cultura atual.

Char

Retorna o caractere como uma cadeia de caracteres.

DateTime

Chama 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 o Decimal valor para a cultura atual.

Double

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

Int16

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

Int32

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

Int64

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

SByte

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

Single

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

UInt16

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

UInt32

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

UInt64

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

Voltar ao início

Contar com o padrão ToString método ou substituindo ToString é apropriado quando um objeto tem uma representação de cadeia de caracteres único. No entanto, o valor de um objeto normalmente tem várias representações. Por exemplo, uma temperatura pode ser expressa em graus Fahrenheit, graus Celsius ou kelvins. De forma similar, o valor de inteiro 10 pode ser representado de várias maneiras, incluindo 10, 10,0, 1.0e01 ou US $10,00.

Para habilitar um único valor com várias representações de cadeia de caracteres, o .NET Framework usa cadeias de caracteres de formato. Uma cadeia de caracteres de formato é uma cadeia 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 cadeia de caracteres de formato é passada como um parâmetro para o objeto ToString método e determina como a representação de cadeia de caracteres do valor do objeto deve ser exibidos.

Todos os tipos numéricos, data e tipos de hora e tipos de enumeração no .NET Framework dá suporte a um conjunto predefinido de especificadores de formato. Você também pode usar cadeias de caracteres de formato para definir várias representações de cadeia de caracteres de seus tipos de dados definidos pelo aplicativo.

Uma cadeia de caracteres de formato padrão contém um único especificador de formato, que é um caractere alfabético que define a representação de cadeia de caracteres do objeto ao qual ela é aplicada, junto com um especificador de precisão opcional que afeta a quantos dígitos serão exibidos na cadeia de caracteres de resultado. Se o especificador de precisão for omitido ou não houver suporte a ele, um especificador de formato padrão será equivalente a uma cadeia de caracteres de formato padrão.

O .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 dá suporte a um especificador de formato padrão "G", que define uma representação de cadeia de caracteres geral de um valor desse mesmo tipo.

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

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 cadeias de caracteres de formato de enumeração, consulte Cadeias de caracteres de formato de enumeração.

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

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

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

    • O posicionamento do símbolo da moeda.

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

    • Se um espaço é ou não exibido entre o valor numérico e o símbolo da moeda.

  • O CurrencyDecimalDigits propriedade, que define o número de dígitos fracionários na cadeia de caracteres de resultado.

  • O CurrencyDecimalSeparator propriedade, que define o símbolo do separador decimal na cadeia de caracteres 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 à esquerda da vírgula decimal.

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

Além disso, cadeias de caracteres de formato numérico podem incluir um especificador de precisão. O significado desse especificador depende da cadeia de caracteres de formato com o qual ele é usado, mas ele normalmente indica o número total de dígitos ou o número de dígitos fracionários que devem aparecer na cadeia de caracteres de resultado. Por exemplo, o exemplo a seguir usa a cadeia de caracteres numérica padrão "X4" e um especificador de precisão para criar um valor de cadeia de caracteres com quatro dígitos hexadecimais.

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 cadeias de caracteres de formatação de padrão numérica, consulte Cadeias de caracteres de formato numérico padrão.

Cadeias 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, chamar o ToString método de um valor de data e hora com o especificador de formato "D" exibe a data e hora usando a cadeia de caracteres de formato personalizado armazenada na cultura atual DateTimeFormatInfo.LongDatePattern propriedade. (Para obter mais informações sobre cadeias de caracteres de formato personalizado, consulte o próxima seção.) O exemplo a seguir ilustra essa relação.

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 o padrão de data e cadeias de caracteres de formato de hora, consulte Cadeias de caracteres de formato de data e hora padrão.

Você também pode usar cadeias de caracteres de formato padrão para definir a representação de cadeia de caracteres de um objeto definido pelo aplicativo que é produzido pelo método ToString(String) do objeto. Você pode definir os especificadores de formato padrão específicos que dão suporte a seu objeto e você pode determinar se eles diferenciam ou não maiúsculas de minúsculas. A implementação do ToString(String) método deve dar suporte ao seguinte:

  • Um especificador de formato "G" que representa um formato comum ou habitual do objeto. A sobrecarga sem parâmetros do método ToString de seu objeto deve chamar sua sobrecarga ToString(String) e passar cadeia de caracteres de formato padrão "G".

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

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

using System;

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 "G":
         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("G"));
      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("G"));
      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("G"));
      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
//       0.00 °C
//       32.00 °F
//       273.15 K
//       -40.00 °C
//       -40.00 °C
//       -40.00 °C
//       -40.00 °F
//       233.15 K
//       16.00 °C
//       16.00 °C
//       16.00 °C
//       60.80 °F
//       289.15 K
//       The temperature is now 16.00 °C.

Voltar ao início

Além de cadeias de caracteres de formato padrão, o .NET Framework define cadeias de caracteres de formato personalizado para valores numéricos e valores de data e hora. Uma cadeia de caracteres de formato personalizado consiste em um ou mais especificadores de formato personalizado que definem a representação de cadeia de caracteres de um valor. Por exemplo, a cadeia de caracteres de formato de data e hora personalizada "aaaa/mm/dd hh:mm:ss.ffff t zzz" converte uma data em sua representação de cadeia de caracteres no formato "2008/11/15 07:45:00.0000 P -08:00" para a cultura en-US. Da mesma forma, a cadeia de caracteres de formato personalizado "0000" converte o valor inteiro 12 em "0012". Para obter uma lista completa de cadeias de caracteres de formato personalizado, consulte Cadeias de caracteres de formato de data e hora personalizado e Cadeias de caracteres de formato numérico personalizado.

Se uma cadeia de caracteres de formato consiste em um único especificador de formato personalizado, 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 especificador de formato personalizado "M" para exibir um número de um ou dois dígitos do mês de uma data específica.

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 pelas propriedades do DateTimeFormatInfo objeto. Cadeias de caracteres de formato personalizado também oferecem flexibilidade considerável no fornecimento de formação definida pelo aplicativo para valores numéricos ou valores de data e hora. Você pode definir suas próprias cadeias de caracteres de resultado personalizadas para valores numéricos e valores de data e hora combinando vários especificadores de formato personalizado em uma única cadeia de caracteres de formato personalizado. O exemplo a seguir define uma cadeia de caracteres de formato personalizado que exibe o dia da semana entre parênteses após o nome do mês, o dia e o ano.

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)      

O exemplo a seguir define uma cadeia de caracteres de formato personalizado que exibe um Int64 valor como um número de telefone dos EUA padrão, sete dígitos junto com seu código de área.

using System;

public class Example
{
   public static void Main()
   {
      long number = 8009999999;
      string fmt = "000-000-0000";
      Console.WriteLine(number.ToString(fmt));
   }
}
// The example displays the following output:
//        800-999-9999

Embora as cadeias de caracteres de formato padrão geralmente tratem da maioria das necessidades de formatação para os tipos definidos pelo aplicativo, você também pode definir especificadores de formato personalizado para formatar seus tipos.

Voltar ao início

Todos os tipos numéricos (ou seja, o Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64, e BigInteger tipos)

, bem como o DateTime, DateTimeOffset, TimeSpan, Guid, e todos os tipos de enumeração, suporte à formatação com cadeias de caracteres de formato. Para obter informações sobre as cadeias de caracteres de formato específico suportado por cada tipo, consulte os tópicos a seguir

Título

Definição

Cadeias de caracteres de formato numérico padrão

Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres de valores numéricos frequentemente usadas.

Cadeias de caracteres de formato numérico personalizado

Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para valores numéricos.

Cadeias de caracteres de formato de data e hora padrão

Descreve cadeias de caracteres de formato padrão que criar representações de cadeia de caracteres mais usadas de DateTime valores.

Cadeias de caracteres de formato de data e hora personalizado

Descreve cadeias de caracteres de formato personalizado que cria formatos específicos de aplicativo para DateTime valores.

Cadeias de caracteres de formato TimeSpan padrão

Descreve cadeias de caracteres de formato padrão que criam representações de intervalos de tempo frequentemente usadas.

Cadeias de caracteres de formato TimeSpan personalizado

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

Cadeias de caracteres de formato de enumeração

Descreve cadeias de caracteres de formato padrão que são usadas para criar representações de cadeia de caracteres de valores de enumeração.

Guid.ToString(String)

Descreve cadeias de caracteres de formato padrão para Guid valores.

Embora os especificadores de formato permitam personalizar a formatação de objetos, a produção de uma representação de cadeia de caracteres de objetos significativa geralmente requer informações de formatação adicionais. Por exemplo, formatar um número como um valor de moeda usando a cadeia de caracteres de formato padrão "C" ou então uma cadeia de caracteres de formato personalizado como "$ #,#.00" requer que, no mínimo, informações sobre o símbolo correto da moeda, o separador de grupo e o separador decimal estejam disponíveis para inclusão na cadeia de caracteres formatada. No .NET Framework, essas informações de formatação adicionais são disponibilizadas por meio do IFormatProvider interface, que é fornecida como um parâmetro para um ou mais sobrecargas do ToString método de tipos numéricos e tipos de data e hora. IFormatProvider as implementações são usadas no .NET Framework para dar suporte a formatação de cultura específica. O exemplo a seguir ilustra como a representação de cadeia de caracteres de um objeto é alterado quando ele é formatado com três IFormatProvider objetos que representam diferentes culturas.

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 puder fornecer um objeto desse tipo, ele retornará esse objeto. Caso contrário, ele retornará uma referência nula (Nothing no Visual Basic).

IFormatProvider.GetFormat é um método de retorno de chamada. Quando você chama um ToString sobrecarga do método que inclui um IFormatProvider parâmetro, ele chama o GetFormat método que IFormatProvider objeto. O GetFormat método é responsável por retornar um objeto que fornece as 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 cadeia de caracteres ou formatação inclui um parâmetro de tipo IFormatProvider, mas em muitos casos o valor do parâmetro é ignorado quando o método é chamado. A tabela a seguir lista alguns dos métodos de formatação que usam o parâmetro e o tipo do Type objeto que passam para o IFormatProvider.GetFormat método.

Método

Tipo de formatType parâmetro

ToString método de tipos numéricos

System.Globalization.NumberFormatInfo

ToString método de tipos de data e hora

System.Globalization.DateTimeFormatInfo

String.Format

System.ICustomFormatter

StringBuilder.AppendFormat

System.ICustomFormatter

System_CAPS_noteObservação

O ToString métodos de tipos numéricos e tipos de data e hora sã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 que é retornado pelo CultureInfo.CurrentCulture propriedade é passada em vez disso. Por exemplo, uma chamada para o padrão Int32.ToString() método acaba resultando em uma chamada de método, como o seguinte: Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture).

O .NET Framework oferece 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, se o seu método GetFormat de sua implementação precisar fornecer informações de formatação ao método ToString, ele deverá retornar um objeto do tipo listado na tabela anterior.

Voltar ao início

Por padrão, a formatação de valores numéricos leva em conta a cultura. Se você não especificar uma cultura quando chamar um método de formatação, as convenções de formatação da cultura do thread atual serão usadas. Isso é ilustrado no exemplo a seguir, que altera a cultura do thread atual quatro vezes e, em seguida, chama o Decimal.ToString(String) método. Em cada caso, a cadeia de caracteres de resultado reflete as convenções de formatação da cultura atual. Isso ocorre porque os métodos ToString e ToString(String) encapsulam chamadas para o método ToString(String, IFormatProvider) de cada tipo numérico.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      string[] cultureNames = { "en-US", "fr-FR", "es-MX", "de-DE" };
      Decimal value = 1043.17m;

      foreach (var cultureName in cultureNames) {
         // Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName);
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name);
         Console.WriteLine(value.ToString("C2"));
         Console.WriteLine();
      }   
   }
}
// The example displays the following output:
//       The current culture is en-US
//       $1,043.17
//       
//       The current culture is fr-FR
//       1 043,17 €
//       
//       The current culture is es-MX
//       $1,043.17
//       
//       The current culture is de-DE
//       1.043,17 €

Você também pode formatar um valor numérico para uma cultura específica chamando um ToString sobrecarga que tem um provider parâmetro e passar um destes procedimentos:

O exemplo a seguir usa NumberFormatInfo objetos que representam o inglês (Estados Unidos) e as culturas neutras francês e russos e culturas inglês (Grã-Bretanha) para formatar um número de ponto flutuante.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {                                                                                                    
      Double value = 1043.62957;
      string[] cultureNames = { "en-US", "en-GB", "ru", "fr" };

      foreach (var name in cultureNames) {
         NumberFormatInfo nfi = CultureInfo.CreateSpecificCulture(name).NumberFormat;
         Console.WriteLine("{0,-6} {1}", name + ":", value.ToString("N3", nfi));
      }   
   }
}
// The example displays the following output:
//       en-US: 1,043.630
//       en-GB: 1,043.630
//       ru:    1 043,630
//       fr:    1 043,630

Por padrão, a formatação de valores de data e hora leva em conta a cultura. Se você não especificar uma cultura quando chamar um método de formatação, as convenções de formatação da cultura do thread atual serão usadas. Isso é ilustrado no exemplo a seguir, que altera a cultura do thread atual quatro vezes e, em seguida, chama o DateTime.ToString(String) método. Em cada caso, a cadeia de caracteres de resultado reflete as convenções de formatação da cultura atual. Isso ocorre porque o DateTime.ToString(), DateTime.ToString(String), DateTimeOffset.ToString(), e DateTimeOffset.ToString(String) métodos encapsulam chamadas para o DateTime.ToString(String, IFormatProvider) e DateTimeOffset.ToString(String, IFormatProvider) métodos.

using System;
using System.Globalization;
using System.Threading;

public class Example
{
   public static void Main()
   {
      string[] cultureNames = { "en-US", "fr-FR", "es-MX", "de-DE" };
      DateTime dateToFormat = new DateTime(2012, 5, 28, 11, 30, 0);

      foreach (var cultureName in cultureNames) {
         // Change the current thread culture.
         Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(cultureName);
         Console.WriteLine("The current culture is {0}", 
                           Thread.CurrentThread.CurrentCulture.Name);
         Console.WriteLine(dateToFormat.ToString("F"));
         Console.WriteLine();
      }   
   }
}
// The example displays the following output:
//       The current culture is en-US
//       Monday, May 28, 2012 11:30:00 AM
//       
//       The current culture is fr-FR
//       lundi 28 mai 2012 11:30:00
//       
//       The current culture is es-MX
//       lunes, 28 de mayo de 2012 11:30:00 a.m.
//       
//       The current culture is de-DE
//       Montag, 28. Mai 2012 11:30:00

Você também pode formatar um valor de data e hora para uma cultura específica chamando um DateTime.ToString ou DateTimeOffset.ToString sobrecarga que tem um provider parâmetro e passar um destes procedimentos:

O exemplo a seguir usa DateTimeFormatInfo objetos que representam o inglês (Estados Unidos) e as culturas neutras francês e russos e culturas inglês (Grã-Bretanha) para formatar uma data.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {                                                                                                    
      DateTime dat1 = new DateTime(2012, 5, 28, 11, 30, 0);
      string[] cultureNames = { "en-US", "en-GB", "ru", "fr" };

      foreach (var name in cultureNames) {
         DateTimeFormatInfo dtfi = CultureInfo.CreateSpecificCulture(name).DateTimeFormat;
         Console.WriteLine("{0}: {1}", name, dat1.ToString(dtfi));
      }   
   }
}
// The example displays the following output:
//       en-US: 5/28/2012 11:30:00 AM
//       en-GB: 28/05/2012 11:30:00
//       ru: 28.05.2012 11:30:00
//       fr: 28/05/2012 11:30:00

Tipos normalmente, essa sobrecarga de ToString método com uma cadeia de caracteres de formato e um IFormatProvider parâmetro também implementam o IFormattable interface. Essa interface possui um único membro, IFormattable.ToString(String, IFormatProvider), que inclui uma cadeia de caracteres de formato e um provedor de formato como parâmetros.

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

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

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 objeto Temperature. Depois, ele chama o ToString método e usa string 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 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 início

Alguns métodos, tais como String.Format e StringBuilder.AppendFormat, dão suporte à formatação de composição. Uma cadeia de caracteres de formato de composição é um tipo de modelo que retorna uma única cadeia de caracteres que incorpora a representação de cadeia de caracteres de zero, um ou mais objetos. Cada objeto é representado na cadeia de caracteres de formato de composição por um item de formato indexado. O índice do item de formato corresponde à posição do objeto que ele representa na lista de parâmetros do método. Os índices são baseados em zero. Por exemplo, na seguinte chamada para o método String.Format, o primeiro item de formato, {0:D}, é substituído pela representação de cadeia de caracteres de thatDate; o segundo item de formato, {1}, é substituído pela representação de cadeia de caracteres de item1 e, por fim, o terceiro item de formato, {2:C2}, é substituído pela representação de cadeia 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.

Além de substituir um item de formato pela representação de cadeia de caracteres de seu objeto correspondente, os itens de formato também permitem que você controle o seguinte:

  • A específicas a forma em que um objeto é representado como uma cadeia de caracteres, se o objeto implementa a IFormattable da interface e oferece suporte a cadeias de caracteres de formato. Você pode fazer isso seguindo o índice do item de formato com um : (dois-pontos) seguido por uma cadeia de caracteres de formato válido. O exemplo anterior já fez isso ao formatar um valor de data com a cadeia de formato "d" (padrão de data abreviada) (por exemplo, {0:d}) e formatando um valor numérico com "C2" cadeia de caracteres de formato (por exemplo, {2:C2} para representar o número como um valor de moeda com dois dígitos fracionários.

  • A largura do campo que contém a representação de cadeia de caracteres do objeto e o alinhamento da representação de cadeia de caracteres nesse campo. Você pode fazer isso seguindo o índice do item de formato com um , (vírgula) seguido a largura do campo. A cadeia de caracteres será alinhada à direita no campo se a largura do campo for um valor positivo ou à esquerda se esse valor for negativo. O exemplo a seguir alinha os valores de data à esquerda em um campo de 20 caracteres e alinha valores decimais com um dígito fracionário à direita em um campo de 11 caracteres.

    DateTime startDate = new DateTime(2015, 8, 28, 6, 0, 0);
    decimal[] temps = { 73.452m, 68.98m, 72.6m, 69.24563m,
                       74.1m, 72.156m, 72.228m };
    Console.WriteLine("{0,-20} {1,11}\n", "Date", "Temperature");
    for (int ctr = 0; ctr < temps.Length; ctr++)
       Console.WriteLine("{0,-20:g} {1,11:N1}", startDate.AddDays(ctr), temps[ctr]);
    
    // The example displays the following output:
    //       Date                 Temperature
    //
    //       8/28/2015 6:00 AM           73.5
    //       8/29/2015 6:00 AM           69.0
    //       8/30/2015 6:00 AM           72.6
    //       8/31/2015 6:00 AM           69.2
    //       9/1/2015 6:00 AM            74.1
    //       9/2/2015 6:00 AM            72.2
    //       9/3/2015 6:00 AM            72.2
    

    Observe que, se o componente de cadeia de caracteres de alinhamento e o componente de cadeia de caracteres de formato estiverem presentes, o primeiro precederá o último (por exemplo, {0,-20:g}.

Para obter mais informações sobre formatação composta, consulte Formatação composta.

Voltar ao início

Dois métodos de formatação compostos, String.Format(IFormatProvider, String, Object[]) e StringBuilder.AppendFormat(IFormatProvider, String, Object[]), incluir um parâmetro de provedor de formato que oferece suporte à formatação personalizada. Quando um desses métodos de formatação é chamado, ele passa um Type objeto que representa um ICustomFormatter interface para o provedor de formato GetFormat método. O GetFormat em seguida, o método é responsável por retornar o ICustomFormatter implementação que oferece formatação personalizada.

O ICustomFormatter interface possui um único método, Format(String, Object, IFormatProvider), que é chamado automaticamente por um método, uma vez para cada item de formato em uma cadeia de caracteres de formato composto de formatação composto. O Format(String, Object, IFormatProvider) método tem três parâmetros: uma cadeia de caracteres de formato, que representa o formatString argumento em um item de formato, um objeto a ser formatado e um IFormatProvider Serviços de objeto que fornece a 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 cadeia de caracteres formatada personalizada do objeto a ser formatado. Se o método não é possível formatar o objeto, ele deverá retornar uma referência nula (Nothing no Visual Basic).

O exemplo a seguir fornece um ICustomFormatter implementação chamada ByteByByteFormatter que exibe valores de inteiro como uma sequência de valores hexadecimais de dois dígitos seguidos por um espaço.

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 classe ByteByByteFormatter para formatar valores inteiros. 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 terceiro porque a.ByteByByteFormatter.Format método não reconhece a cadeia de caracteres de formato "N0" e retorna uma referência nula (Nothing no Visual Basic).

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 início

Título

Definição

Cadeias de caracteres de formato numérico padrão

Descreve cadeias de caracteres de formato padrão que criam representações de cadeia de caracteres de valores numéricos frequentemente usadas.

Cadeias de caracteres de formato numérico personalizado

Descreve cadeias de caracteres de formato personalizado que criam formatos específicos de aplicativo para valores numéricos.

Cadeias de caracteres de formato de data e hora padrão

Descreve cadeias de caracteres de formato padrão que criar representações de cadeia de caracteres mais usadas de DateTime valores.

Cadeias de caracteres de formato de data e hora personalizado

Descreve cadeias de caracteres de formato personalizado que cria formatos específicos de aplicativo para DateTime valores.

Cadeias de caracteres de formato TimeSpan padrão

Descreve cadeias de caracteres de formato padrão que criam representações de intervalos de tempo frequentemente usadas.

Cadeias de caracteres de formato TimeSpan personalizado

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

Cadeias de caracteres de formato de enumeração

Descreve cadeias de caracteres de formato padrão que são usadas para criar representações de cadeia de caracteres de valores de enumeração.

Formatação composta

Descreve como inserir um ou mais valores formatados em uma cadeia de caracteres. A cadeia de caracteres pode posteriormente ser exibida no console ou gravada em um fluxo.

Executando operações de formatação

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

Analisando cadeias de caracteres no .NET Framework

Descreve como inicializar objetos para os valores descritos pelas representações de cadeia de caracteres desses objetos. A análise é a operação inversa da formatação.

Voltar ao início

Mostrar: