Sammansatt formatering

Funktionen sammansatt formatering i .NET tar en lista över objekt och en sammansatt formatsträng som indata. En sammansatt formatsträng består av fast text som blandas med indexerade platshållare, så kallade formatobjekt. Dessa formatobjekt motsvarar objekten i listan. Formateringsåtgärden ger en resultatsträng som består av den ursprungliga fasta texten som blandas med strängrepresentationen av objekten i listan.

Följande metoder stöder funktionen för sammansatt formatering:

• String.Format, som returnerar en formaterad resultatsträng.
• StringBuilder.AppendFormat, som lägger till en formaterad resultatsträng i ett StringBuilder objekt.
• Vissa överlagringar av Console.WriteLine-metoden som visar en formaterad resultatsträng på konsolen.
• Vissa överlagringar av TextWriter.WriteLine-metoden, som skriver den formaterade resultatsträngen till en dataström eller fil. Klasserna som härleds från TextWriter, till exempel StreamWriter och HtmlTextWriter, delar även den här funktionen.
• Debug.WriteLine(String, Object[]), som matar ut ett formaterat meddelande till spårningslyssnare.
• Metoderna Trace.TraceError(String, Object[]), Trace.TraceInformation(String, Object[])och Trace.TraceWarning(String, Object[]) som matar ut formaterade meddelanden till spårningslyssnare.
• Metoden TraceSource.TraceInformation(String, Object[]) , som skriver en informationsmetod för att spåra lyssnare.

Sammansatt formatsträng

En sammansatt formatsträng och objektlista används som argument för metoder som stöder funktionen för sammansatt formatering. En sammansatt formatsträng består av noll eller flera körningar av fast text som blandas med ett eller flera formatobjekt. Den fasta texten är valfri sträng som du väljer, och varje formatobjekt motsvarar ett objekt eller en rutad struktur i listan. Strängrepresentationen för varje objekt ersätter motsvarande formatobjekt.

Överväg följande Format kodfragment:

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

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

Den fasta texten är Name = och , hours = . Formatobjekten är {0}, vars index på 0 motsvarar strängliteralen "Fred", och {1:hh}, vars index på 1 motsvarar värdet DateTime.Nowför .

Formatera objektsyntax

Varje formatobjekt har följande form och består av dessa komponenter:

{index[,width][:formatString]}

Matchande klammerparenteser ({ och }) krävs.

Indexkomponent

Den obligatoriska index komponenten, som även kallas parameterspecificerare, är ett tal från 0 som identifierar ett motsvarande objekt i listan över objekt. Det innebär att det formatobjekt vars parameterspecificerare 0 formaterar det första objektet i listan. Formatobjektet vars parameterspecificerare 1 formaterar det andra objektet i listan och så vidare. I följande exempel ingår fyra parameterspecificerare, numrerade noll till tre, för att representera primära tal som är mindre än 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

Flera formatobjekt kan referera till samma element i listan över objekt genom att ange samma parameterspecificerare. Du kan till exempel formatera samma numeriska värde i hexadecimalt, vetenskapligt och talformat genom att ange en sammansatt formatsträng som "0x{0:X} {0:E} {0:N}", som följande exempel visar:

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

Varje formatobjekt kan referera till valfritt objekt i listan. Om det till exempel finns tre objekt kan du formatera det andra, första och tredje objektet genom att ange en sammansatt formatsträng som {1} {0} {2}. Ett objekt som inte refereras till av ett formatobjekt ignoreras. En FormatException genereras vid körning om en parameterspecificerare anger ett objekt utanför gränserna för listan över objekt.

Breddkomponent

Den valfria width komponenten är ett signerat heltal som anger önskad formaterad fältbredd. Om värdet width för är mindre än längden på den formaterade strängen width ignoreras och längden på den formaterade strängen används som fältbredd. De formaterade data i fältet är högerjusterade om width de är positiva och vänsterjusterade om width de är negativa. Om utfyllnad krävs används tomt utrymme. Kommatecknet krävs om width anges.

I följande exempel definieras två matriser, en som innehåller namnen på anställda och den andra som innehåller de timmar de arbetade under två veckor. Den sammansatta formatsträngen vänsterjusterar namnen i ett fält med 20 tecken och högerjusterar deras timmar i ett fält med 5 tecken. Standardformatsträngen "N1" formaterar timmarna med en bråktalssiffra.

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

Formatera strängkomponent

Den valfria formatString komponenten är en formatsträng som är lämplig för den typ av objekt som formateras. Du kan ange:

• En standard- eller anpassad numerisk formatsträng om motsvarande objekt är ett numeriskt värde.
• En standard- eller anpassad datum- och tidsformatsträng om motsvarande objekt är ett DateTime objekt.
• En uppräkningsformatsträng om motsvarande objekt är ett uppräkningsvärde.

Om formatString inte anges används den allmänna formatspecificeraren ("G") för en numerisk typ, datum och tid eller uppräkningstyp. Kolonet krävs om formatString anges.

I följande tabell visas typer eller kategorier av typer i .NET-klassbiblioteket som stöder en fördefinierad uppsättning formatsträngar och innehåller länkar till de artiklar som visar de formatsträngar som stöds. Strängformatering är en utökningsbar mekanism som gör det möjligt att definiera nya formatsträngar för alla befintliga typer och definiera en uppsättning formatsträngar som stöds av en programdefinierad typ.

Mer information finns i gränssnittsartiklarna IFormattable och ICustomFormatter.

Escape klammerparenteser

Inledande och avslutande klammerparenteser tolkas som att ett formatobjekt börjar och slutar. Om du vill visa en inledande klammerparentes eller avslutande klammerparentes måste du använda en escape-sekvens. Ange två inledande klammerparenteser ({{) i den fasta texten för att visa en inledande klammerparentes ({) eller två avslutande klammerparenteser (}}) för att visa en avslutande klammerparentes (}).

Undantagna klammerparenteser med ett formatobjekt parsas på olika sätt mellan .NET och .NET Framework.

.NÄT

Klamrar kan användas runt ett formatobjekt. Tänk till exempel på formatobjektet {{{0:D}}}, som är avsett att visa en inledande klammerparentes, ett numeriskt värde formaterat som ett decimaltal och en avslutande klammerparentes. Formatobjektet tolkas på följande sätt:

1. De två första inledande klammerparenteserna ({{) är undantagna och ger en inledande klammerparentes.
2. De följande tre tecknen ({0:) tolkas som början på ett formatobjekt.
3. Nästa tecken (D) tolkas som numeriskt decimalformatsspecificerare.
4. Nästa klammerparentes (}) tolkas som slutet på formatobjektet.
5. De sista två avslutande klammerparenteserna är undantagna och ger en avslutande klammerparentes.
6. Det slutliga resultatet som visas är den bokstavliga strängen {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

Klamrar i ett formateringselement tolkas sekventiellt i den ordning de påträffas. Det går inte att tolka kapslade klammerparenteser.

Det sätt som undantagna klammerparenteser tolkas på kan leda till oväntade resultat. Tänk till exempel på formatobjektet {{{0:D}}}, som är avsett att visa en inledande klammerparentes, ett numeriskt värde formaterat som ett decimaltal och en avslutande klammerparentes. Formatobjektet tolkas dock på följande sätt:

1. De två första inledande klammerparenteserna ({{) är undantagna och ger en inledande klammerparentes.
2. De följande tre tecknen ({0:) tolkas som början på ett formatobjekt.
3. Nästa tecken (D) tolkas som den numeriska decimalformatsspecificeraren, men de nästa två undantagna klammerparenteserna (}}) ger en enda klammerparentes. Eftersom den resulterande strängen (D}) inte är en numerisk standardformatsspecificerare tolkas den resulterande strängen som en anpassad formatsträng som innebär att den bokstavliga strängen D} visas.
4. Den sista klammerparentesen (}) tolkas som slutet på formatobjektet.
5. Det slutliga resultatet som visas är den bokstavliga strängen {D}. Det numeriska värde som skulle formateras visas inte.

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}

Ett sätt att skriva koden för att undvika feltolkning av undantagna klammerparenteser och formatera objekt är att formatera klammerparenteser och formatera objekt separat. I den första formatåtgärden visas en bokstavlig öppningsklammer. I nästa åtgärd visar du resultatet av formateringsobjektet och i den sista åtgärden visar du en bokstavlig slutklammer. Följande exempel illustrerar den här metoden:

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}

Bearbetningsordning

Om anropet till den sammansatta formateringsmetoden innehåller ett IFormatProvider argument vars värde inte nullär anropar runtime metoden IFormatProvider.GetFormat för att begära en ICustomFormatter implementering. Under anropet av den sammansatta formateringsmetoden cachelagras implementeringen ICustomFormatter om metoden kan returnera den.

Varje värde i parameterlistan som motsvarar ett formatobjekt konverteras till en sträng enligt följande:

1. Om värdet som ska formateras är nullreturneras en tom sträng String.Empty .

2. Om en ICustomFormatter implementering är tillgänglig anropar körtiden dess Format metod. Körningen skickar formatobjektets formatString värde (eller null om det inte finns) till metoden. Körtiden skickar också implementeringen IFormatProvider till metoden. Om anropet till ICustomFormatter.Format metoden returnerar nullfortsätter körningen till nästa steg. Annars returneras resultatet av anropet ICustomFormatter.Format .

3. Om värdet implementerar IFormattable gränssnittet anropas gränssnittets ToString(String, IFormatProvider) metod. Om en finns i formatobjektet formatString skickas värdet till metoden. Annars null skickas. Argumentet IFormatProvider bestäms på följande sätt:

   • Om en sammansatt formateringsmetod med ett argument som inte är null IFormatProvider anropas för ett numeriskt värde begär körningen ett NumberFormatInfo objekt från dess IFormatProvider.GetFormat metod. Om det inte går att ange en, om värdet för argumentet är null, eller om den sammansatta formateringsmetoden inte har någon IFormatProvider parameter, NumberFormatInfo används objektet för den aktuella kulturen.

   • För ett datum- och tidsvärde, om en sammansatt formateringsmetod med ett argument som inte är null IFormatProvider anropas, begär körningen ett DateTimeFormatInfo objekt från dess IFormatProvider.GetFormat -metod. I följande situationer DateTimeFormatInfo används objektet för den aktuella kulturen i stället:

     • Metoden IFormatProvider.GetFormat kan inte ange ett DateTimeFormatInfo objekt.
     • Värdet för argumentet är null.
     • Den sammansatta formateringsmetoden har IFormatProvider ingen parameter.

   • För objekt av andra typer skickas dess värde direkt till IFormatProvider implementeringen om en sammansatt formateringsmetod anropas med ett IFormattable.ToString argument. Annars null skickas till implementeringen IFormattable.ToString .

4. Typens parameterlösa ToString metod, som antingen åsidosätter Object.ToString() eller ärver beteendet för basklassen, anropas. I det här fallet ignoreras formatsträngen som anges av komponenten formatString i formatobjektet, om den finns.

Justeringen tillämpas när föregående steg har utförts.

Kodexempel

I följande exempel visas en sträng som skapats med sammansatt formatering och en annan som skapats med hjälp av ett objekts ToString metod. Båda formateringstyperna ger motsvarande resultat.

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

Om vi antar att den aktuella dagen är en torsdag i maj, är värdet på båda strängarna i det föregående exemplet Thursday May i amerikansk engelskspråkig kultur.

Console.WriteLine exponerar samma funktioner som String.Format. Den enda skillnaden mellan de två metoderna är att String.Format returnera resultatet som en sträng, medan Console.WriteLine resultatet skrivs till utdataströmmen som är associerad med Console objektet. I följande exempel används Console.WriteLine metoden för att formatera värdet myNumber för till ett valutavärde:

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

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

I följande exempel visas formatering av flera objekt, inklusive formatering av ett objekt på två olika sätt:

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

I följande exempel visas hur bredd används i formateringen. Argumenten som är formaterade placeras mellan lodräta stapeltecken (|) för att markera den resulterande justeringen.

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   |

Se även

• WriteLine
• String.Format
• Stränginterpolation (C#)
• Stränginterpolation (Visual Basic)
• Formateringstyper
• Standardnumeriska formatsträngar
• Anpassade numeriska formatsträngar
• Standardformatsträngar för datum och tid
• Anpassade formatsträngar för datum och tid
• Standardformatsträngar för TimeSpan
• Anpassade TimeSpan-formatsträngar
• Uppräkningsformatsträngar