Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

java.util

Class Formatter

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

Nested Class Summary

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

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(String format, java.lang.Object... args)
Outputs a formatted string based on the supplied specification, fmt, and its arguments using the formatter's locale.
Formatter
format(Locale loc, String fmt, java.lang.Object... args)
Outputs a formatted string based on the supplied specification, fmt, and its arguments using the specified 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, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Formatter

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

Formatter

public Formatter(File file)
            throws FileNotFoundException
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)
            throws FileNotFoundException,
                   UnsupportedEncodingException
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)
            throws FileNotFoundException,
                   UnsupportedEncodingException
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:
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(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:
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(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(String file)
            throws FileNotFoundException
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)
            throws FileNotFoundException,
                   UnsupportedEncodingException
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(String file,
                 String charset,
                 Locale loc)
            throws FileNotFoundException,
                   UnsupportedEncodingException
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:
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(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.

Method Details

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(String format,
                        java.lang.Object... args)
Outputs a formatted string based on the supplied specification, fmt, and its arguments using the formatter's locale.
Parameters:
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(Locale loc,
                        String fmt,
                        java.lang.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.

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 interface Object
Throws:
FormatterClosedException - if the formatter is closed.
Formatter.java -- printf-style formatting Copyright (C) 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About