Samengestelde opmaak

  • Artikel

De functie voor samengestelde .NET-opmaak neemt een lijst met objecten en een tekenreeks met samengestelde opmaak als invoer. Een tekenreeks met samengestelde notatie bestaat uit vaste tekst die is gemengd met geïndexeerde tijdelijke aanduidingen, ook wel opmaakitems genoemd. Deze opmaakitems komen overeen met de objecten in de lijst. De opmaakbewerking levert een resultaattekenreeks op die bestaat uit de oorspronkelijke vaste tekst die is gemengd met de tekenreeksweergave van de objecten in de lijst.

Belangrijk

In plaats van samengestelde notatietekenreeksen te gebruiken, kunt u geïnterpoleerde tekenreeksen gebruiken als de taal en de bijbehorende versie die u gebruikt, deze ondersteunen. Een geïnterpoleerde tekenreeks bevat geïnterpoleerde expressies. Elke geïnterpoleerde expressie wordt opgelost met de waarde van de expressie en opgenomen in de resultaattekenreeks wanneer de tekenreeks wordt toegewezen. Zie Tekenreeksinterpolatie (C#-verwijzing) en geïnterpoleerde tekenreeksen (Visual Basic Reference) voor meer informatie.

De volgende methoden ondersteunen de functie voor samengestelde opmaak:

Tekenreeks voor samengestelde opmaak

Een tekenreeks en objectlijst met samengestelde opmaak worden gebruikt als argumenten van methoden die ondersteuning bieden voor de functie voor samengestelde opmaak. Een tekenreeks met samengestelde notatie bestaat uit nul of meer uitvoeringen van vaste tekst die is gemengd met een of meer opmaakitems. De vaste tekst is een tekenreeks die u kiest en elk opmaakitem komt overeen met een object of een vakkenstructuur in de lijst. De tekenreeksweergave van elk object vervangt het bijbehorende opmaakitem.

Bekijk het volgende Format codefragment:

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

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

De vaste tekst is Name = en , hours = . De notatieitems zijn {0}, waarvan de index van 0 overeenkomt met het object nameen {1:hh}, waarvan de index van 1 overeenkomt met het object DateTime.Now.

Syntaxis van item opmaken

Elk opmaakitem heeft de volgende vorm en bestaat uit de volgende onderdelen:

{index[,alignment][:formatString]}

De overeenkomende accolades ({ en }) zijn vereist.

Indexonderdeel

Het verplichte indexonderdeel , dat ook wel een parameteraanduiding wordt genoemd, is een getal dat begint bij 0 waarmee een bijbehorend item in de lijst met objecten wordt geïdentificeerd. Dat wil gezegd: het indelingsitem waarvan de parameteraanduiding het 0 eerste object in de lijst opmaken. Het opmaakitem waarvan de parameteraanduiding het 1 tweede object in de lijst opmaken, enzovoort. Het volgende voorbeeld bevat vier parameteraanduidingen, genummerd nul tot en met drie, om priemgetallen kleiner dan 10 weer te geven:

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

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

Items met meerdere indelingen kunnen verwijzen naar hetzelfde element in de lijst met objecten door dezelfde parameteraanduiding op te geven. U kunt bijvoorbeeld dezelfde numerieke waarde opmaken in hexadecimale, wetenschappelijke en getalnotatie door een tekenreeks voor samengestelde notatie op te geven, zoals "0x{0:X} {0:E} {0:N}"in het volgende voorbeeld wordt weergegeven:

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

Elk opmaakitem kan verwijzen naar elk object in de lijst. Als er bijvoorbeeld drie objecten zijn, kunt u het tweede, eerste en derde object opmaken door een tekenreeks met samengestelde opmaak op te geven, zoals {1} {0} {2}. Een object waarnaar niet wordt verwezen door een opmaakitem, wordt genegeerd. Een FormatException wordt gegenereerd tijdens runtime als een parameteraanduiding een item aanwijst buiten de grenzen van de lijst met objecten.

Uitlijningsonderdeel

Het optionele uitlijningsonderdeel is een ondertekend geheel getal dat de gewenste breedte van het veld aangeeft. Als de waarde van uitlijning kleiner is dan de lengte van de opgemaakte tekenreeks, wordt uitlijning genegeerd en wordt de lengte van de opgemaakte tekenreeks gebruikt als veldbreedte. De opgemaakte gegevens in het veld worden rechts uitgelijnd als de uitlijning positief en links is uitgelijnd als uitlijning negatief is. Als opvulling nodig is, wordt witruimte gebruikt. De komma is vereist als uitlijning is opgegeven.

In het volgende voorbeeld worden twee matrices gedefinieerd, één met de namen van werknemers en de andere met de uren die ze meer dan twee weken hebben gewerkt. Met de tekenreeks met samengestelde notatie worden de namen in een veld van 20 tekens links uitgelijnd en worden de uren rechts uitgelijnd in een veld van vijf tekens. Met de tekenreeks met de standaardnotatie N1 worden de uren opgemaakt met één breukcijfer.

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

Tekenreeksonderdeel opmaken

Het optionele formatString-onderdeel is een notatietekenreeks die geschikt is voor het type object dat wordt opgemaakt. U kunt het volgende opgeven:

  • Een standaardtekenreeks of aangepaste numerieke notatie als het bijbehorende object een numerieke waarde is.
  • Een standaard- of aangepaste tekenreeks voor datum- en tijdnotatie als het bijbehorende object een DateTime object is.
  • Een opsommingsnotatietekenreeks als het bijbehorende object een opsommingswaarde is.

Als formatString niet is opgegeven, wordt de algemene notatieaanduiding ('G') gebruikt voor een numeriek, datum en tijd- of opsommingstype. De dubbele punt is vereist als formatString is opgegeven.

De volgende tabel bevat typen of categorieën typen typen in de .NET-klassebibliotheek die ondersteuning bieden voor een vooraf gedefinieerde set opmaaktekenreeksen en bevat koppelingen naar de artikelen met de ondersteunde notatietekenreeksen. Tekenreeksopmaak is een uitbreidbaar mechanisme waarmee u nieuwe opmaaktekenreeksen voor alle bestaande typen kunt definiëren en een set opmaaktekenreeksen definieert die worden ondersteund door een toepassingsgedefinieerd type.

Zie de IFormattable artikelen en ICustomFormatter interface voor meer informatie.

Type of typecategorie Onderwerp
Datum- en tijdtypen (DateTime, DateTimeOffset) Standaardnotatietekenreeksen voor datum en tijd

Aangepaste datum- en tijdnotatietekenreeksen
Opsommingstypen (alle typen afgeleid van System.Enum) Opsommingstekenreeksen opmaken
Numerieke typen (BigInteger, , , Decimal, DoubleInt16, , Int32, Int64, , SByte, UInt16Single, ) UInt64UInt32Byte Tekenreeksen met numerieke standaardopmaak

Tekenreeksen voor aangepaste numerieke notatie
Guid Guid.ToString(String)
TimeSpan Tekenreeksen met standaardtijdspannenotatie

Tekenreeksen voor aangepaste tijdspannenotatie

Accolades ontsnappen

Accolades openen en sluiten worden geïnterpreteerd als begin- en eindopmaakitem. Als u een letterlijke accolade of een accolade wilt weergeven, moet u een escape-reeks gebruiken. Geef twee accolades ({{) op in de vaste tekst om één accolade ({) weer te geven, of twee haakjes sluiten (}}) om één afsluitende accolade (}) weer te geven.

Escape-accolades met een opmaakitem worden verschillend geparseerd tussen .NET en .NET Framework.

.NET

Accolades kunnen worden ontsnapt rond een opmaakitem. Denk bijvoorbeeld aan het opmaakitem {{{0:D}}}, dat is bedoeld voor het weergeven van een accolade openen, een numerieke waarde die is opgemaakt als een decimaal getal en een accolade sluiten. Het opmaakitem wordt op de volgende manier geïnterpreteerd:

  1. De eerste twee accolades ({{) zijn ontsnapt en leveren één openingsbrace op.
  2. De volgende drie tekens ({0:) worden geïnterpreteerd als het begin van een opmaakitem.
  3. Het volgende teken (D) wordt geïnterpreteerd als de numerieke notatieaanduiding voor decimalen.
  4. De volgende accolade (}) wordt geïnterpreteerd als het einde van het opmaakitem.
  5. De laatste twee sluiten accolades worden ontsnapt en één afsluitende accolade opleveren.
  6. Het uiteindelijke resultaat dat wordt weergegeven, is de letterlijke tekenreeks. {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

Accolades in een opmaakitem worden opeenvolgend geïnterpreteerd in de volgorde waarin ze worden aangetroffen. Het interpreteren van geneste accolades wordt niet ondersteund.

De manier waarop accolades worden geïnterpreteerd, kan leiden tot onverwachte resultaten. Denk bijvoorbeeld aan het opmaakitem {{{0:D}}}, dat is bedoeld voor het weergeven van een accolade openen, een numerieke waarde die is opgemaakt als een decimaal getal en een accolade sluiten. Het opmaakitem wordt echter op de volgende manier geïnterpreteerd:

  1. De eerste twee accolades ({{) zijn ontsnapt en leveren één openingsbrace op.
  2. De volgende drie tekens ({0:) worden geïnterpreteerd als het begin van een opmaakitem.
  3. Het volgende teken (D) wordt geïnterpreteerd als de numerieke standaardaanduiding voor de decimale standaardnotatie, maar de volgende twee escape-accolades (}}) leveren één accolade op. Omdat de resulterende tekenreeks (D}) geen standaardaanduiding voor numerieke notatie is, wordt de resulterende tekenreeks geïnterpreteerd als een tekenreeks met een aangepaste notatie die betekent dat de letterlijke tekenreeks D}wordt weergegeven.
  4. De laatste accolade (}) wordt geïnterpreteerd als het einde van het opmaakitem.
  5. Het uiteindelijke resultaat dat wordt weergegeven, is de letterlijke tekenreeks. {D} De numerieke waarde die moet worden opgemaakt, wordt niet weergegeven.
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}

Een manier om uw code te schrijven om te voorkomen dat escape-accolades verkeerd worden geïnterpreteerd en items opmaken, is door de accolades op te maken en items afzonderlijk op te maken. In de eerste notatiebewerking wordt een letterlijke openingsbrace weergegeven. In de volgende bewerking geeft u het resultaat van het opmaakitem weer en geeft u in de laatste bewerking een letterlijke accolade weer. In het volgende voorbeeld ziet u deze benadering:

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}

Verwerkingsvolgorde

Als de aanroep van de samengestelde opmaakmethode een IFormatProvider argument bevat waarvan de waarde niet nullis, roept IFormatProvider.GetFormat de runtime de methode aan om een ICustomFormatter implementatie aan te vragen. Als de methode een ICustomFormatter implementatie kan retourneren, wordt deze in de cache opgeslagen tijdens de aanroep van de samengestelde opmaakmethode.

Elke waarde in de parameterlijst die overeenkomt met een opmaakitem wordt als volgt geconverteerd naar een tekenreeks:

  1. Als de waarde die moet worden opgemaakt, wordt nulleen lege tekenreeks String.Empty geretourneerd.

  2. Als er een ICustomFormatter implementatie beschikbaar is, roept de runtime de methode aan Format . De runtime geeft de waarde van het opmaakitem formatString (of null als het niet aanwezig is) door aan de methode. De runtime geeft de IFormatProvider implementatie ook door aan de methode. Als de aanroep van de ICustomFormatter.Format methode wordt geretourneerd null, gaat de uitvoering verder met de volgende stap. Anders wordt het resultaat van de ICustomFormatter.Format aanroep geretourneerd.

  3. Als de waarde de IFormattable interface implementeert, wordt de methode van ToString(String, IFormatProvider) de interface aangeroepen. Als er een aanwezig is in het opmaakitem, wordt de formatString-waarde doorgegeven aan de methode. Anders wordt null het doorgegeven. Het IFormatProvider argument wordt als volgt bepaald:

  4. De parameterloze ToString methode van het type, die het gedrag van de basisklasse overschrijft Object.ToString() of overneemt, wordt aangeroepen. In dit geval wordt de opmaaktekenreeks die door het formatString onderdeel in het opmaakitem is opgegeven, genegeerd als deze aanwezig is.

Uitlijning wordt toegepast nadat de voorgaande stappen zijn uitgevoerd.

Codevoorbeelden

In het volgende voorbeeld ziet u één tekenreeks die is gemaakt met samengestelde opmaak en een andere tekenreeks die is gemaakt met behulp van de methode van ToString een object. Beide typen opmaak produceren gelijkwaardige resultaten.

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

Ervan uitgaande dat de huidige dag een donderdag in mei is, bevindt Thursday May de waarde van beide tekenreeksen in het voorgaande voorbeeld zich in de Engelse cultuur van de V.S. .

Console.WriteLine biedt dezelfde functionaliteit als String.Format. Het enige verschil tussen de twee methoden is dat het resultaat wordt geretourneerd als een tekenreeks, terwijl Console.WriteLine het resultaat wordt weggeschreven naar de uitvoerstroom die String.Format aan het Console object is gekoppeld. In het volgende voorbeeld wordt de methode gebruikt om de Console.WriteLine waarde van myNumber een valutawaarde op te maken:

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

In het volgende voorbeeld ziet u hoe u meerdere objecten opmaakt, waaronder het op twee verschillende manieren opmaken van één object:

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

In het volgende voorbeeld ziet u het gebruik van uitlijning in opmaak. De argumenten die zijn opgemaakt, worden tussen verticale staaftekens (|) geplaatst om de resulterende uitlijning te markeren.

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   |

Zie ook