Java Formatter is a utility class that can make life simple when working with formatting stream output in Java. It is built to operate similarly to the C/C++ printf function. It is used to format and output data to a specific destination, such as a string or a file output stream. This article explores the class and illustrate some of its utility in everyday programming in Java.
The Java Formatter class is defined in the java.util package and is declared final. It, therefore, cannot be extended or sub-classed. The Formatter class implements the Closeable and Flushable interfaces. The only close() method derived from the Closeable interface is defined by this class to release any held up resources such as a open files, streams, and so forth. And, the flush() method derived from the Flushable interface is invoked to write buffered output to the underlying stream.
The way to display formatted data is possible through the printf function, much like C's printf-style formatting function. This function is particularly suitable for displaying formatted output to a standard output stream. Formatting output with Java's printf-style function is fine, but the Java Formatter class take this utility a step farther. With the help of this class, we can send formatted outputs to other output streams or devices, such as a GUI component or to a file apart from standard output. It provides the same formatting ability as printf, such as layout justification, alignment, formatting for numeric, string, date, time data, and locale-specific output. It basically converts the binary data form into formatted text and stores it into a buffer. It supplies a default buffer, or we can supply a buffer during its creation.
There are numerous overloaded constructors provided by this class, where we can provide an Appendable buffer explicitly during its invocation. The Appendable interface signifies an object to which valid unicode char sequences and values are appended. There are other constructors where we can supply a File object, OutputStream object, or PrintStream object. For example, some of the commonly used constructors are as follows:
- Formatter(): It is a no-argument constructor to create a Formatter object. It operates on a default buffer created from a StringBuilder. It is the commonly used constructor of all of its type.
- Formatter(Appendable a): Here, the Appendable object specifies a buffer for formatted output. If, however, the value is null, the object automatically creates a Stringbuilder to hold the formatted output.
- Formatter(Appendable a, Locale loc): The Locale object regionalizes the output format according to the specified locale. If unspecified, the default locale is used. Sometimes, a locale is necessary to tailor the output according to Geo-political or culturally sensitive data, such as formatting the date and time, substituting a locale-specific decimal separator, and the like.
- Formatter(File file): The file parameter of this constructor designates a reference to a open file where the output will be streamed.
Once the Formatter object is created, it may be used in many ways. The format specifier specifies the way the data is formatted. Refer to the Java API Documentation for complete documentation on them. A few common format specifiers are:
- %S or %s: Specifies String
- %X or %x: Specifies hexadecimal integer
- %o: Specifies Octal integer
- %d: Specifies Decimal integer
- %c: Specifies character
- %T or %t: Specifies Time and date
- %n: Inserts newline character
- %B or %b: Specifies Boolean
- %A or %a: Specifies floating point hexadecimal
- %f: Specifies Decimal floating point
The format specifiers for general, character, and numeric types are applied according to the following syntax:
- The argument_index is optional and the integer value 1$, 2$, and so forth represent the first, second, and so on arguments.
- The optional flag represents the character that modifies the output format.
- The optional width represents the minimum number of characters to be written in the output.
- The optional precision represents a positive decimal integer value defining the precision of a floating point value.
- The conversion is not optional; it indicates the argument data type, such as %d for integer, %s for string, and the like.
A Few Quick Examples
Formatter f=new Formatter(); f.format("%3$3s %2$3s %1$3s", "fear", "strengthen", "weakness"); System.out.println(f);
StringBuilder builder=new StringBuilder(); Formatter f=new Formatter(builder); f.format(Locale.FRANCE,"%.5f", -1325.789); System.out.println(f); Formatter f2=new Formatter(); f2.format(Locale.CANADA, "%.5f", -1325.789); System.out.println(f2);
Formatter f3=new Formatter(); f3.format(Locale.FRENCH,"%1$te %1$tB, %1$tY", Calendar.getInstance()); System.out.println(f3); Formatter f4=new Formatter(); f4.format(Locale.GERMANY,"%1$te %1$tB, %1$tY", Calendar.getInstance()); System.out.println(f4);
Using %n and %% Specifiers
Formatter f = new Formatter(); f.format("Format%n %.2f%% complete", 46.6); System.out.println(f);
It is good to close to the Formatter instance with the help of the close() function, especially when working with files, although Formatter implements the AutoCloseable interface. This frees up the resources used. It is better to use printf when formatting an output to a console because it automatically uses Formatter with System.out. It should be noted that Formatter is not thread-safe. Hence, multi-threaded access should be used cautiously.