Formatação composta

O recurso de formatação composta do .NET usa uma lista de objetos e uma cadeia de caracteres de formato composto como entrada. Uma cadeia de caracteres de formato composto consiste em texto fixo misturado com espaços reservados indexados, chamados itens de formato. Esses itens de formato correspondem aos objetos na lista. A operação de formatação produz uma cadeia de caracteres de resultado que consiste no texto fixo original misturado com a representação de cadeia de caracteres dos objetos na lista.

Os seguintes métodos suportam o recurso de formatação composta:

• String.Format, que retorna uma cadeia de caracteres de resultado formatada.
• StringBuilder.AppendFormat, que acrescenta uma cadeia de caracteres de resultado formatada a um objeto StringBuilder.
• Algumas sobrecargas do método Console.WriteLine, que exibem uma string de resultado formatada no console.
• Algumas sobrecargas do método TextWriter.WriteLine, que gravam a cadeia de caracteres de resultado formatada em um fluxo ou arquivo. As classes derivadas de TextWriter, como StreamWriter e HtmlTextWriter, também compartilham essa funcionalidade.
• Debug.WriteLine(String, Object[]), que gera uma mensagem formatada para rastrear ouvintes.
• Os métodos Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[])e Trace.TraceWarning(String, Object[]), que produzem mensagens formatadas para rastrear ouvintes.
• O método TraceSource.TraceInformation(String, Object[]), que escreve um método informativo para rastrear ouvintes.

Cadeia de caracteres de formato composto

Uma cadeia de caracteres de formato composto e uma lista de objetos são usadas como argumentos de métodos que suportam o recurso de formatação composta. Uma cadeia de caracteres de formato composto consiste em zero ou mais segmentos de texto fixo intercalados com um ou mais elementos de formato. O texto fixo é qualquer cadeia de caracteres escolhida e cada item de formato corresponde a um objeto ou estrutura em caixa na lista. A representação de cadeia de caracteres de cada objeto substitui o item de formato correspondente.

Considere o seguinte fragmento de código Format:

string.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now);

String.Format("Name = {0}, hours = {1:hh}", "Fred", DateTime.Now)

O texto fixo é Name = e , hours = . Os itens de formato são {0}, cujo índice de 0 corresponde à cadeia de caracteres literal "Fred", e {1:hh}, cujo índice de 1 corresponde ao valor de DateTime.Now.

Sintaxe de item de formato

Cada item de formato assume a seguinte forma e consiste nos seguintes componentes:

{index[,width][:formatString]}

As chaves correspondentes ({ e }) são necessárias.

Componente de índice

O componente obrigatório index , que também é chamado de especificador de parâmetro, é um número a partir de 0 que identifica um item correspondente na lista de objetos. Ou seja, o item de formato cujo especificador de parâmetro é 0 formata o primeiro objeto da lista. O item de formato cujo especificador de parâmetro é 1 formata o segundo objeto na lista e assim por diante. O exemplo a seguir inclui quatro especificadores de parâmetros, numerados de zero a três, para representar números primos menores que 10:

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 2, 3, 5, 7

Vários itens de formato podem se referir ao mesmo elemento na lista de objetos especificando o mesmo especificador de parâmetro. Por exemplo, você pode formatar o mesmo valor numérico no formato hexadecimal, científico e numérico especificando uma cadeia de caracteres de formato composto, como "0x{0:X} {0:E} {0:N}", como mostra o exemplo a seguir:

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Cada item de formato pode referir-se a qualquer objeto na lista. Por exemplo, se houver três objetos, você poderá formatar o segundo, o primeiro e o terceiro objeto especificando uma cadeia de caracteres de formato composto como {1} {0} {2}. Um objeto que não é referenciado por um item de formato é ignorado. A FormatException é lançado em tempo de execução se um especificador de parâmetros designar um item fora dos limites da lista de objetos.

componente de largura

O componente opcional width é um inteiro assinado que indica a largura do campo formatado preferido. Se o valor de width for menor que o comprimento da cadeia de caracteres formatada, width será ignorado e o comprimento da cadeia de caracteres formatada será usado como a largura do campo. Os dados formatados no campo são alinhados à direita se width forem positivos e alinhados à esquerda se width forem negativos. Se o preenchimento for necessário, o espaço em branco é usado. A vírgula é necessária se width for especificada.

O exemplo a seguir define duas matrizes, uma contendo os nomes dos funcionários e a outra contendo as horas que eles trabalharam durante duas semanas. A cadeia de caracteres de formato composto alinha à esquerda os nomes em um campo de 20 caracteres e à direita alinha suas horas em um campo de 5 caracteres. A cadeia de caracteres de formato padrão "N1" formata as horas com um dígito fracionário.

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

Componente de formatação de cadeia de caracteres

O componente opcional formatString é uma cadeia de caracteres de formato apropriada para o tipo de objeto que está sendo formatado. Pode especificar:

• Uma cadeia de caracteres de formato numérico padrão ou personalizado se o objeto correspondente for um valor numérico.
• Uma cadeia de caracteres de formato de data e hora padrão ou personalizada se o objeto correspondente for um objeto DateTime.
• Uma cadeia de caracteres de formato de enumeração se o objeto correspondente for um valor de enumeração.

Se formatString não for especificado, o especificador de formato geral ("G") para um tipo numérico, de data e hora ou de enumeração será usado. Os dois pontos são necessários se formatString for especificado.

A tabela a seguir lista tipos ou categorias de tipos na biblioteca de classes .NET que oferecem suporte a um conjunto predefinido de cadeias de caracteres de formato e fornece links para os artigos que listam as cadeias de caracteres de formato suportadas. A formatação de cadeia de caracteres é um mecanismo extensível que torna possível definir novas cadeias de caracteres de formato para todos os tipos existentes e definir um conjunto de cadeias de caracteres de formato suportadas por um tipo definido pelo aplicativo.

Para obter mais informações, consulte os artigos IFormattable e ICustomFormatter interface.

Escape de chavetas

As chaves de abertura e fecho são interpretadas como iniciar e terminar um elemento de formatação. Para exibir uma chave de abertura ou de fechamento literal, deve-se usar uma sequência de escape. Especifique duas chaves de abertura ({{) no texto fixo para exibir uma chave de abertura ({), ou duas chaves de fechamento (}}) para exibir uma chave de fechamento (}).

As chaves com escape com um item de formato são analisadas de forma diferente entre o .NET e o .NET Framework.

.NET

As chaves podem ser escapadas em torno de um item de formato. Por exemplo, considere o item de formato {{{0:D}}}, que se destina a exibir uma chave de abertura, um valor numérico formatado como um número decimal e uma chave de fechamento. O item de formato é interpretado da seguinte maneira:

1. As duas primeiras chaves de abertura ({{) escapam e rendem uma chave de abertura.
2. Os três caracteres seguintes ({0:) são interpretados como o início de um item de formato.
3. O caractere seguinte (D) é interpretado como o especificador de formato numérico padrão decimal.
4. A chaveta seguinte (}) é interpretada como o fim do item de formatação.
5. As duas chaves de fechamento finais são escapadas e resultam numa única chave de fechamento.
6. O resultado final apresentado é a cadeia de caracteres literal, {6324}.

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework

Os colchetes num item de formato são interpretados na sequência na ordem em que são encontrados. Não há suporte para a interpretação de chaves aninhadas.

A forma como as chaves escapadas são interpretadas pode levar a resultados inesperados. Por exemplo, considere o item de formato {{{0:D}}}, que se destina a exibir uma chave de abertura, um valor numérico formatado como um número decimal e uma chave de fechamento. No entanto, o item de formato é interpretado da seguinte maneira:

1. As duas primeiras chaves de abertura ({{) escapam e rendem uma chave de abertura.
2. Os três caracteres seguintes ({0:) são interpretados como o início de um item de formato.
3. O próximo caractere (D) é interpretado como o especificador de formato numérico padrão para decimais, mas as duas chaves escapadas seguintes (}}) resultam em uma única chave. Como a cadeia de caracteres resultante (D}) não é um especificador de formato numérico padrão, a cadeia de caracteres resultante é interpretada como uma cadeia de caracteres de formato personalizado que significa exibir a cadeia de caracteres literal D}.
4. A última chave (}) é interpretada como o final do item de formato.
5. O resultado final apresentado é a cadeia de caracteres literal, {D}. O valor numérico que deveria ser formatado não é exibido.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

Uma maneira de escrever o seu código para evitar a interpretação incorreta de chaves e itens de formato escapados é formatar as chaves e os itens de formato separadamente. Ou seja, na primeira operação de formato, exibir uma chave de abertura literal. Na operação seguinte, exiba o resultado do item de formato e, na operação final, exiba uma chave de fechamento literal. O exemplo a seguir ilustra essa abordagem:

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}",
                                     "{", value, "}")
Console.WriteLine(output)

'The example displays the following output:
'      {6324}

Ordem de processamento

Se a chamada para o método de formatação composta incluir um argumento IFormatProvider cujo valor não é null, o tempo de execução chamará seu método IFormatProvider.GetFormat para solicitar uma implementação ICustomFormatter. Se o método puder retornar uma implementação ICustomFormatter, ele será armazenado em cache durante a chamada do método de formatação composta.

Cada valor na lista de parâmetros que corresponde a um item de formato é convertido em uma cadeia de caracteres da seguinte maneira:

1. Se o valor a ser formatado for null, uma cadeia de caracteres vazia String.Empty será retornada.

2. Se uma implementação ICustomFormatter estiver disponível, o tempo de execução invocará o seu método Format. O tempo de execução passa o valor do item de formatação formatString (ou null se formatString não estiver presente) para o método. O runtime também passa a implementação IFormatProvider para o método. Se a chamada para o método ICustomFormatter.Format retornar null, a execução prosseguirá para a próxima etapa. Caso contrário, o resultado da chamada ICustomFormatter.Format será retornado.

3. Se o valor implementa a interface IFormattable, o método ToString(String, IFormatProvider) da interface é chamado. Se um valor estiver presente no item de formato, o valor formatString é passado para o método. Caso contrário, null é aprovado. O argumento IFormatProvider é determinado da seguinte forma:

   • Para um valor numérico, se um método de formatação composto com um argumento IFormatProvider não nulo for chamado, o tempo de execução solicitará um objeto NumberFormatInfo de seu método IFormatProvider.GetFormat. Se não for possível fornecer um, se o valor do argumento for nullou se o método de formatação composta não tiver um parâmetro IFormatProvider, o objeto NumberFormatInfo para a cultura atual será usado.

   • Para um valor de data e hora, se for chamado um método de formatação composto com um argumento de IFormatProvider não nulo, o tempo de execução irá solicitar um objeto DateTimeFormatInfo através do método IFormatProvider.GetFormat. Nas situações seguintes, é utilizado o objeto DateTimeFormatInfo para a cultura atual:

     • O método IFormatProvider.GetFormat não consegue fornecer um objeto DateTimeFormatInfo.
     • O valor do argumento é null.
     • O método de formatação composta não tem um parâmetro IFormatProvider.

   • Para objetos de outros tipos, se um método de formatação composta for chamado com um argumento IFormatProvider, seu valor será passado diretamente para a implementação IFormattable.ToString. Caso contrário, null é passado para a implementação IFormattable.ToString.

4. O método sem parâmetros ToString do tipo, que substitui Object.ToString() ou herda o comportamento da sua classe base, é invocado. Nesse caso, a cadeia de caracteres de formato especificada pelo componente formatString no item de formato, se estiver presente, será ignorada.

O alinhamento é aplicado após a execução das etapas anteriores.

Exemplos de código

O exemplo a seguir mostra uma cadeia de caracteres criada usando formatação composta e outra criada usando o método ToString de um objeto. Ambos os tipos de formatação produzem resultados equivalentes.

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

Dim formatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim formatString2 As String = DateTime.Now.ToString("dddd MMMM")

Supondo que o dia atual seja uma quinta-feira de maio, o valor de ambas as strings no exemplo anterior é Thursday May na cultura anglo-americana.

Console.WriteLine expõe a mesma funcionalidade que String.Format. A única diferença entre os dois métodos é que String.Format retorna seu resultado como uma cadeia de caracteres, enquanto Console.WriteLine grava o resultado no fluxo de saída associado ao objeto Console. O exemplo a seguir usa o método Console.WriteLine para formatar o valor de myNumber para um valor de moeda:

int myNumber = 100;
Console.WriteLine($"{myNumber:C}");

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

O exemplo a seguir demonstra a formatação de vários objetos, incluindo a formatação de um objeto de duas maneiras diferentes:

string myName = "Fred";
Console.WriteLine(string.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now));

// Depending on the current time, the example displays output like the following:
//        Name = Fred, hours = 11, minutes = 30

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now))
'Depending on the current time, the example displays output Like the following:
'       Name = Fred, hours = 11, minutes = 30

O exemplo a seguir demonstra o uso da largura na formatação. Os argumentos formatados são colocados entre caracteres de barra vertical (|) para realçar o alinhamento resultante.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);

// The example displays the following output on a system whose current
// culture is en-US:
//     First Name = |      Fred|
//     Last Name =  |     Opals|
//     Price =      |   $100.00|
//
//     First Name = |Fred      |
//     Last Name =  |Opals     |
//     Price =      |$100.00   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)

'The example displays the following output on a system whose current
'culture Is en-US:
'    First Name = |      Fred|
'    Last Name =  |     Opals|
'    Price =      |   $100.00|
'
'    First Name = |Fred      |
'    Last Name =  |Opals     |
'    Price =      |$100.00   |

Ver também

• WriteLine
• String.Format
• Interpolação de cadeias de caracteres (C#)
• Interpolação de cadeia de caracteres (Visual Basic)
• Tipos de formatação
• Cadeias de caracteres de formato numérico padrão
• Cadeias de caracteres de formato numérico personalizado
• Cadeias de caracteres de formato de data e hora padrão
• Sequências de formato de data e hora personalizadas
• Cadeias de caracteres de formato TimeSpan padrão
• Cadeias de caracteres de formato TimeSpan personalizadas
• Cadeias de caracteres de formato de enumeração