java.util.Formatter
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public final class Formatter
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$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);
カレンダ オブジェクト 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 は、出力への挿入内容を示す文字です。
変換は、次のカテゴリに分けられます。
Character、byte、Byte、short、および Short に適用されます。Character.isValidCodePoint(int) が true を返す場合、この変換は、int および Integer 型にも適用されます。
Byte、short、Short、int、Integer、long、Long、および BigInteger などの Java 整数型に適用されます。
Float、double、Double、および BigDecimal などの Java 浮動小数点型に適用されます。
Long、Calendar、および Date など、日付または時刻のエンコーディングが可能な Java 型に適用されます。
次の表は、サポートする変換を要約したものです。大文字 (B、 H、 S、 C、 X、 E、 G、 A、および T など) で表された変換は、それぞれの小文字を使用する変換と同じですが、変換の結果は一般的に使用されている Locale の規則に従って大文字に変換されます。結果は、次の String.toUpperCase() を呼び出した場合と同じになります。
out.toUpperCase()
| 変換 | 引数のカテゴリ | 説明 |
|---|---|---|
| b、B | 一般 | 引数 arg が null の場合、結果は false になります。arg が boolean または Boolean の場合、結果は String.valueOf() により返される文字列になります。そうでない場合、結果は true になります。
|
| h、H | 一般 | 引数 arg が null の場合、結果は null になります。そうでない場合、結果は、Integer.toHexString(arg.hashCode()) の呼び出しで取得されます。 |
| s、S | 一般 | 引数 arg が null の場合、結果は null になります。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 | 浮動小数点 | 結果は、有効数字および指数を持つ浮動小数点数として書式設定されます。 |
| t、T | 日付/時刻 | 日付および時刻変換文字の接頭辞「日付/時刻変換」を参照してください。 |
| '%' | 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' | Minute within the hour formatted as two digits with a leading zero as necessary, i.e. 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' が byte、Byte、short、Short、int、Integer、long、および Long に適用される場合
5 'e'、'E'、'f'、'g'、および 'G' 変換のみ
変換として明示的に定義されていないフラグはすべて不正であり、将来の機能拡張に備えて予約されています。
width は、出力に書き込まれる最小文字数です。行区切り文字変換では、width は使用できません。width が指定された場合、エラーがスローされます。
一般の引数型では、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 がスローされます。
指定された例外はすべて、Formatter の format() メソッドのいずれか、および String.format や PrintStream.printf などの format 簡易メソッドのいずれかによりスローされます。
大文字 (B、 H、 S、 C、 X、 E、 G、 A、および T など) で表された変換は、それぞれの小文字を使用する変換と同じですが、変換の結果は一般的に使用されている Locale の規則に従って大文字に変換されます。結果は、次の String.toUpperCase() を呼び出した場合と同じになります。
out.toUpperCase()
次の一般変換を、任意の引数型に適用できます。
| 'b' | '\u0062' | Boolean.toString(boolean) により返される true または false を生成します。
|
| 'B' | '\u0042' | 'b' の大文字のバリアント |
| 'h' | '\u0068' | オブジェクトのハッシュコード値を表す文字列を生成します。 |
| 'H' | '\u0048' | 'h' の大文字のバリアント |
| 「s」 | '\u0073' | 文字列を生成します。 |
| 'S' | '\u0053' | 's' の大文字のバリアント |
次のフラグが一般変換に適用されます。
| '-' | '\u002d' | 左揃えで出力します。必要に応じ、変換された値の末尾に空白 ('\u0020') が追加されて、フィールドの最小幅が満たされます。width が指定されていない場合、MissingFormatWidthException がスローされます。このフラグが設定されていない場合、右揃えで出力されます。
|
| '#' | '\u0023' | 出力で代替フォームを使用する必要があります。フォームの定義は変換で指定されます。 |
width は、出力に書き込まれる最小文字数です。変換後の値の長さが width より小さい場合、総文字数が width に等しくなるまで出力に ' ' (\u0020') がパディングされます。デフォルトでは、左側にパディングされます。'-' フラグが指定された場合、右側にパディングされます。width が指定されていない場合、最小値は存在しません。
precision は、出力に書き込まれる最大文字数です。precision は width の前に適用されるため、width の値が precision より大きい場合でも、出力は precision で指定された文字数に切り詰められます。precision が指定されていない場合、文字数に明示的な制限は存在しません。
Character に適用できます。Character.isValidCodePoint(int) が true を返すときは、byte、Byte、short、Short、int、および Integer の各型にも適用できます。false を返す場合は、IllegalFormatCodePointException がスローされます。
| 「c」 | '\u0063' | 「Unicode 文字表現」の記述に従い、引数を Unicode 文字として書式設定します。引数が補助文字を表す場合、これを 1 つ以上の 16 ビット char にできます。 |
| 'C' | '\u0043' | 'c' の大文字のバリアント |
一般変換用に定義された '-' フラグが適用されます。'#' フラグが指定された場合、FormatFlagsConversionMismatchException がスローされます。
width は、一般変換用に定義されます。
precision は適用できません。precision が指定された場合、IllegalFormatPrecisionException がスローされます。
数値変換は、次のカテゴリに分けられます。
数値型は、次のアルゴリズムに従って書式設定されます。
整数部、小数部、および指数 (データ型で必要な場合) の数字の取得後に、次の変換が適用されます。
値が NaN または正の無限大の場合、リテラル文字列「NaN」または「Infinity」がそれぞれ出力されます。値が負の無限大の場合、'(' フラグが指定されていると出力は「(Infinity)」になり、そうでない場合は「-Infinity」になります。これらの値のローカライズは行われません。
次の変換を byte、Byte、short、Short、int、Integer、long、および Long に適用できます。
| 'd' | '\u0054' | 引数を 10 進整数として書式設定します。ローカリゼーションアルゴリズムが適用されます。 |
| 'o' | '\u006f' | 引数を、基数 8 の整数として書式設定します。ローカリゼーションは適用されません。 |
| 'x' | '\u0078' | 引数を、基数 16 の整数として書式設定します。ローカリゼーションは適用されません。 |
| 'X' | '\u0058' | 'x' の大文字のバリアント。'x' (存在する場合) およびすべての 16 進数 'a' - 'f' ('\u0061' - '\u0066') を含む、数値を表す文字列全体が大文字に変換されます。 |
変換が 'o'、'x'、または 'X' で、フラグ '#' と '0' の両方のフラグが指定されている場合、結果には基数指示子 (8 進の場合は '0'、16 進の場合は "0x" または "0X")、いくつかのゼロ (width に基づく)、および値が含まれます。
'-' フラグが指定されていない場合、符号の前に空白がパディングされます。
次のフラグが、数値整数変換に適用されます。
| '+' | '\u002b' | 出力で、正の数すべてに正の符号を含める必要があります。このフラグが指定されていない場合、負の値にのみ符号が含められます。 |
| ' ' | '\u0020' | 出力で、負以外の値に余分な空白 ('\u0020') を 1 つ含める必要があります。 |
| '0' | '\u0030' | 出力で、次の符号または基数指示子に続く最小フィールド幅の先頭にゼロをパディングする必要があります (NaN または無限の変換時を除く)。width が指定されていない場合、MissingFormatWidthException がスローされます。
|
| ',' | '\u002c' | 出力にロケール固有のグループ区切り文字を含める必要があります。詳細は、ローカリゼーションアルゴリズムのグループセクションを参照してください。 |
| '(' | '\u0028' | 出力で、負の値の先頭に '(' ('\u0028') を、末尾に ')' ('\u0029') を付加する必要があります。 |
フラグが指定されない場合の、デフォルト書式設定は次のとおりです。
width は、出力に書き込まれる最小文字数です。これには、符号、数字、グループ化区切り文字、基数指示子、および括弧が含まれます。変換後の値の長さが width より小さい場合、総文字数が width に等しくなるまで出力に空白 ('\u0020') がパディングされます。デフォルトでは、左側にパディングされます。'-' フラグが指定された場合、右側にパディングされます。width が指定されていない場合、最小値は存在しません。
precision は適用できません。precision が指定された場合、IllegalFormatPrecisionException がスローされます。
次の変換を BigInteger に適用できます。
| 'd' | '\u0054' | 出力を 10 進整数として書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
| 'o' | '\u006f' | 出力を、基数 8 の整数として書式設定する必要があります。ローカリゼーションは適用されません。 |
| 'x' | '\u0078' | 出力を、基数 16 の整数として書式設定する必要があります。ローカリゼーションは適用されません。 |
| '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、Float、double、および Double に適用できます。
| 「e」 | '\u0065' | 出力を浮動小数点表示形式を使用して書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
| 'E' | '\u0045' | 'e' の大文字のバリアントです。指数は 'E' ('\u0045') になります。 |
| 'g' | '\u0067' | 一般の科学表記法を使用して出力を書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
| 'G' | '\u0047' | 'g' の大文字のバリアント |
| 'f' | '\u0066' | 出力を 10 進フォーマットを使用して書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
| 'a' | '\u0061' | 出力の書式を 16 進の指数で設定する必要があります。ローカリゼーションは適用されません。
|
| '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 に適用できます。
| 「e」 | '\u0065' | 出力を浮動小数点表示形式を使用して書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
| 'E' | '\u0045' | 'e' の大文字のバリアントです。指数は 'E' ('\u0045') になります。 |
| 'g' | '\u0067' | 一般の科学表記法を使用して出力を書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
| 'G' | '\u0047' | 'g' の大文字のバリアント |
| 'f' | '\u0066' | 出力を 10 進フォーマットを使用して書式設定する必要があります。ローカリゼーションアルゴリズムが適用されます。 |
Byte、Short、Integer、および Long 用に定義されたすべてのフラグが適用されます。
'#' フラグが指定されている場合、小数点が常に存在します。
フラグが指定されない場合のデフォルト動作は、Float および Double と同じです。
width および precision の仕様は、Float および Double で定義された仕様と同じです。
この変換は、long、Long、Calendar、および 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 が指定されていない場合、'%' だけが出力されます。 一般変換用に定義された '-' フラグが適用されます。ほかのフラグが指定された場合、 precision は適用できません。precision が指定された場合、 |
この変換に対応する引数はありません。
| 'n' | プラットフォーム固有の行区切り文字で、System.getProperty("line.separator") により返されます。
|
flags、width、および precision は適用できません。これらが指定された場合、IllegalFormatFlagsException、IllegalFormatWidthException、および IllegalFormatPrecisionException がそれぞれスローされます。
書式指示子は、次の 3 つの方法で引数を参照できます。
例を示します。
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"
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 仮想マシン仕様で定義されている Java 配列の最大次元により制限される。引数インデックスが利用可能な引数に対応していない場合、MissingFormatArgumentException がスローされます。
書式指示子よりも引数が多い場合、余分な引数は無視される。
特に指定されていないかぎり、null 引数をこのクラスのメソッドまたはコンストラクタに渡すと、NullPointerException がスローされます。
| 入れ子のクラスの概要 | |
|---|---|
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 |
| コンストラクタの詳細 |
|---|
public Formatter()
書式付き出力の宛先は、StringBuilder です。これは、out() を呼び出すことで取得できます。また、toString() を呼び出すことで、現在の内容を文字列に変換できます。使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
public Formatter(Appendable a)
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
a - 書式付き出力の宛先。a が null の場合、StringBuilder が作成されるpublic Formatter(Locale l)
書式付き出力の宛先は、StringBuilder です。これは、out() を呼び出すことで取得できます。また、toString() を呼び出すことで、現在の内容を文字列に変換できます。
l - 書式設定時に適用する locale。l が null の場合、ローカリゼーションは適用されない。
public Formatter(Appendable a,
Locale l)
a - 書式付き出力の宛先。a が null の場合、StringBuilder が作成されるl - 書式設定時に適用する locale。l が null の場合、ローカリゼーションは適用されない。
public Formatter(String fileName)
throws FileNotFoundException
使用される文字セットは、この Java 仮想マシンインスタンスの デフォルト文字セット です。
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
fileName - このフォーマッタの宛先として使用されるファイルの名前。ファイルが存在する場合は、サイズ 0 に切り詰められる。そうでない場合は、新規ファイルが作成される。出力はファイルに書き込まれ、バッファーに格納される
SecurityException - セキュリティーマネージャーが存在し、checkWrite(fileName) がファイルへの書き込みアクセスを拒否した場合
FileNotFoundException - 指定されたファイル名が既存の書き込み可能な通常のファイルを示さず、新規の通常ファイルがその名前で作成できない場合、または、ファイルのオープンまたは作成中にほかのエラーが発生した場合
public Formatter(String fileName,
String csn)
throws FileNotFoundException,
UnsupportedEncodingException
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
fileName - このフォーマッタの宛先として使用されるファイルの名前。ファイルが存在する場合は、サイズ 0 に切り詰められる。そうでない場合は、新規ファイルが作成される。出力はファイルに書き込まれ、バッファーに格納されるcsn - サポートする charset の名前
FileNotFoundException - 指定されたファイル名が既存の書き込み可能な通常のファイルを示さず、新規の通常ファイルがその名前で作成できない場合、または、ファイルのオープンまたは作成中にほかのエラーが発生した場合
SecurityException - セキュリティーマネージャーが存在し、checkWrite(fileName) がファイルへの書き込みアクセスを拒否した場合
UnsupportedEncodingException - 指定された文字セットがサポートされていない場合
public Formatter(String fileName,
String csn,
Locale l)
throws FileNotFoundException,
UnsupportedEncodingException
fileName - このフォーマッタの宛先として使用されるファイルの名前。ファイルが存在する場合は、サイズ 0 に切り詰められる。そうでない場合は、新規ファイルが作成される。出力はファイルに書き込まれ、バッファーに格納されるcsn - サポートする charset の名前l - 書式設定時に適用する locale。l が null の場合、ローカリゼーションは適用されない。
FileNotFoundException - 指定されたファイル名が既存の書き込み可能な通常のファイルを示さず、新規の通常ファイルがその名前で作成できない場合、または、ファイルのオープンまたは作成中にほかのエラーが発生した場合
SecurityException - セキュリティーマネージャーが存在し、checkWrite(fileName) がファイルへの書き込みアクセスを拒否した場合
UnsupportedEncodingException - 指定された文字セットがサポートされていない場合
public Formatter(File file)
throws FileNotFoundException
使用される文字セットは、この Java 仮想マシンインスタンスの デフォルト文字セット です。
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
file - このフォーマッタの宛先として使用されるファイル。ファイルが存在する場合は、サイズ 0 に切り詰められる。そうでない場合は、新規ファイルが作成される。出力はファイルに書き込まれ、バッファーに格納される
SecurityException - セキュリティーマネージャーが存在し、セキュリティーマネージャーの checkWrite(file.getPath()) メソッドがファイルへの書き込みアクセスを許可しない場合
FileNotFoundException - 指定されたファイルオブジェクトが既存のファイルを示さない場合、書き込み可能な通常のファイルおよび新規の通常ファイルがその名前で作成できない場合、またはファイルのオープンまたは作成中にその他のエラーが発生した場合
public Formatter(File file,
String csn)
throws FileNotFoundException,
UnsupportedEncodingException
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
file - このフォーマッタの宛先として使用されるファイル。ファイルが存在する場合は、サイズ 0 に切り詰められる。そうでない場合は、新規ファイルが作成される。出力はファイルに書き込まれ、バッファーに格納されるcsn - サポートする charset の名前
FileNotFoundException - 指定されたファイルオブジェクトが既存のファイルを示さない場合、書き込み可能な通常のファイルおよび新規の通常ファイルがその名前で作成できない場合、またはファイルのオープンまたは作成中にその他のエラーが発生した場合
SecurityException - セキュリティーマネージャーが存在し、セキュリティーマネージャーの checkWrite(file.getPath()) メソッドがファイルへの書き込みアクセスを許可しない場合
UnsupportedEncodingException - 指定された文字セットがサポートされていない場合
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 - 指定された文字セットがサポートされていない場合public Formatter(PrintStream ps)
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
文字は指定された PrintStream オブジェクトに書き込まれるため、このオブジェクトの文字セットを使用してエンコードされます。
ps - このフォーマッタの宛先として使用されるストリームpublic Formatter(OutputStream os)
使用される文字セットは、この Java 仮想マシンインスタンスの デフォルト文字セット です。
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
os - このフォーマッタの宛先として使用される出力ストリーム。出力はバッファーに入れられる
public Formatter(OutputStream os,
String csn)
throws UnsupportedEncodingException
使用されるロケールは、この Java 仮想マシンインスタンスのデフォルトロケールです。
os - このフォーマッタの宛先として使用される出力ストリーム。出力はバッファーに入れられるcsn - サポートする charset の名前
UnsupportedEncodingException - 指定された文字セットがサポートされていない場合
public Formatter(OutputStream os,
String csn,
Locale l)
throws UnsupportedEncodingException
os - このフォーマッタの宛先として使用される出力ストリーム。出力はバッファーに入れられるcsn - サポートする charset の名前l - 書式設定時に適用する locale。l が null の場合、ローカリゼーションは適用されない。
UnsupportedEncodingException - 指定された文字セットがサポートされていない場合| メソッドの詳細 |
|---|
public Locale locale()
ロケール引数を持つこのオブジェクトの format メソッドはこの値を返しません。
FormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合public Appendable out()
FormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合public String 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 内の toStringFormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合public void flush()
Flushable インタフェースを実装する場合、flush メソッドが呼び出されます。
フォーマッタのフラッシュにより、宛先でバッファーに入れられた任意の出力が基になるストリームに書き込まれます。
Flushable 内の flushFormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合public void close()
Closeable インタフェースを実装する場合、close メソッドが呼び出されます。
フォーマッタを閉じると、それが保持していたリソース (開いていたファイルなど) を解放できます。フォーマッタがすでに閉じられている場合、このメソッドを呼び出しても何の効果もありません。
このフォーマッタを閉じたあとで、このフォーマッタ内の ioException() 以外のメソッドを呼び出そうとすると、FormatterClosedException がスローされます。
Closeable 内の closepublic IOException ioException()
Appendable により最後にスローされた IOException を返します。
宛先の append() メソッドがまったく IOException をスローしない場合、このメソッドは常に null を返します。
public Formatter format(String format,
Object... args)
format - 「書式文字列の構文」で説明した書式文字列args - 書式文字列の書式指示子により参照される引数。書式指示子よりも引数が多い場合、余分な引数は無視される。引数の最大数は、Java 仮想マシン仕様で定義されている Java 配列の最大次元により制限される。
IllegalFormatException - 書式文字列が、不正な構文、所定の引数と互換性がない書式指示子、書式文字列に与えられた不適切な引数、あるいはほかの不正な条件を含む場合。考えられるすべての書式エラーの仕様については、フォーマッタクラス仕様の「詳細」セクションを参照
FormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合
public Formatter format(Locale l,
String format,
Object... args)
l - 書式設定時に適用する locale。l が null の場合、ローカリゼーションは適用されない。構築時に設定されたこのオブジェクトのロケールがこれによって変更されることはないformat - 「書式文字列の構文」で説明した書式文字列args - 書式文字列の書式指示子により参照される引数。書式指示子よりも引数が多い場合、余分な引数は無視される。引数の最大数は、Java 仮想マシン仕様で定義された Java 配列の最大サイズの制限を受ける
IllegalFormatException - 書式文字列が、不正な構文、所定の引数と互換性がない書式指示子、書式文字列に与えられた不適切な引数、あるいはほかの不正な条件を含む場合。考えられるすべての書式エラーの仕様については、フォーマッタクラス仕様の「詳細」セクションを参照
FormatterClosedException - close() メソッドを呼び出すことで、このフォーマッタが閉じられた場合
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。