Java : Formatter (String Syntax) with Examples

Formatter (Java SE 22 & JDK 22) with Examples.
You will find code examples on most Formatter methods.

Summary

An interpreter for printf-style format strings. This class provides support for layout justification and alignment, common formats for numeric, string, and date/time data, and locale-specific output.

Class diagram

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
}

Constructors

Formatter ()

Constructs a new formatter.

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

Formatter (File file)

Constructs a new formatter with the specified 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)

Constructs a new formatter with the specified file and charset.

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)

Constructs a new formatter with the specified file, charset, and locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

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))); // Sunday

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

Formatter (File file, Charset charset, Locale l)

Constructs a new formatter with the specified file, charset, and locale.

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)

Constructs a new formatter with the specified output stream.

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)

Constructs a new formatter with the specified output stream and charset.

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)

Constructs a new formatter with the specified output stream, charset, and locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

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)); // Sunday
}
{
    final var os = new ByteArrayOutputStream();
    try (final var formatter = new Formatter(os, csn, Locale.JAPAN)) {
        formatter.format("%tA", DayOfWeek.SUNDAY);
    }
    System.out.println(os.toString(csn)); // 日曜日
}

Formatter (OutputStream os, Charset charset, Locale l)

Constructs a new formatter with the specified output stream, charset, and locale.

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)

Constructs a new formatter with the specified print stream.

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)

Constructs a new formatter with the specified destination.

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)

Constructs a new formatter with the specified destination and locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

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

Formatter (String fileName)

Constructs a new formatter with the specified file name.

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)

Constructs a new formatter with the specified file name and charset.

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)

Constructs a new formatter with the specified file name, charset, and locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

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))); // Sunday

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

Formatter (String fileName, Charset charset, Locale l)

Constructs a new formatter with the specified file name, charset, and locale.

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)

Constructs a new formatter with the specified locale.

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); // 日曜日
}

Methods

void close ()

Closes this formatter.

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

// An example without a try-with-resources statement.
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 ()

Flushes this formatter.

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)

Writes a formatted string to this object's destination using the specified format string and arguments.

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)

Writes a formatted string to this object's destination using the specified locale, format string, and arguments.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

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

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

IOException ioException ()

Returns the IOException last thrown by this formatter's Appendable.

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)) {

    // Intentionally closes the out object to make an error.
    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 ()

Returns the locale set by the construction of this formatter.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

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

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

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

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

Appendable out ()

Returns the destination for the output.

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 ()

Returns the result of invoking toString() on the destination for the output.

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
}

An exhaustive list of format strings

API Examples

Java : Formatter (String Syntax) with Examples

Summary

Constructors

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)

Methods

void close ()

void flush ()

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

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

IOException ioException ()

Locale locale ()

Appendable out ()

String toString ()

Related posts