Build 1.0_r1(from source)

java.util
Class Formatter

java.lang.Object
  extended by java.util.Formatter
All Implemented Interfaces:
Closeable, Flushable

public final class Formatter
extends Object
implements Closeable, Flushable

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.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",> 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.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",> 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.

Since:
1.5

Nested Class Summary
static class Formatter.BigDecimalLayoutForm
          The enumeration giving the available styles for formatting very large decimal numbers.
 
Constructor Summary
Formatter()
          Constructs a formatter.
Formatter(Appendable a)
          Constructs a formatter of which the output is denoted.
Formatter(Appendable a, Locale l)
          Constructs a formatter of which the output and locale is denoted.
Formatter(File file)
          Constructs a formatter of which the file is denoted.
Formatter(File file, String csn)
          Constructs a formatter of which the file and charset is denoted.
Formatter(File file, String csn, Locale l)
          Constructs a formatter of which the file, charset and locale is denoted.
Formatter(Locale l)
          Constructs a formatter of which the locale is denoted.
Formatter(OutputStream os)
          Constructs a formatter of which the output destination is specified.
Formatter(OutputStream os, String csn)
          Constructs a formatter of which the output destination and the charset is specified.
Formatter(OutputStream os, String csn, Locale l)
          Constructs a formatter of which the output destination, the charset and the locale is specified.
Formatter(PrintStream ps)
          Constructs a formatter of which the output destination is specified.
Formatter(String fileName)
          Constructs a formatter of which the filename is denoted.
Formatter(String fileName, String csn)
          Constructs a formatter of which the filename and charset is denoted.
Formatter(String fileName, String csn, Locale l)
          Constructs a formatter of which the filename, charset and locale is denoted.
 
Method Summary
 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 out 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Formatter

public Formatter()
Constructs a formatter. The output is a StringBuilder which can be achieved by invoking the out method and whose contents can be attained by calling the toString method. The locale for the formatter is the default locale of the JVM.


Formatter

public Formatter(Appendable a)
Constructs a formatter of which the output is denoted. The locale for the formatter is the default locale of the JVM.

Parameters:
a - The output of the formatter. If a is null, then a StringBuilder will be used.

Formatter

public Formatter(Locale l)
Constructs a formatter of which the locale is denoted. The output destination is a StringBuilder which can be achieved by invoking the out method and whose contents can be attained by calling the toString method.

Parameters:
l - The locale of the formatter. If l is null, then no localization will be used.

Formatter

public Formatter(Appendable a,
                 Locale l)
Constructs a formatter of which the output and locale is denoted.

Parameters:
a - The output 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.

Formatter

public Formatter(String fileName)
          throws FileNotFoundException
Constructs a formatter of which the filename is denoted. The charset of the formatter is the default charset of JVM. The locale for the formatter is the default locale of the JVM.

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 a new file cannot be created or any error rises when opening or creating the file.
SecurityException - If there is a security manager and it denies writing to the file in checkWrite(file.getPath()).

Formatter

public Formatter(String fileName,
                 String csn)
          throws FileNotFoundException,
                 UnsupportedEncodingException
Constructs a formatter of which the filename and charset is denoted. The locale for the formatter is the default locale of the JVM.

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 a new file cannot be created or any error rises when opening or creating the file.
SecurityException - If there is a security manager and it denies writing to the file in checkWrite(file.getPath()).
UnsupportedEncodingException - If the charset with the specified name is not supported.

Formatter

public Formatter(String fileName,
                 String csn,
                 Locale l)
          throws FileNotFoundException,
                 UnsupportedEncodingException
Constructs a formatter of which the filename, charset and locale is denoted.

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 a new file cannot be created or any error rises when opening or creating the file.
SecurityException - If there is a security manager and it denies writing to the file in checkWrite(file.getPath()).
UnsupportedEncodingException - If the charset with the specified name is not supported.

Formatter

public Formatter(File file)
          throws FileNotFoundException
Constructs a formatter of which the file is denoted. The charset of the formatter is the default charset of JVM. The locale for the formatter is the default locale of the JVM.

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 does not denote a normal and writable file, or a new file cannot be created or any error rises when opening or creating the file.
SecurityException - If there is a security manager and it denies writing to the file in checkWrite(file.getPath()).

Formatter

public Formatter(File file,
                 String csn)
          throws FileNotFoundException,
                 UnsupportedEncodingException
Constructs a formatter of which the file and charset is denoted. The locale for the formatter is the default locale of the JVM.

Parameters:
file - The file 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 file does not denote a normal and writable file, or a new file cannot be created or any error rises when opening or creating the file.
SecurityException - If there is a security manager and it denies writing to the file in checkWrite(file.getPath()).
UnsupportedEncodingException - If the charset with the specified name is not supported.

Formatter

public Formatter(File file,
                 String csn,
                 Locale l)
          throws FileNotFoundException,
                 UnsupportedEncodingException
Constructs a formatter of which the file, charset and locale is denoted.

Parameters:
file - 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 does not denote a normal and writable file, or a new file cannot be created or any error rises when opening or creating the file.
SecurityException - If there is a security manager and it denies writing to the file in checkWrite(file.getPath()).
UnsupportedEncodingException - If the charset with the specified name is not supported.

Formatter

public Formatter(OutputStream os)
Constructs a formatter of which the output destination is specified. The charset of the formatter is the default charset of JVM. The locale for the formatter is the default locale of the JVM.

Parameters:
os - The stream used as the destination of the formatter.

Formatter

public Formatter(OutputStream os,
                 String csn)
          throws UnsupportedEncodingException
Constructs a formatter of which the output destination and the charset is specified. The locale for the formatter is the default locale of the JVM.

Parameters:
os - The stream 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.

Formatter

public Formatter(OutputStream os,
                 String csn,
                 Locale l)
          throws UnsupportedEncodingException
Constructs a formatter of which the output destination, the charset and the locale is specified.

Parameters:
os - The stream 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.

Formatter

public Formatter(PrintStream ps)
Constructs a formatter of which the output destination is specified. The charset of the formatter is the default charset of JVM. The locale for the formatter is the default locale of the JVM.

Parameters:
ps - The print stream used as destination of the formatter. If ps is null, then NullPointerExcepiton will be thrown out.
Method Detail

locale

public Locale locale()
Returns the locale of the formatter.

Returns:
The locale for the formatter and null for no locale.
Throws:
FormatterClosedException - If the formatter has been closed.

out

public Appendable out()
Returns the output destination of the formatter.

Returns:
The output destination of the formatter.
Throws:
FormatterClosedException - If the formatter has been closed.

toString

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

Overrides:
toString in class Object
Returns:
The content by calling the toString() method of the output destination.
Throws:
FormatterClosedException - If the formatter has been closed.

flush

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

Specified by:
flush in interface Flushable
Throws:
FormatterClosedException - If the formatter has been closed.

close

public void close()
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 close will have no effect. Any method but the ioException() that is called after the formatter has been closed will raise a FormatterClosedException.

Specified by:
close in interface Closeable

ioException

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

Returns:
The last IOException thrown out by the formatter's output destination.

format

public Formatter format(String format,
                        Object... args)
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 the arguments are less than those required by the format string or any other illegal situation.
FormatterClosedException - If the formatter has been closed.

format

public Formatter format(Locale l,
                        String format,
                        Object... args)
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 the arguments are less than those required by the format string or any other illegal situation.
FormatterClosedException - If the formatter has been closed.

Build 1.0_r1(from source)

Please submit a feedback, bug or feature