JavaTM Platform
Standard Ed. 6

java.util
クラス Formatter

java.lang.Object
  上位を拡張 java.util.Formatter
すべての実装されたインタフェース:
Closeable, Flushable

public final class Formatter
extends Object
implements Closeable, Flushable

printf 形式の文字列用のインタプリタ。このクラスは、行揃えおよび水平配置レイアウト、数値、文字列、および日付/時刻データ用の共通書式、ロケール固有の出力をサポートします。byteBigDecimal、および 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$tm %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 で、カレンダ オブジェクト c で構成されます。

変換

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

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

次の表は、サポートする変換を要約したものです。大文字 (BHSCXEGA、および T など) で表された変換は、それぞれの小文字を使用する変換と同じですが、変換の結果は一般的に使用されている Locale の規則に従って大文字に変換されます。結果は、次の String.toUpperCase() を呼び出した場合と同じになります。

out.toUpperCase() 
変換 引数のカテゴリ 説明
bB 一般 引数 argnull の場合、結果は false になります。argboolean または Boolean の場合、結果は String.valueOf() により返される文字列になります。そうでない場合、結果は true になります。
hH 一般 引数 argnull の場合、結果は null になります。そうでない場合、結果は、Integer.toHexString(arg.hashCode()) の呼び出しで取得されます。
sS 一般 引数 argnull の場合、結果は null になります。argFormattable を実装する場合に、arg.formatTo が呼び出されます。そうでない場合、結果は arg.toString() の呼び出しで取得されます。
cC 文字 結果は Unicode 文字です。
'd' 整数 結果は、10 進整数として書式設定されます。
'o' 整数 結果は、8 進整数として書式設定されます。
'x''X' 整数 結果は、16 進整数として書式設定されます。
'e''E' 浮動小数点 結果は、浮動小数点表示形式の 10 進数として書式設定されます。
'f' 浮動小数点 結果は、10 進数として書式設定されます。
gG 浮動小数点 結果は、四捨五入処理後の精度および値に応じて浮動小数点表示形式または 10 進数書式を使用して書式設定されます。
aA 浮動小数点 結果は、有効数字および指数を持つ浮動小数点数として書式設定されます。
tT 日付/時刻 日付および時刻変換文字の接頭辞です。「日付/時刻変換」を参照してください。
'%' percent 結果は、リテラル「%」(\u0025) になります。
'n' 行区切り文字 結果は、プラットフォーム固有の行区切り文字です。

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

日付/時刻変換

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

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

'H' 24 時間制の時。必要に応じて 0 を先頭に追加し、2 桁で表現します (00 - 23)。
'I' 12 時間制の時。必要に応じて 0 を先頭に追加し、2 桁で表現します (00 -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 など)。
'Z' タイムゾーンの省略形を表す文字列。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 まで) のミリ秒。

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

'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)。

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

'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 は、指定された引数型でフラグがサポートされることを意味します。

フラグ 全般 文字 整数 浮動小数点 日付/時刻 説明
'-' 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'byteByteshortShortintIntegerlong、および Long に適用される場合

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

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

Width

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

Precision

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

'e''E'、および 'f' の浮動小数点の変換では、 precision は 10 進数の区切り文字の後の桁数になります。変換が 'g' または 'G' の場合は、四捨五入処理後の結果として得られる絶対値の合計桁数になります。'a' または 'A' の変換の場合は、precision は指定されません。

文字、整数、日付/時刻引数タイプ、およびパーセント、行区切り文字変換の場合、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 がそれぞれスローされます。

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

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

大文字 (BHSCXEGA、および T など) で表された変換は、それぞれの小文字を使用する変換と同じですが、変換の結果は一般的に使用されている Locale の規則に従って大文字に変換されます。結果は、次の String.toUpperCase() を呼び出した場合と同じになります。

out.toUpperCase() 

全般

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

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

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

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

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

引数 argnull の場合、結果は null になります。そうでない場合、結果は、Integer.toHexString(arg.hashCode()) の呼び出しで取得されます。

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

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

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

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

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

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

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

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

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

文字

この変換は、char および Character に適用できます。Character.isValidCodePoint(int)true を返すときは、byteByteshortShortint、および Integer の各型にも適用できます。false を返す場合は、IllegalFormatCodePointException がスローされます。
'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') フラグが指定された場合、ロケール固有のグループ区切り文字が挿入されます。文字列の整数部を最小有効桁から最大有効桁までスキャンし、ロケールのグループ化サイズで定義された間隔で区切り文字を挿入します。
  4. '0' フラグが指定された場合、文字列の長さが要求されたフィールド幅と等しくなるまで、ロケール固有のゼロ数字が記号の後ろ (記号が存在する場合)、最初のゼロ以外の数字の前に挿入されます。
  5. 値が負で、'(' フラグが指定されている場合、前に '(' ('\u0028') が、後ろに ')' ('\u0029') がそれぞれ付けられます。
  6. 値が負 (または浮動小数点の負のゼロ) で、'(' フラグが指定されていない場合、前に '-' ('\u002d') が付けられます。
  7. '+' フラグが指定され、かつ値が正またはゼロ (もしくは浮動小数点の正のゼロ) である場合、前に '+' ('\u002b') が付けられます。

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

Byte、Short、Integer、および Long

次の変換を byteByteshortShortintIntegerlong、および Long に適用できます。

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

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

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

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

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

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

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

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

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

x が負の場合、結果は、値に 2n を追加して生成された符号なしの値になります。 n は、必要に応じ、ByteShortInteger、または 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 に基づく)、および値が含まれます。

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

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

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

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

'  ' '\u0020' 出力で、負以外の値に余分な空白 ('\u0020') を 1 つ含める必要があります。

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

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

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

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

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

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

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

BigInteger

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

'd' '\u0054' 出力を 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

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

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

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

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

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

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

n を 10n <= m < 10n+1 などの一意の整数とし、a を 1 <= a < 10 となるような m と 10n の数学的に正確な商とします。 この場合、絶対値は、Long.toString(long, int) メソッドで生成されるように、a の整数部である 1 桁の 10 進数、小数点、a の小数部を表す 10 進数、指数記号 'e' ('\u0065')、指数の記号、n の 10 進整数表現がこの順に並んだ形で表現されます。

結果内の m または a の小数部の桁数は、precision と等しくなります。precision が指定されない場合の、デフォルト値は 6 です。precision が、Float.toString(float) または 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 進フォーマットを使用して書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。

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

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

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

結果内の m または a の小数部の桁数は、precision と等しくなります。precision が指定されない場合の、デフォルト値は 6 です。precision が、Float.toString(float) または 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 進文字列を付加したものです。
  • m がサブノーマル表現を保持する double 値の場合、有効数字は文字 '0x0.' に有効数字の残りの部分 (小数) の 16 進表現を付加したものになります。指数は 'p-1022' で表されます。サブノーマル有効数字内に、ゼロでない数字が 1 つ以上存在する必要があることに留意してください。

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

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

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

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

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

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

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

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

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

BigDecimal

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

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

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

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

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

n を 10n <= m < 10n+1 などの一意の整数とし、a を 1 <= a < 10 となるような m と 10n の数学的に正確な商とします。 この場合、絶対値は、Long.toString(long, int) メソッドで生成されるように、a の整数部である 1 桁の 10 進数、小数点、a の小数部を表す 10 進数、指数記号 'e' ('\u0065')、指数の記号、n の 10 進整数表現がこの順に並んだ形で表現されます。

結果内の m または a の小数部の桁数は、precision と等しくなります。precision が指定されない場合の、デフォルト値は 6 です。precision が、Float.toString(float) または Double.toString(double) によりそれぞれ返される文字列内の小数点以降の桁数よりも小さい場合、値は半切り上げアルゴリズムを使用して四捨五入されます。そうでない場合、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 が、Float.toString(float) または Double.toString(double) によりそれぞれ返される文字列内の小数点以降の桁数よりも小さい場合、値は半切り上げアルゴリズムを使用して四捨五入されます。そうでない場合、precision の値に達するように末尾にゼロを付加できます。値の正規表現では、BigDecimal.toString() を使用します。

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

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

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

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

日付/時刻

この変換は、longLongCalendar、および Date に適用できます。

't' '\u0074' 日付および時刻変換文字の接頭辞
'T' '\u0054' 't' の大文字のバリアント

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

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

'H' '\u0048' 24 時間制の時。必要に応じて 0 を先頭に追加し、2 桁で表現します (00 - 23)。00 は真夜中に対応します。
'I' '\u0049' 12 時間制の時。必要に応じて 0 を先頭に追加し、2 桁で表現します (00 -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 など)。
'Z' '\u005a' タイムゾーンの省略形を表す文字列。
'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 まで) のミリ秒。この値の精度は、背後のオペレーティングシステムまたはハードウェアの解像度により制限されます。

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

'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」は、月の最初の日を表します。

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

'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 より小さい場合、総文字数が width に等しくなるまで出力に空白 ('\u0020') がパディングされます。デフォルトでは、左側にパディングされます。'-' フラグが指定された場合、右側にパディングされます。width が指定されていない場合、最小値は存在しません。

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

パーセント

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

'%' 結果は、リテラル「%」(\u0025) になります。

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

一般変換用に定義された '-' フラグが適用されます。ほかのフラグが指定された場合、FormatFlagsConversionMismatchException がスローされます。

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

行区切り文字

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

'n' プラットフォーム固有の行区切り文字で、System.getProperty("line.separator") により返されます。

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

引数のインデックス

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

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 仮想マシン仕様で定義された Java 配列の最大サイズの制限を受けます。引数インデックスが利用可能な引数に対応していない場合、MissingFormatArgumentException がスローされます。

書式指示子以外にも引数が存在する場合、余分の引数は無視されます。

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

導入されたバージョン:
1.5

入れ子のクラスの概要
static class Formatter.BigDecimalLayoutForm
           
 
コンストラクタの概要
Formatter()
          新しいフォーマッタを構築します。
Formatter(Appendable a)
          指定された宛先を持つ新しいフォーマッタを構築します。
Formatter(Appendable a, Locale l)
          指定された宛先およびロケールを持つ新しいフォーマッタを構築します。
Formatter(File file)
          指定されたファイルを持つ新しいフォーマッタを構築します。
Formatter(File file, String csn)
          指定されたファイルおよび文字セットを持つ新しいフォーマッタを構築します。
Formatter(File file, String csn, Locale l)
          指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
Formatter(Locale l)
          指定されたロケールを持つ新しいフォーマッタを構築します。
Formatter(OutputStream os)
          指定された出力ストリームを持つ新しいフォーマッタを構築します。
Formatter(OutputStream os, String csn)
          指定された出力ストリームおよび文字セットを持つ新しいフォーマッタを構築します。
Formatter(OutputStream os, String csn, Locale l)
          指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
Formatter(PrintStream ps)
          指定された出力ストリームを持つ新しいフォーマッタを構築します。
Formatter(String fileName)
          指定されたファイル名を持つ新しいフォーマッタを構築します。
Formatter(String fileName, String csn)
          指定されたファイル名および文字セットを持つ新しいフォーマッタを構築します。
Formatter(String fileName, String csn, Locale l)
          指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。
 
メソッドの概要
 void close()
          このフォーマッタを閉じます。
 void flush()
          このフォーマッタをフラッシュします。
 Formatter format(Locale l, String format, Object... args)
          指定されたロケール、書式文字列、および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。
 Formatter format(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 - 書式付き出力の宛先。anull の場合、StringBuilder が作成される

Formatter

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

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

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

Formatter

public Formatter(Appendable a,
                 Locale l)
指定された宛先およびロケールを持つ新しいフォーマッタを構築します。

パラメータ:
a - 書式付き出力の宛先。anull の場合、StringBuilder が作成される
l - 書式設定時に適用する ロケールlnull の場合、ローカリゼーションは適用されない

Formatter

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

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

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

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

Formatter

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

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

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

Formatter

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

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

Formatter

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

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

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

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

Formatter

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

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

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

Formatter

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

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

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 - 書式設定時に適用するロケールlnull の場合、ローカリゼーションは適用されない
例外:
UnsupportedEncodingException - 指定された文字セットがサポートされていない場合
メソッドの詳細

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() の内容を返しますが、ストリームではデータが破棄されるためにそれができません。

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

flush

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

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

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

close

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

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

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

定義:
インタフェース Closeable 内の close

ioException

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

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

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

format

public Formatter format(String format,
                        Object... args)
指定された書式文字列および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。使用されるロケールは、このフォーマッタの構築時に定義されたロケールです。

パラメータ:
format - 「書式文字列の構文」で説明した書式文字列
args - 書式文字列内の書式指示子により参照される引数。書式指示子以外にも引数が存在する場合、余分の引数は無視される。引数の最大数は、Java 仮想マシン仕様で定義された Java 配列の最大サイズの制限を受ける
戻り値:
このフォーマッタ
例外:
IllegalFormatException - 書式文字列に不正な構文、指定された引数と互換性のない書式指示子、引数の指定が不十分な書式文字列、またはほかの不正な条件が含まれる場合。 可能性のある書式エラーすべての詳細は、formatter クラス仕様の「詳細」セクションを参照
FormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合

format

public Formatter format(Locale l,
                        String format,
                        Object... args)
指定されたロケール、書式文字列、および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。

パラメータ:
l - 書式設定時に適用するロケールlnull の場合、ローカリゼーションは適用されない。構築時に設定されたこのオブジェクトのロケールがこれによって変更されることはない
format - 「書式文字列の構文」で説明した書式文字列
args - 書式文字列内の書式指示子により参照される引数。書式指示子以外にも引数が存在する場合、余分の引数は無視される。引数の最大数は、Java 仮想マシン仕様で定義された Java 配列の最大サイズの制限を受ける
戻り値:
このフォーマッタ
例外:
IllegalFormatException - 書式文字列に不正な構文、指定された引数と互換性のない書式指示子、引数の指定が不十分な書式文字列、またはほかの不正な条件が含まれる場合。 可能性のある書式エラーすべての詳細は、formatter クラス仕様の「詳細」セクションを参照
FormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。