System.String.Format メソッド

[アーティクル]
01/30/2024

この記事は、この API のリファレンスドキュメントの補足説明です。

重要

String.Format メソッドを呼び出す、あるいは複合書式指定文字列を使用する代わりに、お使いの言語でサポートされている場合、挿入文字列を使用できます。挿入文字列は、挿入式が含まれている文字列です。各挿入式は式の値によって解かれ、文字列が割り当てられるとき、結果文字列に含まれます。詳細については、文字列補間 (C# リファレンス) および補間文字列 (Visual Basic リファレンス) に関するページを参照してください。

例

メソッドを呼び出す Format 多くの例は、この記事全体に散在しています。 C# 用の .NET Core プロジェクトが含まれている一連のString.Formatサンプルをダウンロードすることもできます。

この記事に含まれる例の一部を次に示します。

書式指定文字列を作成する

文字列を挿入する
 書式項目
 同じインデックスを持つアイテムの書式設定

書式設定された出力を制御する

コントロールの書式設定
 コントロールの間隔
 配置を制御する
 整数の桁数を制御する
 小数点区切り記号の後の桁数を制御する
 結果文字列にリテラル中かっこを含める

書式指定文字列をカルチャに依存させる

書式設定操作をカスタマイズする

カスタム書式設定操作
 インターセプトプロバイダーとローマ数字フォーマッタ

String.Format メソッドの概要

オブジェクト、変数、または式の値を別の文字列に挿入する必要がある場合に使用 String.Format します。たとえば、値の値を Decimal 文字列に挿入して、1 つの文字列としてユーザーに表示できます。

Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0} per ounce.",
                         pricePerOunce);
Console.WriteLine(s);
// Result: The current price is 17.36 per ounce.

let pricePerOunce = 17.36m
String.Format("The current price is {0} per ounce.", pricePerOunce)
|> printfn "%s"
// Result: The current price is 17.36 per ounce.

Dim pricePerOunce As Decimal = 17.36D
Dim s As String = String.Format("The current price is {0} per ounce.",
                              pricePerOunce)
' Result: The current price is 17.36 per ounce.

また、その値の書式設定を制御できます。

Decimal pricePerOunce = 17.36m;
String s = String.Format("The current price is {0:C2} per ounce.",
                         pricePerOunce);
Console.WriteLine(s);
// Result if current culture is en-US:
//      The current price is $17.36 per ounce.

let pricePerOunce = 17.36m
String.Format("The current price is {0:C2} per ounce.", pricePerOunce)
|> printfn "%s"
// Result if current culture is en-US:
//      The current price is $17.36 per ounce.

Dim pricePerOunce As Decimal = 17.36D
Dim s As String = String.Format("The current price is {0:C2} per ounce.",
                              pricePerOunce)
' Result if current culture is en-US:
'      The current price is $17.36 per ounce.

書式設定に加えて、配置と間隔を制御することもできます。

文字列を挿入する

String.Format は書式指定文字列で始まり、その後に 1 つ以上のオブジェクトまたは式が続き、文字列に変換され、書式指定文字列内の指定された場所に挿入されます。次に例を示します。

decimal temp = 20.4m;
string s = String.Format("The temperature is {0}°C.", temp);
Console.WriteLine(s);
// Displays 'The temperature is 20.4°C.'

let temp = 20.4m
String.Format("The temperature is {0}°C.", temp)
|> printfn "%s"
// Displays 'The temperature is 20.4°C.'

Dim temp As Decimal = 20.4D
Dim s As String = String.Format("The temperature is {0}°C.", temp)
Console.WriteLine(s)
' Displays 'The temperature is 20.4°C.'

{0}書式指定文字列は書式指定項目です。 0 は、その位置に文字列値が挿入されるオブジェクトのインデックスです。 (インデックスは 0 から始まります)。挿入するオブジェクトが文字列でない場合は、結果 ToString 文字列に挿入する前にメソッドを呼び出して 1 に変換します。

オブジェクトリストで 2 つの書式項目と 2 つのオブジェクトを使用する別の例を次に示します。

string s = String.Format("At {0}, the temperature is {1}°C.",
                         DateTime.Now, 20.4);
Console.WriteLine(s);
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'

String.Format("At {0}, the temperature is {1}°C.", DateTime.Now, 20.4)
|> printfn "%s"
// Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'

Dim s As String = String.Format("At {0}, the temperature is {1}°C.",
                              Date.Now, 20.4)
' Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.'

すべての書式項目のインデックスにオブジェクトリスト内の一致するオブジェクトが含まれている限り、必要な数の書式項目とオブジェクトをオブジェクトリストに含めることができます。また、呼び出すオーバーロードについて心配する必要はありません。コンパイラが適切なものを選択します。

コントロールの書式設定

書式指定文字列を含む書式指定項目のインデックスに従って、オブジェクトの書式設定方法を制御できます。たとえば、 {0:d} "d" 書式指定文字列をオブジェクトリストの最初のオブジェクトに適用します。 1 つのオブジェクトと 2 つの書式項目の例を次に示します。

string s = String.Format("It is now {0:d} at {0:t}", DateTime.Now);
Console.WriteLine(s);
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'

String.Format("It is now {0:d} at {0:t}", DateTime.Now)
|> printfn "%s"
// Output similar to: 'It is now 4/10/2015 at 10:04 AM'

Dim s As String = String.Format("It is now {0:d} at {0:t}",
                              Date.Now)
' Output similar to: 'It is now 4/10/2015 at 10:04 AM'

すべての数値型 (標準書式指定文字列とカスタム書式指定文字列の両方)、すべての日付と時刻 (標準書式指定文字列とカスタム書式指定文字列の両方)、時間間隔 (標準書式指定文字列とカスタム書式指定文字列の両方)、すべての列挙型列挙型、GUID など、さまざまな種類の書式指定文字列がサポートされています。書式指定文字列のサポートを独自の型に追加することもできます。

コントロールの間隔

12 文字の文字列を挿入する構文を {0,12}使用して、結果文字列に挿入される文字列の幅を定義できます。この場合、最初のオブジェクトの文字列表現は、12 文字のフィールドで右揃えになります。 (ただし、最初のオブジェクトの文字列表現の長さが 12 文字を超える場合、優先フィールドの幅は無視され、文字列全体が結果文字列に挿入されます)。

次の例では、文字列 "Year" といくつかの年の文字列を保持する 6 文字のフィールドと、文字列 "Population" と一部の母集団データを保持する 15 文字のフィールドを定義します。フィールド内で文字が右揃えになっていることに注意してください。

int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
var sb = new System.Text.StringBuilder();
sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population"));
for (int index = 0; index < years.Length; index++)
    sb.Append(String.Format("{0,6} {1,15:N0}\n", years[index], population[index]));

Console.WriteLine(sb);

// Result:
//      Year      Population
//
//      2013       1,025,632
//      2014       1,105,967
//      2015       1,148,203

open System
open System.Text
 
let years = [| 2013; 2014; 2015 |]
let population = [| 1025632; 1105967; 1148203 |]
let sb = StringBuilder()
sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population")) |> ignore
for i = 0 to years.Length - 1 do
   sb.Append(String.Format("{0,6} {1,15:N0}\n", years[i], population[i])) |> ignore

printfn $"{sb}"

// Result:
//      Year      Population
//
//      2013       1,025,632
//      2014       1,105,967
//      2015       1,148,203

Dim years() As Integer = {2013, 2014, 2015}
Dim population() As Integer = {1025632, 1105967, 1148203}
Dim sb As New StringBuilder()
sb.Append(String.Format("{0,6} {1,15}{2}{2}",
                       "Year", "Population", vbCrLf))
For index As Integer = 0 To years.Length - 1
    sb.AppendFormat("{0,6} {1,15:N0}{2}",
                  years(index), population(index), vbCrLf)
Next
' Result:
'      Year      Population
'
'      2013       1,025,632
'      2014       1,105,967
'      2015       1,148,203

配置を制御する

既定では、フィールドの幅を指定すると、文字列はフィールド内で右揃えになります。フィールド内の文字列を左揃えにするには、12 文字の左揃えフィールドを定義するなど {0,-12} 、フィールド幅の前に負の符号を付けます。

次の例は前の例と似ていますが、ラベルとデータの両方が左揃えになっている点が異なります。

int[] years = { 2013, 2014, 2015 };
int[] population = { 1025632, 1105967, 1148203 };
String s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population");
for (int index = 0; index < years.Length; index++)
    s += String.Format("{0,-10} {1,-10:N0}\n",
                       years[index], population[index]);
Console.WriteLine($"\n{s}");
// Result:
//    Year       Population
//
//    2013       1,025,632
//    2014       1,105,967
//    2015       1,148,203

let years = [| 2013; 2014; 2015 |]
let population = [| 1025632; 1105967; 1148203 |]
let mutable s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population")
for i = 0 to years.Length - 1 do
    s <- s + String.Format("{0,-10} {1,-10:N0}\n", years[i], population[i])
printfn $"\n{s}"
// Result:
//    Year       Population
//
//    2013       1,025,632
//    2014       1,105,967
//    2015       1,148,203

Dim years() As Integer = {2013, 2014, 2015}
Dim population() As Integer = {1025632, 1105967, 1148203}
Dim s As String = String.Format("{0,-10} {1,-10}{2}{2}",
                               "Year", "Population", vbCrLf)
For index As Integer = 0 To years.Length - 1
    s += String.Format("{0,-10} {1,-10:N0}{2}",
                     years(index), population(index), vbCrLf)
Next
' Result:
'    Year       Population
'
'    2013       1,025,632
'    2014       1,105,967
'    2015       1,148,203

String.Format では、複合書式設定機能が使用されます。詳細については、「複合書式指定」をご覧ください。

どのメソッドを呼び出しますか?

受信先	Call
現在のカルチャの規則を使用して、1 つ以上のオブジェクトを書式設定します。	パラメーターを含む`provider`オーバーロードを除き、再メインFormatオーバーロードには、パラメーターの後に 1 つ以上のオブジェクトパラメーターが含まれますString。このため、呼び出すオーバーロードを決定 Format する必要はありません。言語コンパイラは、引数リストに基づいて、パラメーターを持 `provider` たないオーバーロードの中から適切なオーバーロードを選択します。たとえば、引数リストに 5 つの引数がある場合、コンパイラはメソッドを Format(String, Object[]) 呼び出します。
特定のカルチャの規則を使用して、1 つ以上のオブジェクトを書式設定します。	パラメーターで`provider`始まる各Formatオーバーロードには、パラメーターと 1 つ以上のStringオブジェクトパラメーターが続きます。このため、呼び出す特定 Format のオーバーロードを決定する必要はありません。言語コンパイラは、引数リストに基づいて、パラメーターを持つ `provider` オーバーロードの中から適切なオーバーロードを選択します。たとえば、引数リストに 5 つの引数がある場合、コンパイラはメソッドを Format(IFormatProvider, String, Object[]) 呼び出します。
実装または実装を使用 ICustomFormatter して、カスタム書式設定操作を IFormattable 実行します。	パラメーターを持つ `provider` 4 つのオーバーロードのいずれか。コンパイラは、引数リストに基づいて、パラメーターを持つ `provider` オーバーロードの中から適切なオーバーロードを選択します。

Format メソッドの概要

メソッドのFormat各オーバーロードでは、複合書式指定機能を使用して、書式指定項目と呼ばれる 0 から始まるインデックス付きプレースホルダーを複合書式指定文字列に含めます。実行時に、各書式項目は、パラメーターリスト内の対応する引数の文字列形式に置き換えられます。引数の値が null〘の場合、書式項目は String.Empty. たとえば、次のメソッドの Format(String, Object, Object, Object) 呼び出しには、3 つの書式指定項目を {0}含む書式指定文字列、 {1}および {2}3 つの項目を含む引数リストが含まれます。

DateTime dat = new DateTime(2012, 1, 17, 9, 30, 0); 
string city = "Chicago";
int temp = -16;
string output = String.Format("At {0} in {1}, the temperature was {2} degrees.",
                              dat, city, temp);
Console.WriteLine(output);
// The example displays output like the following:
//    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.

open System

let dat = DateTime(2012, 1, 17, 9, 30, 0) 
let city = "Chicago"
let temp = -16
String.Format("At {0} in {1}, the temperature was {2} degrees.", dat, city, temp)
|> printfn "%s"
// The example displays output like the following:
//    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.

Dim dat As Date = #1/17/2012 9:30AM#
Dim city As String = "Chicago"
Dim temp As Integer = -16
Dim output As String = String.Format("At {0} in {1}, the temperature was {2} degrees.",
                                   dat, city, temp)
Console.WriteLine(output)
' The example displays the following output:
'    At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees.

書式項目

書式項目には、次の構文があります。

{index[,alignment][:formatString]}

角かっこは省略可能な要素を示します。左中かっこと右中かっこが必要です。 (リテラルの開始中かっこまたは右中かっこを書式文字列に含めるには、次を参照してください。複合書式に関する記事の中かっこのエスケープセクション。

たとえば、通貨値を書式設定する書式項目は、次のように表示されます。

var value = String.Format("{0,-10:C}", 126347.89m);
Console.WriteLine(value);

open System

String.Format("{0,-10:C}", 126347.89m)         
|> printfn "%s"

String.Format("{0,-10:C}", 126347.89D)

書式項目には、次の要素があります。

インデックス
文字列形式が文字列内のこの位置に含まれる引数の 0 から始まるインデックス。この引数が指定されている場合、 null空の文字列が文字列内のこの位置に含まれます。

配置
省略可能。引数が挿入されるフィールドの合計長と、引数が右揃え (正の整数) か左揃え (負の整数) かを示す符号付き整数。配置を省略すると、対応する引数の文字列形式が、先頭または末尾のスペースのないフィールドに挿入されます。

配置の値が挿入する引数の長さより小さい場合、配置は無視され、引数の文字列表現の長さがフィールドの幅として使用されます。

Formatstring
省略可能。対応する引数の結果文字列の形式を指定する文字列。 formatString を省略すると、対応する引数のパラメーターなしのToStringメソッドが呼び出されて、その文字列表現が生成されます。 formatString を指定する場合、書式指定項目によって参照される引数はインターフェイスを実装するIFormattable必要があります。書式指定文字列をサポートする型は次のとおりです。

すべての整数型と浮動小数点型。 (「標準の数値書式指定文字列とカスタム数値書式指定文字列。
DateTime および DateTimeOffset。 (「標準の日付と時刻の書式指定文字列とカスタムの日付と時刻の書式指定文字列。
すべての列挙型。 (「列挙型書式指定文字列。)
TimeSpan 値。 (「標準の TimeSpan 書式指定文字列とカスタム TimeSpan 書式指定文字列)。
GUID。 (メソッドを Guid.ToString(String) 参照してください)。)

ただし、任意のカスタム型で既存の型のIFormattable実装を実装IFormattableまたは拡張できることに注意してください。

次の例では、and formatString 引数をalignment使用して書式設定された出力を生成します。

// Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
Tuple<string, DateTime, int, DateTime, int>[] cities = 
    { Tuple.Create("Los Angeles", new DateTime(1940, 1, 1), 1504277, 
                   new DateTime(1950, 1, 1), 1970358),
      Tuple.Create("New York", new DateTime(1940, 1, 1), 7454995, 
                   new DateTime(1950, 1, 1), 7891957),  
      Tuple.Create("Chicago", new DateTime(1940, 1, 1), 3396808, 
                   new DateTime(1950, 1, 1), 3620962),  
      Tuple.Create("Detroit", new DateTime(1940, 1, 1), 1623452, 
                   new DateTime(1950, 1, 1), 1849568) };

// Display header
var header = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n",
                              "City", "Year", "Population", "Change (%)");
Console.WriteLine(header);
foreach (var city in cities) {
   var output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                          city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
                          (city.Item5 - city.Item3)/ (double)city.Item3);
   Console.WriteLine(output);
}
// The example displays the following output:
//    City            Year  Population    Year  Population    Change (%)
//  
//    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
//    New York        1940   7,454,995    1950   7,891,957         5.9 %
//    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
//    Detroit         1940   1,623,452    1950   1,849,568        13.9 %

// Create a list of 5-tuples with population data for three U.S. cities, 1940-1950.
let cities = 
    [ "Los Angeles", DateTime(1940, 1, 1), 1504277, DateTime(1950, 1, 1), 1970358
      "New York", DateTime(1940, 1, 1), 7454995, DateTime(1950, 1, 1), 7891957
      "Chicago", DateTime(1940, 1, 1), 3396808, DateTime(1950, 1, 1), 3620962
      "Detroit", DateTime(1940, 1, 1), 1623452, DateTime(1950, 1, 1), 1849568 ]

// Display header
String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n", "City", "Year", "Population", "Change (%)")
|> printfn "%s"

for name, year1, pop1, year2, pop2 in cities do
    String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                  name, year1, pop1, year2, pop2,
                  double (pop2 - pop1) / double pop1)
    |> printfn "%s"
// The example displays the following output:
//    City            Year  Population    Year  Population    Change (%)
//  
//    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
//    New York        1940   7,454,995    1950   7,891,957         5.9 %
//    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
//    Detroit         1940   1,623,452    1950   1,849,568        13.9 %

Module Example3
    Public Sub Main()
        ' Create array of 5-tuples with population data for three U.S. cities, 1940-1950.
        Dim cities() =
          {Tuple.Create("Los Angeles", #1/1/1940#, 1504277, #1/1/1950#, 1970358),
            Tuple.Create("New York", #1/1/1940#, 7454995, #1/1/1950#, 7891957),
            Tuple.Create("Chicago", #1/1/1940#, 3396808, #1/1/1950#, 3620962),
            Tuple.Create("Detroit", #1/1/1940#, 1623452, #1/1/1950#, 1849568)}

        ' Display header
        Dim header As String = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}",
                                           "City", "Year", "Population", "Change (%)")
        Console.WriteLine(header)
        Console.WriteLine()
        For Each city In cities
            Dim output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}",
                                city.Item1, city.Item2, city.Item3, city.Item4, city.Item5,
                                (city.Item5 - city.Item3) / city.Item3)
            Console.WriteLine(output)
        Next
    End Sub
End Module
' The example displays the following output:
'    City            Year  Population    Year  Population    Change (%)
'    
'    Los Angeles     1940   1,504,277    1950   1,970,358        31.0 %
'    New York        1940   7,454,995    1950   7,891,957         5.9 %
'    Chicago         1940   3,396,808    1950   3,620,962         6.6 %
'    Detroit         1940   1,623,452    1950   1,849,568        13.9 %

引数の書式設定方法

書式指定項目は、文字列の先頭から順番に処理されます。各書式項目には、メソッドの引数リスト内のオブジェクトに対応するインデックスがあります。このメソッドは Format 引数を取得し、次のように文字列表現を派生させます。

引数が指定されている場合、メソッドは null結果文字列に挿入します String.Empty 。 for null 引数の処理 NullReferenceException に関係する必要はありません。
オーバーロードをFormat(IFormatProvider, String, Object[])呼び出し、providerオブジェクトの実装が null ICustomFormatter 以外のIFormatProvider.GetFormat実装を返す場合、引数はそのメソッドにICustomFormatter.Format(String, Object, IFormatProvider)渡されます。書式指定項目に formatString 引数が含まれている場合は、最初の引数としてメソッドに渡されます。実装が ICustomFormatter 使用可能で null 以外の文字列が生成された場合、その文字列は引数の文字列表現として返されます。それ以外の場合は、次の手順が実行されます。
引数がインターフェイスを実装する IFormattable 場合は、その IFormattable.ToString 実装が呼び出されます。
基底クラスの実装をオーバーライドまたは継承する引数のパラメーターなしの ToString メソッドが呼び出されます。

メソッドの呼び出しをICustomFormatter.Formatインターセプトし、複合書式指定文字列の書式項目ごとにメソッドが書式設定メソッドに渡す情報Formatを確認できる例については、「例: インターセプトプロバイダーとローマ数字フォーマッタ」を参照してください。

詳細については、処理順序を参照してください。

同じインデックスを持つアイテムの書式設定

インデックス項目のFormatExceptionインデックスが引数リスト内の引数の数以上の場合、メソッドはFormat例外をスローします。ただし、複数の format 書式指定項目のインデックスが同じである限り、引数よりも多くの書式項目を含めることができます。次の例のメソッドの Format(String, Object) 呼び出しでは、引数リストには 1 つの引数がありますが、書式指定文字列には 2 つの書式項目が含まれています。1 つは数値の 10 進値を表示し、もう 1 つは 16 進数の値を表示します。

short[] values= { Int16.MinValue, -27, 0, 1042, Int16.MaxValue };
Console.WriteLine("{0,10}  {1,10}\n", "Decimal", "Hex");
foreach (short value in values)
{
   string formatString = String.Format("{0,10:G}: {0,10:X}", value);
   Console.WriteLine(formatString);
}   
// The example displays the following output:
//       Decimal         Hex
//    
//        -32768:       8000
//           -27:       FFE5
//             0:          0
//          1042:        412
//         32767:       7FFF

open System

let values= [| Int16.MinValue; -27s; 0s; 1042s; Int16.MaxValue |]
printfn "%10s  %10s\n" "Decimal" "Hex"
for value in values do
    String.Format("{0,10:G}: {0,10:X}", value)
    |> printfn "%s"
// The example displays the following output:
//       Decimal         Hex
//    
//        -32768:       8000
//           -27:       FFE5
//             0:          0
//          1042:        412
//         32767:       7FFF

Module Example1
    Public Sub Main()
        Dim values() As Short = {Int16.MinValue, -27, 0, 1042, Int16.MaxValue}
        Console.WriteLine("{0,10}  {1,10}", "Decimal", "Hex")
        Console.WriteLine()
        For Each value As Short In values
            Dim formatString As String = String.Format("{0,10:G}: {0,10:X}", value)
            Console.WriteLine(formatString)
        Next
    End Sub
End Module
' The example displays the following output:
'       Decimal         Hex
'    
'        -32768:       8000
'           -27:       FFE5
'             0:          0
'          1042:        412
'         32767:       7FFF

書式とカルチャ

通常、引数リスト内のオブジェクトは、プロパティによって返される現在のカルチャの規則を使用して、文字列形式に CultureInfo.CurrentCulture 変換されます。この動作は、パラメーターを含むproviderオーバーロードのいずれかをFormat呼び出すことによって制御できます。パラメーターは provider 、書式設定プロセスを IFormatProvider モデレートするために使用されるカスタムおよびカルチャ固有の書式設定情報を提供する実装です。

IFormatProviderインターフェイスには 1 つのメンバーがあり、GetFormat書式設定情報を提供するオブジェクトを返します。 .NET には、カルチャ固有の書式設定を提供する 3 つの IFormatProvider 実装があります。

CultureInfo. そのメソッドは GetFormat 、数値を書式設定するためのカルチャ固有 NumberFormatInfo のオブジェクトと、日付と時刻の値を書式設定するためのカルチャ固有 DateTimeFormatInfo のオブジェクトを返します。
DateTimeFormatInfoは、日付と時刻の値のカルチャ固有の書式設定に使用されます。そのメソッドは GetFormat それ自体を返します。
NumberFormatInfoは、数値のカルチャ固有の書式設定に使用されます。そのメソッドは GetFormat(Type) それ自体を返します。

カスタム書式設定操作

カスタム書式設定操作を実行する型IFormatProviderのFormatパラメーターを持つproviderメソッドのオーバーロードのいずれかを呼び出すこともできます。たとえば、整数を識別番号または電話番号として書式設定できます。カスタム書式設定を実行するには、引数にproviderインターフェイスとICustomFormatterインターフェイスの両方を実装するIFormatProvider必要があります。メソッドがFormat引数としてprovider実装をICustomFormatter渡されると、メソッドはその実装をFormat IFormatProvider.GetFormat呼び出し、型のオブジェクトを要求しますICustomFormatter。次に、返されたオブジェクトのFormatメソッドを呼び出して、渡されたICustomFormatter複合文字列内の各書式項目を書式設定します。

カスタム書式設定ソリューションの提供の詳細については、「方法: カスタム数値書式プロバイダーを定義して使用する ICustomFormatter」および「整数を書式設定されたカスタム数値に変換する例については、「例: カスタム書式設定操作」を参照してください。符号なしバイトをローマ数字に変換する例については、「例: インターセプトプロバイダーとローマ数字フォーマッタ」を参照してください。

例: カスタム書式設定操作

この例では、整数値を x-xxxxx-xx 形式の顧客アカウント番号として書式設定する書式プロバイダーを定義します。

using System;

public class TestFormatter
{
   public static void Main()
   {
      int acctNumber = 79203159;
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:G}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:S}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:P}", acctNumber));
      try {
         Console.WriteLine(String.Format(new CustomerFormatter(), "{0:X}", acctNumber));
      }
      catch (FormatException e) {
         Console.WriteLine(e.Message);
      }
   }
}

public class CustomerFormatter : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType) 
   {
      if (formatType == typeof(ICustomFormatter))        
         return this; 
      else
         return null;
   }
   
   public string Format(string format, 
                         object arg, 
                         IFormatProvider formatProvider) 
   {                       
      if (! this.Equals(formatProvider))
      {
         return null;
      }
      else
      {
         if (String.IsNullOrEmpty(format)) 
            format = "G";
         
         string customerString = arg.ToString();
         if (customerString.Length < 8)
            customerString = customerString.PadLeft(8, '0');
         
         format = format.ToUpper();
         switch (format)
         {
            case "G":
               return customerString.Substring(0, 1) + "-" +
                                     customerString.Substring(1, 5) + "-" +
                                     customerString.Substring(6);
            case "S":                          
               return customerString.Substring(0, 1) + "/" +
                                     customerString.Substring(1, 5) + "/" +
                                     customerString.Substring(6);
            case "P":                          
               return customerString.Substring(0, 1) + "." +
                                     customerString.Substring(1, 5) + "." +
                                     customerString.Substring(6);
            default:
               throw new FormatException( 
                         String.Format("The '{0}' format specifier is not supported.", format));
         }
      }   
   }
}
// The example displays the following output:
//       7-92031-59
//       7-92031-59
//       7/92031/59
//       7.92031.59
//       The 'X' format specifier is not supported.

open System

type CustomerFormatter() = 
    interface IFormatProvider with
        member this.GetFormat(formatType) =
            if formatType = typeof<ICustomFormatter> then
                this
            else
                null

    interface ICustomFormatter with
        member this.Format(format, arg, formatProvider: IFormatProvider) = 
            if this.Equals formatProvider |> not then
                null
            else
                let format = 
                    if String.IsNullOrEmpty format then "G"
                    else format.ToUpper()
                
                let customerString = 
                    let s = string arg
                    if s.Length < 8 then
                        s.PadLeft(8, '0')
                    else s
                
                match format with
                | "G" ->
                    customerString.Substring(0, 1) + "-" +
                        customerString.Substring(1, 5) + "-" +
                        customerString.Substring 6
                | "S" ->                          
                    customerString.Substring(0, 1) + "/" +
                        customerString.Substring(1, 5) + "/" +
                        customerString.Substring 6
                | "P" ->                          
                    customerString.Substring(0, 1) + "." +
                        customerString.Substring(1, 5) + "." +
                        customerString.Substring 6
                | _ ->
                    raise (FormatException $"The '{format}' format specifier is not supported.")

let acctNumber = 79203159
String.Format(CustomerFormatter(), "{0}", acctNumber)
|> printfn "%s"
String.Format(CustomerFormatter(), "{0:G}", acctNumber)
|> printfn "%s"
String.Format(CustomerFormatter(), "{0:S}", acctNumber)
|> printfn "%s"
String.Format(CustomerFormatter(), "{0:P}", acctNumber)
|> printfn "%s"
try
    String.Format(CustomerFormatter(), "{0:X}", acctNumber)
    |> printfn "%s"
with :? FormatException as e ->
    printfn $"{e.Message}"

// The example displays the following output:
//       7-92031-59
//       7-92031-59
//       7/92031/59
//       7.92031.59
//       The 'X' format specifier is not supported.

Module TestFormatter
   Public Sub Main()
      Dim acctNumber As Integer = 79203159
      Console.WriteLine(String.Format(New CustomerFormatter, "{0}", acctNumber))
      Console.WriteLine(String.Format(New CustomerFormatter, "{0:G}", acctNumber))
      Console.WriteLine(String.Format(New CustomerFormatter, "{0:S}", acctNumber))
      Console.WriteLine(String.Format(New CustomerFormatter, "{0:P}", acctNumber))
      Try
         Console.WriteLine(String.Format(New CustomerFormatter, "{0:X}", acctNumber))
      Catch e As FormatException
         Console.WriteLine(e.Message)
      End Try   
   End Sub
End Module

Public Class CustomerFormatter : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(type As Type) As Object  _
                   Implements IFormatProvider.GetFormat
      If type Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function
   
   Public Function Format(fmt As String, _
                           arg As Object, _
                           formatProvider As IFormatProvider) As String _
                    Implements ICustomFormatter.Format
      If Not Me.Equals(formatProvider) Then
         Return Nothing
      Else
         If String.IsNullOrEmpty(fmt) Then fmt = "G"
         
         Dim customerString As String = arg.ToString()
         if customerString.Length < 8 Then _
            customerString = customerString.PadLeft(8, "0"c)
         
         Select Case fmt
            Case "G"
               Return customerString.Substring(0, 1) & "-" & _
                                     customerString.Substring(1, 5) & "-" & _
                                     customerString.Substring(6)
            Case "S"                         
               Return customerString.Substring(0, 1) & "/" & _
                                     customerString.Substring(1, 5) & "/" & _
                                     customerString.Substring(6)
            Case "P"
               Return customerString.Substring(0, 1) & "." & _
                                     customerString.Substring(1, 5) & "." & _
                                     customerString.Substring(6)
            Case Else
               Throw New FormatException( _
                         String.Format("The '{0}' format specifier is not supported.", fmt))
         End Select                                                     
      End If   
   End Function
End Class
' The example displays the following output:
'       7-92031-59
'       7-92031-59
'       7/92031/59
'       7.92031.59
'       The 'X' format specifier is not supported.

例: インターセプトプロバイダーとローマ数字フォーマッタ

この例では、次の 2 つの処理を ICustomFormatter 行うインターフェイスを IFormatProvider 実装するカスタム形式プロバイダーを定義します。

実装 ICustomFormatter.Format に渡されたパラメーターが表示されます。これにより、メソッドが書式設定を試みる各オブジェクトのカスタム書式設定実装に渡すパラメーター Format(IFormatProvider, String, Object[]) を確認できます。これは、アプリケーションをデバッグするときに役立ちます。
書式設定するオブジェクトが、"R" 標準書式指定文字列を使用して書式設定される符号なしバイト値である場合、カスタムフォーマッタは数値をローマ数字として書式設定します。

using System;
using System.Globalization;

public class InterceptProvider : IFormatProvider, ICustomFormatter
{
   public object GetFormat(Type formatType)
   {
      if (formatType == typeof(ICustomFormatter))
         return this;
      else
         return null;
   }
   
   public string Format(String format, Object obj, IFormatProvider provider) 
   {
      // Display information about method call.
      string formatString = format ?? "<null>";
      Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
                        provider.GetType().Name, obj ?? "<null>", formatString);
                        
      if (obj == null) return String.Empty;
            
      // If this is a byte and the "R" format string, format it with Roman numerals.
      if (obj is Byte && formatString.ToUpper().Equals("R")) {
         Byte value = (Byte) obj;
         int remainder;
         int result;
         String returnString = String.Empty;

         // Get the hundreds digit(s)
         result = Math.DivRem(value, 100, out remainder);
         if (result > 0)  
            returnString = new String('C', result);
         value = (Byte) remainder;
         // Get the 50s digit
         result = Math.DivRem(value, 50, out remainder);
         if (result == 1)
            returnString += "L";
         value = (Byte) remainder;
         // Get the tens digit.
         result = Math.DivRem(value, 10, out remainder);
         if (result > 0)
            returnString += new String('X', result);
         value = (Byte) remainder; 
         // Get the fives digit.
         result = Math.DivRem(value, 5, out remainder);
         if (result > 0)
            returnString += "V";
         value = (Byte) remainder;
         // Add the ones digit.
         if (remainder > 0) 
            returnString += new String('I', remainder);
         
         // Check whether we have too many X characters.
         int pos = returnString.IndexOf("XXXX");
         if (pos >= 0) {
            int xPos = returnString.IndexOf("L"); 
            if (xPos >= 0 & xPos == pos - 1)
               returnString = returnString.Replace("LXXXX", "XC");
            else
               returnString = returnString.Replace("XXXX", "XL");   
         }
         // Check whether we have too many I characters
         pos = returnString.IndexOf("IIII");
         if (pos >= 0)
            if (returnString.IndexOf("V") >= 0)
               returnString = returnString.Replace("VIIII", "IX");
            else
               returnString = returnString.Replace("IIII", "IV");    

         return returnString; 
      }   

      // Use default for all other formatting.
      if (obj is IFormattable)
         return ((IFormattable) obj).ToString(format, CultureInfo.CurrentCulture);
      else
         return obj.ToString();
   }
}

public class Example
{
   public static void Main()
   {
      int n = 10;
      double value = 16.935;
      DateTime day = DateTime.Now;
      InterceptProvider provider = new InterceptProvider();
      Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day));
      Console.WriteLine(String.Format(provider, "{0}: {1:F}\n", "Today: ", 
                                      (DayOfWeek) DateTime.Now.DayOfWeek));
      Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", 
                                      (Byte) 2, (Byte) 12, (Byte) 199));
      Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}\n", 
                                      (Byte) 2, (Byte) 12, (Byte) 199));
   }
}
// The example displays the following output:
//    Provider: InterceptProvider, Object: 10, Format String: N0
//    Provider: InterceptProvider, Object: 16.935, Format String: C2
//    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
//    10: $16.94 on 1/31/2013
//    
//    Provider: InterceptProvider, Object: Today: , Format String: <null>
//    Provider: InterceptProvider, Object: Thursday, Format String: F
//    Today: : Thursday
//    
//    Provider: InterceptProvider, Object: 2, Format String: X
//    Provider: InterceptProvider, Object: 12, Format String: <null>
//    Provider: InterceptProvider, Object: 199, Format String: <null>
//    2, 12, 199
//    
//    Provider: InterceptProvider, Object: 2, Format String: R
//    Provider: InterceptProvider, Object: 12, Format String: R
//    Provider: InterceptProvider, Object: 199, Format String: R
//    II, XII, CXCIX

open System
open System.Globalization

type InterceptProvider() =
    interface IFormatProvider with
        member this.GetFormat(formatType) =
            if formatType = typeof<ICustomFormatter> then
                this
            else
                null
    interface ICustomFormatter with
        member _.Format(format, obj, provider: IFormatProvider) = 
            // Display information about method call.
            let formatString =
                if format = null then "<null>" else format
            printfn $"Provider: {provider.GetType().Name}, Object: %A{obj}, Format String: %s{formatString}"
                                
            if obj = null then
                String.Empty
            else
                // If this is a byte and the "R" format string, format it with Roman numerals.
                match obj with
                | :? byte as value when formatString.ToUpper().Equals "R" -> 
                    let mutable returnString = String.Empty

                    // Get the hundreds digit(s)
                    let struct (result, remainder) = Math.DivRem(value, 100uy)
                    if result > 0uy then
                        returnString <- String('C', int result)
                    let value = byte remainder
                    // Get the 50s digit
                    let struct (result, remainder) = Math.DivRem(value, 50uy)
                    if result = 1uy then
                        returnString <- returnString + "L"
                    let value = byte remainder
                    // Get the tens digit.
                    let struct (result, remainder) = Math.DivRem(value, 10uy)
                    if result > 0uy then
                        returnString <- returnString + String('X', int result)
                    let value = byte remainder 
                    // Get the fives digit.
                    let struct (result, remainder) = Math.DivRem(value, 5uy)
                    if result > 0uy then
                        returnString <- returnString + "V"
                    let value = byte remainder
                    // Add the ones digit.
                    if remainder > 0uy then 
                        returnString <- returnString + String('I', int remainder)
                    
                    // Check whether we have too many X characters.
                    let pos = returnString.IndexOf "XXXX"
                    if pos >= 0 then
                        let xPos = returnString.IndexOf "L" 
                        returnString <-
                            if xPos >= 0 && xPos = pos - 1 then
                                returnString.Replace("LXXXX", "XC")
                            else
                                returnString.Replace("XXXX", "XL")   
                    // Check whether we have too many I characters
                    let pos = returnString.IndexOf "IIII"
                    if pos >= 0 then
                        returnString <-
                            if returnString.IndexOf "V" >= 0 then
                                returnString.Replace("VIIII", "IX")
                            else
                                returnString.Replace("IIII", "IV")    
                    returnString 

                // Use default for all other formatting.
                | :? IFormattable as x ->
                    x.ToString(format, CultureInfo.CurrentCulture)
                | _ ->
                    string obj

let n = 10
let value = 16.935
let day = DateTime.Now
let provider = InterceptProvider()
String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day)
|> printfn "%s"
String.Format(provider, "{0}: {1:F}\n", "Today: ", DateTime.Now.DayOfWeek)
|> printfn "%s"
String.Format(provider, "{0:X}, {1}, {2}\n", 2uy, 12uy, 199uy)
|> printfn "%s"
String.Format(provider, "{0:R}, {1:R}, {2:R}\n", 2uy, 12uy, 199uy)
|> printfn "%s"
// The example displays the following output:
//    Provider: InterceptProvider, Object: 10, Format String: N0
//    Provider: InterceptProvider, Object: 16.935, Format String: C2
//    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
//    10: $16.94 on 1/31/2013
//    
//    Provider: InterceptProvider, Object: Today: , Format String: <null>
//    Provider: InterceptProvider, Object: Thursday, Format String: F
//    Today: : Thursday
//    
//    Provider: InterceptProvider, Object: 2, Format String: X
//    Provider: InterceptProvider, Object: 12, Format String: <null>
//    Provider: InterceptProvider, Object: 199, Format String: <null>
//    2, 12, 199
//    
//    Provider: InterceptProvider, Object: 2, Format String: R
//    Provider: InterceptProvider, Object: 12, Format String: R
//    Provider: InterceptProvider, Object: 199, Format String: R
//    II, XII, CXCIX

Imports System.Globalization

Public Class InterceptProvider : Implements IFormatProvider, ICustomFormatter
   Public Function GetFormat(formatType As Type) As Object _
         Implements IFormatProvider.GetFormat
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function
   
   Public Function Format(fmt As String, obj As Object, provider As IFormatProvider) As String _
         Implements ICustomFormatter.Format

      Dim formatString As String = If(fmt IsNot Nothing, fmt, "<null>")
      Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}",
                        provider, If(obj IsNot Nothing, obj, "<null>"), formatString)

      If obj Is Nothing Then Return String.Empty
            
      ' If this is a byte and the "R" format string, format it with Roman numerals.
      If TypeOf(obj) Is Byte AndAlso formatString.ToUpper.Equals("R") Then
         Dim value As Byte = CByte(obj)
         Dim remainder As Integer
         Dim result As Integer
         Dim returnString As String = String.Empty

         ' Get the hundreds digit(s)
         result = Math.DivRem(value, 100, remainder)
         If result > 0 Then returnString = New String("C"c, result)
         value = CByte(remainder)
         ' Get the 50s digit
         result = Math.DivRem(value, 50, remainder)
         If result = 1 Then returnString += "L"
         value = CByte(remainder)
         ' Get the tens digit.
         result = Math.DivRem(value, 10, remainder)
         If result > 0 Then returnString += New String("X"c, result)
         value = CByte(remainder) 
         ' Get the fives digit.
         result = Math.DivRem(value, 5, remainder)
         If result > 0 Then returnString += "V"
         value = CByte(remainder)
         ' Add the ones digit.
         If remainder > 0 Then returnString += New String("I"c, remainder)
         
         ' Check whether we have too many X characters.
         Dim pos As Integer = returnString.IndexOf("XXXX")
         If pos >= 0 Then
            Dim xPos As Integer = returnString.IndexOf("L") 
            If xPos >= 0 And xPos = pos - 1 Then
               returnString = returnString.Replace("LXXXX", "XC")
            Else
               returnString = returnString.Replace("XXXX", "XL")   
            End If         
         End If
         ' Check whether we have too many I characters
         pos = returnString.IndexOf("IIII")
         If pos >= 0 Then
            If returnString.IndexOf("V") >= 0 Then
               returnString = returnString.Replace("VIIII", "IX")
            Else
               returnString = returnString.Replace("IIII", "IV")    
            End If
         End If
         Return returnString 
      End If   

      ' Use default for all other formatting.
      If obj Is GetType(IFormattable)
         Return CType(obj, IFormattable).ToString(fmt, CultureInfo.CurrentCulture)
      Else
         Return obj.ToString()
      End If
   End Function
End Class

Module Example
   Public Sub Main()
      Dim n As Integer = 10
      Dim value As Double = 16.935
      Dim day As DateTime = Date.Now
      Dim provider As New InterceptProvider()
      Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}", n, value, day))
      Console.WriteLine()
      Console.WriteLine(String.Format(provider, "{0}: {1:F}", "Today", 
                                      CType(Date.Now.DayOfWeek, DayOfWeek)))
      Console.WriteLine()
      Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", 
                                      CByte(2), CByte(12), CByte(199)))
      Console.WriteLine()
      Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}", 
                                      CByte(2), CByte(12), CByte(199)))
   End Sub
End Module
' The example displays the following output:
'    Provider: InterceptProvider, Object: 10, Format String: N0
'    Provider: InterceptProvider, Object: 16.935, Format String: C2
'    Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d
'    10: $16.94 on 1/31/2013
'    
'    Provider: InterceptProvider, Object: Today: , Format String: <null>
'    Provider: InterceptProvider, Object: Thursday, Format String: F
'    Today: : Thursday
'    
'    Provider: InterceptProvider, Object: 2, Format String: X
'    Provider: InterceptProvider, Object: 12, Format String: <null>
'    Provider: InterceptProvider, Object: 199, Format String: <null>
'    2, 12, 199
'    
'    Provider: InterceptProvider, Object: 2, Format String: R
'    Provider: InterceptProvider, Object: 12, Format String: R
'    Provider: InterceptProvider, Object: 199, Format String: R
'    II, XII, CXCIX

よく寄せられる質問

メソッドの呼び出しよりも文字列補間を `String.Format` 推奨するのはなぜですか?

文字列補間は次のとおりです。

柔軟性が高い。複合書式をサポートするメソッドの呼び出しを必要とせずに、任意の文字列で使用できます。それ以外の場合は、メソッドまたは複合書式をサポートする別のメソッドを呼び出すFormat必要があります。たとえばConsole.WriteLine StringBuilder.AppendFormat、
読みやすい。文字列に挿入する式は引数リストではなく補間式に表示されるため、挿入文字列はコード化と読み取りがはるかに簡単です。読みやすさが高いため、挿入文字列は複合形式メソッドの呼び出しだけでなく、文字列連結操作で使用して、より簡潔で明確なコードを生成することもできます。

次の 2 つのコード例を比較すると、文字列連結と複合書式設定メソッドの呼び出しに対する補間文字列の優位性が示されています。次の例で複数の文字列連結操作を使用すると、詳細で読みにくいコードが生成されます。

string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" };
string output = names[0] + ", " + names[1] + ", " + names[2] + ", " +
                names[3] + ", " + names[4] + ", " + names[5] + ", " +
                names[6];

output += "\n";
var date = DateTime.Now;
output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.",
                        date, date.DayOfWeek);
Console.WriteLine(output);
// The example displays the following output:
//     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
//     It is 10:29 AM on 1/8/2018. The day of the week is Monday.

open System

let names = [| "Balto"; "Vanya"; "Dakota"; "Samuel"; "Koani"; "Yiska"; "Yuma" |]
let output = 
    names[0] + ", " + names[1] + ", " + names[2] + ", " + 
    names[3] + ", " + names[4] + ", " + names[5] + ", " + 
    names[6] + "\n"

let date = DateTime.Now
output + String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", date, date.DayOfWeek)
|> printfn "%s"
// The example displays the following output:
//     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
//     It is 10:29 AM on 1/8/2018. The day of the week is Monday.


Module Example12
    Public Sub Main()
        Dim names = {"Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma"}
        Dim output = names(0) + ", " + names(1) + ", " + names(2) + ", " +
                   names(3) + ", " + names(4) + ", " + names(5) + ", " +
                   names(6)

        output += vbCrLf
        Dim dat = DateTime.Now
        output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.",
                              dat, dat.DayOfWeek)
        Console.WriteLine(output)
    End Sub
End Module
' The example displays the following output:
'     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
'     It is 10:29 AM on 1/8/2018. The day of the week is Monday.

これに対し、次の例で挿入文字列を使用すると、文字列連結ステートメントや前の例のメソッドの Format 呼び出しよりもはるかに明確で簡潔なコードが生成されます。

string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" };
string output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, " +
                $"{names[5]}, {names[6]}";

var date = DateTime.Now;
output += $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}.";
Console.WriteLine(output);
// The example displays the following output:
//     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
//     It is 10:29 AM on 1/8/2018. The day of the week is Monday.

open System

let names = [| "Balto"; "Vanya"; "Dakota"; "Samuel"; "Koani"; "Yiska"; "Yuma" |]
let output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, {names[5]}, {names[6]}"  

let date = DateTime.Now
output + $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}."
|> printfn "%s" 
// The example displays the following output:
//     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
//     It is 10:29 AM on 1/8/2018. The day of the week is Monday.


Module Example13
    Public Sub Main()
        Dim names = {"Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma"}
        Dim output = $"{names(0)}, {names(1)}, {names(2)}, {names(3)}, {names(4)}, " +
                   $"{names(5)}, {names(6)}"

        Dim dat = DateTime.Now
        output += $"{vbCrLf}It is {dat:t} on {dat:d}. The day of the week is {dat.DayOfWeek}."
        Console.WriteLine(output)
    End Sub
End Module
' The example displays the following output:
'     Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma
'     It is 10:29 AM on 1/8/2018. The day of the week is Monday.

定義済みの書式指定文字列はどこにありますか?

整数型と浮動小数点型については、「標準の数値書式指定文字列」および「カスタム数値書式指定文字列」を参照してください。
日付と時刻の値については、「標準の日時書式指定文字列」および「カスタム日時書式指定文字列」を参照してください。
列挙値については、「列挙型書式指定文字列」を参照してください。
値については、「TimeSpan標準の TimeSpan 書式指定文字列」および「カスタム TimeSpan 書式指定文字列」を参照してください。
値については Guid 、リファレンスページの「解説」セクションを Guid.ToString(String) 参照してください。

操作方法書式指定項目を置き換える結果文字列の配置を制御しますか?

書式項目の一般的な構文は次のとおりです。

{index[,alignment][: formatString]}

配置はフィールドの幅を定義する符号付き整数です。この値が負の場合、フィールド内のテキストは左揃えになります。正の場合、テキストは右揃えになります。

操作方法小数点の後の桁数を制御しますか?

"D" (整数でのみ使用)、"G"、"R"、および "X" を除くすべての標準数値書式指定文字列では、結果文字列の 10 進数の数を定義する精度指定子を使用できます。次の例では、標準の数値書式指定文字列を使用して、結果文字列の 10 進数の数を制御します。

object[] values = { 1603, 1794.68235, 15436.14 };
string result;
foreach (var value in values)
{
    result = String.Format("{0,12:C2}   {0,12:E3}   {0,12:F4}   {0,12:N3}  {1,12:P2}\n",
                           Convert.ToDouble(value), Convert.ToDouble(value) / 10000);
    Console.WriteLine(result);
}
// The example displays output like the following:
//       $1,603.00     1.603E+003      1603.0000      1,603.000       16.03 %
//    
//       $1,794.68     1.795E+003      1794.6824      1,794.682       17.95 %
//    
//      $15,436.14     1.544E+004     15436.1400     15,436.140      154.36 %

open System

let values: obj list = [ 1603, 1794.68235, 15436.14 ]
for value in values do
   String.Format("{0,12:C2}   {0,12:E3}   {0,12:F4}   {0,12:N3}  {1,12:P2}\n", Convert.ToDouble(value), Convert.ToDouble(value) / 10000.)
   |> printfn "%s"
// The example displays output like the following:
//       $1,603.00     1.603E+003      1603.0000      1,603.000       16.03 %
//    
//       $1,794.68     1.795E+003      1794.6824      1,794.682       17.95 %
//    
//      $15,436.14     1.544E+004     15436.1400     15,436.140      154.36 %

Module Example7
    Public Sub Main()
        Dim values() As Object = {1603, 1794.68235, 15436.14}
        Dim result As String
        For Each value In values
            result = String.Format("{0,12:C2}   {0,12:E3}   {0,12:F4}   {0,12:N3}  {1,12:P2}",
                                value, CDbl(value) / 10000)
            Console.WriteLine(result)
            Console.WriteLine()
        Next
    End Sub
End Module
' The example displays the following output:
'       $1,603.00     1.603E+003      1603.0000      1,603.000       16.03 %
'    
'       $1,794.68     1.795E+003      1794.6824      1,794.682       17.95 %
'    
'      $15,436.14     1.544E+004     15436.1400     15,436.140      154.36 %

カスタム数値書式指定文字列を使用している場合は、次の例に示すように、"0" 書式指定子を使用して、結果文字列の 10 進数の数を制御します。

decimal value = 16309.5436m;
string result = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}",
                              value);
Console.WriteLine(result);
// The example displays the following output:
//        16309.54360    16,309.54    16309.544

let value = 16309.5436m
String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", value)
|> printfn "%s"
// The example displays the following output:
//        16309.54360    16,309.54    16309.544

Module Example8
    Public Sub Main()
        Dim value As Decimal = 16309.5436D
        Dim result As String = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}",
                                           value)
        Console.WriteLine(result)
    End Sub
End Module
' The example displays the following output:
'    16309.54360    16,309.54    16309.544

整数の桁数を制御操作方法?

既定では、書式設定操作では 0 以外の整数の数字のみが表示されます。整数を書式設定する場合は、"D" および "X" 標準書式指定文字列で精度指定子を使用して、桁数を制御できます。

int value = 1326;
string result = String.Format("{0,10:D6} {0,10:X8}", value);
Console.WriteLine(result);
// The example displays the following output:
//     001326   0000052E

open System

let value = 1326
String.Format("{0,10:D6} {0,10:X8}", value)
|> printfn "%s"
// The example displays the following output:
//     001326   0000052E

Module Example10
    Public Sub Main()
        Dim value As Integer = 1326
        Dim result As String = String.Format("{0,10:D6} {0,10:X8}", value)
        Console.WriteLine(result)
    End Sub
End Module
' The example displays the following output:
'       001326   0000052E

次の例に示すように、整数または浮動小数点数に先行ゼロを埋め込んで、"0" カスタム数値書式指定子を使用して、指定した整数桁数の結果文字列を生成できます。

int value = 16342;
string result = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}",
                              value);
Console.WriteLine(result);
// The example displays the following output:
//           00016342       00016342.000    0,000,016,342.0

open System

let value = 16342
String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", value)
|> printfn "%s"
// The example displays the following output:
//           00016342       00016342.000    0,000,016,342.0

Module Example9
    Public Sub Main()
        Dim value As Integer = 16342
        Dim result As String = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}",
                                           value)
        Console.WriteLine(result)
    End Sub
End Module
' The example displays the following output:
'           00016342       00016342.000    0,000,016,342.0

書式リストに含めることができる項目の数はいくつですか?

実際的な制限はありません。メソッドの 2 番目の Format(IFormatProvider, String, Object[]) パラメーターには属性のタグが付 ParamArrayAttribute けられます。これにより、区切りリストまたはオブジェクト配列を書式リストとして含めることができます。

結果文字列にリテラル中かっこ ("{" と "}") を含める操作方法?

たとえば、次のメソッド呼び出しで例外がスロー FormatException されないようにするにはどうすればよいですか?

result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
                       nOpen, nClose);

let result = 
    String.Format("The text has {0} '{' characters and {1} '}' characters.", nOpen, nClose)

result = String.Format("The text has {0} '{' characters and {1} '}' characters.",
                 nOpen, nClose)

1 つの開始中かっこまたは右中かっこは、常に書式指定項目の先頭または末尾として解釈されます。リテラルで解釈するには、エスケープする必要があります。次のメソッド呼び出しのように、"{" と "}" の代わりに別の中かっこ ("{" と "}}" を追加して中かっこをエスケープします。

string result;
int nOpen = 1;
int nClose = 2;
result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
                       nOpen, nClose);
Console.WriteLine(result);

let result =
    String.Format("The text has {0} '{{' characters and {1} '}}' characters.", nOpen, nClose)

result = String.Format("The text has {0} '{{' characters and {1} '}}' characters.",
                 nOpen, nClose)

ただし、エスケープされた中かっこも簡単に誤って解釈されます。次の例に示すように、書式リストに中かっこを含め、書式設定項目を使用して結果文字列に挿入することをお勧めします。

string result;
int nOpen = 1;
int nClose = 2;
result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
                       nOpen, "{", nClose, "}");
Console.WriteLine(result);

let result =
    String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.", nOpen, "{", nClose, "}")

result = String.Format("The text has {0} '{1}' characters and {2} '{3}' characters.",
                 nOpen, "{", nClose, "}")

String.Format メソッドの呼び出しで FormatException がスローされる理由

例外の最も一般的な原因は、書式指定項目のインデックスが書式リスト内のオブジェクトに対応していないということです。通常、これは、書式指定項目のインデックスの番号が間違っているか、オブジェクトを書式リストに含め忘れたことを示します。エスケープされていない左または右の中かっこ文字を含めようとすると、 FormatException. 場合によっては、例外は入力ミスの結果です。たとえば、一般的な間違いは、"{" (左中かっこ) ではなく "[" (左角かっこ) を誤って入力することです。

Format(System.IFormatProvider,System.String,System.Object[]) メソッドがパラメーター配列をサポートしている場合、配列を使用するときにコードで例外がスローされるのはなぜですか?

たとえば、次のコードは例外を FormatException スローします。

Random rnd = new Random();
int[] numbers = new int[4];
int total = 0;
for (int ctr = 0; ctr <= 2; ctr++)
{
    int number = rnd.Next(1001);
    numbers[ctr] = number;
    total += number;
}
numbers[3] = total;
Console.WriteLine("{0} + {1} + {2} = {3}", numbers);

open System

let rnd = Random()
let mutable total = 0
let numbers = Array.zeroCreate<int> 4
for i = 0 to 2 do
   let number = rnd.Next 1001
   numbers[i] <- number
   total <- total + number
numbers[3] <- total
Console.WriteLine("{0} + {1} + {2} = {3}", numbers)

Imports System.Collections.Generic

Module Example5
    Public Sub Main()
        Dim rnd As New Random()
        Dim numbers(3) As Integer
        Dim total As Integer = 0
        For ctr = 0 To 2
            Dim number As Integer = rnd.Next(1001)
            numbers(ctr) = number
            total += number
        Next
        numbers(3) = total
        Console.WriteLine("{0} + {1} + {2} = {3}", numbers)
    End Sub
End Module

これは、コンパイラのオーバーロード解決の問題です。コンパイラは整数の配列をオブジェクト配列に変換できないため、整数配列を 1 つの引数として扱うため、メソッドを Format(String, Object) 呼び出します。この例外は、4 つの書式項目がありますが、書式リストには 1 つの項目しかないためスローされます。

Visual Basic も C# も整数配列をオブジェクト配列に変換できないため、メソッドを呼び出す前に自分で変換を実行する Format(String, Object[]) 必要があります。次の例で 1 つの実装を示します。

Random rnd = new Random();
int[] numbers = new int[4];
int total = 0;
for (int ctr = 0; ctr <= 2; ctr++)
{
    int number = rnd.Next(1001);
    numbers[ctr] = number;
    total += number;
}
numbers[3] = total;
object[] values = new object[numbers.Length];
numbers.CopyTo(values, 0);
Console.WriteLine("{0} + {1} + {2} = {3}", values);

open System

let rnd = Random()
let numbers = Array.zeroCreate<int> 4
let mutable total = 0
for i = 0 to 2 do
   let number = rnd.Next 1001
   numbers[i] <- number
   total <- total + number
numbers[3] <- total
let values = Array.zeroCreate<obj> numbers.Length
numbers.CopyTo(values, 0)
Console.WriteLine("{0} + {1} + {2} = {3}", values)

Imports System.Collections.Generic

Module Example6
    Public Sub Main()
        Dim rnd As New Random()
        Dim numbers(3) As Integer
        Dim total As Integer = 0
        For ctr = 0 To 2
            Dim number As Integer = rnd.Next(1001)
            numbers(ctr) = number
            total += number
        Next
        numbers(3) = total
        Dim values(numbers.Length - 1) As Object
        numbers.CopyTo(values, 0)
        Console.WriteLine("{0} + {1} + {2} = {3}", values)
    End Sub
End Module

System.String.Format メソッド

例

書式指定文字列を作成する

書式設定された出力を制御する

書式指定文字列をカルチャに依存させる

書式設定操作をカスタマイズする

String.Format メソッドの概要

文字列を挿入する

コントロールの書式設定

コントロールの間隔

配置を制御する

どのメソッドを呼び出しますか?

Format メソッドの概要

書式項目

引数の書式設定方法

同じインデックスを持つアイテムの書式設定

書式とカルチャ

カスタム書式設定操作

例: カスタム書式設定操作

例: インターセプトプロバイダーとローマ数字フォーマッタ

よく寄せられる質問

定義済みの書式指定文字列はどこにありますか?

操作方法書式指定項目を置き換える結果文字列の配置を制御しますか?

操作方法小数点の後の桁数を制御しますか?

整数の桁数を制御操作方法?

書式リストに含めることができる項目の数はいくつですか?

結果文字列にリテラル中かっこ ("{" と "}") を含める操作方法?

String.Format メソッドの呼び出しで FormatException がスローされる理由

Format(System.IFormatProvider,System.String,System.Object[]) メソッドがパラメーター配列をサポートしている場合、配列を使用するときにコードで例外がスローされるのはなぜですか?

フィードバック

その他のリソース

System.String.Format メソッド

例

書式指定文字列を作成する

書式設定された出力を制御する

書式指定文字列をカルチャに依存させる

書式設定操作をカスタマイズする

String.Format メソッドの概要

文字列を挿入する

コントロールの書式設定

コントロールの間隔

配置を制御する

どのメソッドを呼び出しますか?

Format メソッドの概要

書式項目

引数の書式設定方法

同じインデックスを持つアイテムの書式設定

書式とカルチャ

カスタム書式設定操作

例: カスタム書式設定操作

例: インターセプト プロバイダーとローマ数字フォーマッタ

よく寄せられる質問

メソッドの呼び出しよりも文字列補間を String.Format 推奨するのはなぜですか?

定義済みの書式指定文字列はどこにありますか?

操作方法書式指定項目を置き換える結果文字列の配置を制御しますか?

操作方法小数点の後の桁数を制御しますか?

整数の桁数を制御操作方法?

書式リストに含めることができる項目の数はいくつですか?

結果文字列にリテラル中かっこ ("{" と "}") を含める操作方法?

String.Format メソッドの呼び出しで FormatException がスローされる理由

Format(System.IFormatProvider,System.String,System.Object[]) メソッドがパラメーター配列をサポートしている場合、配列を使用するときにコードで例外がスローされるのはなぜですか?

フィードバック

その他のリソース

例: インターセプトプロバイダーとローマ数字フォーマッタ

メソッドの呼び出しよりも文字列補間を `String.Format` 推奨するのはなぜですか?