|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.util.Formatter
public final class Formatter
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.
Nested Class Summary | |
---|---|
static class |
Formatter.BigDecimalLayoutForm
The type of numeric output format for a BigDecimal . |
Constructor Summary | |
---|---|
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 | |
---|---|
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 |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public Formatter()
Formatter
using the default
locale and a StringBuilder
as the output stream.
public Formatter(Locale loc)
Formatter
using the specified
locale and a StringBuilder
as the output stream.
If the locale is null
, then no localization
is applied.
loc
- the locale to use.public Formatter(Appendable app)
Formatter
using the default
locale and the specified output stream.
app
- the output stream to use.public Formatter(Appendable app, Locale loc)
Formatter
using the specified
locale and the specified output stream. If the locale is
null
, then no localization is applied.
app
- the output stream to use.loc
- the locale to use.public Formatter(File file) throws FileNotFoundException
Formatter
using the default
locale and character set, with the specified file as the
output stream.
file
- the file to use for output.
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.public Formatter(File file, String charset) throws FileNotFoundException, UnsupportedEncodingException
Formatter
using the default
locale, with the specified file as the output stream
and the supplied character set.
file
- the file to use for output.charset
- the character set to use for output.
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.public Formatter(File file, String charset, Locale loc) throws FileNotFoundException, UnsupportedEncodingException
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.
file
- the file to use for output.charset
- the character set to use for output.loc
- the locale to use.
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.public Formatter(OutputStream out)
Formatter
using the default
locale and character set, with the specified output stream.
out
- the output stream to use.public Formatter(OutputStream out, String charset) throws UnsupportedEncodingException
Formatter
using the default
locale, with the specified file output stream and the
supplied character set.
out
- the output stream.charset
- the character set to use for output.
UnsupportedEncodingException
- if the supplied character
set is not supported.public Formatter(OutputStream out, String charset, Locale loc) throws UnsupportedEncodingException
Formatter
using the specified
output stream with the supplied character set and locale.
If the locale is null
, then no localization is
applied.
out
- the output stream.charset
- the character set to use for output.loc
- the locale to use.
UnsupportedEncodingException
- if the supplied character
set is not supported.public Formatter(PrintStream out)
Formatter
using the default
locale with the specified output stream. The character
set used is that of the output stream.
out
- the output stream to use.public Formatter(String file) throws FileNotFoundException
Formatter
using the default
locale and character set, with the specified file as the
output stream.
file
- the file to use for output.
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.public Formatter(String file, String charset) throws FileNotFoundException, UnsupportedEncodingException
Formatter
using the default
locale, with the specified file as the output stream
and the supplied character set.
file
- the file to use for output.charset
- the character set to use for output.
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.public Formatter(String file, String charset, Locale loc) throws FileNotFoundException, UnsupportedEncodingException
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.
file
- the file to use for output.charset
- the character set to use for output.loc
- the locale to use.
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.Method Detail |
---|
public void close()
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
.
close
in interface Closeable
public void flush()
Flushable
interface, it is also flushed.
flush
in interface Flushable
FormatterClosedException
- if the formatter is closed.public Formatter format(Locale loc, String fmt, Object... args)
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.
loc
- the locale to use for this format.fmt
- the format specification.args
- the arguments to apply to the specification.
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.public Formatter format(String format, Object... args)
fmt
, and its arguments using the formatter's locale.
format
- the format specification.args
- the arguments to apply to the specification.
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.public IOException ioException()
append()
operation of the underlying
output stream.
public Locale locale()
FormatterClosedException
- if the formatter is closed.public Appendable out()
FormatterClosedException
- if the formatter is closed.public String toString()
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.
toString
in class Object
FormatterClosedException
- if the formatter is closed.Object.getClass()
,
Object.hashCode()
,
Class.getName()
,
Integer.toHexString(int)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |