Partilhar via

Formatação composta

  • Artigo

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.

Importante

Em vez de usar cadeias de caracteres de formato composto, você pode usar cadeias de caracteres interpoladas se o idioma e sua versão que você está usando oferecer suporte a elas. Uma cadeia de caracteres interpolada contém expressões interpoladas. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres de resultado quando a cadeia de caracteres é atribuída. Para obter mais informações, consulte Interpolação de cadeia de caracteres (referência C#) e Cadeias de caracteres interpoladas (referência do Visual Basic).

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

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 execuções de texto fixo misturado com um ou mais itens 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 Format fragmento de código:

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 ao objeto name, e {1:hh}, cujo índice de 1 corresponde ao objeto DateTime.Now.

Sintaxe do item de formato

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

{index[,alignment][:formatString]}

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

Componente de índice

O componente de índice obrigatório, 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 , como "0x{0:X} {0:E} {0:N}"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âmetro designa um item fora dos limites da lista de objetos.

Componente de alinhamento

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

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 Formatar 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 DateTime objeto.
  • 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 e IFormattableICustomFormatter interface.

Tipo ou categoria de tipo Consulte
Tipos de data e hora (DateTime, DateTimeOffset) Cadeias de Formato de Data e Hora Padrão

Cadeias de Formato de Data e Hora Personalizadas
Tipos de enumeração (todos os tipos derivados de System.Enum) Cadeias de caracteres de formato de enumeração
Tipos numéricos (, , , , , Int16Int32, , Int64SByte, , Single, UInt16UInt64UInt32, ) DoubleDecimalByteBigInteger Standard Numeric Format Strings (Cadeias de Formato Numérico Padrão)

Cadeias de caracteres de formato numérico personalizado
Guid Guid.ToString(String)
TimeSpan Cadeias de caracteres de formato TimeSpan padrão

Cadeias de caracteres de formato TimeSpan personalizadas

Chaves de fuga

As chaves de abertura e fechamento são interpretadas como iniciar e terminar um item de formato. Para exibir uma chave de abertura ou de fechamento literal, você deve 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 {{{0:D}}}de formato , 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 próximos três caracteres ({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 chave seguinte (}) é interpretada como o fim do item de formato.
  5. As duas chaves de fechamento finais são escapadas e rendem uma chave de fechamento.
  6. O resultado final exibido é 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

As chaves em um item de formato são interpretadas sequencialmente na ordem em que são encontradas. Não há suporte para a interpretação de chaves aninhadas.

A forma como os aparelhos escapados são interpretados pode levar a resultados inesperados. Por exemplo, considere o item {{{0:D}}}de formato , 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 próximos três caracteres ({0:) são interpretados como o início de um item de formato.
  3. O próximo caractere (D) seria interpretado como o especificador de formato numérico padrão decimal, mas as duas chaves seguintes escapadas (}}) produzem 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 D}literal.
  4. A última chave (}) é interpretada como o fim do item de formato.
  5. O resultado final exibido é 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 seu código para evitar interpretações incorretas de chaves e itens de formato escapados é formatar as chaves e formatar itens 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 IFormatProvider argumento cujo valor não nullé, o tempo de execução chamará seu IFormatProvider.GetFormat método para solicitar uma ICustomFormatter implementação. Se o método puder retornar uma ICustomFormatter implementação, 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 String.Empty vazia será retornada.

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

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

  4. O método sem ToString parâmetros do tipo, que substitui Object.ToString() ou herda o comportamento de sua classe base, é chamado. Nesse caso, a cadeia de caracteres de formatString formato especificada pelo componente 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 de ToString 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 está Thursday May na cultura inglesa dos EUA.

Console.WriteLine expõe a mesma funcionalidade que String.Formato . 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 Console objeto. O exemplo a seguir usa o Console.WriteLine método para formatar o valor de para um valor de myNumber moeda:

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

// 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 do alinhamento 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   |

Consulte também