Formattazione composta

Articolo
08/11/2011

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 myName dell'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 il valore di allineamento è positivo e a sinistra se il valore di allineamento è 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 standard o personalizzata se l'oggetto corrispondente è un valore numerico, una stringa di formato di data e ora standard o personalizzata 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.

Nota
Per un elenco di stringhe di formato numerico standard e personalizzate, vedere Stringhe di formato numerico standard e Stringhe di formato numerico personalizzate.Per un elenco di stringhe di formato di data e ora standard e personalizzate, vedere Stringhe di formato di data e ora standard e Stringhe di formato data e ora personalizzate.

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 annidate 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. Questo approccio viene illustrato nell'esempio seguente:

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}

Ordine di elaborazione

Ogni valore nell'elenco di parametri che corrisponde a un elemento di formato viene convertito in una stringa, attenendosi alla procedura dell'elenco seguente. Se una condizione qualsiasi nei primi tre passaggi è true, la rappresentazione in formato stringa del valore viene restituita in tale passaggio e i passaggi successivi non vengono eseguiti.

Se il valore da formattare è null, viene restituita una stringa vuota ("").
Se il metodo di formattazione composita include un parametro di tipo IFormatProvider che implementa anche l'interfaccia ICustomFormatter, il valore viene passato al metodo ICustomFormatter.Format.
Se il valore implementa l'interfaccia IFormattable, verrà chiamato il relativo metodo IFormattable.ToString.
Viene chiamato il metodo ToString del tipo, sottoposto a override o ereditato dalla classe Object.

L'allineamento viene applicato al termine dei precedenti passaggi.

Esempi di codice

Nell'esempio seguente vengono illustrate una stringa creata con la formattazione composita 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 sono specificate le impostazioni cultura Inglese (Stati Uniti).

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

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

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

Nell'esempio seguente 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)
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   |

Vedere anche

Condividi tramite