Delen via

Tekenreeksinterpolatie met behulp van $

Het $ teken identificeert een letterlijke tekenreeks als een geïnterpoleerde tekenreeks. Een geïnterpoleerde tekenreeks is een letterlijke tekenreeks die interpolatie-expressies kan bevatten. Wanneer een geïnterpoleerde tekenreeks wordt omgezet in een resultaattekenreeks, vervangt de compiler items door interpolatie-expressies door de tekenreeksweergaven van de expressieresultaten.

Tekenreeksinterpolatie biedt een beter leesbare, handige syntaxis voor het opmaken van tekenreeksen. Het is gemakkelijker te lezen dan samengestelde tekenreeksopmaak. In het volgende voorbeeld worden beide functies gebruikt om dezelfde uitvoer te produceren:

var name = "Mark";
var date = DateTime.Now;

// Composite formatting:
Console.WriteLine("Hello, {0}! Today is {1}, it's {2:HH:mm} now.", name, date.DayOfWeek, date);
// String interpolation:
Console.WriteLine($"Hello, {name}! Today is {date.DayOfWeek}, it's {date:HH:mm} now.");
// Both calls produce the same output that is similar to:
// Hello, Mark! Today is Wednesday, it's 19:40 now.

U kunt een geïnterpoleerde tekenreeks gebruiken om een constante tekenreeks te initialiseren. U kunt dit alleen doen als alle interpolatie-expressies in de geïnterpoleerde tekenreeks ook constante tekenreeksen zijn.

Structuur van een geïnterpoleerde tekenreeks

Als u een letterlijke tekenreeks wilt identificeren als een geïnterpoleerde tekenreeks, wordt deze voorafgegaan door het $ symbool. U kunt geen witruimte hebben tussen de $ en de " tekenreeks die een letterlijke tekenreeks start.

De structuur van een item met een interpolatie-expressie is als volgt:

{<interpolationExpression>[,<width>][:<formatString>]}

Elementen in vierkante haken zijn optioneel. In de volgende tabel wordt elk element beschreven:

Onderdeel Beschrijving
interpolationExpression De expressie die een resultaat produceert dat moet worden opgemaakt. Wanneer de expressie is null, is de uitvoer de lege tekenreeks (String.Empty).
width De constante expressie waarvan de waarde het minimum aantal tekens in de tekenreeksweergave van het expressieresultaat definieert. Als dit positief is, wordt de tekenreeksweergave rechts uitgelijnd; indien negatief, links uitgelijnd. Voor meer informatie, zie de sectie Breedte van het artikel Samengestelde opmaak.
formatString Een notatietekenreeks die door het type van het resultaat van de expressie wordt ondersteund. Zie de sectie Opmaaktekenreeksonderdeel van het artikel Samengestelde opmaak voor meer informatie.

In het volgende voorbeeld worden optionele opmaakonderdelen gebruikt die in de voorgaande tabel worden beschreven:

Console.WriteLine($"|{"Left",-7}|{"Right",7}|");

const int FieldWidthRightAligned = 20;
Console.WriteLine($"{Math.PI,FieldWidthRightAligned} - default formatting of the pi number");
Console.WriteLine($"{Math.PI,FieldWidthRightAligned:F3} - display only three decimal digits of the pi number");
// Output is:
// |Left   |  Right|
//     3.14159265358979 - default formatting of the pi number
//                3.142 - display only three decimal digits of the pi number

Vanaf C# 11 kunt u nieuwe regels in een interpolatie-expressie gebruiken om de code van de expressie beter leesbaar te maken. In het volgende voorbeeld ziet u hoe nieuwe regels de leesbaarheid van een expressie met patroonkoppeling kunnen verbeteren:

string message = $"The usage policy for {safetyScore} is {
    safetyScore switch
    {
        > 90 => "Unlimited usage",
        > 80 => "General usage, with daily safety check",
        > 70 => "Issues must be addressed within 1 week",
        > 50 => "Issues must be addressed within 1 day",
        _ => "Issues must be addressed before continued use",
    }
    }";

Letterlijke tekenreeksen geïnterpoleerd

Vanaf C# 11 kunt u een onbewerkte geïnterpoleerde letterlijke tekenreeks gebruiken, zoals in het volgende voorbeeld wordt getoond.

int X = 2;
int Y = 3;

var pointMessage = $"""The point "{X}, {Y}" is {Math.Sqrt(X * X + Y * Y):F3} from the origin""";

Console.WriteLine(pointMessage);
// Output is:
// The point "2, 3" is 3.606 from the origin

Om { en } tekens in de resultaattekenreeks in te sluiten, start u een geïnterpoleerde onbewerkte tekenreeks met meerdere $ tekens. Als u dat doet, wordt een reeks tekens { korter } dan het aantal $ tekens in de resultaattekenreeks ingesloten. Als u een interpolatie-expressie in die tekenreeks wilt insluiten, moet u hetzelfde aantal accolades gebruiken als het aantal $ tekens, zoals in het volgende voorbeeld wordt weergegeven:

int X = 2;
int Y = 3;

var pointMessage = $$"""{The point {{{X}}, {{Y}}} is {{Math.Sqrt(X * X + Y * Y):F3}} from the origin}""";
Console.WriteLine(pointMessage);
// Output is:
// {The point {2, 3} is 3.606 from the origin}

In het voorgaande voorbeeld begint een geïnterpoleerde letterlijke tekenreeks met twee $ tekens. Je moet elke interpolatie-uitdrukking tussen dubbele accolades ({{ en }}) plaatsen. Eén accolade wordt geplaatst in een resultaatstring. Als u herhaalde { tekens of } tekens wilt insluiten in een resultaatstring, gebruikt u een passend groter aantal $ tekens om een geïnterpoleerde raw string-literal aan te wijzen. Als de tekenreeks meer accolades heeft dan het aantal $ tekens, worden de { en } tekens van binnen naar buiten gegroepeerd. In het voorgaande voorbeeld interpreteert de letterlijke The point {{{X}}, {{Y}}} expressies {{X}} en {{Y}} als geïnterpoleerde expressies. De buitenste { en } worden letterlijk opgenomen in de uitvoertekenreeks.

Speciale tekens

Als u een accolade, {of }, wilt opnemen in de tekst die wordt geproduceerd door een geïnterpoleerde tekenreeks, gebruikt u twee accolades: {{of }}. Zie de sectie Escape-accolades van het artikel Samengestelde opmaak voor meer informatie.

Als de dubbele punt (':') een speciale betekenis heeft in een interpolatie-expressie, kunt u een voorwaardelijke operator gebruiken. Plaats die expressie tussen haakjes.

In het volgende voorbeeld ziet u hoe u een accolade in een resultaatstring opneemt. U ziet ook hoe u een voorwaardelijke operator gebruikt:

string name = "Horace";
int age = 34;
Console.WriteLine($"He asked, \"Is your name {name}?\", but didn't wait for a reply :-{{");
Console.WriteLine($"{name} is {age} year{(age == 1 ? "" : "s")} old.");
// Output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Een geïnterpoleerde verbatim tekenreeks begint met zowel de $ als de @ tekens. U kunt $ en @ in elke willekeurige volgorde gebruiken: beide $@"..." en @$"..." zijn geldige, geïnterpoleerde verbatim-tekenreeksen. Zie de artikelen over tekenreeksen en verbatim-id's voor meer informatie over verbatimtekenreeksen.

Cultuurspecifieke opmaak

Standaard gebruikt een geïnterpoleerde tekenreeks de huidige cultuur, zoals gedefinieerd door de CultureInfo.CurrentCulture-eigenschap, voor alle opmaakbewerkingen.

Als u een geïnterpoleerde tekenreeks wilt oplossen naar een cultuurspecifieke resultaattekenreeks, gebruikt u de String.Create(IFormatProvider, DefaultInterpolatedStringHandler) methode die beschikbaar is vanaf .NET 6. In het volgende voorbeeld ziet u hoe u dit doet:

double speedOfLight = 299792.458;

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = string.Create(
    specificCulture, $"The speed of light is {speedOfLight:N3} km/s.");

string messageInInvariantCulture = string.Create(
    System.Globalization.CultureInfo.InvariantCulture, $"The speed of light is {speedOfLight:N3} km/s.");

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Output is:
// nl-NL      The speed of light is 299.792,458 km/s.
// en-IN      The speed of light is 2,99,792.458 km/s.
// Invariant  The speed of light is 299,792.458 km/s.

Gebruik in .NET 5 en eerdere versies van .NET impliciete conversie van een geïnterpoleerde tekenreeks naar een FormattableString exemplaar. Vervolgens kunt u een instantiemethode FormattableString.ToString(IFormatProvider) of een statische FormattableString.Invariant methode gebruiken om een cultuurspecifieke resultaattekenreeks te produceren. In het volgende voorbeeld ziet u hoe u dit doet:

double speedOfLight = 299792.458;
FormattableString message = $"The speed of light is {speedOfLight:N3} km/s.";

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);
Console.WriteLine(messageInSpecificCulture);
// Output:
// The speed of light is 2,99,792.458 km/s.

string messageInInvariantCulture = FormattableString.Invariant(message);
Console.WriteLine(messageInInvariantCulture);
// Output is:
// The speed of light is 299,792.458 km/s.

Zie de sectie Aangepaste opmaak met de sectie ICustomFormatter van de opmaaktypen in .NET voor meer informatie over aangepaste opmaak.

Andere bronnen

Als u geen gebruik hebt gemaakt van tekenreeksinterpolatie, raadpleegt u de interactieve zelfstudie tekenreeksinterpolatie in C# . Deze zelfstudie laat zien hoe u geïnterpoleerde tekenreeksen gebruikt om opgemaakte tekenreeksen te produceren.

Compilatie van geïnterpoleerde tekenreeksen

De compiler controleert of een geïnterpoleerde tekenreeks is toegewezen aan een type dat voldoet aan het geïnterpoleerde tekenreekshandlerpatroon. Een geïnterpoleerde tekenreekshandler is een type waarmee de geïnterpoleerde tekenreeks wordt geconverteerd naar een resultaattekenreeks. Wanneer een geïnterpoleerde tekenreeks het type stringheeft, wordt deze verwerkt door de System.Runtime.CompilerServices.DefaultInterpolatedStringHandler. Zie de zelfstudie Een aangepaste tekenreeksinterpolatiehandler schrijven voor het voorbeeld van een aangepaste geïnterpoleerde tekenreekshandler. Het gebruiken van een geïnterpoleerde tekenreekshandler is een geavanceerd scenario, meestal vereist om performantieredenen.

Notitie

Een neveneffect van geïnterpoleerde tekenreekshandlers is dat een aangepaste handler, waaronder System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, mogelijk niet alle interpolatie-expressies binnen de geïnterpoleerde tekenreeks onder alle voorwaarden evalueert. Dat betekent dat bijwerkingen van deze expressies mogelijk niet optreden.

Als een geïnterpoleerde tekenreeks het type stringheeft, wordt deze meestal omgezet in een String.Format methodeaanroep. De compiler kan String.Format vervangen door String.Concat als het geanalyseerde gedrag equivalent aan de samenvoeging zou zijn.

Als een geïnterpoleerde tekenreeks het type IFormattable heeft of FormattableString, genereert de compiler een aanroep naar de FormattableStringFactory.Create methode.

C#-taalspecificatie

Zie de sectie Geïnterpoleerde tekenreeksexpressies van de C#-taalspecificatie en de volgende nieuwe functiespecificaties voor meer informatie:

Zie ook