java.util

Class Formatter

public final class Formatter extends Object implements Closeable, Flushable

A Java formatter for printf-style format strings, as seen in the C programming language. This differs from the C interpretation of such strings by performing much stricter checking of format specifications and their corresponding arguments. While unknown conversions will be ignored in C, and invalid conversions will only produce compiler warnings, the Java version utilises a full range of run-time exceptions to handle these cases. The Java version is also more customisable by virtue of the provision of the {@link Formattable} interface, which allows an arbitrary class to be formatted by the formatter.

The formatter is accessible by more convienient static methods. For example, streams now have appropriate format methods (the equivalent of fprintf) as do String objects (the equivalent of sprintf).

Note: the formatter is not thread-safe. For multi-threaded access, external synchronization should be provided.

Since: 1.5

Nested Class Summary
static class	Formatter.BigDecimalLayoutForm The type of numeric output format for a {@link BigDecimal}.

Constructor Summary
	Formatter() Constructs a new `Formatter` using the default locale and a {@link StringBuilder} as the output stream.
	Formatter(Locale loc) Constructs a new `Formatter` using the specified locale and a {@link StringBuilder} as the output stream.
	Formatter(Appendable app) Constructs a new `Formatter` using the default locale and the specified output stream.
	Formatter(Appendable app, Locale loc) Constructs a new `Formatter` using the specified locale and the specified output stream.
	Formatter(File file) Constructs a new `Formatter` using the default locale and character set, with the specified file as the output stream.
	Formatter(File file, String charset) Constructs a new `Formatter` using the default locale, with the specified file as the output stream and the supplied character set.
	Formatter(File file, String charset, Locale loc) Constructs a new `Formatter` using the specified file as the output stream with the supplied character set and locale.
	Formatter(OutputStream out) Constructs a new `Formatter` using the default locale and character set, with the specified output stream.
	Formatter(OutputStream out, String charset) Constructs a new `Formatter` using the default locale, with the specified file output stream and the supplied character set.
	Formatter(OutputStream out, String charset, Locale loc) Constructs a new `Formatter` using the specified output stream with the supplied character set and locale.
	Formatter(PrintStream out) Constructs a new `Formatter` using the default locale with the specified output stream.
	Formatter(String file) Constructs a new `Formatter` using the default locale and character set, with the specified file as the output stream.
	Formatter(String file, String charset) Constructs a new `Formatter` using the default locale, with the specified file as the output stream and the supplied character set.
	Formatter(String file, String charset, Locale loc) Constructs a new `Formatter` using the specified file as the output stream with the supplied character set and locale.

Method Summary
void	close() Closes the formatter, so as to release used resources.
void	flush() Flushes the formatter, writing any cached data to the output stream.
Formatter	format(Locale loc, String fmt, Object... args) Outputs a formatted string based on the supplied specification, `fmt`, and its arguments using the specified locale.
Formatter	format(String format, Object... args) Outputs a formatted string based on the supplied specification, `fmt`, and its arguments using the formatter's locale.
IOException	ioException() Returns the last I/O exception thrown by the `append()` operation of the underlying output stream.
Locale	locale() Returns the locale used by this formatter.
Appendable	out() Returns the output stream used by this formatter.
String	toString() Returns the result of applying {@link Object#toString()} to the underlying output stream.

Constructor Detail

Formatter

public Formatter()

Constructs a new Formatter using the default locale and a {@link StringBuilder} as the output stream.

Formatter

public Formatter(Locale loc)

Constructs a new Formatter using the specified locale and a {@link StringBuilder} as the output stream. If the locale is null, then no localization is applied.

Parameters: loc the locale to use.

Formatter

public Formatter(Appendable app)

Constructs a new Formatter using the default locale and the specified output stream.

Parameters: app the output stream to use.

Formatter

public Formatter(Appendable app, Locale loc)

Constructs a new Formatter using the specified locale and the specified output stream. If the locale is null, then no localization is applied.

Parameters: app the output stream to use. loc the locale to use.

Formatter

public Formatter(File file)

Constructs a new Formatter using the default locale and character set, with the specified file as the output stream.

Parameters: file the file to use for output.

Throws: FileNotFoundException if the file does not exist and can not be created. SecurityException if a security manager is present and doesn't allow writing to the file.

Formatter

public Formatter(File file, String charset)

Constructs a new Formatter using the default locale, with the specified file as the output stream and the supplied character set.

Parameters: file the file to use for output. charset the character set to use for output.

Throws: FileNotFoundException if the file does not exist and can not be created. SecurityException if a security manager is present and doesn't allow writing to the file. UnsupportedEncodingException if the supplied character set is not supported.

Formatter

public Formatter(File file, String charset, Locale loc)

Constructs a new Formatter using the specified file as the output stream with the supplied character set and locale. If the locale is null, then no localization is applied.

Parameters: file the file to use for output. charset the character set to use for output. loc the locale to use.

Formatter

public Formatter(OutputStream out)

Constructs a new Formatter using the default locale and character set, with the specified output stream.

Parameters: out the output stream to use.

Formatter

public Formatter(OutputStream out, String charset)

Constructs a new Formatter using the default locale, with the specified file output stream and the supplied character set.

Parameters: out the output stream. charset the character set to use for output.

Throws: UnsupportedEncodingException if the supplied character set is not supported.

Formatter

public Formatter(OutputStream out, String charset, Locale loc)

Constructs a new Formatter using the specified output stream with the supplied character set and locale. If the locale is null, then no localization is applied.

Parameters: file the output stream. charset the character set to use for output. loc the locale to use.

Throws: UnsupportedEncodingException if the supplied character set is not supported.

Formatter

public Formatter(PrintStream out)

Constructs a new Formatter using the default locale with the specified output stream. The character set used is that of the output stream.

Parameters: out the output stream to use.

Formatter

public Formatter(String file)

Constructs a new Formatter using the default locale and character set, with the specified file as the output stream.

Parameters: file the file to use for output.

Throws: FileNotFoundException if the file does not exist and can not be created. SecurityException if a security manager is present and doesn't allow writing to the file.

Formatter

public Formatter(String file, String charset)

Constructs a new Formatter using the default locale, with the specified file as the output stream and the supplied character set.

Parameters: file the file to use for output. charset the character set to use for output.

Formatter

public Formatter(String file, String charset, Locale loc)

Constructs a new Formatter using the specified file as the output stream with the supplied character set and locale. If the locale is null, then no localization is applied.

Parameters: file the file to use for output. charset the character set to use for output. loc the locale to use.

Method Detail

close

public void close()

Closes the formatter, so as to release used resources. If the underlying output stream supports the {@link Closeable} interface, then this is also closed. Attempts to use a formatter instance, via any method other than {@link #ioException()}, after closure results in a {@link FormatterClosedException}.

flush

public void flush()

Flushes the formatter, writing any cached data to the output stream. If the underlying output stream supports the {@link Flushable} interface, it is also flushed.

Throws: FormatterClosedException if the formatter is closed.

format

public Formatter format(Locale loc, String fmt, Object... args)

Outputs a formatted string based on the supplied specification, fmt, and its arguments using the specified locale. The locale of the formatter does not change as a result; the specified locale is just used for this particular formatting operation. If the locale is null, then no localization is applied.

Parameters: loc the locale to use for this format. fmt the format specification. args the arguments to apply to the specification.

Throws: IllegalFormatException if there is a problem with the syntax of the format specification or a mismatch between it and the arguments. FormatterClosedException if the formatter is closed.

format

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

Outputs a formatted string based on the supplied specification, fmt, and its arguments using the formatter's locale.

Parameters: fmt the format specification. args the arguments to apply to the specification.

Throws: IllegalFormatException if there is a problem with the syntax of the format specification or a mismatch between it and the arguments. FormatterClosedException if the formatter is closed.

ioException

public IOException ioException()

Returns the last I/O exception thrown by the append() operation of the underlying output stream.

Returns: the last I/O exception.

locale

public Locale locale()

Returns the locale used by this formatter.

Returns: the formatter's locale.

Throws: FormatterClosedException if the formatter is closed.

out

public Appendable out()

Returns the output stream used by this formatter.

Returns: the formatter's output stream.

Throws: FormatterClosedException if the formatter is closed.

toString

public String toString()

Returns the result of applying {@link Object#toString()} to the underlying output stream. The results returned depend on the particular {@link Appendable} being used. For example, a {@link StringBuilder} will return the formatted output but an I/O stream will not.

Throws: FormatterClosedException if the formatter is closed.