Interpolação de cadeias de caracteres em C#

  • Artigo

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 os conceitos básicos do C# e a formatação de tipos do .NET. Se você não estiver familiarizado com a interpolação de cadeia de caracteres ou com a formatação de tipos do .NET, confira primeiro o tutorial interativo sobre a interpolação de cadeia de caracteres. Para obter mais informações sobre tipos de formatação no .NET, confira Tipos de formatação no .NET.

Introdução

Para identificar uma literal de cadeia de caracteres como uma cadeia de caracteres interpolada, preceda-o com o símbolo $. Você pode inserir qualquer expressão C# válida que retorna um valor em uma cadeia de caracteres interpolada. No seguinte exemplo, assim que uma expressão é avaliada, o 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>}

Cadeia de caracteres interpoladas são compatíveis com todos os recursos do recurso formatação composta de cadeia de caracteres. Isso as torna uma alternativa mais legível ao uso do método String.Format.

Como especificar uma cadeia de caracteres de formato para uma expressão de interpolação

Para especificar uma cadeia de caracteres de formato compatível com o tipo do resultado de expressão, siga a expressão de interpolação com dois pontos (“:”) e a cadeia de caracteres de formato:

{<interpolationExpression>:<formatString>}

O seguinte exemplo mostra como especificar cadeias de caracteres de formato padrão e personalizadas para expressões que produzem resultados numéricos ou de data e hora:

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 de cadeia de caracteres de formato 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 de expressão formatada, siga a expressão de interpolação com uma vírgula (“,”) e a expressão de constante:

{<interpolationExpression>,<alignment>}

Se o valor alignment for positivo, o resultado da expressão formatada será alinhado à direita; se for negativo, ele será alinhado à esquerda.

Caso precise especificar o alinhamento e uma cadeia de caracteres de formato, comece com o componente de alinhamento:

{<interpolationExpression>,<alignment>:<formatString>}

O seguinte exemplo mostra como especificar o alinhamento e usa caracteres de barra vertical ("|") 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 tamanho do resultado da expressão formatada exceder a largura de campo especificada, o valor alignment 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

Cadeias de caracteres interpoladas dão suporte a 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 sequências de escape literalmente, use um literal de cadeia de caracteres textual. Uma cadeia de caracteres verbatim interpolada começa com os caracteres $ e @. Você pode usar $ e @ em qualquer ordem: $@"..." e @$"..." são cadeias de caracteres verbatim 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 escape do artigo Formatação composta.

O seguinte exemplo mostra como incluir chaves em uma cadeia de caracteres de resultado e construir uma cadeia de caracteres interpolada textual:

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 e interpolada.

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-a entre parênteses, como mostra o seguinte exemplo:

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 caracteres de resultado específica a uma cultura com a interpolação de cadeia de caracteres

Por padrão, uma cadeia de caracteres interpolada usa a cultura atual definida pela propriedade CultureInfo.CurrentCulture para todas as operações de formatação.

A partir do .NET 6, você pode usar o método String.Create(IFormatProvider, DefaultInterpolatedStringHandler) para resolve uma cadeia de caracteres interpolada para uma cadeia de caracteres de resultado específica da cultura, como mostra o 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 System.FormattableString e chame seu método ToString(IFormatProvider) para criar uma cadeia de caracteres de resultado específica da cultura. O seguinte exemplo 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 instância FormattableString para gerar várias cadeias de caracteres de resultado para várias culturas.

Como criar uma cadeia de caracteres de resultado usando a cultura invariável

A partir do .NET 6, use o método String.Create(IFormatProvider, DefaultInterpolatedStringHandler) para resolver uma cadeia de caracteres interpolada em uma cadeia de caracteres de resultado para InvariantCulture, como mostra o exemplo 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 FormattableString.ToString(IFormatProvider), você pode usar o método estático FormattableString.Invariant, como mostra o 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 da interpolação de cadeia de caracteres. Para obter mais informações sobre a interpolação de cadeia de caracteres, consulte Interpolação de cadeia de caracteres. Para obter mais informações sobre os tipos de formatação no .NET, confira os artigos Tipos de formatação no .NET e Formatação composta.

Confira também