Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The Formatter class

Reference for java.util.Formatter: write formatted text to a StringBuilder, stream or file, set the locale, implement Formattable and handle closing.

java.util.Formatter is the class that does the work behind String.format(), printf() and PrintStream.format(). You can use it directly when you want to send many formatted pieces to one destination: a StringBuilder, a PrintStream, a Writer, or a file. It keeps its own locale, so every format() call uses the same one.

Create a Formatter for an Appendable target, call format(pattern, args...) as often as you like, and close it. The pattern syntax is the one described in printf and format specifiers.

Java
StringBuilder out = new StringBuilder();
try (Formatter f = new Formatter(out, Locale.US)) {
    f.format("%-6s%6.2f%n", "pi", Math.PI);
}

Try it

Java Building a report with one Formatter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java A Formattable class and System.out

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public class Formatter implements Closeable, Flushable
Constructor Writes to
Formatter() an internal StringBuilder, default locale
Formatter(Locale l) an internal StringBuilder with that locale
Formatter(Appendable a) the appendable (StringBuilder, Writer, PrintStream ...)
Formatter(Appendable a, Locale l) the appendable, fixed locale
Formatter(PrintStream ps) the stream
Formatter(OutputStream os) the stream, using the default charset
Formatter(String fileName), Formatter(File file) a file (checked FileNotFoundException)
Method Description
format(String format, Object... args) formats with the formatter's locale; returns this
format(Locale l, String format, Object... args) formats with another locale for this call only
toString() out().toString(); useful for the default StringBuilder target
out() the destination Appendable
locale() the locale the formatter was created with
flush(), close() flush or close; closing also closes the target if it is Closeable
ioException() the last IOException thrown by the target, or null

Throws: FormatterClosedException when used after close(); the same IllegalFormatException subclasses as printf for bad patterns.

Usage notes

  • IO errors are not thrown. If the target Appendable throws IOException, the Formatter remembers it and you read it with ioException(). This is why format() declares no checked exceptions.
  • Closing closes the target. new Formatter(System.out).close() closes System.out. Use flush() instead for streams you do not own.
  • Formatter() with the default StringBuilder is mainly a convenience; for a one-off string, String.format() is shorter.
  • Formattable lets your class control %s: formatTo() receives the flags (LEFT_JUSTIFY, UPPERCASE, ALTERNATE from FormattableFlags), the width and the precision (-1 when absent). It is rarely needed; most code just overrides toString().
  • Not thread-safe. Do not share a Formatter between threads without external locking.
  • Locale vs. default. new Formatter() captures Locale.getDefault(Locale.Category.FORMAT) once at creation; later changes to the default do not affect it.
  • Argument indexes (%1$s, %<s) work the same as in String.format, and they are relative to each format() call, not to the whole formatter.