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.
StringBuilder out = new StringBuilder(); try (Formatter f = new Formatter(out, Locale.US)) { f.format("%-6s%6.2f%n", "pi", Math.PI); }
Try it
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.
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
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
AppendablethrowsIOException, theFormatterremembers it and you read it withioException(). This is whyformat()declares no checked exceptions. - Closing closes the target.
new Formatter(System.out).close()closesSystem.out. Useflush()instead for streams you do not own. Formatter()with the defaultStringBuilderis mainly a convenience; for a one-off string,String.format()is shorter.Formattablelets your class control%s:formatTo()receives the flags (LEFT_JUSTIFY,UPPERCASE,ALTERNATEfromFormattableFlags), the width and the precision (-1when absent). It is rarely needed; most code just overridestoString().- Not thread-safe. Do not share a
Formatterbetween threads without external locking. - Locale vs. default.
new Formatter()capturesLocale.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 inString.format, and they are relative to eachformat()call, not to the whole formatter.