Formattazione composta

Articolo
08/22/2007

La funzionalità di formattazione composta di .NET Framework consente di utilizzare come input un elenco di oggetti e una stringa di formato composto. Una stringa di formato composto è costituita da testo fisso alternato a segnaposto indicizzati, denominati elementi di formato, che corrispondono agli oggetti dell'elenco. L'operazione di formattazione produce una stringa risultato costituita dal testo fisso originale alternato alla rappresentazione di stringa degli oggetti dell'elenco.

La funzionalità di formattazione composta è supportata da metodi quali Format, AppendFormat e da alcuni overload di WriteLine e TextWriter.WriteLine. Il metodo String.Format produce una stringa risultato formattata, il metodo AppendFormat aggiunge una stringa risultato formattata a un oggetto StringBuilder, i metodi Console.WriteLine visualizzano la stringa risultato formattata nella console e il metodo TextWriter.WriteLine scrive la stringa risultato formattata in un flusso o in un file.

Stringa di formato composto

Una stringa di formato composto e un elenco di oggetti vengono utilizzati come argomenti di metodi che supportano la funzionalità di formattazione composta. Una stringa di formato composto è costituita da zero o più esecuzioni di testo fisso alternate a uno o più elementi di formato. Il testo fisso corrisponde a una stringa di propria scelta e ogni elemento di formato corrisponde a un oggetto o una struttura boxed dell'elenco. La funzionalità di formattazione composta restituisce una nuova stringa risultato in cui ciascun elemento di formato viene sostituito dalla rappresentazione di stringa di origine dell'oggetto corrispondente dell'elenco.

Si consideri il frammento di codice Format riportato di seguito.

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);

Il testo fisso è "Name = " e ", hours = ". Gli elementi di formato sono "{0}", il cui indice è 0, che corrisponde all'elemento myNamedell'oggetto, e "{1:hh}", il cui indice è 1, che corrisponde all'elemento DateTime.Now dell'oggetto.

Sintassi degli elementi di formato

Ogni elemento di formato utilizza il formato seguente ed è costituito dai componenti riportati di seguito:

{ indice[,allineamento][:StringaFormato]}

Le parentesi graffe corrispondenti "{" e "}" sono obbligatorie.

Componente di indice

Il componente obbligatorio indice, denominato anche identificatore di parametro, corrisponde a un numero a partire da 0 che identifica un elemento corrispondente nell'elenco di oggetti. Con l'elemento di formato con identificatore di parametro 0 viene formattato il primo oggetto dell'elenco, con l'elemento di formato con identificatore di parametro 1 viene formattato il secondo oggetto dell'elenco e così via.

Più elementi di formato possono fare riferimento allo stesso elemento dell'elenco di oggetti specificando lo stesso identificatore di parametro. È ad esempio possibile formattare lo stesso valore numerico in formato esadecimale, scientifico e numerico specificando una stringa di formato composto "{0:X} {0:E} {0:N}".

Ogni elemento di formato può fare riferimento a un oggetto dell'elenco. Se ad esempio sono presenti tre oggetti, è possibile formattare il secondo, il primo e il terzo oggetto specificando una stringa di formato composto "{1} {0} {2}". Gli oggetti a cui non fa riferimento un elemento di formato vengono ignorati. Se un identificatore di parametro corrisponde a un elemento non incluso nei limiti dell'elenco di oggetti, verrà generata un'eccezione in fase di esecuzione.

Componente di allineamento

Il componente facoltativo allineamento corrisponde a un valore integer con segno che indica la larghezza preferita del campo formattato. Se il valore di allineamento è inferiore alla lunghezza della stringa formattata, il componente allineamento verrà ignorato e come larghezza del campo verrà utilizzata la lunghezza della stringa. I dati formattati verranno allineati a destra se allineamento è un valore positivo e a sinistra se è negativo. Per la spaziatura eventualmente necessaria verranno utilizzati spazi vuoti. Se viene specificato il componente allineamento, la virgola è obbligatoria.

Componente della stringa di formato

Il componente StringaFormato facoltativo è una stringa di formato appropriata per il tipo di oggetto formattato. Specificare una stringa di formato numerico se l'oggetto corrispondente è un valore numerico, una stringa di formato di data e ora se l'oggetto corrispondente è un oggetto DateTime o una stringa di formato di enumerazione se l'oggetto corrispondente è un valore di enumerazione. Se il componente StringaFormato viene omesso, verrà utilizzato l'identificatore di formato generale "G" per un tipo numerico, di data e ora o di enumerazione. Se viene specificato il componente StringaFormato, i due punti sono obbligatori.

Sequenze di escape delle parentesi graffe

Le parentesi graffe di apertura e di chiusura sono interpretate come l'inizio e la fine di un elemento di formato. Di conseguenza, è necessario utilizzare una sequenza di escape per visualizzare una parentesi graffa di apertura o di chiusura letterale. Specificare due parentesi graffe di apertura ("{{") nel testo fisso per visualizzare una parentesi di apertura ("{") oppure due parentesi graffe di chiusura ("}}") per visualizzare una parentesi graffa di chiusura ("}"). Le parentesi graffe in un elemento di formato vengono interpretate sequenzialmente nell'ordine in cui sono rilevate. L'interpretazione delle parentesi graffe nidificate non è supportata.

Il tipo di interpretazione delle parentesi graffe in sequenza di escape può produrre risultati imprevisti. Si consideri, ad esempio, l'elemento di formato "{{{0:D}}}", destinato alla visualizzazione di una parentesi graffa di apertura, un valore numerico formattato come numero decimale e una parentesi graffa di chiusura. L'elemento di formato viene tuttavia interpretato nel modo seguente:

Le prime due parentesi apertura ("{{") presentano una sequenza di escape e producono una parentesi graffa di apertura.
I tre caratteri successivi ("{0:") sono interpretati come l'inizio di un elemento di formato.
Il carattere successivo ("D") verrebbe interpretato come identificatore del formato numerico standard Decimal, ma le due parentesi graffe successive con sequenza di escape ("}}") producono una parentesi graffa singola. Poiché la stringa risultante ("D}") non è un identificatore di un formato numerico standard, viene interpretata come una stringa di formato personalizzata che indica la visualizzazione della stringa letterale "D}".
L'ultima parentesi graffa ("}") viene interpretata come la fine dell'elemento di formato.
Il risultato finale visualizzato è la stringa letterale "{D}". Il valore numerico da formattare non viene visualizzato.

Per evitare di interpretare in modo errato gli elementi di formato e le parentesi graffe con sequenza di escape, è preferibile formattarli separatamente, ovvero nella prima operazione di formattazione visualizzare una parentesi graffa di apertura letterale, nella successiva operazione visualizzare il risultato dell'elemento di formato, quindi nell'ultima operazione visualizzare una parentesi graffa di chiusura letterale.

Ordine di elaborazione

Se il valore da formattare è null (Nothing in Visual Basic), verrà restituita una stringa vuota ("").

Se il tipo da formattare implementa l'interfaccia ICustomFormatter, verrà chiamato il metodo ICustomFormatter.Format.

Se il tipo non viene formattato con il passaggio precedente e implementa l'interfaccia IFormattable, verrà chiamato il metodo IFormattable.ToString.

Se nel passaggio precedente non viene eseguita la formattazione del tipo, verrà chiamato il metodo ToString del tipo, ereditato dalla classe Object.

L'allineamento viene applicato al termine dei precedenti passaggi.

Esempi di codice

Nell'esempio riportato di seguito vengono illustrate una stringa creata con la formattazione composta e un'altra creata mediante il metodo ToString di un oggetto. Entrambi i tipi di formattazione producono risultati equivalenti.

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");

Presupponendo che il giorno corrente sia un giovedì di maggio, il valore di entrambe le stringhe dell'esempio precedente sarà Thursday May se è impostata la lingua inglese.

Console.WriteLine espone la stessa funzionalità di String.Format. L'unica differenza tra i due metodi è che String.Format restituisce il risultato ottenuto come stringa, mentre Console.WriteLine scrive il risultato nel flusso di output associato all'oggetto Console. Nell'esempio riportato di seguito viene utilizzato il metodo Console.WriteLine per formattare il valore di MyInt come valuta.

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

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

Con questo codice viene visualizzato $100.00 alla console sui computer nei quali è impostato l'italiano come lingua corrente.

Nell'esempio riportato di seguito vengono illustrate la formattazione di più oggetti e la formattazione di un oggetto in due diversi modi.

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);

L'output della stringa precedente è "Name = Fred, hours = 07, minutes = 23", dove i numeri indicano l'ora corrente.

Negli esempi riportati di seguito viene illustrato l'utilizzo dell'allineamento nella formattazione. Gli argomenti formattati sono inseriti tra barre verticali (|) per evidenziare l'allineamento ottenuto.

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);

Con il codice precedente verrà visualizzato quanto segue alla console, se è impostata la lingua italiana. Per le diverse lingue vengono visualizzati separatori e simboli di valuta differenti.

First Name = |          Fred|
Last Name = |         Opals|
Price = |           $100.00|
First Name = |Fred      |
Last Name = |Opals     |
Price = |$100.00   |

Vedere anche