Formatação Composta
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 no 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.Especifique uma sequência de formato numérico se o objeto correspondente é um valor numérico, uma sequência de caracteres de formato de data e hora se o objeto correspondente for um objeto DateTime, ou uma sequência de caracteres de formato de enumeração se o objeto correrspondente é 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.
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 sistema autônomo 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.
Ordem de processamento
Se o valor a ser formatado é Null ( Nothing no Visual Basic), uma sequência de caracteres vazia (" ") é retornada.
Se o tipo a ser formatado implementa a interface ICustomFormatter, o método ICustomFormatter.Format é chamado.
Se a etapa anterior não formata o tipo e o tipo implementa a interface IFormattable, o método IFormattable.ToString é chamado.
Se a etapa anterior não formata o tipo, o método ToString do tipo, que é herdado da classe Object, é chamado.
O alinhamento é aplicado depois das etapas anteriores terem sido executadas.
Exemplos de código
O exemplo a seguir mostra uma sequência de caracteres criada usando formatação composta e outra criada usando o método ToString de um objeto.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 corrente é uma quinta-feira em maio, o valor de ambas as seqüências no exemplo anterior é Thursday May nos EUA. Cultura em inglês.
Console.WriteLine expõe a mesma funcionalidade que String.Format .A única diferença entre os dois métodos é que String.Format retorna o resultado como uma sequência de caracteres, enquanto Console.WriteLine grava o resultado para o fluxo de saída associado ao objeto Console.O exemplo a seguir usa o método Console.WriteLine para formatar o valor de MyInt com um valor de moeda.
Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)
int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
Esse código exibe $100.00 no console em computadores que possuem Estados Unidos Inglês sistema autônomo a cultura corrente.
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"
String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
myName, DateTime.Now)
string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
myName, DateTime.Now);
A saída da sequência precedente é "Name = Fred, hours = 07, minutes = 23", onde esses números refletem a hora atual.
Os exemplos a seguir demonstram 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)
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)
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);
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);
O código anterior exibe o seguinte ao console nos EUA.Cultura em inglês.Diferentes culturas exibem símbolos de moeda diferente e separadores.
First Name = | Fred|
Last Name = | Opals|
Price = | $100.00|
First Name = |Fred |
Last Name = |Opals |
Price = |$100.00 |