モジュール java.base
パッケージ java.util

クラスFormatter

java.lang.Object
java.util.Formatter
すべての実装されたインタフェース:
Closeable, Flushable, AutoCloseable
public final class Formatter extends Object implements Closeable, Flushable
printf形式の文字列用のインタプリタ。 このクラスは、行揃えおよび水平配置レイアウト、数値、文字列、および日付/時刻データ用の共通書式、ロケール固有の出力をサポートします。 byte、BigDecimal、およびCalendarなどの一般的なJavaの型をサポートします。 任意のユーザー型に対する限定的な書式のカスタマイズについては、Formattableインタフェースを使用します。

マルチスレッド・アクセスを実行する場合、フォーマッタは必ずしも安全ではありません。 スレッドの安全性はこのクラスのメソッドを使用するユーザーによってオプションで保証されます。

Java言語の書式付き出力は、Cのprintfの影響を大きく受けています。 書式文字列はCに似ていますが、Java言語に対応し、その機能を活用するために、一部がカスタマイズされています。 また、Javaの書式は、Cよりも厳密です。たとえば、変換がフラグと互換性がない場合、例外がスローされます。 Cでは、適用不可能なフラグは、無視されるだけです。 このため、書式文字列は、Cプログラマになじみのあるものになっていますが、Cとの完全な互換性を保っているわけではありません。

使用例: 

   StringBuilder sb = new StringBuilder();
   // Send all output to the Appendable object sb
   Formatter formatter = new Formatter(sb, Locale.US);

   // Explicit argument indices may be used to re-order output.
   formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
   // -> " d  c  b  a"

   // Optional locale as the first argument can be used to get
   // locale-specific formatting of numbers.  The precision and width can be
   // given to round and align the value.
   formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E);
   // -> "e =    +2,7183"

   // The '(' numeric flag may be used to format negative numbers with
   // parentheses rather than a minus sign.  Group separators are
   // automatically inserted.
   formatter.format("Amount gained or lost since last statement: $ %(,.2f",
                    balanceDelta);
   // -> "Amount gained or lost since last statement: $ (6,217.58)"

一般的な書式設定要求で使用可能な便利なメソッドが存在します。 

   // Writes a formatted string to System.out.
   System.out.format("Local time: %tT", Calendar.getInstance());
   // -> "Local time: 13:34:18"

   // Writes formatted output to System.err.
   System.err.printf("Unable to open file '%1$s': %2$s",
                     fileName, exception.getMessage());
   // -> "Unable to open file 'food': No such file or directory"

Cのsprintf(3)と同様に、staticメソッドString.formatを使用して文字列の書式を設定できます。 

   // Format a string containing a date.
   import java.util.Calendar;
   import java.util.GregorianCalendar;
   import static java.util.Calendar.*;

   Calendar c = new GregorianCalendar(1995, MAY, 23);
   String s = String.format("Duke's Birthday: %1$tb %1$te, %1$tY", c);
   // -> s == "Duke's Birthday: May 23, 1995"

組織

この仕様は、2つのセクションに分けられます。 最初の「サマリー」セクションでは、書式設定の基本的な概念を扱います。 このセクションは、このクラスをすぐに利用することを望む、ほかのプログラミング言語での書式付き出力に慣れたユーザーを対象にしています。 続く「詳細」セクションでは、このクラスに固有の実装の詳細を説明します。 このセクションは、より厳密な仕様の書式設定を必要とするユーザーを対象にしています。

サマリー

このセクションでは、書式設定の概要を簡潔に説明します。 動作の詳細については、「詳細」セクションを参照してください。

書式文字列の構文

書式付きの出力を生成する各メソッドには、書式文字列と引数リストを指定する必要があります。 書式文字列はStringで、これには固定のテキストと1つ以上の埋め込まれた書式指示子を含めることができます。 次の例を検討してください: 

   Calendar c = ...;
   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
この場合、書式文字列はformatメソッドの最初の引数です。 これには、引数の処理方法およびテキスト内の挿入位置を示す3つの書式指示子「%1$tm」、「%1$te」、および「%1$tY」が含まれます。 書式文字列の残りの部分は固定テキストで、"Dukes Birthday: "およびほかの空白や句読点が含まれます。 引数リストは、書式文字列のあとにメソッドに渡されるすべての引数で構成されます。 前述した例では、引数リストのサイズは1で、Calendarオブジェクトcで構成されます。
  • 一般、文字、および数値型の書式指示子では、次の構文が使用されます。 
       %[argument_index$][flags][width][.precision]conversion

    オプションのargument_indexは、引数リスト内での引数の位置を示す10進整数です。 最初の引数は「1$」、2番目の引数は「2$」で参照されます。

    オプションのflagsは、出力書式を変更する文字のセットです。 有効なフラグのセットは、変換によって異なります。

    オプションのwidthは、出力に書き込む最小文字数を示す正の10進整数です。

    オプションのprecisionは、文字数を制限するために通常使用される正の10進整数です。 その動作は、変換によって異なります。

    必須のconversionは、引数を書式設定する方法を示す文字です。 指定された引数で有効な変換セットは、引数のデータ型によって異なります。

  • 日付および時刻表現に使用する型の書式指示子では、次の構文が使用されます。 
       %[argument_index$][flags][width]conversion

    オプションのargument_index、flags、およびwidthの定義は、前述のとおりです。

    必須のconversionは、2つの文字シーケンスです。 最初の文字は't'または'T'です。 2番目の文字は使用する書式を示します。 これらの文字は、GNU dateおよびPOSIX strftime(3c)で定義された文字に類似していますが完全に同一ではありません。

  • 引数に対応しない書式指示子では、次の構文が使用されます。 
       %[flags][width]conversion

    オプションのflagsおよびwidthの定義は、前述のとおりです。

    必須のconversionは、出力への挿入内容を示す文字です。

変換

変換は、次のカテゴリに分けられます。

  1. 一般 - 任意の引数型に適用されます
  2. 文字 - Unicode文字を表す基本型char、文字、byte、Byte、short、およびShortに適用されます。 Character.isValidCodePoint(int)がtrueを返す場合、この変換は、intおよびInteger型にも適用されます。
  3. 数値
    1. 整数 - byte、Byte、short、Short、int、Integer、long、Long、BigIntegerなどのJava整数型に適用されます(ただし、charまたは文字を除く)
    2. 浮動小数点 - float、Float、double、Double、およびBigDecimalなどのJava浮動小数点型に適用されます
  4. 日付/時間 - long、Long、Calendar、Date、TemporalAccessorなど、日付または時間のエンコーディングが可能なJava型に適用されます
  5. パーセント - リテラル'%' ('\u0025')を生成
  6. 行区切り文字 - プラットフォーム固有の行区切り文字を生成します

カテゴリ一般、文字、数値、整数および日付/時間の変換では、引数argがnullの場合、結果は"null"です。

次の表は、サポートする変換を要約したものです。 大文字(つまり、'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A'、および'T')で表された変換は、それぞれの小文字を使用する変換と同じですが、変換の結果は一般的に使用されているLocaleのルールに従って大文字に変換されます。 インスタンスの構成時、またはメソッドの起動に対するパラメータとして明示的なロケールが指定されていない場合は、default localeが使用されます。

genConv
変換 引数のカテゴリ 説明
'b', 'B' 一般 引数argがnullの場合、結果は「false」になります。 argがbooleanまたはBooleanの場合、結果はString.valueOf(arg)により返される文字列になります。 そうでない場合、結果はtrueになります。
'h', 'H' 一般 結果はInteger.toHexString(arg.hashCode())を呼び出すことによって得られます。
's', 'S' 一般 argがFormattableを実装する場合、arg.formatToが呼び出されます。 それ以外の場合、結果はarg.toString()の呼出しで取得されます。
'c', 'C' 文字 結果はUnicode文字です。
'd' 整数 結果は、10進整数として書式設定されます。
'o' 整数 結果は、8進整数として書式設定されます。
'x', 'X' 整数 結果は、16進整数として書式設定されます。
'e', 'E' 浮動小数点 結果は、浮動小数点表示形式の10進数として書式設定されます。
'f' 浮動小数点 結果は、10進数として書式設定されます。
'g', 'G' 浮動小数点 結果は、四捨五入処理後の精度および値に応じて浮動小数点表示形式または10進数書式を使用して書式設定されます。
'a', 'A' 浮動小数点 結果は、有効数字および指数を持つ16進浮動小数点数として書式設定されます。 この変換は、後者の引数カテゴリが浮動小数点であるにもかかわらず、BigDecimal型ではサポートされていません。
't', 'T' 日付/時刻 日付および時刻変換文字の接頭辞です。 「日付/時刻変換」を参照してください。
'%' パーセント 結果は、リテラル'%' ('\u0025')です
'n' 行区切り文字 結果は、プラットフォーム固有の行区切り文字です。

変換として明示的に定義されていない文字はすべて不正であり、将来の機能拡張に備えて予約されています。

日付/時刻変換

次の日付および時刻変換文字の接尾辞が、't'および'T'変換用に定義されています。 この型は、GNU dateおよびPOSIX strftime(3c)で定義された型に類似していますが完全に同一ではありません。 秒内のミリ秒を表す'L'など、Java固有の機能にアクセスするための追加の変換型が提供されています。

時刻の書式設定では、次の変換文字が使用されます。

time
変換 説明
'H' 24時間制の時。必要に応じて0を先頭に追加し、2桁で表現します(00 - 23)。
'I' 12時間制の時。必要に応じて0を先頭に追加し、2桁で表現します(01 - 12)。
'k' 24時間制の時(0 - 23)。
'l' 12時間制の時(1 - 12)。
'M' 分。必要に応じて0を先頭に追加し、2桁で表現します(00 - 59)。
'S' 秒。必要に応じて0を先頭に追加し、2桁で表現します(00 - 60)。「60」はうるう年での秒のサポートに必要な特殊な値です。
'L' ミリ秒。必要に応じて0を先頭に追加し、3桁で表現します(000 - 999)。
'N' ナノ秒。必要に応じて0を先頭に追加し、9桁で表現します(000000000 - 999999999)。
'p' ロケール固有の午前または午後を示す小文字のマーカー(「am」または「pm」など)。 変換接頭辞の'T'を使用すると、結果は大文字で強制出力されます。
'z' RFC 822に準拠した、GMTからの数値タイムゾーン・オフセット(-0800など)。 この値は、必要に応じて夏時間で調整されます。 long、Long、およびDateの場合、使用されるタイムゾーンは、このJava仮想マシン・インスタンスのデフォルト・タイム・ゾーンです。
'Z' タイムゾーンの省略形を表す文字列。 この値は、必要に応じて夏時間で調整されます。 long、Long、およびDateの場合、使用されるタイムゾーンは、このJava仮想マシン・インスタンスのデフォルト・タイム・ゾーンです。 Formatterのロケールは、引数のロケール(存在する場合)よりも優先されます。
's' 1970年1月1日00:00:00 UTCの元期開始からの秒(Long.MIN_VALUE/1000からLong.MAX_VALUE/1000まで)。
'Q' 1970年1月1日00:00:00 UTCの元期開始からのミリ秒(Long.MIN_VALUEからLong.MAX_VALUEまで)。

日付の書式設定では、次の変換文字が使用されます。

date
変換 説明
'B' ロケール固有の月の完全な名前 ("January"、"February"など)。
'b' ロケール固有の月の省略名 ("Jan"、"Feb"など)。
'h' 'b'と同じ。
'A' ロケール固有の曜日の完全な名前("Sunday"、"Monday"など)。
'a' ロケール固有の曜日の短縮名("Sun"、"Mon"など)。
'C' 4桁の年を100で割った値。必要に応じて0を先頭に追加し、2桁で表示します(00 - 99)
'Y' 年。必要に応じて0を先頭に追加し、4桁以上で表現します。たとえば、0092は、グレゴリオ歴の92 CEと等価です。
'y' 年の下2桁。必要に応じて0を先頭に追加します(00 - 99)。
'j' 年の何日目かを表す日。必要に応じて0を先頭に追加し、3桁で表現します。たとえば、グレゴリオ歴の場合、001 - 366になります。
'm' 月。必要に応じて0を先頭に追加し、2桁で表現します(01 - 13)。
'd' 月の何日目かを表す日。必要に応じて0を先頭に追加し、2桁で表現します(01 - 31)
'e' 月の何日目かを表す日。最大2桁で表現します(1 - 31)。

一般の日付/時刻変換の書式設定では、次の変換文字が使用されます。

composites
変換 説明
'R' "%tH:%tM"として24時間制で書式設定された時刻。
'T' "%tH:%tM:%tS"として24時間制で書式設定された時刻。
'r' "%tI:%tM:%tS %Tp"として12時間制で書式設定された時刻。 午前および午後を示すマーカー('%Tp')の位置はロケールによって異なります。
'D' "%tm/%td/%ty"として書式設定された日付。
'F' "%tY-%tm-%td"として書式設定されたISO 8601に準拠した日付。
'c' "%ta %tb %td %tT %tZ %tY"として書式設定された日付および時間("Sun Jul 20 16:17:00 EDT 1969"など)。

日付/時刻変換の接尾辞として明示的に定義されていない文字はすべて不正であり、将来の機能拡張に備えて予約されています。

フラグ

次の表に、サポートされるフラグのサマリーを示します。yは、指定された引数型でフラグがサポートされることを意味します。

genConv
フラグ 一般 文字 整数 浮動小数点 日付/時刻 説明
'-' y y y y y 結果は左揃えになります。
'#' y1 - y3 y - 結果は、変換に依存する代替フォームを使用する必要があります。
'+' - - y4 y - 結果には、常に符号が含まれます。
'  ' - - y4 y - 結果の先頭には、正の値を示す空白が含まれます。
'0' - - y y - 結果にはゼロが追加されます。
',' - - y2 y5 - 結果には、ロケール固有のグループ化区切り文字が含まれます。
'(' - - y4 y5 - 負の数値をカッコで囲みます。

1 Formattableの定義に依存する。

2 'd'変換のみ。

3 'o'、'x'、および'X'変換のみ。

4 'd'、'o'、'x'、および'X'変換がBigIntegerに適用されるか、'd'がbyte、Byte、short、Short、int、Integer、long、およびLongに適用される場合。

5 'e'、'E'、'f'、'g'、および'G'変換のみ。

変換として明示的に定義されていないフラグはすべて不正であり、将来の機能拡張に備えて予約されています。

Width

widthは、出力に書き込まれる最小文字数です。 行区切り文字変換では、widthは使用できません。widthが指定された場合、エラーがスローされます。

Precision

一般の引数型では、precisionは出力に書き込まれる最大文字数です。

'a'、'A'、'e'、'E'、および'f'の浮動小数点の変換では、precisionは基数点以下の桁数になります。 変換が'g'または'G'の場合は、四捨五入処理後の結果として得られる絶対値の合計桁数になります。

文字、整数、日付/時刻引数タイプ、およびパーセント、行区切り文字変換の場合、precisionは適用できません。precisionが指定された場合、例外がスローされます。

引数のインデックス

引数インデックスは、引数リスト内での引数の位置を示す10進整数です。 最初の引数は「1$」、2番目の引数は「2$」で参照されます。

位置によって引数を参照する別の方法は、'<' ('\u003c')フラグを使用することです。これにより、以前の書式指定子の引数が再使用されます。 たとえば、次の2つの文では、同一の文字列が生成されます。 

   Calendar c = ...;
   String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);

   String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);

詳細

このセクションでは、条件や例外、サポートされるデータ型、ローカリゼーション、およびフラグ、変換、データ型間の相互作用を含む、書式設定の動作の詳細を示します。 書式設定の概念については、「サマリー」を参照してください。

変換、日付/時刻変換の接尾辞、またはフラグとして明示的に宣言されていない文字はすべて不正であり、将来の機能拡張に備えて予約されています。 書式文字列内でこの種の文字を使用すると、UnknownFormatConversionExceptionまたはUnknownFormatFlagsExceptionがスローされます。

書式指示子にwidthが含まれる場合、precisionの値が無効な場合、または書式指示子がサポートされない場合は、IllegalFormatWidthExceptionまたはIllegalFormatPrecisionExceptionがそれぞれスローされます。 同様に、引数索引の値がゼロの場合、IllegalFormatExceptionになります。

書式指示子に、対応する引数に適用不可能な変換文字が含まれる場合、IllegalFormatConversionExceptionがスローされます。

precisionの値はゼロからInteger.MAX_VALUEの範囲内 (包含)である必要があり、そうでない場合はIllegalFormatPrecisionExceptionがスローされます。

widthの値は、1からInteger.MAX_VALUEの範囲内 (包含)である必要があります。それ以外の場合は、IllegalFormatWidthExceptionがスローされます。幅は負の値になる可能性がありますが、負の符号はflagであることに注意してください。 たとえば、書式文字列"%-20s"では、widthは20で、flagは"-"です。

「インデックス」の値は、1からInteger.MAX_VALUEの範囲内 (包含)である必要があります。そうでない場合は、IllegalFormatExceptionがスローされます。

指定された例外はすべて、Formatterのformatメソッドのいずれか、およびString.formatやPrintStream.printfなどのformat簡易メソッドのいずれかによりスローされます。

カテゴリ一般、文字、数値、整数および日付/時間の変換では、引数argがnullの場合、結果は"null"です。

大文字(つまり、'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A'、および'T')で表された変換は、それぞれの小文字を使用する変換と同じですが、変換の結果は一般的に使用されているLocaleのルールに従って大文字に変換されます。 インスタンスの構成時、またはメソッドの起動に対するパラメータとして明示的なロケールが指定されていない場合は、default localeが使用されます。

一般

次の一般変換を、任意の引数型に適用できます。

dgConv
変換 Unicode 説明
'b' '\u0062' Boolean.toString(boolean)により返されるtrueまたはfalseを生成します。

引数がnullの場合、結果は「false」になります。 引数がbooleanまたはBooleanの場合、結果はString.valueOf()により返される文字列になります。 そうでない場合、結果はtrueになります。

'#'フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'B' '\u0042' 'b'の大文字のバリアントです。
'h' '\u0068' オブジェクトのハッシュ・コード値を表す文字列を生成します。

結果はInteger.toHexString(arg.hashCode())を呼び出すことによって得られます。

'#'フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'H' '\u0048' 'h'の大文字のバリアントです。
's' '\u0073' 文字列を生成します。

引数がFormattableを実装する場合、formatToメソッドが呼び出されます。 そうでない場合、結果は引数のtoString()メソッドの呼出しで取得されます。

'#'フラグが指定され、引数がFormattableでない場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'S' '\u0053' 's'の大文字のバリアントです。

次のフラグが一般変換に適用されます。

dFlags
フラグ Unicode 説明
'-' '\u002d' 左揃えで出力します。 スペース('\u0020')は、フィールドの最小幅を埋めるために必要に応じて、変換された値の末尾に追加されます。 widthが指定されていない場合は、MissingFormatWidthExceptionがスローされます。 このフラグが指定されていない場合、右揃えで出力されます。
'#' '\u0023' 出力で代替フォームを使用する必要があります。 フォームの定義は変換で指定されます。

widthは、出力に書き込まれる最小文字数です。 変換された値の長さが幅より小さい場合、合計文字数が幅に等しくなるまで、出力は'  ' ('\u0020')によってパディングされます。 デフォルトでは、左側にパディングされます。 '-'フラグが指定された場合、右側にパディングされます。 widthが指定されていない場合、最小値は存在しません。

precisionは、出力に書き込まれる最大文字数です。 precisionはwidthの前に適用されるため、widthの値がprecisionより大きい場合でも、出力はprecisionで指定された文字数に切り詰められます。 precisionが指定されていない場合、文字数に明示的な制限は存在しません。

文字

この変換は、charおよびCharacterに適用できます。 Character.isValidCodePoint(int)がtrueを返すときは、byte、Byte、short、Short、int、およびIntegerの各型にも適用できます。 falseが返された場合、IllegalFormatCodePointExceptionがスローされます。

charConv
変換 Unicode 説明
'c' '\u0063' 「Unicode文字表現」の記述に従い、引数をUnicode文字として書式設定します。 引数が補助文字を表す場合、これを1つ以上の16ビットcharにできます。

'#'フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'C' '\u0043' 'c'の大文字のバリアントです。

一般変換用に定義された'-'フラグが適用されます。 '#'フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

widthは、一般変換用に定義されます。

precisionは適用できません。 precisionが指定された場合は、IllegalFormatPrecisionExceptionがスローされます。

数値

数値変換は、次のカテゴリに分けられます。

  1. Byte、Short、Integer、およびLong
  2. BigInteger
  3. FloatおよびDouble
  4. BigDecimal

数値型は、次のアルゴリズムに従って書式設定されます。

数値のローカリゼーション・アルゴリズム

整数部、小数部、および指数(データ型で必要な場合)の数字の取得後に、次の変換が適用されます。

  1. 文字列内の各数字dは、現在のロケールのゼロ数字 zを基準に計算されたロケール固有の数字で置き換えられます。つまり、d -  '0'  + zになります。
  2. 小数区切り文字が存在する場合、ロケール固有の小数区切り文字に置き換えられます。
  3. ',' ('\u002c') flagが指定されている場合は、文字列の整数の部分を最下位から最上位の桁までスキャンし、ロケールの「グループ・サイズ」で定義された間隔でセパレータを挿入することで、ロケール固有の「グループ化セパレータ」が挿入されます。
  4. '0'フラグが指定された場合、文字列の長さが要求されたフィールド幅と等しくなるまで、ロケール固有のゼロ数字が記号の後ろ(記号が存在する場合)と、最初のゼロ以外の数字の前に挿入されます。
  5. 値が負の値で、'('フラグが指定されている場合は、'(' ('\u0028')が先頭に付加され、')' ('\u0029')が追加されます。
  6. 値が負の(または浮動小数点が負のゼロです)で、'('フラグが指定されていない場合は、'-' ('\u002d')が先頭に付加されます。
  7. '+'フラグが指定され、値が正またはゼロの (または浮動小数点の正のゼロ)である場合、'+' ('\u002b')が先頭に付加されます。

値がNaNまたは正の無限大の場合、リテラル文字列「NaN」または「Infinity」がそれぞれ出力されます。 値が負の無限大の場合、'('フラグが指定されていると出力は「(Infinity)」になり、そうでない場合は「-Infinity」になります。 これらの値のローカライズは行われません。

Byte、Short、Integer、およびLong

次の変換をbyte、Byte, short、Short, int、Integer, long、およびLongに適用できます。

IntConv
変換 Unicode 説明
'd' '\u0064' 引数を10進整数として書式設定します。 ローカリゼーション・アルゴリズムが適用されます。

'0'フラグが指定され、値が負の場合、符号の後ろにゼロがパディングされます。

'#'フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'o' '\u006f' 引数を、基数8の整数として書式設定します。 ローカリゼーションは適用されません。

xが負の場合、結果は、値に2nを追加して生成された符号なしの値になります。nは必要に応じ、Byte、Short、Integer、またはLongクラス内のstatic SIZEフィールドにより返される型のビット数です。

'#'フラグが指定された場合、出力は常に基数指示子'0'で始まります。

'0'フラグが指定された場合、出力では、符号指示に続くフィールド幅の先頭にゼロがパディングされます。

'('、'+'、'  '、または','フラグが指定されている場合、FormatFlagsConversionMismatchExceptionがスローされます。

'x' '\u0078' 引数を、基数16の整数として書式設定します。 ローカリゼーションは適用されません。

xが負の場合、結果は、値に2nを追加して生成された符号なしの値になります。nは必要に応じ、Byte、Short、Integer、またはLongクラス内のstatic SIZEフィールドにより返される型のビット数です。

'#'フラグが指定された場合、出力は常に基数指示子"0x"で始まります。

'0'フラグが指定された場合、出力では、基数指示子または符号(存在する場合)のあとのフィールド幅の先頭にゼロがパディングされます。

'(', '  ', '+'または','フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'X' '\u0058' 'x'の大文字のバリアントです。 数値を表す文字列全体が、'x' (もしあれば)およびすべての16進数'a' - 'f' ('\u0061' - '\u0066')を含む「大文字」に変換されます。

変換が'o'、'x'、または'X'で、フラグ'#'と'0'の両方のフラグが指定されている場合、結果には基数指示子(8進の場合は'0'、16進の場合は"0x"または"0X")、いくつかのゼロ(widthに基づく)、および値が含まれます。

'-'フラグが指定されていない場合、符号の前に空白がパディングされます。

次のフラグが、数値整数変換に適用されます。

intFlags
変換 Unicode 説明
'+' '\u002b' 出力で、正の数すべてに正の符号を含める必要があります。 このフラグが指定されていない場合、負の値にのみ符号が含められます。

'+'フラグと'  'フラグの両方が指定されている場合は、IllegalFormatFlagsExceptionがスローされます。

'  ' '\u0020' 負でない値に対して1つの余分な領域('\u0020')を出力に含める必要があります。

'+'フラグと'  'フラグの両方が指定されている場合は、IllegalFormatFlagsExceptionがスローされます。

'0' '\u0030' 出力で、次の符号または基数指示子に続く最小フィールド幅の先頭にゼロをパディングする必要があります(NaNまたは無限の変換時を除く)。 widthが指定されていない場合は、MissingFormatWidthExceptionがスローされます。

フラグ'-'と'0''の両方が指定されている場合は、IllegalFormatFlagsExceptionがスローされます。

',' '\u002c' 出力にロケール固有のグループ区切り文字を含める必要があります。詳細は、ローカリゼーション・アルゴリズムの「グループ」セクションを参照してください。
'(' '\u0028' '(' ('\u0028')の前に')' ('\u0029')を負の値に追加するには、出力が必要です。

フラグが指定されていない場合の、デフォルト書式設定は次のとおりです。

  • 出力は、width内で右揃えされる
  • 負の数は、'-' ('\u002d')で始まります
  • 正の数およびゼロには、符号も先頭の余分な空白も付加されない
  • グループ化区切り文字は含まれない

widthは、出力に書き込まれる最小文字数です。 これには、符号、数字、グループ化区切り文字、基数指示子、およびカッコが含まれます。 変換された値の長さが幅より小さい場合、合計文字数が幅になるまで、出力は空白('\u0020')でパディングされます。 デフォルトでは、左側にパディングされます。 '-'フラグが指定された場合、右側にパディングされます。 widthが指定されていない場合、最小値は存在しません。

precisionは適用できません。 precisionが指定された場合は、IllegalFormatPrecisionExceptionがスローされます。

BigInteger

次の変換をBigIntegerに適用できます。

bIntConv
変換 Unicode 説明
'd' '\u0064' 出力を10進整数として書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

'#'フラグが指定された場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'o' '\u006f' 出力を、基数8の整数として書式設定する必要があります。 ローカリゼーションは適用されません。

xが負の場合、結果は'-' ('\u002d')で始まる符号付きの値になります。 これは、プリミティブ型とは異なり、明示的なデータ型サイズを想定せずに等価な符号なしの値を作成することは不可能であるためです。

xが正またはゼロで、'+'フラグが指定されている場合、結果は'+' ('\u002b')で始まります。

'#'フラグが指定された場合、出力は常に接頭辞'0'で始まります。

'0'フラグが指定された場合、出力では、符号指示に続くフィールド幅の先頭にゼロがパディングされます。

','フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'x' '\u0078' 出力を、基数16の整数として書式設定する必要があります。 ローカリゼーションは適用されません。

xが負の場合、結果は'-' ('\u002d')で始まる符号付きの値になります。 これは、プリミティブ型とは異なり、明示的なデータ型サイズを想定せずに等価な符号なしの値を作成することは不可能であるためです。

xが正またはゼロで、'+'フラグが指定されている場合、結果は'+' ('\u002b')で始まります。

'#'フラグが指定された場合、出力は常に基数指示子"0x"で始まります。

'0'フラグが指定された場合、出力では、基数指示子または符号(存在する場合)のあとのフィールド幅の先頭にゼロがパディングされます。

','フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'X' '\u0058' 'x'の大文字のバリアントです。 数値を表す文字列全体が、'x' (もしあれば)およびすべての16進数'a' - 'f' ('\u0061' - '\u0066')を含む「大文字」に変換されます。

変換が'o'、'x'、または'X'で、フラグ'#'と'0'の両方のフラグが指定されている場合、結果には基底指示子(8進の場合は'0'、16進の場合は"0x"または"0X")、いくつかのゼロ(widthに基づく)、および値が含まれます。

'0'フラグが指定され、値が負の場合、符号の後ろにゼロがパディングされます。

'-'フラグが指定されていない場合、符号の前に空白がパディングされます。

Byte、Short、Integer、およびLong用に定義されたすべてのフラグが適用されます。 フラグが指定されない場合のデフォルト動作は、Byte、Short、Integer、およびLongのデフォルト動作と同じです。

widthの仕様は、Byte、Short、Integer、およびLongで定義された仕様と同じです。

precisionは適用できません。 precisionが指定された場合は、IllegalFormatPrecisionExceptionがスローされます。

FloatおよびDouble

次の変換をfloat、Float、double、およびDoubleに適用できます。

floatConv
変換 Unicode 説明
'e' '\u0065' 出力を浮動小数点表記を使用して書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

floatまたはFloat引数は、精度を失うことなく、最初にdoubleまたはDoubleに変換されます。

絶対値mの書式設定は、値により異なります。

mがNaNまたは無限大の場合、リテラル文字列「NaN」または「Infinity」がそれぞれ出力されます。 これらの値のローカライズは行われません。

mが正のゼロまたは負のゼロの場合、指数は"+00"になります。

そうでない場合、結果は、引数の符号および絶対値を表す文字列になります。 符号の書式設定については、ローカリゼーション・アルゴリズムを参照してください。 絶対値mの書式設定は、値により異なります。

nを10n <= m < 10n+1などの一意の整数とし、aを1 <= a < 10となるようなmと10nの数学的に正確な商とします。 大きさは、aの整数部分として1桁の10進数で表され、その後に小数点セパレータの後に、aの小数部を表す10進数に続いて指数で表されます。記号'e' ('\u0065')のあとに指数の符号が続き、そのあとにnを10進整数で表したものがメソッドLong.toString(long, int)によって生成され、少なくとも2桁を含むようにゼロが埋め込まれます。

結果内のmまたはaの小数部の桁数は、precisionと等しくなります。 precisionが指定されていない場合、デフォルト値は6です。 精度が、Double.toString(double)で返される文字列の小数点以下に表示される桁数より小さい場合、値は「端数切上げアルゴリズム」を使用して丸められます。 そうでない場合、precisionの値に達するように末尾にゼロを付加できます。 値の正規表現の場合は、Float.toString(float)またはDouble.toString(double)を適宜使用します。

','フラグが指定された場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'E' '\u0045' 'e'の大文字のバリアントです。 指数記号は、'E' ('\u0045')になります。
'g' '\u0067' 一般の科学表記法を使用して出力を書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

precisionの四捨五入処理後の結果として得られる絶対値mの書式設定は、その値により異なります。

mが10-4以上で、10precision未満の場合、それは10進フォーマットで表現されます。

mが10-4未満、あるいは10precision以上の場合、それは浮動小数点表記で表現されます。

mの有効桁数の合計は、precisionと等しくなります。 precisionが指定されていない場合、デフォルト値は6です。 precisionが0の場合、それは1になります。

'#'フラグが指定された場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'G' '\u0047' 'g'の大文字のバリアントです。
'f' '\u0066' 出力を10進フォーマットを使用して書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

floatまたはFloat引数は、精度を失うことなく、最初にdoubleまたはDoubleに変換されます。

結果は、引数の符号および絶対値を表す文字列になります。 符号の書式設定については、ローカリゼーション・アルゴリズムを参照してください。 絶対値mの書式設定は、値により異なります。

mがNaNまたは無限大の場合、リテラル文字列「NaN」または「Infinity」がそれぞれ出力されます。 これらの値のローカライズは行われません。

絶対値の書式は、mの整数部(先頭にゼロが付加されない)、小数点、およびmの小数部を表す1桁以上の10進数が、その順番で表記されたものになります。

結果内のmまたはaの小数部の桁数は、precisionと等しくなります。 precisionが指定されていない場合、デフォルト値は6です。 精度が、Double.toString(double)で返される文字列の小数点以下に表示される桁数より小さい場合、値は「端数切上げアルゴリズム」を使用して丸められます。 そうでない場合、precisionの値に達するように末尾にゼロを付加できます。 値の正規表現の場合は、Float.toString(float)またはDouble.toString(double)を適宜使用します。

'a' '\u0061' 出力の書式を16進の指数で設定する必要があります。 ローカリゼーションは適用されません。

結果は、引数xの符号および絶対値を表す文字列になります。

xが負の値または負のゼロの値の場合、結果は'-' ('\u002d')で始まります。

xが正の値または正の値で、'+'フラグが指定されている場合、結果は'+' ('\u002b')で始まります。

絶対値mの書式設定は、値により異なります。

  • 値がNaNまたは無限大の場合、リテラル文字列「NaN」または「Infinity」がそれぞれ出力されます。
  • mがゼロの場合、これは文字列"0x0.0p0"で表現されます。
  • mが正規化された表現のdouble値の場合は、有効数字と指数のフィールドを表すのに部分文字列が使用されます。 有効数字は、文字列"0x1."と、有効数字の残りの小数部分の16進表現を付加して表現されます。 指数は、'p' ('\u0070')の後に、指数値に対してInteger.toStringを呼び出すことによって生成される場合と同様に、バイアスされていない指数の10進文字列が続きます。 precisionが指定されている場合、その値は指定された16進の桁数に丸められます。
  • mが非正規表現のdouble値の場合、precisionが1-12(これを含む)の範囲になるように指定されないかぎり、有効数字は文字列'0x0.'に、有効数字の残りの小数部分の16進表現と、'p-1022'で表された指数を付加して表現されます。 precisionの間隔が[1, 12]である場合、非正規化値は、'0x1.'という文字で始まり、precisionが16進の桁数に丸められるように正規化され、それに従って指数が調整されます。 サブノーマル有効数字内に、ゼロでない数字が1つ以上存在する必要があることに留意してください。

'('または','フラグが指定されている場合、FormatFlagsConversionMismatchExceptionがスローされます。

'A' '\u0041' 'a'の大文字のバリアントです。 数を表す文字列全体が、'x' ('\u0078')および'p' ('\u0070'およびすべての16進数'a'を含む大文字に変換されます - 'f' ('\u0061' - '\u0066').

Byte、Short、Integer、およびLong用に定義されたすべてのフラグが適用されます。

'#'フラグが指定されている場合、小数点が常に存在します。

フラグが指定されていない場合の、デフォルト書式設定は次のとおりです。

  • 出力は、width内で右揃えされる
  • 負の数は、'-'で始まる
  • 正の数および正のゼロには、符号も先頭の余分な空白も付加されない
  • グループ化区切り文字は含まれない
  • 小数点は、そのあとに数字が表記される場合にのみ表示される

widthは、出力に書き込まれる最小文字数です。 これには、符号、数字、グループ化区切り文字、10進数区切り文字、指数記号、基数指示子、カッコ、およびInfinityとNaNを規定どおりに表す文字列が含まれます。 変換された値の長さが幅より小さい場合、合計文字数が幅になるまで、出力は空白('\u0020')でパディングされます。 デフォルトでは、左側にパディングされます。 '-'フラグが指定された場合、右側にパディングされます。 widthが指定されていない場合、最小値は存在しません。

変換が'e'、'E'、または'f'の場合、precisionは小数以下の桁数です。 precisionが指定されていない場合、6であるとみなされます。

変換が'g'または'G'の場合は、四捨五入処理後の結果として得られる絶対値の有効桁の合計数です。 precisionが指定されていない場合、デフォルト値は6です。 precisionが0の場合、それは1になります。

変換が'a'または'A'の場合、precisionは基数点以下の16進の桁数になります。 precisionが指定されない場合、Double.toHexString(double)によって返される、すべての桁が出力されます。

BigDecimal

次の変換をBigDecimalに適用できます。

floatConv
変換 Unicode 説明
'e' '\u0065' 出力を浮動小数点表記を使用して書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

絶対値mの書式設定は、値により異なります。

mが正のゼロまたは負のゼロの場合、指数は"+00"になります。

そうでない場合、結果は、引数の符号および絶対値を表す文字列になります。 符号の書式設定については、ローカリゼーション・アルゴリズムを参照してください。 絶対値mの書式設定は、値により異なります。

nを10n <= m < 10n+1などの一意の整数とし、aを1 <= a < 10となるようなmと10nの数学的に正確な商とします。 大きさは、aの整数部分として1桁の10進数で表され、その後に小数点セパレータの後に、aの小数部を表す10進数に続いて指数で表されます。記号'e' ('\u0065')のあとに指数の符号が続き、そのあとにnを10進整数で表したものがメソッドLong.toString(long, int)によって生成され、少なくとも2桁を含むようにゼロが埋め込まれます。

結果内のmまたはaの小数部の桁数は、precisionと等しくなります。 precisionが指定されていない場合、デフォルト値は6です。 precisionが小数点の右側にある桁数よりも小さい場合、その値は半切上げアルゴリズムを使用して四捨五入されます。 そうでない場合、precisionの値に達するように末尾にゼロを付加できます。 値の正規表現では、BigDecimal.toString()を使用します。

','フラグが指定された場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'E' '\u0045' 'e'の大文字のバリアントです。 指数記号は、'E' ('\u0045')になります。
'g' '\u0067' 一般の科学表記法を使用して出力を書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

precisionの四捨五入処理後の結果として得られる絶対値mの書式設定は、その値により異なります。

mが10-4以上で、10precision未満の場合、それは10進フォーマットで表現されます。

mが10-4未満、あるいは10precision以上の場合、それは浮動小数点表記で表現されます。

mの有効桁数の合計は、precisionと等しくなります。 precisionが指定されていない場合、デフォルト値は6です。 precisionが0の場合、それは1になります。

'#'フラグが指定された場合は、FormatFlagsConversionMismatchExceptionがスローされます。

'G' '\u0047' 'g'の大文字のバリアントです。
'f' '\u0066' 出力を10進フォーマットを使用して書式設定する必要があります。 ローカリゼーション・アルゴリズムが適用されます。

結果は、引数の符号および絶対値を表す文字列になります。 符号の書式設定については、ローカリゼーション・アルゴリズムを参照してください。 絶対値mの書式設定は、値により異なります。

絶対値の書式は、mの整数部(先頭にゼロが付加されない)、小数点、およびmの小数部を表す1桁以上の10進数が、その順番で表記されたものになります。

結果内のmまたはaの小数部の桁数は、precisionと等しくなります。 precisionが指定されていない場合、デフォルト値は6です。 precisionが小数点の右側にある桁数よりも小さい場合、その値は半切上げアルゴリズムを使用して四捨五入されます。 そうでない場合、precisionの値に達するように末尾にゼロを付加できます。 値の正規表現では、BigDecimal.toString()を使用します。

Byte、Short、Integer、およびLong用に定義されたすべてのフラグが適用されます。

'#'フラグが指定されている場合、小数点が常に存在します。

フラグが指定されない場合のデフォルト動作は、FloatおよびDoubleと同じです。

widthおよびprecisionの仕様は、FloatおよびDoubleで定義された仕様と同じです。

日付/時間

この変換は、long、Long、Calendar、Date、およびTemporalAccessorに適用できます

DTConv
変換 Unicode 説明
't' '\u0074' 日付および時刻変換文字の接頭辞です。
'T' '\u0054' 't'の大文字のバリアントです。

次の日付および時刻変換文字の接尾辞が、't'および'T'変換用に定義されています。 この型は、GNU dateおよびPOSIX strftime(3c)で定義された型に類似していますが完全に同一ではありません。 秒内のミリ秒を表す'L'など、Java固有の機能にアクセスするための追加の変換型が提供されています。

時刻の書式設定では、次の変換文字が使用されます。

time
変換 Unicode 説明
'H' '\u0048' 24時間制の時。必要に応じて0を先頭に追加し、2桁で表現します(00 - 23)。00は深夜零時に対応します。
'I' '\u0049' 12時間制の時。必要に応じて0を先頭に追加し、2桁で表現します(01 - 12)。01は1時(午前または午後)に対応します。
'k' '\u006b' 24時間制の時(0 - 23)。0は深夜零時に対応します。
'l' '\u006c' 12時間制の時(1 - 12)。1は1時(午前または午後)に対応します。
'M' '\u004d' 分。必要に応じて0を先頭に追加し、2桁で表現します(00 - 59)。
'S' '\u0053' 秒。必要に応じて0を先頭に追加し、2桁で表現します(00 - 60)。「60」はうるう年での秒のサポートに必要な特殊な値です。
'L' '\u004c' ミリ秒。必要に応じて0を先頭に追加し、3桁で表現します(000 - 999)。
'N' '\u004e' ナノ秒。必要に応じて0を先頭に追加し、9桁で表現します(000000000 - 999999999)。 この値の精度は、背後のオペレーティング・システムまたはハードウェアの解像度により制限されます。
'p' '\u0070' ロケール固有の午前または午後を示す小文字のマーカー(「am」または「pm」など)。 変換接頭辞の'T'を使用すると、結果は大文字で強制出力されます。 ('p'は小文字で出力される。 これは大文字で出力されるGNUのdateおよびPOSIXのstrftime(3c)とは異なる)。
'z' '\u007a' RFC 822に準拠した、GMTからの数値タイムゾーン・オフセット(-0800など)。 この値は、必要に応じて夏時間で調整されます。 long、Long、およびDateの場合、使用されるタイムゾーンは、このJava仮想マシン・インスタンスのデフォルト・タイム・ゾーンです。
'Z' '\u005a' タイムゾーンの省略形を表す文字列。 この値は、必要に応じて夏時間で調整されます。 long、Long、およびDateの場合、使用されるタイムゾーンは、このJava仮想マシン・インスタンスのデフォルト・タイム・ゾーンです。 Formatterのロケールは、引数のロケール(存在する場合)よりも優先されます。
's' '\u0073' 1970年1月1日00:00:00 UTCの元期開始からの秒(Long.MIN_VALUE/1000からLong.MAX_VALUE/1000まで)。
'Q' '\u004f' 1970年1月1日00:00:00 UTCの元期開始からのミリ秒(Long.MIN_VALUEからLong.MAX_VALUEまで)。 この値の精度は、背後のオペレーティング・システムまたはハードウェアの解像度により制限されます。

日付の書式設定では、次の変換文字が使用されます。

date
変換 Unicode 説明
'B' '\u0042' ロケール固有の月の完全な名前 ("January"、"February"など)。
'b' '\u0062' ロケール固有の月の省略名 ("Jan"、"Feb"など)。
'h' '\u0068' 'b'と同じ。
'A' '\u0041' ロケール固有の曜日の完全な名前("Sunday"、"Monday"など)。
'a' '\u0061' ロケール固有の曜日の短縮名("Sun"、"Mon"など)。
'C' '\u0043' 4桁の年を100で割った値。必要に応じて0を先頭に追加し、2桁で表示します(00 - 99)
'Y' '\u0059' 年。必要に応じて0を先頭に追加し、4桁以上で表現します。たとえば、0092は、グレゴリオ歴の92 CEと等価です。
'y' '\u0079' 年の下2桁。必要に応じて0を先頭に追加します(00 - 99)。
'j' '\u006a' 年の何日目かを表す日。必要に応じて0を先頭に追加し、3桁で表現します。たとえば、グレゴリオ歴の場合、001 - 366になります。001は、年の最初の日に対応します。
'm' '\u006d' 月。必要に応じて0を先頭に追加し、2桁で表現します(01 - 13)。「01」は、年の最初の月です(「13」は太陰暦のサポートに必要な特殊な値)。
'd' '\u0064' 月の何日目かを表す日。必要に応じて0を先頭に追加し、2桁で表現します(01 - 31)。「01」は、月の最初の日を表します。
'e' '\u0065' 月の何日目かを表す日。最大2桁で表現します(1 - 31)。「1」は、月の最初の日を表します。

一般の日付/時刻変換の書式設定では、次の変換文字が使用されます。

composites
変換 Unicode 説明
'R' '\u0052' "%tH:%tM"として24時間制で書式設定された時刻。
'T' '\u0054' "%tH:%tM:%tS"として24時間制で書式設定された時刻。
'r' '\u0072' "%tI:%tM:%tS %Tp"として12時間制で書式設定された時刻。 午前および午後を示すマーカー('%Tp')の位置はロケールによって異なります。
'D' '\u0044' "%tm/%td/%ty"として書式設定された日付。
'F' '\u0046' "%tY-%tm-%td"として書式設定されたISO 8601に準拠した日付。
'c' '\u0063' "%ta %tb %td %tT %tZ %tY"として書式設定された日付および時間("Sun Jul 20 16:17:00 EDT 1969"など)。

一般変換用に定義された'-'フラグが適用されます。 '#'フラグが指定されている場合は、FormatFlagsConversionMismatchExceptionがスローされます。

widthは、出力に書き込まれる最小文字数です。 変換された値の長さがwidthより小さい場合、合計文字数が幅になるまで、出力は空白('\u0020')でパディングされます。 デフォルトでは、左側にパディングされます。 '-'フラグが指定された場合、右側にパディングされます。 widthが指定されていない場合、最小値は存在しません。

precisionは適用できません。 precisionが指定された場合は、IllegalFormatPrecisionExceptionがスローされます。

パーセント

この変換に対応する引数はありません。

DTConv
変換 説明
'%' 結果は、リテラル'%' ('\u0025')です

widthは、出力に書き込まれる、'%'を含む最小文字数です。 変換された値の長さがwidthより小さい場合、合計文字数が幅になるまで、出力は空白('\u0020')でパディングされます。 パディングは左側に行われます。 widthが指定されていない場合、'%'だけが出力されます。

一般変換用に定義された'-'フラグが適用されます。 その他のフラグを指定すると、IllegalFormatFlagsExceptionがスローされます。

precisionは適用できません。 precisionが指定された場合は、IllegalFormatPrecisionExceptionがスローされます。

行区切り文字

この変換に対応する引数はありません。

DTConv
変換 説明
'n' System.lineSeparator()によって返されるプラットフォーム固有の行区切り文字。

flags、width、およびprecisionは適用できません。 これらが指定された場合、IllegalFormatFlagsException, IllegalFormatWidthException、およびIllegalFormatPrecisionExceptionがそれぞれスローされます。

引数索引

書式指示子は、次の3つの方法で引数を参照できます。

  • 明示的なインデックス指定は、書式指示子に引数インデックスが含まれる場合に使用します。 引数インデックスは、引数リスト内での引数の位置を示す10進整数です。 最初の引数は「1$」、2番目の引数は「2$」で参照されます。引数は、複数回参照できます。

    たとえば、 

       formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s",
                    "a", "b", "c", "d")
   // -> "d c b a d c b a"
  • 「相対索引付け」は、書式指定子に'<' ('\u003c')フラグが含まれている場合に使用されます。このフラグによって、前の書式指定子の引数が再使用されます。 以前の引数が存在しない場合、MissingFormatArgumentExceptionがスローされます。 
        formatter.format("%s %s %<s %<s", "a", "b", "c", "d")
    // -> "a b b b"
    // "c" and "d" are ignored because they are not referenced
  • 通常のインデックス指定は、書式指示子に引数インデックスも'<'フラグも含まれない場合に使用します。 通常のインデックス指定を使用する各書式指示子には、引数リストに対する暗黙の順次インデックスが割り当てられます。 
       formatter.format("%s %s %s %s", "a", "b", "c", "d")
   // -> "a b c d"

1つの書式文字列ですべてのインデックス指定を使用できます。たとえば: 

   formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
   // -> "b a a b"
   // "c" and "d" are ignored because they are not referenced

引数の最大数は、「Java Virtual Machine仕様」で定義されているJava配列の最大サイズによって制限されます。 引数索引が使用可能な引数に対応していない場合は、MissingFormatArgumentExceptionがスローされます。

書式指示子よりも引数が多い場合、余分な引数は無視されます。

特に指定されていないかぎり、null引数をこのクラスのメソッドまたはコンストラクタに渡すと、NullPointerExceptionがスローされます。

導入されたバージョン:
1.5
外部仕様

  • ネストされたクラスのサマリー

    ネストされたクラス
    修飾子と型
    クラス
    説明
    static enum 
    Formatter.BigDecimalLayoutForm
    BigDecimalの書式設定用の列挙型です。

  • コンストラクタのサマリー

    コンストラクタ
    コンストラクタ
    説明
    Formatter()
    新しいフォーマッタを構築します。
    Formatter(File file)
    指定されたファイルを持つ新しいフォーマッタを構築します。
    Formatter(File file, String csn)
    指定されたファイルおよび文字セットを持つ新しいフォーマッタを構築します。
    Formatter(File file, String csn, Locale l)
    指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(File file, Charset charset, Locale l)
    指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(OutputStream os)
    指定された出力ストリームを持つ新しいフォーマッタを構築します。
    Formatter(OutputStream os, String csn)
    指定された出力ストリームおよび文字セットを持つ新しいフォーマッタを構築します。
    Formatter(OutputStream os, String csn, Locale l)
    指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(OutputStream os, Charset charset, Locale l)
    指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(PrintStream ps)
    指定された出力ストリームを持つ新しいフォーマッタを構築します。
    Formatter(Appendable a)
    指定された宛先を持つ新しいフォーマッタを構築します。
    Formatter(Appendable a, Locale l)
    指定された宛先およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(String fileName)
    指定されたファイル名を持つ新しいフォーマッタを構築します。
    Formatter(String fileName, String csn)
    指定されたファイル名および文字セットを持つ新しいフォーマッタを構築します。
    Formatter(String fileName, String csn, Locale l)
    指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(String fileName, Charset charset, Locale l)
    指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
    Formatter(Locale l)
    指定されたロケールを持つ新しいフォーマッタを構築します。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    close()
    このフォーマッタを閉じます。
    void
    flush()
    このフォーマッタをフラッシュします。
    Formatter
    format(String format, Object... args)
    指定された書式文字列および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。
    Formatter
    format(Locale l, String format, Object... args)
    指定されたロケール、書式文字列、および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。
    IOException
    ioException()
    このフォーマッタのAppendableにより最後にスローされたIOExceptionを返します。
    Locale
    locale()
    このフォーマッタを構築することで設定されたロケールを返します。
    Appendable
    out()
    出力先を返します。
    String
    toString()
    出力先に対してtoString()を呼び出した結果を返します。

    クラスjava.lang.Objectで宣言されたメソッド

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • コンストラクタの詳細

    • Formatter

      public Formatter()
      新しいフォーマッタを構築します。

      書式付き出力の宛先は、StringBuilderです。これは、out()を呼び出すことで取得できます。また、toString()を呼び出すことで、現在の内容を文字列に変換できます。 使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

    • Formatter

      public Formatter(Appendable a)
      指定された宛先を持つ新しいフォーマッタを構築します。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      a - 書式付き出力の宛先。 aがnullの場合、StringBuilderが作成される。

    • Formatter

      public Formatter(Locale l)
      指定されたロケールを持つ新しいフォーマッタを構築します。

      書式付き出力の宛先は、StringBuilderです。これは、out()を呼び出すことで取得できます。また、toString()を呼び出すことで、現在の内容を文字列に変換できます。

      パラメータ:
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。

    • Formatter

      public Formatter(Appendable a, Locale l)
      指定された宛先およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      a - 書式付き出力の宛先。 aがnullの場合、StringBuilderが作成される。
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。

    • Formatter

      public Formatter(String fileName) throws FileNotFoundException
      指定されたファイル名を持つ新しいフォーマッタを構築します。

      使用される文字セットは、このJava仮想マシン・インスタンスのデフォルト文字セットです。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      fileName - このフォーマッタの宛先として使用されるファイルの名前。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      スロー:
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(fileName)がファイルへの書込みアクセスを拒否した場合
      FileNotFoundException - 指定されたファイル名が既存の書込み可能な通常ファイルを示さず、新規の通常ファイルをその名前で作成できない場合、またはファイルのオープンまたは作成中にほかのエラーが発生した場合

    • Formatter

      public Formatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException
      指定されたファイル名および文字セットを持つ新しいフォーマッタを構築します。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      fileName - このフォーマッタの宛先として使用されるファイルの名前。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      csn - サポートされているcharsetの名前
      スロー:
      FileNotFoundException - 指定されたファイル名が既存の書込み可能な通常ファイルを示さず、新規の通常ファイルをその名前で作成できない場合、またはファイルのオープンまたは作成中にほかのエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(fileName)がファイルへの書込みアクセスを拒否した場合
      UnsupportedEncodingException - 指定された文字セットがサポートされていない場合

    • Formatter

      public Formatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
      指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      fileName - このフォーマッタの宛先として使用されるファイルの名前。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      csn - サポートされているcharsetの名前
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。
      スロー:
      FileNotFoundException - 指定されたファイル名が既存の書込み可能な通常ファイルを示さず、新規の通常ファイルをその名前で作成できない場合、またはファイルのオープンまたは作成中にほかのエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(fileName)がファイルへの書込みアクセスを拒否した場合
      UnsupportedEncodingException - 指定された文字セットがサポートされていない場合

    • Formatter

      public Formatter(String fileName, Charset charset, Locale l) throws IOException
      指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      fileName - このフォーマッタの宛先として使用されるファイルの名前。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      charset - A charset
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。
      スロー:
      IOException - ファイルのオープンまたは作成中にI/Oエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(fileName)がファイルへの書込みアクセスを拒否した場合
      NullPointerException - fileNameまたはcharsetがnullの場合。

    • Formatter

      public Formatter(File file) throws FileNotFoundException
      指定されたファイルを持つ新しいフォーマッタを構築します。

      使用される文字セットは、このJava仮想マシン・インスタンスのデフォルト文字セットです。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      file - このフォーマッタの宛先として使用されるファイル。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      スロー:
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(file.getPath())がファイルへの書込みアクセスを拒否した場合
      FileNotFoundException - 指定されたファイル・オブジェクトが既存のファイルを示さない場合、書込み可能な通常ファイルおよび新規の通常ファイルがその名前で作成できない場合、またはファイルのオープンまたは作成中にその他のエラーが発生した場合

    • Formatter

      public Formatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException
      指定されたファイルおよび文字セットを持つ新しいフォーマッタを構築します。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      file - このフォーマッタの宛先として使用されるファイル。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      csn - サポートされているcharsetの名前
      スロー:
      FileNotFoundException - 指定されたファイル・オブジェクトが既存のファイルを示さない場合、書込み可能な通常ファイルおよび新規の通常ファイルがその名前で作成できない場合、またはファイルのオープンまたは作成中にその他のエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(file.getPath())がファイルへの書込みアクセスを拒否した場合
      UnsupportedEncodingException - 指定された文字セットがサポートされていない場合

    • Formatter

      public Formatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
      指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      file - このフォーマッタの宛先として使用されるファイル。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      csn - サポートされているcharsetの名前
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。
      スロー:
      FileNotFoundException - 指定されたファイル・オブジェクトが既存のファイルを示さない場合、書込み可能な通常ファイルおよび新規の通常ファイルがその名前で作成できない場合、またはファイルのオープンまたは作成中にその他のエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(file.getPath())がファイルへの書込みアクセスを拒否した場合
      UnsupportedEncodingException - 指定された文字セットがサポートされていない場合

    • Formatter

      public Formatter(File file, Charset charset, Locale l) throws IOException
      指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      file - このフォーマッタの宛先として使用されるファイル。 ファイルが存在する場合は、サイズ0に切り詰められる。そうでない場合は、新規ファイルが作成される。 出力はファイルに書き込まれ、バッファに格納される。
      charset - A charset
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。
      スロー:
      IOException - ファイルのオープンまたは作成中にI/Oエラーが発生した場合
      SecurityException - セキュリティ・マネージャが存在し、checkWrite(file.getPath())がファイルへの書込みアクセスを拒否した場合
      NullPointerException - fileまたはcharsetがnullの場合。

    • Formatter

      public Formatter(PrintStream ps)
      指定された出力ストリームを持つ新しいフォーマッタを構築します。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      文字は指定されたPrintStreamオブジェクトに書き込まれるため、このオブジェクトの文字セットを使用してエンコードされます。

      パラメータ:
      ps - このフォーマッタの宛先として使用されるストリーム。

    • Formatter

      public Formatter(OutputStream os)
      指定された出力ストリームを持つ新しいフォーマッタを構築します。

      使用される文字セットは、このJava仮想マシン・インスタンスのデフォルト文字セットです。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      os - このフォーマッタの宛先として使用される出力ストリーム。 出力はバッファに入れられる。

    • Formatter

      public Formatter(OutputStream os, String csn) throws UnsupportedEncodingException
      指定された出力ストリームおよび文字セットを持つ新しいフォーマッタを構築します。

      使用されるロケールは、このJava仮想マシン・インスタンスの書式設定用のデフォルト・ロケールです。

      パラメータ:
      os - このフォーマッタの宛先として使用される出力ストリーム。 出力はバッファに入れられる。
      csn - サポートされているcharsetの名前
      スロー:
      UnsupportedEncodingException - 指定された文字セットがサポートされていない場合

    • Formatter

      public Formatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException
      指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      os - このフォーマッタの宛先として使用される出力ストリーム。 出力はバッファに入れられる。
      csn - サポートされているcharsetの名前
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。
      スロー:
      UnsupportedEncodingException - 指定された文字セットがサポートされていない場合

    • Formatter

      public Formatter(OutputStream os, Charset charset, Locale l)
      指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
      パラメータ:
      os - このフォーマッタの宛先として使用される出力ストリーム。 出力はバッファに入れられる。
      charset - A charset
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。
      スロー:
      NullPointerException - osまたはcharsetがnullの場合。

  • メソッドの詳細

    • locale

      public Locale locale()
      このフォーマッタを構築することで設定されたロケールを返します。

      ロケール引数を持つこのオブジェクトのformatメソッドはこの値を変更しません。

      戻り値:
      ローカリゼーションが適用されない場合はnull、そうでない場合はロケール
      スロー:
      FormatterClosedException - close()メソッドを呼び出すことで、このフォーマッタが閉じられた場合

    • out

      public Appendable out()
      出力先を返します。
      戻り値:
      出力先
      スロー:
      FormatterClosedException - close()メソッドを呼び出すことで、このフォーマッタが閉じられた場合

    • toString

      public String toString()
      出力先に対してtoString()を呼び出した結果を返します。 たとえば、次のコードによりテキストがStringBuilder内で書式設定されて、結果の文字列が取得されます。 
         Formatter f = new Formatter();
   f.format("Last reboot at %tc", lastRebootDate);
   String s = f.toString();
   // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"

      このメソッド呼出しの動作は、次の呼出しの動作とまったく同一です。 

           out().toString()

      Appendableに対するtoStringの指定に応じて、返される文字列に宛先に書き込まれた文字が含まれることも、含まれないこともあります。 たとえば、通常、バッファはtoString()の内容を返しますが、ストリームではデータが破棄されるためにそれができません。

      オーバーライド:
      toString、クラスObject
      戻り値:
      出力先に対してtoString()を呼び出した結果
      スロー:
      FormatterClosedException - close()メソッドを呼び出すことで、このフォーマッタが閉じられた場合

    • flush

      public void flush()
      このフォーマッタをフラッシュします。 宛先がFlushableインタフェースを実装した場合、そのflushメソッドが呼び出されます。

      フォーマッタのフラッシュにより、宛先でバッファに入れられた任意の出力が基になるストリームに書き込まれます。

      定義:
      flush、インタフェースFlushable
      スロー:
      FormatterClosedException - close()メソッドを呼び出すことで、このフォーマッタが閉じられた場合

    • close

      public void close()
      このフォーマッタを閉じます。 宛先がCloseableインタフェースを実装した場合、そのcloseメソッドが呼び出されます。

      フォーマッタを閉じると、それが保持していたリソース(開いていたファイルなど)を解放できます。 フォーマッタがすでに閉じられている場合、このメソッドを呼び出しても何の効果もありません。

      このフォーマッタを閉じたあとで、このフォーマッタ内のioException()以外のメソッドを呼び出そうとすると、FormatterClosedExceptionがスローされます。

      定義:
      close、インタフェースAutoCloseable
      定義:
      close、インタフェースCloseable

    • ioException

      public IOException ioException()
      このフォーマッタのAppendableにより最後にスローされたIOExceptionを返します。

      宛先のappend()メソッドがまったくIOExceptionをスローしない場合、このメソッドは常にnullを返します。

      戻り値:
      Appendableによりスローされた最後の例外。該当する例外が存在しない場合はnull。

    • format

      public Formatter format(String format, Object... args)
      指定された書式文字列および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。 使用されるロケールは、このフォーマッタの構築時に定義されたロケールです。
      パラメータ:
      format - 「書式文字列の構文」で説明した書式文字列。
      args - 書式文字列の書式指示子により参照される引数。 引数が書式指定子よりも多い場合、余分な引数は無視されます。 引数の最大数は、「Java Virtual Machine仕様」で定義されているJava配列の最大サイズによって制限されます。
      戻り値:
      このフォーマッタ
      スロー:
      IllegalFormatException - 書式文字列が、不正な構文、所定の引数と互換性がない書式指示子、書式文字列に指定された不適切な引数、またはほかの不正な条件を含む場合。 考えられるすべての書式エラーの仕様については、フォーマッタ・クラス仕様の「詳細」セクションを参照。
      FormatterClosedException - close()メソッドを呼び出すことで、このフォーマッタが閉じられた場合

    • format

      public Formatter format(Locale l, String format, Object... args)
      指定されたロケール、書式文字列、および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。
      パラメータ:
      l - 書式設定時に適用するlocale。 lがnullの場合、ローカリゼーションは適用されない。 構築時に設定されたこのオブジェクトのロケールがこれによって変更されることはない。
      format - 「書式文字列の構文」で説明した書式文字列
      args - 書式文字列の書式指示子により参照される引数。 引数が書式指定子よりも多い場合、余分な引数は無視されます。 引数の最大数は、「Java Virtual Machine仕様」で定義されているJava配列の最大サイズによって制限されます。
      戻り値:
      このフォーマッタ
      スロー:
      IllegalFormatException - 書式文字列が、不正な構文、所定の引数と互換性がない書式指示子、書式文字列に指定された不適切な引数、またはほかの不正な条件を含む場合。 考えられるすべての書式エラーの仕様については、フォーマッタ・クラス仕様の「詳細」セクションを参照。
      FormatterClosedException - close()メソッドを呼び出すことで、このフォーマッタが閉じられた場合