書式指定文字列 (Format Strings)

構文

複合書式指定 (Composite Formatting)

{index[,alignment][:formatString]}
書式指定項目の構文 - 複合書式指定 | Microsoft Learn
  • index … パラメータ指定子 (parameter specifier)。リスト内で対応する項目の番号。{0}、{1}など
  • alignment … 書式設定フィールドの幅。正の値ならば右揃え、負ならば左揃え。書式設定する文字列の長さよりも小さい場合は、指定が無視される。{0,5:G}、{0,-10:G}など
  • formatString … 対象の種類ごとの書式指定文字列。{0:G5}、{0:N}など

補間文字列ならば、項目のインデックスではなく式でパラメータを指定できます。

String.Format( "{0,5:G}",   10 ); // "   10"
String.Format( "{0,-10:G}", 10 ); // "10        "

String.Format( "{0:G5}",  12345 ); // "12345"
String.Format( "{0:G5}", 123456 ); // "1.2346E+05"

String.Format( "{0:N}",  12.345 ); // "12.35"
String.Format( "{0:N1}", 12.345 ); // "12.3"
String.Format( "{0:N5}", 12.345 ); // "12.34500"

波かっこのエスケープ

波かっこは書式指定の記号として解釈されるため、波かっこ自体を出力するにはエスケープしなければなりません。それには{{のように、同じかっこを重ねて記述します。書式指定項目の構文 - 複合書式指定 | MSDN

String.Format("{0} {{ }}", 123); // "123 { }"
String.Format("{{{0}}}", 123);   // "{123}"

もしくは波かっこ自体を書式指定で出力すれば、エスケープは不要です。

String.Format("{0}{1}{2}", "{", 123, "}"); // "{123}"

未定義の指定子

未定義の指定子を1文字指定すると、FormatExceptionが投げられます。それに該当しない場合は、指定した文字列が返されます。

String.Format("{0:a}", 1);  // System.FormatException
String.Format("{0:aa}", 1); // "aa"
String.Format("{0:@}", 1);  // "@"

文字列

書式指定をせず{0}や{1}とすると、文字列がそのまま出力されます。

String.Format("{0,2}", "ABC"); // "ABC"
String.Format("{0,4}", "ABC"); // " ABC"

数値

整数 (Int型)

次のようなコードを用いて、各種の書式指定子による出力結果をまとめたものを下表に示します。

String.Format( "{0:G}", 1234 );
標準の数値書式指定文字列 (Standard Numeric Format Strings)
指定子 説明 出力例
{0:指定子} フィールド幅
{0,6:指定子}		 精度
{0:指定子6}
G 一般
(General)		 
1234
 
   1234
 
1234
N 数値
(Number)		 
1,234.00
※1		 
1,234.00
 
1,234.000000
F 固定小数点数
(Fixed-point)		 
1234.00
※1		 
1234.00
 
1234.000000
E 指数
(Exponential)		 
1.234000E+003
 
1.234000E+003
 
1.234000E+003
P パーセント
(Percent)		 
123,400.00%
 
123,400.00%
 
123,400.000000%
D 10進数
(Decimal)		 
1234
 
   1234
 
001234
X 16進数 [大文字]
(Hexadecimal)		 
4D2
 
    4D2
 
0004D2
x 16進数 [小文字]
(Hexadecimal)		 
4d2
 
    4d2
 
0004d2
C 通貨
(Currency)		 
¥1,234
 
  ¥1,234
 
¥1,234.000000
標準の数値書式指定文字列 - .NET | Microsoft Learn

※1 小数部の桁数を指定する精度 (precision) を省略すると、インバリアント カルチャではNumberFormatInfo.NumberDecimalDigitsの指定により2桁となるため、必要ならばそれを明示します。数値書式指定子 (N) - 標準の数値書式指定文字列 | Microsoft Learn

String.Format("{0:N}", 1234);  // "1,234.00"
String.Format("{0:N0}", 1234); // "1,234"

または、その既定の桁数を変更します。

NumberFormatInfo formatInfo = (NumberFormatInfo)NumberFormatInfo.CurrentInfo.Clone();
formatInfo.NumberDecimalDigits = 0;

1234.ToString("N", formatInfo); // "1,234"
NumberFormatInfo.NumberDecimalDigits プロパティ (System.Globalization) | Microsoft Learn
カスタム数値書式指定文字列 (Custom Numeric Format Strings)
指定子 説明
0 ゼロ プレースホルダ
# 桁プレースホルダ
, 桁区切り記号
; セクション区切り記号
カスタム数値形式文字列 - .NET | Microsoft Learn 
String.Format( "{0:00}",   123 ); // "123"
String.Format( "{0:0000}", 123 ); // "0123"
String.Format( "{0:##}",   123 ); // "123"
String.Format( "{0:####}", 123 ); // "123"

String.Format( "{0:00}", 0 ); // "00"
String.Format( "{0:##}", 0 ); // ""

// 桁区切り
String.Format( "{0:#,#}", 123 );    // "123"
String.Format( "{0:#,#}", 1234 );   // "1,234"
String.Format( "{0:#,#}", 1234567); // "1,234,567"

// セクション区切り
String.Format( "{0:+#;-#}",  123 ); // "+123"
String.Format( "{0:+#;-#}", -123 ); // "-123"

1つの数値を文字列へ変換するだけならば、Int32.ToString()でも可能です。

桁区切り記号

桁区切り記号は単独では使用できないため、必ず他の指定子と組み合わせて使用します。その組み合わせによって出力結果が異なるため、使用には注意が必要です。

String.Format( "{0:#,#}", 0 ); // ""
String.Format( "{0:0,0}", 0 ); // "00"

String.Format( "{0:#,0}", 0 ); // "0"
String.Format( "{0:0,#}", 0 ); // "00"


String.Format( "{0:#,}", 12345); // "12"
String.Format( "{0:0,}", 12345); // "12"

String.Format( "{0:,#}", 12345); // "12345"
String.Format( "{0:,0}", 12345); // "12345"

小数 (Double型)

標準の数値書式指定文字列 (Standard Numeric Format Strings)
指定子 説明 出力例
{0:指定子} フィールド幅
{0,6:指定子}		 精度
{0:指定子6}
G 一般
(General)		 
1234.567
 
  1234.567
 
1234.567
N 数値
(Number)		 
1,234.57
 
  1,234.57
 
1,234.567000
F 固定小数点数
(Fixed-point)		 
1234.57
 
  1234.57
 
1234.567000
E 指数
(Exponential)		 
1.234567E+003
 
1.234567E+003
 
1.234567E+003
P パーセント
(Percent)		 
123,456.70%
 
123,456.70%
 
123,456.700000%
D 10進数
(Decimal)		 × × ×
X 16進数 [大文字]
(Hexadecimal)		 × × ×
x 16進数 [小字]
(Hexadecimal)		 × × ×
C 通貨
(Currency)		 
¥1,235
 
    ¥1,235
 
¥1,234.567000
カスタム数値書式指定文字列 (Custom Numeric Format Strings)
指定子 説明
0 ゼロ プレースホルダ
# 桁プレースホルダ
. 小数点
% パーセント 
String.Format( "{0}",     55.55 ); // "55.55"

// ゼロ プレースホルダ
String.Format( "{0:0}",   55.55 ); // "56"
String.Format( "{0:000}", 55.55 ); // "056"

// 桁プレースホルダ
String.Format( "{0:#}",   55.55 ); // "56"
String.Format( "{0:###}", 55.55 ); // "56"

// 小数点
String.Format( "{0:.#}",   5.55 ); // "5.6"
String.Format( "{0:.0}",   5.55 ); // "5.6"
String.Format( "{0:.###}", 5.55 ); // "5.55"
String.Format( "{0:.000}", 5.55 ); // "5.550"

String.Format( "{0:#.#}",  0.55 ); // ".6"
String.Format( "{0:0.0}",  0.55 ); // "0.6"

// パーセント
String.Format( "{0:%}",    0.1 ); // "%"
String.Format( "{0:0%}",   0.1 ); // "10%"
String.Format( "{0:#%}",   0.1 ); // "10%"
String.Format( "{0:000%}", 0.1 ); // "010%"
String.Format( "{0:###%}", 0.1 ); // "10%"

String.Format( "{0:0%}",  5.6789 ); // "568%"
String.Format( "{0:.0%}", 5.6789 ); // "567.9%"

出力する桁数が不足するときは結果が丸められますが、その方法は.NET Core 2.1より前はMidpointRounding.AwayFromZero、以降はMidpointRounding.ToEvenとなります。

// .NET Core 2.1より前の結果
String.Format("{0:.0}", 1.04); // "1.0"
String.Format("{0:.0}", 1.05); // "1.1"
String.Format("{0:.0}", 1.06); // "1.1"

String.Format("{0:.0}", -1.04); // "-1.0"
String.Format("{0:.0}", -1.05); // "-1.1"
String.Format("{0:.0}", -1.06); // "-1.1"

日時

String.Format("{0:F}", new DateTime());          // "0001年1月1日 0:00:00"
String.Format("{0:yyyy-MM-dd}", new DateTime()); // "0001-01-01"

≫DateTimeの日時書式指定文字列

参考

参考書

関連ページ

Microsoft Learnから検索