Interpolação de cordas em C#
Este tutorial mostra como usar a interpolação de cadeia de caracteres para formatar e incluir resultados de expressão em uma cadeia de caracteres de resultado. Os exemplos pressupõem que você esteja familiarizado com conceitos básicos de C# e formatação de tipo .NET. Se você é novo em interpolação de cadeia de caracteres ou formatação de tipo .NET, confira primeiro o tutorial interativo de interpolação de cadeia de caracteres. Para obter mais informações sobre tipos de formatação no .NET, consulte Tipos de formatação no .NET.
Introdução
Para identificar um literal de cadeia de caracteres como uma cadeia de caracteres interpolada, coloque-a com o $ símbolo. Você pode incorporar qualquer expressão C# válida que retorne um valor em uma cadeia de caracteres interpolada. No exemplo a seguir, assim que uma expressão é avaliada, seu resultado é convertido em uma cadeia de caracteres e incluído em uma cadeia de caracteres de resultado:
double a = 3;
double b = 4;
Console.WriteLine($"Area of the right triangle with legs of {a} and {b} is {0.5 * a * b}");
Console.WriteLine($"Length of the hypotenuse of the right triangle with legs of {a} and {b} is {CalculateHypotenuse(a, b)}");
double CalculateHypotenuse(double leg1, double leg2) => Math.Sqrt(leg1 * leg1 + leg2 * leg2);
// Output:
// Area of the right triangle with legs of 3 and 4 is 6
// Length of the hypotenuse of the right triangle with legs of 3 and 4 is 5
Como mostra o exemplo, você inclui uma expressão em uma cadeia de caracteres interpolada colocando-a com chaves:
{<interpolationExpression>}
As cadeias de caracteres interpoladas suportam todos os recursos do recurso de formatação composta de cadeia de caracteres. Isso os torna uma alternativa mais legível ao uso do String.Format método.
Como especificar uma cadeia de caracteres de formato para uma expressão de interpolação
Para especificar uma cadeia de caracteres de formato suportada pelo tipo do resultado da expressão, siga a expressão de interpolação com dois pontos (":") e a cadeia de caracteres de formato:
{<interpolationExpression>:<formatString>}
O exemplo a seguir mostra como especificar cadeias de caracteres de formato padrão e personalizado para expressões que produzem data e hora ou resultados numéricos:
var date = new DateTime(1731, 11, 25);
Console.WriteLine($"On {date:dddd, MMMM dd, yyyy} L. Euler introduced the letter e to denote {Math.E:F5}.");
// Output:
// On Sunday, November 25, 1731 L. Euler introduced the letter e to denote 2.71828.
Para obter mais informações, consulte a seção Componente Formatar cadeia de caracteres do artigo Formatação composta.
Como controlar a largura do campo e o alinhamento da expressão de interpolação formatada
Para especificar a largura mínima do campo e o alinhamento do resultado da expressão formatada, siga a expressão de interpolação com uma vírgula (",") e a expressão constante:
{<interpolationExpression>,<alignment>}
Se o valor do alinhamento for positivo, o resultado da expressão formatada será alinhado à direita e, se negativo, alinhado à esquerda.
Se você precisar especificar o alinhamento e uma cadeia de caracteres de formato, comece com o componente de alinhamento:
{<interpolationExpression>,<alignment>:<formatString>}
O exemplo a seguir mostra como especificar o alinhamento e usa caracteres de pipe ("|") para delimitar campos de texto:
const int NameAlignment = -9;
const int ValueAlignment = 7;
double a = 3;
double b = 4;
Console.WriteLine($"Three classical Pythagorean means of {a} and {b}:");
Console.WriteLine($"|{"Arithmetic",NameAlignment}|{0.5 * (a + b),ValueAlignment:F3}|");
Console.WriteLine($"|{"Geometric",NameAlignment}|{Math.Sqrt(a * b),ValueAlignment:F3}|");
Console.WriteLine($"|{"Harmonic",NameAlignment}|{2 / (1 / a + 1 / b),ValueAlignment:F3}|");
// Output:
// Three classical Pythagorean means of 3 and 4:
// |Arithmetic| 3.500|
// |Geometric| 3.464|
// |Harmonic | 3.429|
Como mostra a saída de exemplo, se o comprimento do resultado da expressão formatada exceder a largura do campo especificado, o valor do alinhamento será ignorado.
Para obter mais informações, consulte a seção Componente de alinhamento do artigo Formatação composta.
Como usar sequências de escape em uma cadeia de caracteres interpolada
As cadeias de caracteres interpoladas suportam todas as sequências de escape que podem ser usadas em literais de cadeia de caracteres comuns. Para obter mais informações, consulte Sequências de escape de cadeia de caracteres.
Para interpretar as sequências de escape literalmente, use uma string literal literal . Uma sequência literal interpolada começa com os caracteres e $@ ambos. Você pode usar $ e em qualquer ordem: ambos $@"..." e @$"..."@ são strings literais interpoladas válidas.
Para incluir uma chave, "{" ou "}", em uma cadeia de caracteres de resultado, use duas chaves, "{{" ou "}}". Para obter mais informações, consulte a seção Chaves de fuga do artigo Formatação composta.
O exemplo a seguir mostra como incluir chaves em uma cadeia de caracteres de resultado e construir uma cadeia de caracteres interpolada literal:
var xs = new int[] { 1, 2, 7, 9 };
var ys = new int[] { 7, 9, 12 };
Console.WriteLine($"Find the intersection of the {{{string.Join(", ",xs)}}} and {{{string.Join(", ",ys)}}} sets.");
// Output:
// Find the intersection of the {1, 2, 7, 9} and {7, 9, 12} sets.
var userName = "Jane";
var stringWithEscapes = $"C:\\Users\\{userName}\\Documents";
var verbatimInterpolated = $@"C:\Users\{userName}\Documents";
Console.WriteLine(stringWithEscapes);
Console.WriteLine(verbatimInterpolated);
// Output:
// C:\Users\Jane\Documents
// C:\Users\Jane\Documents
A partir do C# 11, você pode usar literais de cadeia de caracteres bruta interpolados.
Como usar um operador ?: condicional ternário em uma expressão de interpolação
Como os dois pontos (":") têm um significado especial em um item com uma expressão de interpolação, para usar um operador condicional em uma expressão, coloque-o entre parênteses, como mostra o exemplo a seguir:
var rand = new Random();
for (int i = 0; i < 7; i++)
{
Console.WriteLine($"Coin flip: {(rand.NextDouble() < 0.5 ? "heads" : "tails")}");
}
Como criar uma cadeia de resultados específica da cultura com interpolação de cadeia de caracteres
Por padrão, uma cadeia de caracteres interpolada CultureInfo.CurrentCulture usa a cultura atual definida pela propriedade para todas as operações de formatação.
A partir do .NET 6, você pode usar o método para resolver uma cadeia de caracteres interpolada para uma cadeia de caracteres de resultado específica da cultura, como mostra o String.Create(IFormatProvider, DefaultInterpolatedStringHandler) exemplo a seguir:
var cultures = new System.Globalization.CultureInfo[]
{
System.Globalization.CultureInfo.GetCultureInfo("en-US"),
System.Globalization.CultureInfo.GetCultureInfo("en-GB"),
System.Globalization.CultureInfo.GetCultureInfo("nl-NL"),
System.Globalization.CultureInfo.InvariantCulture
};
var date = DateTime.Now;
var number = 31_415_926.536;
foreach (var culture in cultures)
{
var cultureSpecificMessage = string.Create(culture, $"{date,23}{number,20:N3}");
Console.WriteLine($"{culture.Name,-10}{cultureSpecificMessage}");
}
// Output is similar to:
// en-US 8/27/2023 12:35:31 PM 31,415,926.536
// en-GB 27/08/2023 12:35:31 31,415,926.536
// nl-NL 27-08-2023 12:35:31 31.415.926,536
// 08/27/2023 12:35:31 31,415,926.536
Em versões anteriores do .NET, use a conversão implícita de uma cadeia de caracteres interpolada em uma instância e chame seu ToString(IFormatProvider) método para criar uma System.FormattableString cadeia de caracteres de resultado específica da cultura. O exemplo a seguir mostra como fazer isso:
var cultures = new System.Globalization.CultureInfo[]
{
System.Globalization.CultureInfo.GetCultureInfo("en-US"),
System.Globalization.CultureInfo.GetCultureInfo("en-GB"),
System.Globalization.CultureInfo.GetCultureInfo("nl-NL"),
System.Globalization.CultureInfo.InvariantCulture
};
var date = DateTime.Now;
var number = 31_415_926.536;
FormattableString message = $"{date,23}{number,20:N3}";
foreach (var culture in cultures)
{
var cultureSpecificMessage = message.ToString(culture);
Console.WriteLine($"{culture.Name,-10}{cultureSpecificMessage}");
}
// Output is similar to:
// en-US 8/27/2023 12:35:31 PM 31,415,926.536
// en-GB 27/08/2023 12:35:31 31,415,926.536
// nl-NL 27-08-2023 12:35:31 31.415.926,536
// 08/27/2023 12:35:31 31,415,926.536
Como mostra o exemplo, você pode usar uma FormattableString instância para gerar várias cadeias de caracteres de resultado para várias culturas.
Como criar uma cadeia de caracteres de resultado usando a cultura invariante
A partir do .NET 6, use o método para resolver uma cadeia de caracteres interpolada para uma cadeia de caracteres de resultado para o , como mostra o String.Create(IFormatProvider, DefaultInterpolatedStringHandler)InvariantCultureexemplo a seguir:
string message = string.Create(CultureInfo.InvariantCulture, $"Date and time in invariant culture: {DateTime.Now}");
Console.WriteLine(message);
// Output is similar to:
// Date and time in invariant culture: 05/17/2018 15:46:24
Em versões anteriores do .NET, juntamente com o método, você pode usar o método estáticoFormattableString.Invariant, como mostra o FormattableString.ToString(IFormatProvider) exemplo a seguir:
string message = FormattableString.Invariant($"Date and time in invariant culture: {DateTime.Now}");
Console.WriteLine(message);
// Output is similar to:
// Date and time in invariant culture: 05/17/2018 15:46:24
Conclusão
Este tutorial descreve cenários comuns de uso de interpolação de cadeia de caracteres. Para obter mais informações sobre interpolação de cadeia de caracteres, consulte Interpolação de cadeia de caracteres. Para obter mais informações sobre tipos de formatação no .NET, consulte os artigos Tipos de formatação no .NET e Formatação composta.
