Tekenreeksinterpolatie met behulp van $

  • Artikel

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, worden items met interpolatie-expressies vervangen 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.

Vanaf C# 10 kunt u 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>[,<alignment>][:<formatString>]}

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

Element Beschrijving
interpolationExpression De expressie die een resultaat produceert dat moet worden opgemaakt. Tekenreeksweergave null is String.Empty.
alignment 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; als dit negatief is, wordt deze links uitgelijnd. Zie de sectie Uitlijning van het artikel Samengestelde opmaak voor meer informatie.
formatString Een notatietekenreeks die wordt ondersteund door het type expressieresultaat. Zie de sectie Opmaaktekenreeksonderdeel van het artikel Samengestelde opmaak voor meer informatie.

In het volgende voorbeeld worden optionele opmaakonderdelen gebruikt die hierboven 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 letterlijke letterlijke geïnterpoleerde onbewerkte tekenreeks gebruiken, 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

Als u tekens in de resultaattekenreeks wilt insluiten en } tekens wilt insluiten{, start u een letterlijke letterlijke tekst van 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. Daarom moet u elke interpolatie-expressie tussen dubbele accolades {{ en }}. Eén accolade wordt ingesloten in een resultaattekenreeks. Als u herhaalde { tekens of } tekens wilt insluiten in een resultaattekenreeks, gebruikt u een passend groter aantal $ tekens om een letterlijke tekst voor geïnterpoleerde onbewerkte tekenreeksen aan te wijzen.

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 (':') speciale betekenis heeft in een interpolatie-expressie-item, om een voorwaardelijke operator in een interpolatie-expressie te gebruiken, plaatst u deze expressie tussen haakjes.

In het volgende voorbeeld ziet u hoe u een accolade in een resultaattekenreeks 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 verbatimtekenreeks begint met de beide $ tekens en @ tekens. U kunt en @ in elke willekeurige volgorde gebruiken$: beide $@"..." en @$"..." zijn geldige, geïnterpoleerde verbatimtekenreeksen. Zie de artikelen over tekenreeksen en verbatim-id's voor meer informatie over verbatimtekenreeksen.

Cultuurspecifieke opmaak

Standaard maakt een geïnterpoleerde tekenreeks gebruik van de huidige cultuur die door de CultureInfo.CurrentCulture eigenschap is gedefinieerd 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.

Meer informatie

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

Compilatie van geïnterpoleerde tekenreeksen

Vanaf C# 10 en .NET 6 controleert de compiler 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 gebruik van een geïnterpoleerde tekenreekshandler is een geavanceerd scenario, meestal vereist om prestatieredenen.

Notitie

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

Vóór C# 10, als een geïnterpoleerde tekenreeks het type stringheeft, wordt deze meestal omgezet in een String.Format methodeaanroep. De compiler kan vervangen door String.FormatString.Concat als het geanalyseerde gedrag gelijk is aan samenvoeging.

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