Java in a Nutshell, 5th Edition

Name

Formatter

Synopsis

The Formatter class is a utility for formatting text in the style of the printf( ) method of the C programming language. Every Formatter has an associated java.lang.Appendable object (such as a StringBuilder or PrintWriter) that is specified when the Formatter is created. format( ) is a varargs method that expects a “format string” argument followed by some number of Object arguments. The format string uses a grammar, described in detail later in the entry, to specify how the arguments that follow are to be converted to strings. After the arguments are converted, they are substituted into the format string, and the resulting text is appended to the Appendable. A variant of the format( ) method accepts a Locale object that can affect the argument conversions.

For ease of use, a Formatter never throws a java.io.IOException, even when the underlying Appendable throws one. When using a Formatter with a stream-based Appendable object that may throw an IOException, you can use the ioException( ) method to obtain the most recently thrown exception, or null if no exception has been thrown by the Appendable.

Formatter implements the Closeable and Flushable interfaces of the java.io package, and its close( ) and flush( ) methods call the corresponding methods on its Appendable object, if that object itself implements Closeable or Flushable. When a Formatter sends its output to a stream or similar Appendable, remember to call close( ) when you are done with it. It is ...