Java : Formatter (書式文字列) - API使用例

Formatter (Java SE 22 & JDK 22) の使い方まとめです。
ほとんどのメソッドにサンプルコードがあります。
API仕様書のおともにどうぞ。

概要

printf形式の文字列用のインタプリタ。このクラスは、行揃えおよび水平配置レイアウト、数値、文字列、および日付/時刻データ用の共通書式、ロケール固有の出力をサポートします。 byte、BigDecimal、およびCalendarなどの一般的なJavaの型をサポートします。

クラス構成

Formatter クラスは、書式付きの文字列を出力します。
書式とは、例えば %s は文字列、%d は数値に対応しています。

書式文字列の構文の詳細は、上記の引用先にある Formatterクラスの API仕様をご確認ください。

Formatter クラスの他には、

System.out.printf
String.format
String.formatted

などのメソッドでも書式文字列が使えます。

try (final var formatter = new Formatter()) {
    formatter.format("str = %s : num = %d", "abc", 1234);

    final var str = formatter.toString();
    System.out.println(str); // str = abc : num = 1234
}

try (final var formatter = new Formatter()) {
    final var value = "abc";
    formatter.format("%s : %S", value, value);

    final var str = formatter.toString();
    System.out.println(str); // abc : ABC
}

try (final var formatter = new Formatter()) {
    final var value = 'x';
    formatter.format("%c : %C", value, value);

    final var str = formatter.toString();
    System.out.println(str); // x : X
}

try (final var formatter = new Formatter()) {
    final var value = 255;
    formatter.format("%d : %x : %X", value, value, value);

    final var str = formatter.toString();
    System.out.println(str); // 255 : ff : FF
}

try (final var formatter = new Formatter()) {
    final var value = 0.12345;
    formatter.format("%e : %f", value, value);

    final var str = formatter.toString();
    System.out.println(str); // 1.234500e-01 : 0.123450
}

try (final var formatter = new Formatter()) {
    formatter.format("%1$d : %2$d : %3$d", 111, 222, 333);
    System.out.println(formatter); // 111 : 222 : 333
}

try (final var formatter = new Formatter()) {
    formatter.format("%3$d : %2$d : %1$d", 111, 222, 333);
    System.out.println(formatter); // 333 : 222 : 111
}

コンストラクタ

Formatter ()

新しいフォーマッタを構築します。

try (final var formatter = new Formatter()) {
    formatter.format("%s : %d", "abc", 1234);
    System.out.println(formatter); // abc : 1234
}

Formatter (File file)

指定されたファイルを持つ新しいフォーマッタを構築します。

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

try (final var formatter = new Formatter(file.toFile())) {
    formatter.format("%s : %d", "abc", 1234);
}

System.out.println(Files.readString(file)); // abc : 1234

Formatter (File file, String csn)

指定されたファイルおよび文字セットを持つ新しいフォーマッタを構築します。

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

final var csn = "Shift_JIS";

try (final var formatter = new Formatter(file.toFile(), csn)) {
    formatter.format("%s : %d", "○△×", 1234);
}

System.out.println(Files.readString(file, Charset.forName(csn))); // ○△× : 1234

Formatter (File file, String csn, Locale l)

指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

final var csn = StandardCharsets.UTF_8.name();
System.out.println(csn); // UTF-8

try (final var formatter = new Formatter(file.toFile(), csn)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, Charset.forName(csn))); // 日曜日

try (final var formatter = new Formatter(file.toFile(), csn, Locale.US)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, Charset.forName(csn))); // Sunday

Formatter (File file, Charset charset, Locale l)

指定されたファイル、文字セット、およびロケールを持つ新しいフォーマッタを構築します。

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

final var charset = StandardCharsets.UTF_8;

try (final var formatter = new Formatter(file.toFile(), charset, Locale.US)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, charset)); // Sunday

try (final var formatter = new Formatter(file.toFile(), charset, Locale.JAPAN)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, charset)); // 日曜日

Formatter (OutputStream os)

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

final var os = new ByteArrayOutputStream();
try (final var formatter = new Formatter(os)) {
    formatter.format("%s : %d", "abc", 1234);
}

System.out.println(os); // abc : 1234

Formatter (OutputStream os, String csn)

指定された出力ストリームおよび文字セットを持つ新しいフォーマッタを構築します。

final var csn = "Shift_JIS";

final var os = new ByteArrayOutputStream();
try (final var formatter = new Formatter(os, csn)) {
    formatter.format("%s : %d", "○△×", 1234);
}

System.out.println(os.toString(csn)); // ○△× : 1234

Formatter (OutputStream os, String csn, Locale l)

指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

final var csn = StandardCharsets.UTF_8.name();
System.out.println(csn); // UTF-8

{
    final var os = new ByteArrayOutputStream();
    try (final var formatter = new Formatter(os, csn)) {
        formatter.format("%tA", DayOfWeek.SUNDAY);
    }
    System.out.println(os.toString(csn)); // 日曜日
}
{
    final var os = new ByteArrayOutputStream();
    try (final var formatter = new Formatter(os, csn, Locale.US)) {
        formatter.format("%tA", DayOfWeek.SUNDAY);
    }
    System.out.println(os.toString(csn)); // Sunday
}

Formatter (OutputStream os, Charset charset, Locale l)

指定された出力ストリーム、文字セット、およびロケールを持つ新しいフォーマッタを構築します。

final var charset = StandardCharsets.UTF_8;

final var os = new ByteArrayOutputStream();
try (final var formatter = new Formatter(os, charset, Locale.US)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(os.toString(charset)); // Sunday

final var charset = StandardCharsets.UTF_8;

final var os = new ByteArrayOutputStream();
try (final var formatter = new Formatter(os, charset, Locale.JAPAN)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(os.toString(charset)); // 日曜日

Formatter (PrintStream ps)

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

final var out = new ByteArrayOutputStream();
try (final var ps = new PrintStream(out)) {

    try (final var formatter = new Formatter(ps)) {
        formatter.format("%s : %d", "abc", 1234);
    }
}

System.out.println(out); // abc : 1234

Formatter (Appendable a)

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

final var a = new StringBuilder();
try (final var formatter = new Formatter(a)) {
    formatter.format("%s : %d", "abc", 1234);
}

System.out.println(a); // abc : 1234

Formatter (Appendable a, Locale l)

指定された宛先およびロケールを持つ新しいフォーマッタを構築します。

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

{
    final var a = new StringBuilder();
    try (final var formatter = new Formatter(a)) {
        formatter.format("%tA", DayOfWeek.SUNDAY);
    }
    System.out.println(a); // 日曜日
}
{
    final var a = new StringBuilder();
    try (final var formatter = new Formatter(a, Locale.US)) {
        formatter.format("%tA", DayOfWeek.SUNDAY);
    }
    System.out.println(a); // Sunday
}

Formatter (String fileName)

指定されたファイル名を持つ新しいフォーマッタを構築します。

final var file = Path.of("R:", "java-work", "aaa.txt");
final var fileName = file.toString();
System.out.println(fileName); // R:\java-work\aaa.txt

try (final var formatter = new Formatter(fileName)) {
    formatter.format("%s : %d", "abc", 1234);
}

System.out.println(Files.readString(file)); // abc : 1234

Formatter (String fileName, String csn)

指定されたファイル名および文字セットを持つ新しいフォーマッタを構築します。

final var file = Path.of("R:", "java-work", "aaa.txt");
final var fileName = file.toString();
System.out.println(fileName); // R:\java-work\aaa.txt

final var csn = "Shift_JIS";

try (final var formatter = new Formatter(fileName, csn)) {
    formatter.format("%s : %d", "○△×", 1234);
}

System.out.println(Files.readString(file, Charset.forName(csn))); // ○△× : 1234

Formatter (String fileName, String csn, Locale l)

指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

final var file = Path.of("R:", "java-work", "aaa.txt");
final var fileName = file.toString();
System.out.println(fileName); // R:\java-work\aaa.txt

final var csn = StandardCharsets.UTF_8.name();
System.out.println(csn); // UTF-8

try (final var formatter = new Formatter(fileName, csn)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, Charset.forName(csn))); // 日曜日

try (final var formatter = new Formatter(fileName, csn, Locale.US)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, Charset.forName(csn))); // Sunday

Formatter (String fileName, Charset charset, Locale l)

指定されたファイル名、文字セット、およびロケールを持つ新しいフォーマッタを構築します。

final var file = Path.of("R:", "java-work", "aaa.txt");
final var fileName = file.toString();
System.out.println(fileName); // R:\java-work\aaa.txt

final var charset = StandardCharsets.UTF_8;

try (final var formatter = new Formatter(fileName, charset, Locale.US)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, charset)); // Sunday

try (final var formatter = new Formatter(fileName, charset, Locale.JAPAN)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
}
System.out.println(Files.readString(file, charset)); // 日曜日

Formatter (Locale l)

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

try (final var formatter = new Formatter(Locale.US)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
    System.out.println(formatter); // Sunday
}

try (final var formatter = new Formatter(Locale.JAPAN)) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
    System.out.println(formatter); // 日曜日
}

メソッド

void close ()

このフォーマッタを閉じます。

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

try (final var formatter = new Formatter(file.toFile())) {
    formatter.format("%s : %d", "abc", 1234);
}

System.out.println(Files.readString(file)); // abc : 1234

// try-with-resources文を使わない例です。
final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

final var formatter = new Formatter(file.toFile());
try {
    formatter.format("%s : %d", "abc", 1234);
} finally {
    formatter.close();
}

System.out.println(Files.readString(file)); // abc : 1234

void flush ()

このフォーマッタをフラッシュします。

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

try (final var formatter = new Formatter(file.toFile())) {

    formatter.format("abc");
    System.out.println(Files.readString(file).isEmpty()); // true

    formatter.flush();
    System.out.println(Files.readString(file)); // abc

    formatter.format("XYZ");
    System.out.println(Files.readString(file)); // abc
}

System.out.println(Files.readString(file)); // abcXYZ

Formatter format (String format, Object... args)

指定された書式文字列および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。

try (final var formatter = new Formatter()) {
    final var value = "abc";
    formatter.format("%s : %S", value, value);

    final var str = formatter.toString();
    System.out.println(str); // abc : ABC
}

try (final var formatter = new Formatter()) {
    final var value = 'x';
    formatter.format("%c : %C", value, value);

    final var str = formatter.toString();
    System.out.println(str); // x : X
}

try (final var formatter = new Formatter()) {
    final var value = 255;
    formatter.format("%d : %x : %X", value, value, value);

    final var str = formatter.toString();
    System.out.println(str); // 255 : ff : FF
}

try (final var formatter = new Formatter()) {
    final var value = 0.12345;
    formatter.format("%e : %f", value, value);

    final var str = formatter.toString();
    System.out.println(str); // 1.234500e-01 : 0.123450
}

Formatter format (Locale l, String format, Object... args)

指定されたロケール、書式文字列、および引数を使用して、書式付き文字列をこのオブジェクトの宛先に書き込みます。

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

try (final var formatter = new Formatter()) {
    formatter.format("%tA", DayOfWeek.SUNDAY);
    System.out.println(formatter); // 日曜日
}

try (final var formatter = new Formatter()) {
    formatter.format(Locale.US, "%tA", DayOfWeek.SUNDAY);
    System.out.println(formatter); // Sunday
}

IOException ioException ()

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

try (final var formatter = new Formatter()) {

    formatter.format("%s : %d", "abc", 1234);
    System.out.println(formatter); // abc : 1234

    final var ret = formatter.ioException();
    System.out.println(ret); // null
}

final var file = Path.of("R:", "java-work", "aaa.txt");
System.out.println(file); // R:\java-work\aaa.txt

try (final var out = Files.newOutputStream(file);
     final var formatter = new Formatter(out)) {

    // エラーを起こすために、意図的にcloseします。
    out.close();

    formatter.format("%s : %d", "abc", 1234);
    formatter.flush();

    final var ret = formatter.ioException();
    System.out.println(ret); // java.nio.channels.ClosedChannelException
}

Locale locale ()

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

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

try (final var formatter = new Formatter()) {
    System.out.println(formatter.locale().toLanguageTag()); // ja-JP

    formatter.format("%tA", DayOfWeek.SUNDAY);
    System.out.println(formatter); // 日曜日
}

try (final var formatter = new Formatter(Locale.US)) {
    System.out.println(formatter.locale().toLanguageTag()); // en-US

    formatter.format("%tA", DayOfWeek.SUNDAY);
    System.out.println(formatter); // Sunday
}

Appendable out ()

出力先を返します。

try (final var formatter = new Formatter()) {
    final var out = formatter.out();
    System.out.println(out.getClass().getSimpleName()); // StringBuilder
}

try (final var formatter = new Formatter(new ByteArrayOutputStream())) {
    final var out = formatter.out();
    System.out.println(out.getClass().getSimpleName()); // BufferedWriter
}

String toString ()

出力先に対してtoString()を呼び出した結果を返します。

try (final var formatter = new Formatter()) {
    final var value = "abc";
    formatter.format("%s : %S", value, value);

    final var str = formatter.toString();
    System.out.println(str); // abc : ABC
}

try (final var formatter = new Formatter()) {
    final var value = 'x';
    formatter.format("%c : %C", value, value);

    final var str = formatter.toString();
    System.out.println(str); // x : X
}

try (final var formatter = new Formatter()) {
    final var value = 255;
    formatter.format("%d : %x : %X", value, value, value);

    final var str = formatter.toString();
    System.out.println(str); // 255 : ff : FF
}

try (final var formatter = new Formatter()) {
    final var value = 0.12345;
    formatter.format("%e : %f", value, value);

    final var str = formatter.toString();
    System.out.println(str); // 1.234500e-01 : 0.123450
}

API 使用例