java.util

Class Formatter

java.lang.Object

java.util.Formatter

All Implemented Interfaces:

Closeable, Flushable

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 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

Author:

Tom Tromey (tromey@redhat.com), Andrew John Hughes (gnu_andrew@member.fsf.org)

Constructor Summary

Constructors

Constructor and Description
Formatter() Constructs a new Formatter using the default locale and a 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(Locale loc) Constructs a new Formatter using the specified locale and a StringBuilder as the output stream.
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

Modifier and Type	Method and Description
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 Object.toString() to the underlying output stream.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Formatter

public Formatter()

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

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)
          throws IOException

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:

IOException

java.lang.SecurityException - if a security manager is present and doesn't allow writing to the file.

Formatter

public Formatter(File file,
                 String charset)
          throws IOException

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:

IOException

java.lang.SecurityException - if a security manager is present and doesn't allow writing to the file.

Formatter

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

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.

Throws:

IOException

java.lang.SecurityException - if a security manager is present and doesn't allow writing to the file.

Formatter

public Formatter(Locale loc)

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

Parameters:

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)
          throws UnsupportedEncodingException

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)
          throws UnsupportedEncodingException

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:

out - 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)
          throws IOException

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:

IOException

java.lang.SecurityException - if a security manager is present and doesn't allow writing to the file.

Formatter

public Formatter(String file,
                 String charset)
          throws IOException

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:

IOException

java.lang.SecurityException - if a security manager is present and doesn't allow writing to the file.

Formatter

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

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.

Throws:

IOException

java.lang.SecurityException - if a security manager is present and doesn't allow writing to the file.

Method Detail

close

public void close()

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

Specified by:

close in interface Closeable

flush

public void flush()

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

Specified by:

flush in interface Flushable

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:

format - 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 Object.toString() to the underlying output stream. The results returned depend on the particular Appendable being used. For example, a StringBuilder will return the formatted output but an I/O stream will not.

Overrides:

toString in class Object

Throws:

FormatterClosedException - if the formatter is closed.