`$` を使う文字列補間

[アーティクル]
12/07/2022

$ 特殊文字は、リテラル文字列を挿入文字列として識別します。挿入文字列は、補間式が含まれている可能性がある文字列リテラルです。挿入文字列が結果の文字列に解決されると、補間式を含む項目は、式の結果の文字列表現によって置き換えられます。

文字列補間により、より読みやすく便利な構文で文字列を書式設定できます。文字列の複合書式設定よりも読みやすくなります。両方の機能を使用して同じ出力を生成している次の例を比較してみてください。

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.

挿入文字列の構造

文字列リテラルを挿入文字列として識別するため、先頭に $ の記号を追加してください。 $ と文字列リテラルを開始する " の間に空白を入れることはできません。複数の補間された文字列を連結するには、特殊文字 $ を各文字列リテラルに追加します。

補間式を含む項目の構造は、次のとおりです。

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

角かっこ内の要素は省略可能です。次の表は、それぞれの要素の説明です。

要素	説明
`interpolationExpression`	書式設定される結果を生成する式です。 `null` の文字列表記は String.Empty です。
`alignment`	式の結果の文字列表現で、最小文字数を定義する値を持つ定数式です。正の場合は、文字列表現は右揃えで配置され、負の場合は、左揃えで配置されます。詳細については、「Alignment コンポーネント」を参照してください。
`formatString`	式の結果の型によってサポートされる書式指定文字列です。詳細については、「Format String コンポーネント」を参照してください。

次の例では、前述したオプションの書式設定コンポーネントを使用します。

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

C# 10 からは、文字列補間を使用して定数文字列を初期化できます。プレースホルダーに使用されるすべての式は、定数文字列である必要があります。つまり、すべての "補間式" は文字列である必要があり、コンパイル時には定数である必要があります。

C# 11 以降では、補間される式に改行を含めることができます。 { と } の間のテキストは有効な C# である必要があります。そのため、読みやすさを向上させる改行を含めることができます。次の例は、改行によって、どのようにパターンマッチングを含む式の読みやすさを向上させることができるかを示しています。

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

また、C# 11 以降では、書式指定文字列に生文字列リテラルを使用できます。

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.

補間された生文字列リテラルで複数の $ 文字を使用して、エスケープせずに出力文字列に { および } 文字を埋め込むことができます。

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.

出力文字列に繰り返し { または } 文字を含める必要がある場合は、補間された文字列を指定するためにさらに $ を追加できます。 $ の数より短い { または } のシーケンスは、出力文字列に埋め込まれます。前の例に示すように、$ 文字のシーケンスよりも長いシーケンスは、追加の { または } 文字を出力に埋め込みます。中かっこ文字のシーケンスが $ 文字のシーケンスの長さの 2 倍以上の場合、コンパイラはエラーを発行します。

.NET 7 SDK を使用してこの機能を試すことができます。または、.NET SDK 6.00.200 以降がある場合は、csproj ファイル内の <LangVersion> 要素を preview に設定できます。

特殊文字

挿入文字列で生成された文字列にかっこ "{" または "}" を含めるには、2 つのかっこ "{{" または "}}" を使用します。詳細については、「エスケープ中かっこ ({})」を参照してください。

コロン (":") は補間式の項目で特別な意味を持つため、補間式で条件演算子を使用するには、その式を丸かっこで囲みます。

次の例は、結果の文字列にかっこを含める方法を示しています。また、条件演算子の使用方法も示しています。

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.

verbatim 補間文字列は、$ 文字で始まり、@ 文字が続きます。 $ と @ のトークンを任意の順序で使用できます。$@"..." と @$"..." はどちらも有効な verbatim 補間文字列です。逐語的文字列の詳細については、string と逐語的識別子に関する記事を参照してください。

暗黙的な変換と `IFormatProvider` 実装の指定方法

挿入文字列から暗黙の変換を行う方法は 3 種類あります。

補間された文字列から String インスタンスへの変換。文字列は、補間された文字列の解決の結果です。すべての補間式の項目は、その結果の適切に書式設定された文字列形式に置き換えられます。この変換では CurrentCulture を使用して、式の結果の書式を設定します。
書式設定される式の結果と、挿入文字列から複合書式指定文字列を表す FormattableString インスタンスへの変換。これは、単一の FormattableString インスタンスから、カルチャ固有のコンテンツを持つ複数の結果文字列の作成を可能にするものです。そのためには、次のいずれかのメソッドを呼び出します。
- CurrentCulture の結果文字列を生成する ToString() オーバーロード。
- InvariantCulture の結果文字列を生成する Invariant メソッド。
- 特定のカルチャの結果文字列を生成する ToString(IFormatProvider) メソッド。
ToString(IFormatProvider) により、カスタム書式設定をサポートする IFormatProvider インターフェイスのユーザー定義の実装が提供されます。詳細については、「ICustomFormatter を使用したカスタム書式設定」の「.NET での書式設定」のセクションを参照してください。
挿入文字列から IFormattable インスタンスへの変換。これは、単一の IFormattable インスタンスから、カルチャ固有のコンテンツを持つ複数の結果文字列の作成も可能にするものです。

次の例では、カルチャ固有の結果の文字列を作成するために、FormattableString への暗黙の変換を使用します。

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.

その他のリソース

文字列補間を初めてお使いの場合は、C# の文字列補完に関する対話形式チュートリアルを参照してください。また、別の「C# における文字列補間」チュートリアルを参照することもできます。このチュートリアルでは、補間された文字列を使用して書式設定された文字列を生成する方法が示されています。

補完文字列のコンパイル

補完文字列が string 型の場合、通常は String.Format メソッドの呼び出しに変換されます。分析後の動作が連結と等しくなるようであれば、コンパイラでは、String.Format を String.Concat に置換する場合があります。

補間文字列の型が IFormattable または FormattableString の場合、コンパイラは FormattableStringFactory.Create メソッドの呼び出しを生成します。

C# 10 以降では、補間された文字列を使用する場合、補間された文字列が "補間された文字列ハンドラーパターン" を満たす型に代入されているかどうかがコンパイラによって確認されます。 "補間された文字列ハンドラー" は、補間された文字列を文字列に変換するカスタム型です。補間された文字列ハンドラーは高度なシナリオであり、通常はパフォーマンス上の理由で使用されます。補間された文字列ハンドラーを作成するための要件の詳細については、補間された文字列の改善のための言語仕様を参照してください。「C# の新機能」セクションにある補間された文字列ハンドラーのチュートリアルに従って作成できます。 .NET 6 では、string 型の引数に補間された文字列を使用すると、補間された文字列は System.Runtime.CompilerServices.DefaultInterpolatedStringHandler によって処理されます。

注意

補間された文字列ハンドラーの副作用の 1 つは、System.Runtime.CompilerServices.DefaultInterpolatedStringHandler を含むカスタムハンドラーでは、すべての条件下で、補間された文字列のプレースホルダーとして使用されているすべての式が評価されない可能性があることです。つまり、それらの式の副作用が発生しない可能性があります。

C# 言語仕様

詳細については、C# 言語仕様の補間文字列セクション、C# 11 - Raw 文字列リテラル機能仕様、C# 11 - 文字列補間の改行機能仕様を参照してください。

$ を使う文字列補間

挿入文字列の構造

特殊文字

暗黙的な変換と IFormatProvider 実装の指定方法

その他のリソース

補完文字列のコンパイル

C# 言語仕様

関連項目

その他のリソース

その他のリソース

`$` を使う文字列補間

暗黙的な変換と `IFormatProvider` 実装の指定方法