Format Método
TOC
Recolher sumário
Expandir sumário
Este artigo foi traduzido por máquina. Coloque o ponteiro do mouse sobre as frases do artigo para ver o texto original. Mais informações.
Tradução
Original

String.Format Método

 

Converte o valor de objetos em cadeias de caracteres com base nos formatos especificados e os insere em outra cadeia de caracteres.

Se você estiver familiarizado com o String.Format método, consulte o guia de Introdução com o método String. Format seção para obter uma visão geral rápida.

Consulte o comentários seção para obter a documentação completa para todas as String.Format sobrecargas.

Namespace:   System
Assembly:  mscorlib (em mscorlib.dll)

NomeDescrição
System_CAPS_pubmethodSystem_CAPS_staticFormat(IFormatProvider, String, Object)

Substitui o item de formato ou itens em uma cadeia de caracteres especificada com a representação de cadeia de caracteres do objeto correspondente.Um parâmetro fornece informações de formatação específicas da cultura.

System_CAPS_pubmethodSystem_CAPS_staticFormat(IFormatProvider, String, Object, Object)

Substitui os itens de formato em uma String especificada com a representação de String de dois objetos especificados.Um parâmetro fornece informações de formatação específicas da cultura.

System_CAPS_pubmethodSystem_CAPS_staticFormat(IFormatProvider, String, Object, Object, Object)

Substitui os itens de formato em uma String especificada com a representação de String de três objetos especificados.Um parâmetro fornece informações de formatação específicas da cultura.

System_CAPS_pubmethodSystem_CAPS_staticFormat(IFormatProvider, String, Object[])

Substitui os itens de formato em uma cadeia de caracteres especificada com as representações de cadeia de caracteres de objetos correspondentes em uma matriz especificada.Um parâmetro fornece informações de formatação específicas da cultura.

System_CAPS_pubmethodSystem_CAPS_staticFormat(String, Object)

Substitui um ou mais itens de formato em uma String especificada com a representação de String de um objeto especificado.

System_CAPS_pubmethodSystem_CAPS_staticFormat(String, Object, Object)

Substitui os itens de formato em uma String especificada com a representação de String de dois objetos especificados.

System_CAPS_pubmethodSystem_CAPS_staticFormat(String, Object, Object, Object)

Substitui os itens de formato em uma String especificada com a representação de String de três objetos especificados.

System_CAPS_pubmethodSystem_CAPS_staticFormat(String, Object[])

Substitui o item de formato em uma String especificada com a representação de String de um objeto correspondente em um array especificado.

Use String.Format se você precisar inserir o valor de um objeto, variável ou expressão na outra cadeia de caracteres.Por exemplo, você pode inserir o valor de uma Decimal valor em uma cadeia de caracteres para exibi-lo ao usuário como uma única cadeia de caracteres:

Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0} per ounce.",
                         pricePerOunce);
// Result: The current price is 17.36 per ounce.

E você pode controlar a formatação do valor:

Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0:C2} per ounce.",
                         pricePerOunce);
// Result if current culture is en-US:
//      The current price is $17.36 per ounce.

Além de formatação, você também pode controlar alinhamento e o espaçamento.

Inserir uma cadeia de caracteres

String.Format começa com uma cadeia de caracteres de formato, seguida por um ou mais objetos ou expressões que serão convertidas em cadeias de caracteres e inseridas em um local especificado na cadeia de caracteres de formato. Por exemplo:

decimal temp = 20.4m;
string s = String.Format("The temperature is {0}°C.", temp);
Console.WriteLine(s);
// Displays 'The temperature is 20.4°C.'

O {0} no formato de cadeia de caracteres é um item de formato. 0 é o índice do objeto cujo valor de cadeia de caracteres será inserido nessa posição.(Índices começassem com 0). Se o objeto a ser inserido não é uma cadeia de caracteres, sua ToString método é chamado para convertê-lo em um antes de inseri-lo na cadeia de caracteres resultante.

Aqui está outro exemplo que usa dois itens de formato e dois objetos na lista de objetos:

string s = String.Format("At {0}, the temperature is {1}°C.",
                         DateTime.Now, 20.4);
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'

Você pode ter quantos itens de formato e quantos objetos na lista de objetos, como você desejar, desde que o índice de cada item de formato tem um objeto correspondente na lista de objetos.Você também não precisa se preocupar sobre qual sobrecarga chamar; o compilador irá selecionar o apropriado para você.

Controlando a formatação

Você pode seguir o índice de um item de formato com uma cadeia de caracteres de formato para controlar como um objeto é formatado.Por exemplo, {0:d} aplica-se a cadeia de caracteres de formato "d" para o primeiro objeto na lista de objetos.Aqui está um exemplo com um único objeto e dois itens de formato:

string s = String.Format("It is now {0:d} at {0:t}", DateTime.Now);
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'

Um número de suporte de tipos Formatar cadeias de caracteres, incluindo todos os tipos numéricos (ambos e cadeias de caracteres de formato), todas as datas e horas (ambos e cadeias de caracteres de formato) e intervalos de tempo (ambos e cadeias de caracteres de formato), todos os tipos de enumeração , e GUIDs.Você também pode adicionar suporte para cadeias de caracteres de formato para seus próprios tipos.

Controlando o espaçamento

Você pode definir a largura da cadeia de caracteres que é inserida na cadeia de caracteres resultante usando sintaxe como {0,12}, que insere uma cadeia de caracteres de 12.Nesse caso, a representação de cadeia de caracteres do primeiro objeto é alinhado à esquerda no campo de 12 caracteres.

O exemplo a seguir define um campo de 6 caracteres para armazenar a cadeia de caracteres "Ano" e algumas cadeias de caracteres do ano, bem como um campo de 15 caracteres para manter a cadeia de caracteres "População" e alguns dados de população.Observe que os caracteres são alinhados à esquerda do campo.

int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
String s = String.Format("{0,6} {1,15}\n\n", "Year", "Population");
for(int index = 0; index < years.Length; index++)
   s += String.Format("{0,6} {1,15:N0}\n",
                      years[index], population[index]);
// Result:
//      Year      Population
//
//      2013       1,025,632
//      2014       1,105,967
//      2015       1,148,203
Controlando o alinhamento

Por padrão, cadeias de caracteres são alinhados à esquerda em seu campo se você especificar uma largura de campo.Para cadeias de caracteres em um campo à direita, você precede a largura do campo com um sinal negativo, como {0,-12} para definir um campo de 12 caracteres alinhado à direita.

O exemplo a seguir é semelhante ao anterior, exceto que ele alinha à direita os rótulos e os dados.

int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
String s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population");
for(int index = 0; index < years.Length; index++)
   s += String.Format("{0,-10} {1,-10:N0}\n",
                      years[index], population[index]);
// Result:
//    Year       Population
//
//    2013       1,025,632
//    2014       1,105,967
//    2015       1,148,203

String.Format utiliza o recurso de formatação composta.Para obter mais informações, consulte Composite Formatting.

Para obter orientação adicional sobre como escolher uma sobrecarga, consulte Qual método devo chamar?

String String.Format(String format, Object arg0)

Substitui os itens de formato com a representação de cadeia de caracteres de um objeto especificado (exemplo).

String String.Format(String format, Object arg0, Object arg1)

Substitui os itens de formato com a representação de cadeia de caracteres de dois objetos especificados (exemplo).

String String.Format(String format, Object arg0, Object arg1, Object arg2)

Substitui os itens de formato com a representação de cadeia de caracteres de três objetos especificados (exemplo).

String String.Format(String format, params Object[] args)

Substitui os itens de formato com as representações de cadeia de caracteres de objetos correspondentes em uma matriz especificada (exemplo).

String String.Format(IFormatProvider provider, String format, params Object[] args)

Substitui os itens de formato com a representação de cadeia de caracteres de objetos correspondentes em uma matriz especificado e usa as informações de formatação específicas da cultura especificadas (exemplo) ou as informações de formatação personalizada (exemplo).

Esta é uma lista completa de parâmetros para o Format método; consulte a sintaxe de sobrecarga acima para os parâmetros usados por cada sobrecarga.Somente o format parâmetro é usado por todas as sobrecargas.

PARAMETER

Tipo

Descrição

s

String

Uma cadeia de caracteres de formato composto que inclui um ou mais itens de formato (consulte o item de formato).

arg0

String

O primeiro ou apenas o objeto a ser formatado.

arg1

String

O segundo objeto a ser formatado.

arg2

String

O terceiro objeto a ser formatado.

args

String[]

Zero ou mais objetos para formatar, fornecido em uma lista delimitada por vírgulas ou como uma matriz.

provider

IFormatProvider

Um objeto que fornece informações de formatação personalizadas ou específicas de cultura.

Tipo: String
Uma cópia do format em que os itens de formato foram substituídos pelas representações de cadeia de caracteres de argumentos correspondentes.

Exception

Condição

Lançado por

ArgumentNullException

format é null.

Todas as sobrecargas.

FormatException

format é inválido.

-ou-

O índice de um item de formato é menor que zero, ou maior que ou igual ao número de argumentos na lista de argumentos.

Todas as sobrecargas.

Para

Chamada

Formate um ou mais objetos usando as convenções da cultura atual.

Exceto para as sobrecargas que incluem um provider parâmetro, o restante Format sobrecargas incluem um String parâmetro seguido por um ou mais parâmetros de objeto.Por isso, você não precisa determinar qual Format sobrecarga que você pretende chamar.O compilador de linguagem selecionará a sobrecarga apropriada entre as sobrecargas que não têm um provider parâmetro, com base em sua lista de argumentos.Por exemplo, se a lista de argumentos tem cinco argumentos, o compilador irá chamar o Format(String, Object[]) método.

Formate um ou mais objetos usando as convenções de uma cultura específica.

Cada Format sobrecarga que começa com um provider parâmetro é seguido por um String parâmetro e um ou mais parâmetros do objeto.Por isso, não é necessário determinar qual específico Format sobrecarga que você pretende chamar.O compilador de linguagem selecionará a sobrecarga apropriada entre as sobrecargas que têm um provider parâmetro, com base em sua lista de argumentos.Por exemplo, se a lista de argumentos tem cinco argumentos, o compilador irá chamar o Format(IFormatProvider, String, Object[]) método.

Executar uma operação de formatação personalizada com um ICustomFormatter implementação ou um IFormattable implementação.

Qualquer uma das quatro sobrecargas com um provider parâmetro.compilador selecionará a sobrecarga apropriada entre as sobrecargas que têm um provider parâmetro, com base em sua lista de argumentos.

Cada sobrecarga do Format método usa o para incluir com base em zero espaços reservados indexados, chamados de itens de formato, em uma cadeia de caracteres de formato composto.Em tempo de execução, cada item de formato é substituído com a representação de cadeia de caracteres do argumento correspondente em uma lista de parâmetros.Se o valor do argumento for null, o item de formato é substituído pelo String.Empty.Por exemplo, a seguinte chamada para o Format(String, Object, Object, Object) método inclui uma cadeia de caracteres de formato com formato de três itens, {0}, {1} e {2} e uma lista de argumentos com três itens.

DateTime dat = new DateTime(2012, 1, 17, 9, 30, 0); 
string city = "Chicago";
int temp = -16;
string output = String.Format("At {0} in {1}, the temperature was {2} degrees.",
                              dat, city, temp);
Console.WriteLine(output);
// The example displays the following output:
//    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.   

Um item de formato tem a seguinte sintaxe:


{
index[,alignment][ :formatString] }

Colchetes indicam elementos opcionais.As chaves de abertura e fechamento são necessários.(Para incluir uma literal abertura ou fechamento na cadeia de formato, consulte a seção "Chaves de escape" o Composite Formatting artigo.)

Por exemplo, um item de formato para formatar um valor monetário será algo como:

String.Format("{0,-10:C}", 126347.89m);         

Um item de formato tem os seguintes elementos:

índice

O índice baseado em zero do argumento cuja representação de cadeia de caracteres deve ser incluído nessa posição na cadeia de caracteres.Se esse argumento for null, uma cadeia de caracteres vazia será incluída nessa posição na cadeia de caracteres.

alinhamento

Opcional. Um inteiro que indica o comprimento total do campo em que o argumento é inserido e se ele está alinhado à direita (um inteiro positivo) ou alinhado à esquerda (um inteiro negativo).Se você omitir alinhamento, a representação de cadeia de caracteres do argumento correspondente é inserida em um campo sem espaços à esquerda ou direita.

formatString

Opcional. Uma cadeia de caracteres que especifica o formato de cadeia de caracteres de resultado do argumento correspondente.Se você omitir formatString, o argumento correspondente sem parâmetros ToString método é chamado para produzir sua representação de cadeia de caracteres.Se você especificar formatString, o argumento referenciado pelo item de formato deve implementar o IFormattable interface.Tipos que oferecem suporte a cadeias de caracteres de formato:

No entanto, observe que qualquer tipo personalizado pode implementar IFormattable ou estender um tipo existente IFormattable implementação.

O exemplo a seguir usa a alignment e formatString argumentos para produzir saída formatada.

using System;

public class Example
{
   public static void Main()
   {
      // Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
      Tuple<string, DateTime, int, DateTime, int>[] cities = 
          { Tuple.Create("Los Angeles", new DateTime(1940, 1, 1), 1504277, 
                         new DateTime(1950, 1, 1), 1970358),
            Tuple.Create("New York", new DateTime(1940, 1, 1), 7454995, 
                         new DateTime(1950, 1, 1), 7891957),  
            Tuple.Create("Chicago", new DateTime(1940, 1, 1), 3396808, 
                         new DateTime(1950, 1, 1), 3620962),  
            Tuple.Create("Detroit", new DateTime(1940, 1, 1), 1623452, 
                         new DateTime(1950, 1, 1), 1849568) };

      // Display header
      string header = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n",
                                    "City", "Year", "Population", "Change (%)");
      Console.WriteLine(header);
      string output;      
      foreach (var city in cities) {
         output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                                city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
                                (city.Item5 - city.Item3)/ (double)city.Item3);
         Console.WriteLine(output);
      }
   }
}
// The example displays the following output:
//    City            Year  Population    Year  Population    Change (%)
//    
//    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
//    New York        1940   7,454,995    1950   7,891,957         5.9 %
//    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
//    Detroit         1940   1,623,452    1950   1,849,568        13.9 %

Itens de formato são processadas em sequência desde o início da cadeia de caracteres.Cada item de formato tem um índice que corresponde a um objeto na lista de argumentos do método.O Format recupera o argumento de método e sua representação de cadeia de caracteres é derivada da seguinte maneira:

Para obter um exemplo que intercepta as chamadas para o ICustomFormatter.Format método e permite que você veja quais informações o Format método passa um método de formatação para cada item de formato em uma cadeia de caracteres de formato composto, consulte exemplo 7: um provedor de interceptação e formatador de algarismo romano.

O Format método lança um FormatException exceção se o índice de um item do índice for maior ou igual ao número de argumentos na lista de argumentos.No entanto, format pode incluir itens de formato mais do que o número de argumentos, como vários itens de formato têm o mesmo índice.Na chamada para o Format(String, Object) método no exemplo a seguir, a lista de argumentos tem um único argumento, mas a cadeia de caracteres de formato inclui dois itens de formato: um exibe o valor decimal de um número, e o outro exibe seu valor hexadecimal.

public class Example
{
   public static void Main()
   {
      short[] values= { Int16.MinValue, -27, 0, 1042, Int16.MaxValue };
      Console.WriteLine("{0,10}  {1,10}\n", "Decimal", "Hex");
      foreach (short value in values)
      {
         string formatString = String.Format("{0,10:G}: {0,10:X}", value);
         Console.WriteLine(formatString);
      }   
   }
}
// The example displays the following output:
//       Decimal         Hex
//    
//        -32768:       8000
//           -27:       FFE5
//             0:          0
//          1042:        412
//         32767:       7FFF

Em geral, os objetos na lista de argumentos são convertidos em suas representações de cadeia de caracteres usando as convenções da cultura atual, que é retornada pelo CultureInfo.CurrentCulture propriedade.Você pode controlar esse comportamento, chamando uma das sobrecargas de Format que inclui um provider parâmetro.O provider parâmetro é um IFormatProvider o processo de implementação que fornece informações de formatação personalizadas e específicas de cultura que são usadas para moderado a formatação.

O IFormatProvider interface possui um único membro, GetFormat, que é responsável por retornar o objeto que fornece informações de formatação.O .NET Framework tem três IFormatProvider implementações que fornecem a formatação de cultura específica:

Você também pode chamar qualquer uma das sobrecargas do Format método tem um provider parâmetro Format(IFormatProvider, String, Object[]) sobrecarga para executar operações de formatação personalizadas.Por exemplo, você pode formatar um número inteiro como um número de identificação ou como um número de telefone.Para executar a formatação personalizada, sua provider argumento deve implementar a IFormatProvider e ICustomFormatter interfaces.Quando o Format método é passado um ICustomFormatter implementação como o provider argumento, o Format chamadas de método seu IFormatProvider.GetFormat implementação e solicita um objeto do tipo ICustomFormatter.Em seguida, chama retornado ICustomFormatter do objeto Format método para cada item de formato na cadeia de caracteres composta de formato passado para ele.

Para obter mais informações sobre o fornecimento de soluções de formatação personalizadas, consulte How to: Define and Use Custom Numeric Format Providers e ICustomFormatter.Para obter um exemplo que converte números inteiros em números personalizados formatados, consulte exemplo 6: uma operação de formatação personalizada.Para obter um exemplo que converte bytes não assinados em numerais romanos, consulte exemplo 7: um provedor de interceptação e formatador de algarismo romano.

O exemplo a seguir usa o método Format(String, Object) para incorporar a idade de uma pessoa no meio de uma seqüência de caracteres.

using System;

[assembly: CLSCompliant(true)]
public class Example
{
   public static void Main()
   {
      DateTime birthdate = new DateTime(1993, 7, 28);
      DateTime[] dates = { new DateTime(1993, 8, 16), 
                           new DateTime(1994, 7, 28), 
                           new DateTime(2000, 10, 16), 
                           new DateTime(2003, 7, 27), 
                           new DateTime(2007, 5, 27) };

      foreach (DateTime dateValue in dates)
      {
         TimeSpan interval = dateValue - birthdate;
         // Get the approximate number of years, without accounting for leap years.
         int years = ((int) interval.TotalDays) / 365;
         // See if adding the number of years exceeds dateValue.
         string output;
         if (birthdate.AddYears(years) <= dateValue) {
            output = String.Format("You are now {0} years old.", years);
            Console.WriteLine(output);
         }   
         else {
            output = String.Format("You are now {0} years old.", years - 1);
            Console.WriteLine(output);
         }      
      }
   }
}
// The example displays the following output:
//       You are now 0 years old.
//       You are now 1 years old.
//       You are now 7 years old.
//       You are now 9 years old.
//       You are now 13 years old.

Este exemplo usa o Format(String, Object, Object) método para exibir a hora e a temperatura dados armazenados em um genérico Dictionary<TKey, TValue> objeto.Observe que a cadeia de caracteres de formato tem três itens de formato, embora haja apenas dois objetos a serem formatados.Isso ocorre porque o primeiro objeto na lista (um valor de data e hora) usado pelos dois itens de formato: os monitores de item de formato primeiro o tempo e o segundo exibe a data.

using System;
using System.Collections.Generic;

public class Example
{
   public static void Main()
   {
      Dictionary<DateTime, Double> temperatureInfo = new Dictionary<DateTime, Double>(); 
      temperatureInfo.Add(new DateTime(2010, 6, 1, 14, 0, 0), 87.46);
      temperatureInfo.Add(new DateTime(2010, 12, 1, 10, 0, 0), 36.81);

      Console.WriteLine("Temperature Information:\n");
      string output;   
      foreach (var item in temperatureInfo)
      {
         output = String.Format("Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F", 
                                item.Key, item.Value);
         Console.WriteLine(output);
      }
   }
}
// The example displays the following output:
//       Temperature Information:
//       
//       Temperature at  2:00 PM on  6/1/2010:  87.5°F
//       Temperature at 10:00 AM on 12/1/2010:  36.8°F

Este exemplo usa o Format(String, Object, Object, Object) método para criar uma cadeia de caracteres que ilustra o resultado de um valor booleano And operação com dois valores inteiros.Observe que a cadeia de caracteres de formato inclui seis itens de formato, mas o método tem apenas três itens na lista de parâmetros, pois cada item é formatada de duas maneiras diferentes.

using System;

public class Example
{
   public static void Main()
   {
      string formatString = "    {0,10} ({0,8:X8})\n" + 
                            "And {1,10} ({1,8:X8})\n" + 
                            "  = {2,10} ({2,8:X8})";
      int value1 = 16932;
      int value2 = 15421;
      string result = String.Format(formatString, 
                                    value1, value2, value1 & value2);
      Console.WriteLine(result);
   }
}
// The example displays the following output:
//                16932 (00004224)
//       And      15421 (00003C3D)
//         =         36 (00000024)

Este exemplo cria uma cadeia de caracteres que contém dados sobre a temperatura alta e baixa em uma determinada data.A cadeia de caracteres de formato composto tem cinco itens de formato de exemplo do c# e seis no exemplo do Visual Basic.Dois itens de formato definem a largura da representação de cadeia de caracteres do valor de seu correspondente e o primeiro item de formato também inclui um padrão de data e a cadeia de caracteres de formato de hora.

using System;

public class Example
{
   public static void Main()
   {
      DateTime date1 = new DateTime(2009, 7, 1);
      TimeSpan hiTime = new TimeSpan(14, 17, 32);
      decimal hiTemp = 62.1m; 
      TimeSpan loTime = new TimeSpan(3, 16, 10);
      decimal loTemp = 54.8m; 

      string result1 = String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", 
                                     date1, hiTime, hiTemp, loTime, loTemp);
      Console.WriteLine(result1);
      Console.WriteLine();

      string result2 = String.Format("Temperature on {0:d}:\n{1,11}: {2} degrees (hi)\n{3,11}: {4} degrees (lo)", 
                                     new object[] { date1, hiTime, hiTemp, loTime, loTemp });
      Console.WriteLine(result2);
   }
}
// The example displays the following output:
//       Temperature on 7/1/2009:
//          14:17:32: 62.1 degrees (hi)
//          03:16:10: 54.8 degrees (lo)
//       Temperature on 7/1/2009:
//          14:17:32: 62.1 degrees (hi)
//          03:16:10: 54.8 degrees (lo)

Você também pode passar os objetos a serem formatadas como uma matriz em vez de uma lista de argumentos.

using System;

public class CityInfo
{
   public CityInfo(String name, int population, Decimal area, int year)
   {
      this.Name = name;
      this.Population = population;
      this.Area = area;
      this.Year = year;
   }

   public readonly String Name; 
   public readonly int Population;
   public readonly Decimal Area;
   public readonly int Year;
}

public class Example
{
   public static void Main()
   {
      CityInfo nyc2010 = new CityInfo("New York", 8175133, 302.64m, 2010);
      ShowPopulationData(nyc2010);
      CityInfo sea2010 = new CityInfo("Seattle", 608660, 83.94m, 2010);      
      ShowPopulationData(sea2010); 
   }

   private static void ShowPopulationData(CityInfo city)
   {
      object[] args = { city.Name, city.Year, city.Population, city.Area };
      String result = String.Format("{0} in {1}: Population {2:N0}, Area {3:N1} sq. feet", 
                                    args);
      Console.WriteLine(result); 
   }
}
// The example displays the following output:
//       New York in 2010: Population 8,175,133, Area 302.6 sq. feet
//       Seattle in 2010: Population 608,660, Area 83.9 sq. feet

Este exemplo usa o Format(IFormatProvider, String, Object[]) método para exibir a representação de cadeia de caracteres de alguns valores de data e hora e valores numéricos usando várias culturas diferentes.

using System;
using System.Globalization;

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

      DateTime dateToDisplay = new DateTime(2009, 9, 1, 18, 32, 0);
      double value = 9164.32;

      Console.WriteLine("Culture     Date                                Value\n");
      foreach (string cultureName in cultureNames)
      {
         CultureInfo culture = new CultureInfo(cultureName);
         string output = String.Format(culture, "{0,-11} {1,-35:D} {2:N}", 
                                       culture.Name, dateToDisplay, value);
         Console.WriteLine(output);
      }    
   }
}
// The example displays the following output:
//    Culture     Date                                Value
//    
//    en-US       Tuesday, September 01, 2009         9,164.32
//    fr-FR       mardi 1 septembre 2009              9 164,32
//    de-DE       Dienstag, 1. September 2009         9.164,32
//    es-ES       martes, 01 de septiembre de 2009    9.164,32

Este exemplo define um provedor de formato que formata um valor inteiro como um número de conta de cliente no formulário x-xxxxx-xx.

using System;

public class TestFormatter
{
   public static void Main()
   {
      int acctNumber = 79203159;
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:G}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:S}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:P}", acctNumber));
      try {
         Console.WriteLine(String.Format(new CustomerFormatter(), "{0:X}", acctNumber));
      }
      catch (FormatException e) {
         Console.WriteLine(e.Message);
      }
   }
}

public class CustomerFormatter : 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 (! this.Equals(formatProvider))
      {
         return null;
      }
      else
      {
         if (String.IsNullOrEmpty(format)) 
            format = "G";

         string customerString = arg.ToString();
         if (customerString.Length < 8)
            customerString = customerString.PadLeft(8, '0');

         format = format.ToUpper();
         switch (format)
         {
            case "G":
               return customerString.Substring(0, 1) + "-" +
                                     customerString.Substring(1, 5) + "-" +
                                     customerString.Substring(6);
            case "S":                          
               return customerString.Substring(0, 1) + "/" +
                                     customerString.Substring(1, 5) + "/" +
                                     customerString.Substring(6);
            case "P":                          
               return customerString.Substring(0, 1) + "." +
                                     customerString.Substring(1, 5) + "." +
                                     customerString.Substring(6);
            default:
               throw new FormatException( 
                         String.Format("The '{0}' format specifier is not supported.", format));
         }
      }   
   }
}
// The example displays the following output:
//       7-92031-59
//       7-92031-59
//       7/92031/59
//       7.92031.59
//       The 'X' format specifier is not supported.

Este exemplo define um provedor de formato personalizado que implementa o ICustomFormatter e IFormatProvider interfaces fazer duas coisas:

  • Exibe os parâmetros passados para seus ICustomFormatter.Format implementação.Isso nos permite ver quais parâmetros o Format(IFormatProvider, String, Object[]) método está passando para a implementação de formatação personalizada para cada objeto que ele tenta formatar.Isso pode ser útil quando você estiver depurando seu aplicativo.

  • Se o objeto a ser formatado for um valor de bytes não assinado que deve ser formatada usando a cadeia de caracteres de formato padrão "R", o formatador personalizado formata o valor numérico como um numeral romano.

using System;
using System.Globalization;

public class InterceptProvider : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType)
   {
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }

   public string Format(String format, Object obj, IFormatProvider provider) 
   {
      // Display information about method call.
      string formatString = format ?? "<null>";
      Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
                        provider, obj ?? "<null>", formatString);

      if (obj == null) return String.Empty;

      // If this is a byte and the "R" format string, format it with Roman numerals.
      if (obj is Byte && formatString.ToUpper().Equals("R")) {
         Byte value = (Byte) obj;
         int remainder;
         int result;
         String returnString = String.Empty;

         // Get the hundreds digit(s)
         result = Math.DivRem(value, 100, out remainder);
         if (result > 0)  
            returnString = new String('C', result);
         value = (Byte) remainder;
         // Get the 50s digit
         result = Math.DivRem(value, 50, out remainder);
         if (result == 1)
            returnString += "L";
         value = (Byte) remainder;
         // Get the tens digit.
         result = Math.DivRem(value, 10, out remainder);
         if (result > 0)
            returnString += new String('X', result);
         value = (Byte) remainder; 
         // Get the fives digit.
         result = Math.DivRem(value, 5, out remainder);
         if (result > 0)
            returnString += "V";
         value = (Byte) remainder;
         // Add the ones digit.
         if (remainder > 0) 
            returnString += new String('I', remainder);

         // Check whether we have too many X characters.
         int pos = returnString.IndexOf("XXXX");
         if (pos >= 0) {
            int xPos = returnString.IndexOf("L"); 
            if (xPos >= 0 & xPos == pos - 1)
               returnString = returnString.Replace("LXXXX", "XC");
            else
               returnString = returnString.Replace("XXXX", "XL");   
         }
         // Check whether we have too many I characters
         pos = returnString.IndexOf("IIII");
         if (pos >= 0)
            if (returnString.IndexOf("V") >= 0)
               returnString = returnString.Replace("VIIII", "IX");
            else
               returnString = returnString.Replace("IIII", "IV");    

         return returnString; 
      }   

      // Use default for all other formatting.
      if (obj is IFormattable)
         return ((IFormattable) obj).ToString(format, CultureInfo.CurrentCulture);
      else
         return obj.ToString();
   }
}

public class Example
{
   public static void Main()
   {
      int n = 10;
      double value = 16.935;
      DateTime day = DateTime.Now;
      InterceptProvider provider = new InterceptProvider();
      Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day));
      Console.WriteLine(String.Format(provider, "{0}: {1:F}\n", "Today: ", 
                                      (DayOfWeek) DateTime.Now.DayOfWeek));
      Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", 
                                      (Byte) 2, (Byte) 12, (Byte) 199));
      Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}\n", 
                                      (Byte) 2, (Byte) 12, (Byte) 199));
   }
}
// The example displays the following output:
//    Provider: InterceptProvider, Object: 10, Format String: N0
//    Provider: InterceptProvider, Object: 16.935, Format String: C2
//    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
//    10: $16.94 on 1/31/2013
//    
//    Provider: InterceptProvider, Object: Today: , Format String: <null>
//    Provider: InterceptProvider, Object: Thursday, Format String: F
//    Today: : Thursday
//    
//    Provider: InterceptProvider, Object: 2, Format String: X
//    Provider: InterceptProvider, Object: 12, Format String: <null>
//    Provider: InterceptProvider, Object: 199, Format String: <null>
//    2, 12, 199
//    
//    Provider: InterceptProvider, Object: 2, Format String: R
//    Provider: InterceptProvider, Object: 12, Format String: R
//    Provider: InterceptProvider, Object: 199, Format String: R
//    II, XII, CXCIX

.NET Framework

Todas as sobrecargas são suportadas em: 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Todas as sobrecargas são suportadas em: 4, 3.5 SP1

Biblioteca de Classes Portátil

Apenas Format(String, Object[]) e Format(IFormatProvider, String, Object[]) são suportados

.NET para aplicativos da Windows Store

Apenas Format(String, Object[]) e Format(IFormatProvider, String, Object[]) são suportados no Windows 8

  • Para todos os tipos de ponto flutuante e integrais, consulte e .

  • Para obter valores de data e hora, consulte e .

  • Para valores de enumeração, consulte .

  • Para TimeSpan valores, consulte e .

  • Para Guid valores, consulte a seção comentários a Guid.ToString(String) página de referência.

A sintaxe geral de um item de formato é:

{index[,alignment][: formatString]}

onde alinhamento é um inteiro que define a largura do campo.Se esse valor for negativo, o texto do campo é alinhado à esquerda.Se for positivo, o texto será alinhado à direita.

Todos os exceto "D" (que é usada com apenas números inteiros), "G", "R" e "X" permitir que um especificador de precisão que define o número de casas decimais na cadeia de caracteres de resultado.O exemplo a seguir usa cadeias de caracteres de formato numérico padrão para controlar o número de casas decimais na cadeia de caracteres de resultado.

using System;

public class Example
{
   public static void Main()
   {
      object[] values = { 1603, 1794.68235, 15436.14 };
      string result;
      foreach (var value in values) {
         result = String.Format("{0,12:C2}   {0,12:E3}   {0,12:F4}   {0,12:N3}  {1,12:P2}\n",
                                Convert.ToDouble(value), Convert.ToDouble(value) / 10000);
         Console.WriteLine(result);
      }                           
   }
}
// The example displays the following output:
//       $1,603.00     1.603E+003      1603.0000      1,603.000       16.03 %
//    
//       $1,794.68     1.795E+003      1794.6824      1,794.682       17.95 %
//    
//      $15,436.14     1.544E+004     15436.1400     15,436.140      154.36 %

Se você estiver usando um , use o especificador de formato "0" para controlar o número de dígitos decimais na cadeia de caracteres resultante, como mostra o exemplo a seguir.

using System;

public class Example
{
   public static void Main()
   {
      decimal value = 16309.5436m;
      string result = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", 
                                    value);
      Console.WriteLine(result);
   }
}
// The example displays the following output:
//        16309.54360    16,309.54    16309.544

Por padrão, as operações de formatação só exibem dígitos integrais diferente de zero.Se você estiver formatando números inteiros, você pode usar um especificador de precisão com "D" e "X" cadeias de caracteres de formato padrão para controlar o número de dígitos.

using System;

public class Example
{
   public static void Main()
   {
      int value = 1326;
      string result = String.Format("{0,10:D6} {0,10:X8}", value);
      Console.WriteLine(result);
   }
}
// The example displays the following output:
//     001326   0000052E

Você pode acrescentar um inteiro ou um número de ponto flutuante com zeros à esquerda para produzir uma cadeia de caracteres de resultado com um número especificado de dígitos integrais usando "0" , como mostra o exemplo a seguir.

using System;

public class Example
{
   public static void Main()
   {
      int value = 16342;
      string result = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", 
                                    value);
      Console.WriteLine(result);
   }
}
// The example displays the following output:
//           00016342       00016342.000    0,000,016,342.0

Há um limite prático.O segundo parâmetro do Format(IFormatProvider, String, Object[]) método é marcado com o ParamArrayAttribute atributo, que permite que você inclua uma lista delimitada ou uma matriz de objeto como sua lista de formato.

Por exemplo, como evitar a seguinte chamada de método de lançar um FormatException exceção?

result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
                       nOpen, nClose);

Um simples de abertura ou fechamento é sempre interpretado como o início ou fim de um item de formato.Para ser interpretado literalmente, ele deve ser substituído.Substituir uma chave adicionando outra chave ("{{" e "}}", em vez de "{" e "}"), como a chamada de método a seguir:

result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
                       nOpen, nClose);

No entanto, até mesmo chaves são facilmente mal interpretadas.É recomendável que você inclua chaves na lista formato e usa itens de formato para inseri-los na cadeia de caracteres resultante, como mostra o exemplo a seguir.

result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
                       nOpen, "{", nClose, "}");

A causa mais comum de exceção é que o índice de um item de formato não corresponde a um objeto na lista de formato.Geralmente isso indica que você misnumbered os índices de itens de formato ou você esqueceu de incluir um objeto na lista de formato.Ocasionalmente, a exceção é o resultado de um erro de digitação; Por exemplo, um erro comum é digitar "[" (o colchete esquerdo), em vez de "{" (a chave à esquerda).

Por exemplo, o código a seguir gera um FormatException exceção:

using System;
using System.Collections.Generic;

public class Example
{
   public static void Main()
   {
      Random rnd = new Random();
      int[]  numbers = new int[4];
      int total = 0;
      for (int ctr = 0; ctr <= 2; ctr++) {
         int number = rnd.Next(1001);
         numbers[ctr] = number;
         total += number;
      }   
      numbers[3] = total;
      Console.WriteLine("{0} + {1} + {2} = {3}", numbers);   
   }
}

Este é um problema de resolução de sobrecarga do compilador.Porque o compilador não pode converter uma matriz de inteiros em uma matriz de objetos, ele trata a matriz de inteiros como um único argumento, portanto, ele chama o Format(String, Object) método.A exceção é gerada porque há quatro itens de formato, mas apenas um único item na lista formato.

Como o Visual Basic nem c# pode converter uma matriz de inteiros em uma matriz de objeto, você precisa executar a conversão antes de chamar o Format(String, Object[]) método.O exemplo a seguir fornece uma implementação.

using System;
using System.Collections.Generic;

public class Example
{
   public static void Main()
   {
      Random rnd = new Random();
      int[]  numbers = new int[4];
      int total = 0;
      for (int ctr = 0; ctr <= 2; ctr++) {
         int number = rnd.Next(1001);
         numbers[ctr] = number;
         total += number;
      }   
      numbers[3] = total;
      object[] values = new object[numbers.Length];
      numbers.CopyTo(values, 0);
      Console.WriteLine("{0} + {1} + {2} = {3}", values);   
   }
}
Retornar ao topo
Mostrar:
© 2016 Microsoft