Interpolação de cadeia de caracteres usando $

  • Artigo

O caractere especial $ identifica um literal de cadeia de caracteres como uma cadeia de caracteres interpolada. Uma cadeia de caracteres interpolada é um literal de cadeia de caracteres que pode conter expressões de interpolação. Quando uma cadeia de caracteres interpolada é resolvida em uma cadeia de caracteres de resultado, itens com expressões de interpolação são substituídos pelas representações de cadeia de caracteres dos resultados da expressão.

A interpolação de cadeia de caracteres fornece uma sintaxe mais acessível e prática para as cadeias de caracteres de formato. Ela é mais fácil de ler do que a formatação composta de cadeia de caracteres. Compare o exemplo a seguir que usa os dois recursos para produzir a mesma saída:

string 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.

Estrutura de uma cadeia de caracteres interpolada

Para identificar uma literal de cadeia de caracteres como uma cadeia de caracteres interpolada, preceda-o com o símbolo $. Não pode haver nenhum espaço em branco entre o $ e " que iniciam um literal de cadeia de caracteres. Para concatenar várias cadeias de caracteres interpoladas, adicione o $ caractere especial a cada literal de cadeia de caracteres.

A estrutura de um item com uma expressão de interpolação é da seguinte maneira:

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

Os elementos entre colchetes são opcionais. A seguinte tabela descreve cada elemento:

Elemento Descrição
interpolationExpression A expressão que produz um resultado a ser formatado. A representação da cadeia de caracteres de null é String.Empty.
alignment A expressão de constante cujo valor define o número mínimo de caracteres da representação de cadeia de caracteres do resultado da expressão. Se for positiva, a representação de cadeia de caracteres será alinhada à direita; se for negativa, será alinhada à esquerda. Para obter mais informações, consulte Componente de alinhamento.
formatString Uma cadeia de caracteres de formato compatível com o tipo do resultado da expressão. Para obter mais informações, consulte Componente da cadeia de caracteres de formato.

O exemplo a seguir usa os componentes opcionais de formatação descritos acima:

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");
// Expected output is:
// |Left   |  Right|
//     3.14159265358979 - default formatting of the pi number
//                3.142 - display only three decimal digits of the pi number

A partir do C# 10, você pode usar a interpolação de cadeia de caracteres para inicializar uma cadeia de caracteres constante. Todas as expressões usadas para espaços reservados devem ser cadeias de caracteres constantes. Em outras palavras, cada expressão de interpolação deve ser uma cadeia de caracteres e uma constante em tempo de compilação.

A partir do C# 11, as expressões interpoladas podem incluir novas linhas. O texto entre o { e o } deve ser o C# válido. Portanto, pode incluir novas linhas que melhoram a legibilidade. O exemplo a seguir mostra como as novas linhas podem melhorar a legibilidade de uma expressão que envolve padrões correspondentes:

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",
    }
    }";

Além disso, a partir do C# 11, você pode usar um literal de cadeia de caracteres bruto para a cadeia de caracteres de formato:

int X = 2;
int Y = 3;

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

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

Você pode usar vários caracteres $ em um literal de cadeia de caracteres bruto interpolado, para inserir os caracteres { e } na cadeia de caracteres de saída, sem escapar deles:

int X = 2;
int Y = 3;

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

Caso a cadeia de caracteres de saída deva conter os caracteres { ou } repetidos, você pode adicionar mais $ para designar a cadeia de caracteres interpolada. Qualquer sequência de { ou } menor que o número de $ será inserida na cadeia de caracteres de saída. Conforme mostrado no exemplo anterior, as sequências maiores que a sequência de caracteres $ inserem os caracteres adicionais { ou } na saída. O compilador emitirá um erro se a sequência de caracteres de chave for igual ou maior que o dobro do comprimento da sequência de caracteres $.

Você pode experimentar esses recursos usando o SDK do .NET 7. Ou, se você tiver o SDK do .NET 6.00.200 ou posterior, pode definir o elemento <LangVersion> no arquivo csproj como preview.

Caracteres especiais

Para incluir uma chave, "{" ou "}", no texto produzido por uma cadeia de caracteres interpolada, use duas chaves, "{{" ou "}}". Para obter mais informações, consulte Chaves de escape.

Como os dois-pontos (":") têm um significado especial em um item de expressão de interpolação, para usar um operador condicional em uma expressão de interpolação, coloque essa expressão entre parênteses.

O exemplo a seguir mostra como incluir uma chave em uma cadeia de caracteres de resultado. Ele também mostra como usar um operador condicional:

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.");
// Expected output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Uma cadeia de caracteres verbatim interpolada começa com o caractere $, seguido pelo caractere @. Você pode usar os $ tokens e @ em qualquer ordem: e $@"..."@$"..." são cadeias de caracteres textuais interpoladas válidas. Para obter mais informações sobre cadeias de caracteres textuais, confira os artigos cadeia de caracteres e identificador textual.

Conversões implícitas e como especificar a implementação IFormatProvider

Há três conversões implícitas de uma cadeia de caracteres interpolada:

  1. Conversão de uma cadeia de caracteres interpolada em uma instância String. A cadeia de caracteres é o resultado da resolução de cadeia de caracteres interpolada. Todos os itens de expressão de interpolação são substituídos pelas representações de cadeia de caracteres formatadas corretamente dos resultados. Essa conversão usa o CurrentCulture para formatar os resultados da expressão.

  2. Conversão de uma cadeia de caracteres interpolada em uma instância de FormattableString, que representa uma cadeia de caracteres de formato composto, juntamente com os resultados da expressão a ser formatada. Isso permite criar várias cadeias de caracteres de resultado com conteúdo específico da cultura com base em uma única instância FormattableString. Para fazer isso, chame um dos seguintes métodos:

    O ToString(IFormatProvider) fornece uma implementação definida pelo usuário da interface IFormatProvider, que permite formatação personalizada. Para obter mais informações, confira a seção Formatação personalizada com ICustomFormatter do artigo Formatação de tipos no .NET .

  3. Conversão de uma cadeia de caracteres interpolada em uma instância IFormattable, que também permite criar várias cadeias de caracteres de resultado com conteúdo específico da cultura com base em uma única instância IFormattable.

O exemplo a seguir usa a conversão implícita em FormattableString para a criação de cadeias de caracteres de resultado específicas de cultura:

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

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = message.ToString();

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);

string messageInInvariantCulture = FormattableString.Invariant(message);

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Expected 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.

Outros recursos

Se não estiver familiarizado com a interpolação de cadeia de caracteres, confira o tutorial Interpolação de cadeia de caracteres no C# Interativo. Você também pode verificar outro tutorial Interpolação de cadeia de caracteres no C#. Esse tutorial demonstra como usar cadeias de caracteres interpoladas para produzir cadeias de caracteres formatadas.

Compilação de cadeias de caracteres interpoladas

Se uma cadeia de caracteres interpolada tiver o tipo string, ela normalmente será transformada em uma chamada de método String.Format. O compilador pode substituir String.Format por String.Concat se o comportamento analisado for equivalente à concatenação.

Se uma cadeia de caracteres interpolada tiver o tipo IFormattable ou FormattableString, o compilador gerará uma chamada para o método FormattableStringFactory.Create.

A partir do C# 10, quando uma cadeia de caracteres interpolada é usada, o compilador verifica se a cadeia de caracteres interpolada é atribuída a um tipo que atende ao padrão do manipulador de cadeia de caracteres interpolada. Um manipulador de cadeia de caracteres interpolada é um tipo personalizado que converte a cadeia de caracteres interpolada em uma cadeia de caracteres. Um manipulador de cadeia de caracteres interpolada é um cenário avançado, normalmente usado por motivos de desempenho. Você pode saber mais sobre os requisitos para criar um manipulador de cadeia de caracteres interpolada na especificação de linguagem para melhorias da cadeia de caracteres interpolada. Você pode compilar um ao seguir o tutorial do manipulador de cadeia de caracteres interpolada na seção Novidades do C#. No .NET 6, quando você usa uma cadeia de caracteres interpolada para um argumento do tipo string, a cadeia de caracteres interpolada é processada pelo System.Runtime.CompilerServices.DefaultInterpolatedStringHandler.

Observação

Um efeito colateral dos manipuladores de cadeia de caracteres interpolada é que um manipulador personalizado, incluindo System.Runtime.CompilerServices.DefaultInterpolatedStringHandler, pode não avaliar todas as expressões usadas como espaços reservados na cadeia de caracteres interpolada em todas as condições. Isso significa que os efeitos colaterais nessas expressões podem não ocorrer.

Especificação da linguagem C#

Para obter mais informações, consulte a seção Cadeias de caracteres interpoladas da especificação da linguagem C#, a especificação do recurso C# 11 – Literais de cadeia de caracteres brutas e o C# 11 – Novas linhas na especificação de recursos de interpolações de cadeia de caracteres .

Confira também