public final class

Formatter

extends Object
implements Closeable Flushable
java.lang.Object
   ↳ java.util.Formatter

Class Overview

The Formatter class is a String-formatting utility that is designed to work like the printf function of the C programming language. Its key methods are the format methods which create a formatted String by replacing a set of placeholders (format tokens) with formatted values. The style used to format each value is determined by the format token used. For example, the call
format("My decimal value is %d and my String is %s.", 3, "Hello");
returns the String
My decimal value is 3 and my String is Hello.

The format token consists of a percent sign, optionally followed by flags and precision arguments, and then a single character that indicates the type of value being formatted. If the type is a time/date, then the type character t is followed by an additional character that indicates how the date is to be formatted. The two characters <$ immediately following the % sign indicate that the previous value should be used again instead of moving on to the next value argument. A number n and a dollar sign immediately following the % sign make n the next argument to be used.

The available choices are the following:

Text value types
s String format("%s, %s", "hello", "Hello"); hello, Hello
S, s String to capitals format("%S, %S", "hello", "Hello"); HELLO, HELLO
c Character format("%c, %c", 'd', 0x65); d, e
C Character to capitals format("%C, %C", 'd', 0x65); D, E
Text option flags
The value between the option and the type character indicates the minimum width in characters of the formatted value
- Left justify (width value is required) format("%-3C, %3C", 'd', 0x65); D , E
Integer types
d int, formatted as decimal format("%d, %d"1$, 35, 0x10); 35, 16
o int, formatted as octal format("%o, %o", 8, 010); 10, 10
X, x int, formatted as hexidecimal format("%x, %X", 10, 10); a, A
Integer option flags
The value between the option and the type character indicates the minimum width in characters of the formatted value
+ lead with the number's sign format("%+d, %+4d", 5, 5); +5, +5
- Left justify (width value is required) format("%-6dx", 5); 5 x
# Print the leading characters that indicate hexidecimal or octal (for use only with hex and octal types) format("%#o", 010); 010
A space indicates that non-negative numbers should have a leading space. format("x% d% 5d", 4, 4); x 4 4
0 Pad the number with leading zeros (width value is required) format("%07d, %03d", 4, 5555); 0000004, 5555
( Put parentheses around negative numbers (decimal only) format("%(d, %(d, %(6d", 12, -12, -12); 12, (12), (12)
Float types
A value immediately following the % symbol gives the minimum width in characters of the formatted value; if it is followed by a period and another integer, then the second value gives the precision (6 by default).
f float (or double) formatted as a decimal, where the precision indicates the number of digits after the decimal. format("%f %<.1f %<1.5f %<10f %<6.0f", 123.456f); 123.456001 123.5 123.45600 123.456001 123
E, e float (or double) formatted in decimal exponential notation, where the precision indicates the number of significant digits. format("%E %<.1e %<1.5E %<10E %<6.0E", 123.456f); 1.234560E+02 1.2e+02 1.23456E+02 1.234560E+02 1E+02
G, g float (or double) formatted in decimal exponential notation , where the precision indicates the maximum number of significant digits. format("%G %<.1g %<1.5G %<10G %<6.0G", 123.456f); 123.456 1e+02 123.46 123.456 1E+02
A, a float (or double) formatted as a hexidecimal in exponential notation, where the precision indicates the number of significant digits. format("%A %<.1a %<1.5A %<10A %<6.0A", 123.456f); 0X1.EDD2F2P6 0x1.fp6 0X1.EDD2FP6 0X1.EDD2F2P6 0X1.FP6
Float-type option flags
See the Integer-type options. The options for float-types are the same as for integer types with one addition:
, Use a comma in place of a decimal if the locale requires it. format(new Locale("fr"), "%,7.2f", 6.03f); 6,03
Date types
t, T Date format(new Locale("fr"), "%tB %TB", Calendar.getInstance(), Calendar.getInstance()); avril AVRIL
Date format precisions
The format precision character follows the t.
A, a The day of the week format("%ta %tA", cal, cal); Tue Tuesday
b, B, h The name of the month format("%tb % Apr April Apr
C The century format("%tC\n", cal); 20
d, e The day of the month (with or without leading zeros) format("%td %te", cal, cal); 01 1
F The complete date formatted as YYYY-MM-DD format("%tF", cal); 2008-04-01
D The complete date formatted as MM/DD/YY (not corrected for locale) format(new Locale("en_US"), "%tD", cal);
format(new Locale("en_UK"), " %tD", cal);		 04/01/08 04/01/08
j The number of the day (from the beginning of the year). format("%tj\n", cal); 092
m The number of the month format("%tm\n", cal); 04
y, Y The year format("%ty %tY", cal, cal); 08 2008
H, I, k, l The hour of the day, in 12 or 24 hour format, with or without a leading zero format("%tH %tI %tk %tl", cal, cal, cal, cal); 16 04 16 4
p a.m. or p.m. format("%tp %Tp", cal, cal); pm PM
M, S, L, N The minutes, seconds, milliseconds, and nanoseconds format("%tM %tS %tL %tN", cal, cal, cal, cal); 08 17 359 359000000
Z, z The time zone: its abbreviation or offset from GMT format("%tZ %tz", cal, cal); CEST +0100
R, r, T The complete time format("%tR %tr %tT", cal, cal, cal); 16:15 04:15:32 PM 16:15:32
s, Q The number of seconds or milliseconds from "the epoch" (1 January 1970 00:00:00 UTC) format("%ts %tQ", cal, cal); 1207059412 1207059412656
c The complete time and date format("%tc", cal); Tue Apr 01 16:19:17 CEST 2008
Other data types
B, b Boolean format("%b, %B", true, false); true, FALSE
H, h Hashcode format("%h, %H", obj, obj); 190d11, 190D11
n line separator format("first%nsecond", "???"); first
second
Escape sequences
% Escape the % character format("%d%%, %d", 50, 60); 50%, 60

An instance of Formatter can be created to write the formatted output to standard types of output streams. Its functionality can also be accessed through the format methods of an output stream or of String:
System.out.println(String.format("%ty\n", cal));
System.out.format("%ty\n", cal);

The class is not multi-threaded safe. The user is responsible for maintaining a thread-safe design if a Formatter is accessed by multiple threads.

Summary

Nested Classes
enum Formatter.BigDecimalLayoutForm The enumeration giving the available styles for formatting very large decimal numbers. 
Public Constructors
Formatter()
Constructs a Formatter.
Formatter(Appendable a)
Constructs a Formatter whose output will be written to the specified Appendable.
Formatter(Locale l)
Constructs a Formatter with the specified Locale.
Formatter(Appendable a, Locale l)
Constructs a Formatter with the specified Locale and whose output will be written to the specified Appendable.
Formatter(String fileName)
Constructs a Formatter whose output is written to the specified file.
Formatter(String fileName, String csn)
Constructs a Formatter whose output is written to the specified file.
Formatter(String fileName, String csn, Locale l)
Constructs a Formatter with the given Locale and charset, and whose output is written to the specified file.
Formatter(File file)
Constructs a Formatter whose output is written to the specified File.
Formatter(File file, String csn)
Constructs a Formatter with the given charset, and whose output is written to the specified File.
Formatter(File file, String csn, Locale l)
Constructs a Formatter with the given Locale and charset, and whose output is written to the specified File.
Formatter(OutputStream os)
Constructs a Formatter whose output is written to the specified OutputStream.
Formatter(OutputStream os, String csn)
Constructs a Formatter with the given charset, and whose output is written to the specified OutputStream.
Formatter(OutputStream os, String csn, Locale l)
Constructs a Formatter with the given Locale and charset, and whose output is written to the specified OutputStream.
Formatter(PrintStream ps)
Constructs a Formatter whose output is written to the specified PrintStream.
Public Methods
void close()
Closes the Formatter.
void flush()
Flushes the Formatter.
Formatter format(Locale l, String format, Object... args)
Writes a formatted string to the output destination of the Formatter.
Formatter format(String format, Object... args)
Writes a formatted string to the output destination of the Formatter.
IOException ioException()
Returns the last IOException thrown by the Formatter's output destination.
Locale locale()
Returns the Locale of the Formatter.
Appendable out()
Returns the output destination of the Formatter.
String toString()
Returns the content by calling the toString() method of the output destination.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.io.Flushable

Public Constructors

public Formatter ()

Since: API Level 1

Constructs a Formatter. The output is written to a StringBuilder which can be acquired by invoking out() and whose content can be obtained by calling toString(). The Locale for the Formatter is the default Locale.

public Formatter (Appendable a)

Since: API Level 1

Constructs a Formatter whose output will be written to the specified Appendable. The locale for the Formatter is the default Locale.

Parameters
a the output destination of the Formatter. If a is null, then a StringBuilder will be used.

public Formatter (Locale l)

Since: API Level 1

Constructs a Formatter with the specified Locale. The output is written to a StringBuilder which can be acquired by invoking out() and whose content can be obtained by calling toString().

Parameters
l the Locale of the Formatter. If l is null, then no localization will be used.

public Formatter (Appendable a, Locale l)

Since: API Level 1

Constructs a Formatter with the specified Locale and whose output will be written to the specified Appendable.

Parameters
a the output destination of the Formatter. If a is null, then a StringBuilder will be used.
l the Locale of the Formatter. If l is null, then no localization will be used.

public Formatter (String fileName)

Since: API Level 1

Constructs a Formatter whose output is written to the specified file. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.

Parameters
fileName the filename of the file that is used as the output destination for the Formatter. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the Formatter is buffered.
Throws
FileNotFoundException if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
SecurityException if there is a SecurityManager in place which denies permission to write to the file in checkWrite(file.getPath()).

public Formatter (String fileName, String csn)

Since: API Level 1

Constructs a Formatter whose output is written to the specified file. The Locale for the Formatter is the default Locale.

Parameters
fileName the filename of the file that is used as the output destination for the Formatter. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the Formatter is buffered.
csn the name of the charset for the Formatter.
Throws
FileNotFoundException if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
SecurityException if there is a SecurityManager in place which denies permission to write to the file in checkWrite(file.getPath()).
UnsupportedEncodingException if the charset with the specified name is not supported.

public Formatter (String fileName, String csn, Locale l)

Since: API Level 1

Constructs a Formatter with the given Locale and charset, and whose output is written to the specified file.

Parameters
fileName the filename of the file that is used as the output destination for the Formatter. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the Formatter is buffered.
csn the name of the charset for the Formatter.
l the Locale of the Formatter. If l is null, then no localization will be used.
Throws
FileNotFoundException if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
SecurityException if there is a SecurityManager in place which denies permission to write to the file in checkWrite(file.getPath()).
UnsupportedEncodingException if the charset with the specified name is not supported.

public Formatter (File file)

Since: API Level 1

Constructs a Formatter whose output is written to the specified File. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.

Parameters
file the File that is used as the output destination for the Formatter. The File will be truncated to zero size if the File exists, or else a new File will be created. The output of the Formatter is buffered.
Throws
FileNotFoundException if the File is not a normal and writable File, or if a new File cannot be created, or if any error rises when opening or creating the File.
SecurityException if there is a SecurityManager in place which denies permission to write to the File in checkWrite(file.getPath()).

public Formatter (File file, String csn)

Since: API Level 1

Constructs a Formatter with the given charset, and whose output is written to the specified File. The Locale for the Formatter is the default Locale.

Parameters
file the File that is used as the output destination for the Formatter. The File will be truncated to zero size if the File exists, or else a new File will be created. The output of the Formatter is buffered.
csn the name of the charset for the Formatter.
Throws
FileNotFoundException if the File is not a normal and writable File, or if a new File cannot be created, or if any error rises when opening or creating the File.
SecurityException if there is a SecurityManager in place which denies permission to write to the File in checkWrite(file.getPath()).
UnsupportedEncodingException if the charset with the specified name is not supported.

public Formatter (File file, String csn, Locale l)

Since: API Level 1

Constructs a Formatter with the given Locale and charset, and whose output is written to the specified File.

Parameters
file the File that is used as the output destination for the Formatter. The File will be truncated to zero size if the File exists, or else a new File will be created. The output of the Formatter is buffered.
csn the name of the charset for the Formatter.
l the Locale of the Formatter. If l is null, then no localization will be used.
Throws
FileNotFoundException if the File is not a normal and writable File, or if a new File cannot be created, or if any error rises when opening or creating the File.
SecurityException if there is a SecurityManager in place which denies permission to write to the File in checkWrite(file.getPath()).
UnsupportedEncodingException if the charset with the specified name is not supported.

public Formatter (OutputStream os)

Since: API Level 1

Constructs a Formatter whose output is written to the specified OutputStream. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.

Parameters
os the stream to be used as the destination of the Formatter.

public Formatter (OutputStream os, String csn)

Since: API Level 1

Constructs a Formatter with the given charset, and whose output is written to the specified OutputStream. The Locale for the Formatter is the default Locale.

Parameters
os the stream to be used as the destination of the Formatter.
csn the name of the charset for the Formatter.
Throws
UnsupportedEncodingException if the charset with the specified name is not supported.

public Formatter (OutputStream os, String csn, Locale l)

Since: API Level 1

Constructs a Formatter with the given Locale and charset, and whose output is written to the specified OutputStream.

Parameters
os the stream to be used as the destination of the Formatter.
csn the name of the charset for the Formatter.
l the Locale of the Formatter. If l is null, then no localization will be used.
Throws
UnsupportedEncodingException if the charset with the specified name is not supported.

public Formatter (PrintStream ps)

Since: API Level 1

Constructs a Formatter whose output is written to the specified PrintStream. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.

Parameters
ps the PrintStream used as destination of the Formatter. If ps is null, then a NullPointerException will be raised.

Public Methods

public void close ()

Since: API Level 1

Closes the Formatter. If the output destination is Closeable, then the method close() will be called on that destination. If the Formatter has been closed, then calling the this method will have no effect. Any method but the ioException() that is called after the Formatter has been closed will raise a FormatterClosedException.

public void flush ()

Since: API Level 1

Flushes the Formatter. If the output destination is Flushable, then the method flush() will be called on that destination.

Throws
FormatterClosedException if the Formatter has been closed.

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

Since: API Level

Writes a formatted string to the output destination of the Formatter.

Parameters
l the Locale used in the method. If locale is null, then no localization will be applied. This parameter does not influence the Locale specified during construction.
format a format string.
args the arguments list used in the format() method. If there are more arguments than those specified by the format string, then the additional arguments are ignored.
Returns
  • this Formatter.
Throws
IllegalFormatException if the format string is illegal or incompatible with the arguments, or if fewer arguments are sent than those required by the format string, or any other illegal situation.
FormatterClosedException if the Formatter has been closed.

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

Since: API Level

Writes a formatted string to the output destination of the Formatter.

Parameters
format a format string.
args the arguments list used in the format() method. If there are more arguments than those specified by the format string, then the additional arguments are ignored.
Returns
  • this Formatter.
Throws
IllegalFormatException if the format string is illegal or incompatible with the arguments, or if fewer arguments are sent than those required by the format string, or any other illegal situation.
FormatterClosedException if the Formatter has been closed.

public IOException ioException ()

Since: API Level 1

Returns the last IOException thrown by the Formatter's output destination. If the append() method of the destination does not throw IOExceptions, the ioException() method will always return null.

Returns
  • the last IOException thrown by the Formatter's output destination.

public Locale locale ()

Since: API Level 1

Returns the Locale of the Formatter.

Returns
  • the Locale for the Formatter or null for no Locale.
Throws
FormatterClosedException if the Formatter has been closed.

public Appendable out ()

Since: API Level 1

Returns the output destination of the Formatter.

Returns
  • the output destination of the Formatter.
Throws
FormatterClosedException if the Formatter has been closed.

public String toString ()

Since: API Level 1

Returns the content by calling the toString() method of the output destination.

Returns
  • the content by calling the toString() method of the output destination.
Throws
FormatterClosedException if the Formatter has been closed.