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.

Viktigt!

I stället för att använda sammansatta formatsträngar kan du använda interpolerade strängar om språket och dess version som du använder stöder dem. En interpolerad sträng innehåller interpolerade uttryck. Varje interpolerat uttryck matchas med uttryckets värde och ingår i resultatsträngen när strängen tilldelas. Mer information finns i Stränginterpolation (C#-referens) och Interpolerade strängar (Visual Basic Reference).

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 för 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 objektet name, och {1:hh}, vars index på 1 motsvarar objektet DateTime.Now.

Formatera objektsyntax

Varje formatobjekt har följande formulär och består av följande komponenter:

{index[,alignment][:formatString]}

Matchande klammerparenteser ({ och }) krävs.

Indexkomponent

Den obligatoriska indexkomponenten , 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.

Justeringskomponent

Den valfria justeringskomponenten är ett signerat heltal som anger önskad formaterad fältbredd. Om värdet för justering är mindre än längden på den formaterade strängen ignoreras justeringen och längden på den formaterade strängen används som fältbredd. De formaterade data i fältet är högerjusterade om justeringen är positiv och vänsterjusterad om justeringen är negativ. Om utfyllnad krävs används tomt utrymme. Kommatecknet krävs om justering 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 har angetts används den allmänna formatspecificeraren ("G") för en numerisk typ, datum och tid eller uppräkningstyp. Kolonet krävs om formatString har angetts.

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 artiklarna och IFormattableICustomFormatter gränssnittet.

Typ eller typkategori	Gå till
Datum- och tidstyper (DateTime, DateTimeOffset)	Standardformatsträngar för datum och tid Anpassade formatsträngar för datum och tid
Uppräkningstyper (alla typer som härletts från System.Enum)	Uppräkningsformatsträngar
Numeriska typer (BigInteger, Byte, Decimal, Double, Int16, , Int64Int32, , SByte, Single, UInt16, UInt32, ) UInt64	Standardsträngar med numeriskt format Anpassade numeriska formatsträngar
Guid	Guid.ToString(String)
TimeSpan	Standard TimeSpan-formatsträngar Anpassade timeSpan-formatsträngar

Undfly klammerparenteser

Inledande och avslutande klammerparenteser tolkas som att ett formatobjekt startas och avslutas. 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.

.NET

Klammerparenteser kan undvikas 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 strängen literal, {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

Klammerparenteser i ett formatobjekt 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 numeriskt decimalformatsspecificerare, men de följande 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 strängen literal D}visas .
4. Den sista klammerparentesen (}) tolkas som slutet på formatobjektet.
5. Det slutliga resultatet som visas är strängen literal, {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 visar du alltså en literalöppningsparentes. I nästa åtgärd visar du resultatet av formatobjektet och i den sista åtgärden visar du en literalslutparentes. 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. Om metoden kan returnera en ICustomFormatter implementering cachelagras den under anropet av den sammansatta formateringsmetoden.

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örningen dess Format metod. Körningen skickar formatobjektets formatString värde (eller null om det inte finns) till metoden. Körningen skickar även 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 skickas formatString-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 IFormattable.ToString implementeringen om en sammansatt formateringsmetod anropas med ett IFormatProvider 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 finns Thursday May värdet för båda strängarna i föregående exempel i den amerikanska engelska kulturen.

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("{0:C}", myNumber);

// 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 användningen av justering 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
• Standardsträngar med numeriskt format
• Anpassade numeriska formatsträngar
• Standardformatsträngar för datum och tid
• Anpassade formatsträngar för datum och tid
• Standard TimeSpan-formatsträngar
• Anpassade timeSpan-formatsträngar
• Uppräkningsformatsträngar