Formatação Composta

Artigo
08/01/2011

O recurso de Formatação composta do .NET Framework utiliza uma lista de objetos e uma sequência de caracteres de formato composto como entrada. Uma sequência de caracteres de formato composto consiste de um texto fixo misturado com espaços reservados indexados, chamados de itens de formato, que correspondem aos objetos na lista. A operação de formatação produz uma sequência de resultado que consiste no texto fixo original misturado com as representação de sequência de caracteres dos objetos na lista.

O recuros de formatação composta recebe suporte por métodos como Format, AppendFormat e alguns sobrecargas de WriteLine e TextWriter.WriteLine. O método String.Format produz uma sequência de resultado formatada, o método AppendFormat acrescenta uma sequência de resultado formatada a um objeto StringBuilder, os métodos Console.WriteLine exibem a sequência de resultado formatada no console, e o método TextWriter.WriteLine grava a sequência de resultado formatada em um fluxo ou arquivo.

Sequência de caracteres de formato composto

Uma sequência de formato composto e uma lista de objetos são usados como argumentos dos métodos que oferecem suporte ao recurso de formatação composta. Uma sequência de caracteres de formato conspoto consiste de zero ou mais execuções de texto fixo misturado com um ou mais itens de formato. O texto fixo é qualquer sequência de caracteres que você escolher, e cada item de formato corresponde a um objeto ou a uma estrutura embutida na lista. O recurso de Formatação composta retorna uma nova sequência de resultado onde cada item de formato é substituído pela representação de sequência de caracteres do objeto correspondente na lista.

Considere o fragmento de código a seguir Format.

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

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

O texto fixo é "Name = " e ", hours = ". Os itens de formato são "{0}", cujo índice é 0, que corresponde ao objeto myName e "{1:hh}", cujo índice é 1, que corresponde ao objeto DateTime.Now.

Sintaxe de item de formato

Cada item de formato pega o formulário a seguir e consiste nos seguintes componentes:

{Índice [, Alinhamento ] [: formatString ]}

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

Componente de índice

O componente Index obrigatório, também chamado de especificador de parâmetro, é um número começando 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 na lista, o item de formato cujo especificador de parâmetro é 1 formata o segundo objeto na lista e assim por diante.

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 em formato hexadecimal, científico e número, especificando uma seqüência de caracteres de formato composto como este: "{0: X} {0:E} {0: N}".

Cada item de formato pode fazer referência a qualquer objeto na lista. Por exemplo, se houver três objetos, você pode formatar a segunda, primeiro, e terceiro objeto especificando uma seqüência de caracteres de formato composto como este: "{1} {0} {2}". Um objeto que não é referenciado por um item de formato será ignorado. Uma exceção de tempo de execução é lançada se um especificador de parâmetro designa um item fora dos limites da lista de objetos.

Alinhamento de componente

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

Componentes de sequência de caracteres de formato

O componente opcional formatString é uma sequência de caracteres de formato que é apropriada para o tipo de objeto que está sendo formatado. Especificar uma seqüência de caracteres de formato numérico de padrão ou personalizados se o objeto correspondente é um valor numérico, padrão ou personalizada de data e hora formatar seqüência se o objeto correspondente é um DateTime o objeto, ou um seqüência de formato de enumeração se o objeto correspondente é um valor de enumeração. Se formatString não for especificado, será usado o especificador de formato geral ("G") para um tipo numérico, data e hora ou de enumeração. Os dois-pontos são necessários se formatString for especificada.

Observação

Para obter uma lista de seqüências de caracteres de formato numérico de padrão e personalizados, consulte Sequências de Caracteres de Formato Numérico Padrão e Sequências de Caracteres de Formato Numérico Personalizado.Para obter uma lista de data padrão e seqüências de formato de hora, consulte Sequências de caracteres de formato padrão de data e hora e Sequências de Caracteres de Formato Personalizado de Data e Hora.

Chaves de Escape

Abrir e Fechar chaves são interpretados como início e fim de um item formato. Consequentemente, você deve usar uma sequência de escape para exibir um abrir chave ou fechar chave literal. 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 ("}"). Chaves em um item de formato são interpretadas sequencialmente na ordem que são encontrados. Não há suporte para interpretar chaves aninhadas.

A maneira com que as chaves são interpretadas pode levar a resultados inesperados. Por exemplo, considere o item de formato "{{{0:D}}}", que é destinado 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 é realmente interpretado da seguinte maneira:

As duas primeiras chaves de abertura (" {{") são escapadas e produzem uma chave de abertura.
Os próximos três caracteres ("{0:") são interpretados como o início de um item de formato.
O próximo caractere ("D") deve ser interpretado como o especificador de formato numérico decimal padrão, mas as próximas duas chaves de escape ("}} ") produzem uma única chave. Como a sequência resultante de caracteres ("D}") não é um especificador de formato numérico padrão, a sequência de caracteres resultante é interpretada como uma sequência de formato personalizado que significa exibir a sequência literal "D}".
A última chave ("}") é interpretada como final do item de formato.
O resultado final que é exibido é a sequência literal, "{D}". O valor numérico que estava para ser formatado não é exibido.

Uma maneira para escrever o código para evitar má interpretação chaves de escape e itens de formato é formatar as chaves e itens de formato separadamente. Isto é, na primeira operação de formato exibe uma chave literal de abertura, na próxima operação exibe o resultado do item de formato, em seguida, na operação final exibe uma chave de fechamento literal. O exemplo a seguir ilustra essa abordagem.

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}

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Ordem de processamento

Cada valor na lista de parâmetros que corresponde a um item de formato é convertido em uma seqüência, executando as etapas na seguinte lista. Se qualquer condição em que as três primeiras etapas for true, a representação de seqüência de caracteres do valor é retornada na etapa e etapas subseqüentes não serão executadas.

Se o valor a ser formatada for null, uma seqüência vazia ("") é retornado.
Se o método de formatação de composição inclui um parâmetro do tipo IFormatProvider que também implementa o ICustomFormatter interface, o valor é passado para o ICustomFormatter.Format método.
Se o valor implementa o IFormattable interface, sua IFormattable.ToString método é chamado.
O tipo ToString método, que pode é substituído ou herdado da Object da classe, que é chamado.

O alinhamento é aplicado depois das etapas anteriores terem sido executadas.

Exemplos de código

O exemplo a seguir mostra uma seqüência de caracteres criada usando a formatação composto e outro criados usando um objeto ToString método. Os dois tipos de formatação produzem resultados equivalentes.

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

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");

Supondo que o dia atual é uma quinta-feira em maio, o valor de ambas as seqüências de caracteres no exemplo anterior é Thursday May nos EUA. Cultura em inglês.

Console.WriteLineexpõe a mesma funcionalidade que String.Format. A única diferença entre os dois métodos é que String.Format retorna o resultado como uma seqüência de caracteres, enquanto Console.WriteLine grava o resultado para o fluxo de saída associado a Console objeto. O exemplo a seguir usa a Console.WriteLine método para formatar o valor de MyInt para um valor de moeda.

Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)
' The example displays the following output
' if en-US is the current culture:
'        $100.00

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
// 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 formatação de um objeto de duas maneiras diferentes.

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

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

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

Dim myFName As String = "Fred"
Dim myLName As String = "Opals"

Dim myInt As Integer = 100
Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
Dim FormatPrice As String = String.Format("Price = |{0,10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
Console.WriteLine()

FormatFName = String.Format("First Name = |{0,-10}|", myFName)
FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
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   |

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt); 
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
Console.WriteLine();

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
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   |