Save This Page
Home » openjdk-7 » java » util » [javadoc | source]
java.util
public final class: Formatter [javadoc | source]
java.lang.Object
   java.util.Formatter

All Implemented Interfaces:
    Flushable, Closeable

The {@code Formatter} class is a String-formatting utility that is designed to work like the {@code printf} function of the C programming language. Its key methods are the {@code format} methods which create a formatted {@code String} by replacing a set of placeholders (format tokens) with formatted values. The style used to format each value is determined by the format token used. For example, the call
{@code format("My decimal value is %d and my String is %s.", 3, "Hello");}
returns the {@code String}
{@code My decimal value is 3 and my String is Hello.}

The format token consists of a percent sign, optionally followed by flags and precision arguments, and then a single character that indicates the type of value being formatted. If the type is a time/date, then the type character {@code t} is followed by an additional character that indicates how the date is to be formatted. The two characters {@code <$} immediately following the % sign indicate that the previous value should be used again instead of moving on to the next value argument. A number {@code n} and a dollar sign immediately following the % sign make n the next argument to be used.

The available choices are the following:
Text value types
{@code s} String {@code format("%s, %s", "hello", "Hello");} {@code hello, Hello}
{@code S}, {@code s} String to capitals {@code format("%S, %S", "hello", "Hello");} {@code HELLO, HELLO}
{@code c} Character {@code format("%c, %c", 'd', 0x65);} {@code d, e}
{@code C} Character to capitals {@code format("%C, %C", 'd', 0x65);} {@code D, E}
Text option flags
The value between the option and the type character indicates the minimum width in characters of the formatted value
{@code -} Left justify (width value is required) {@code format("%-3C, %3C", 'd', 0x65);} {@code D , E}
Integer types
{@code d} int, formatted as decimal {@code format("%d, %d"1$, 35, 0x10);} {@code 35, 16}
{@code o} int, formatted as octal {@code format("%o, %o", 8, 010);} {@code 10, 10}
{@code X}, {@code x} int, formatted as hexidecimal {@code format("%x, %X", 10, 10);} {@code a, A}
Integer option flags
The value between the option and the type character indicates the minimum width in characters of the formatted value
{@code +} lead with the number's sign {@code format("%+d, %+4d", 5, 5);} {@code +5, +5}
{@code -} Left justify (width value is required) {@code format("%-6dx", 5);} {@code 5 x}
{@code #} Print the leading characters that indicate hexidecimal or octal (for use only with hex and octal types) {@code format("%#o", 010);} {@code 010}
{@code } A space indicates that non-negative numbers should have a leading space. {@code format("x% d% 5d", 4, 4);} {@code x 4 4}
{@code 0} Pad the number with leading zeros (width value is required) {@code format("%07d, %03d", 4, 5555);} {@code 0000004, 5555}
{@code (} Put parentheses around negative numbers (decimal only) {@code format("%(d, %(d, %(6d", 12, -12, -12);} {@code 12, (12), (12)}
Float types
A value immediately following the % symbol gives the minimum width in characters of the formatted value; if it is followed by a period and another integer, then the second value gives the precision (6 by default).
{@code f} float (or double) formatted as a decimal, where the precision indicates the number of digits after the decimal. {@code format("%f %<.1f %<1.5f %<10f %<6.0f", 123.456f);} {@code 123.456001 123.5 123.45600 123.456001 123}
{@code E}, {@code e} float (or double) formatted in decimal exponential notation, where the precision indicates the number of significant digits. {@code format("%E %<.1e %<1.5E %<10E %<6.0E", 123.456f);} {@code 1.234560E+02 1.2e+02 1.23456E+02 1.234560E+02 1E+02}
{@code G}, {@code g} float (or double) formatted in decimal exponential notation , where the precision indicates the maximum number of significant digits. {@code format("%G %<.1g %<1.5G %<10G %<6.0G", 123.456f);} {@code 123.456 1e+02 123.46 123.456 1E+02}
{@code A}, {@code a} float (or double) formatted as a hexidecimal in exponential notation, where the precision indicates the number of significant digits. {@code format("%A %<.1a %<1.5A %<10A %<6.0A", 123.456f);} {@code 0X1.EDD2F2P6 0x1.fp6 0X1.EDD2FP6 0X1.EDD2F2P6 0X1.FP6}
Float-type option flags
See the Integer-type options. The options for float-types are the same as for integer types with one addition:
{@code ,} Use a comma in place of a decimal if the locale requires it. {@code format(new Locale("fr"), "%,7.2f", 6.03f);} {@code 6,03}
Date types
{@code t}, {@code T} Date {@code format(new Locale("fr"), "%tB %TB", Calendar.getInstance(), Calendar.getInstance());} {@code avril AVRIL}
Date format precisions
The format precision character follows the {@code t}.
{@code A}, {@code a} The day of the week {@code format("%ta %tA", cal, cal);} {@code Tue Tuesday}
{@code b}, {@code B}, {@code h} The name of the month {@code format("%tb % {@code Apr April Apr}
{@code C} The century {@code format("%tC\n", cal);} {@code 20}
{@code d}, {@code e} The day of the month (with or without leading zeros) {@code format("%td %te", cal, cal);} {@code 01 1}
{@code F} The complete date formatted as YYYY-MM-DD {@code format("%tF", cal);} {@code 2008-04-01}
{@code D} The complete date formatted as MM/DD/YY (not corrected for locale) {@code format(new Locale("en_US"), "%tD", cal);
format(new Locale("en_UK"), " %tD", cal);}
{@code 04/01/08 04/01/08}
{@code j} The number of the day (from the beginning of the year). {@code format("%tj\n", cal);} {@code 092}
{@code m} The number of the month {@code format("%tm\n", cal);} {@code 04}
{@code y}, {@code Y} The year {@code format("%ty %tY", cal, cal);} {@code 08 2008}
{@code H}, {@code I}, {@code k}, {@code l} The hour of the day, in 12 or 24 hour format, with or without a leading zero {@code format("%tH %tI %tk %tl", cal, cal, cal, cal);} {@code 16 04 16 4}
{@code p} a.m. or p.m. {@code format("%tp %Tp", cal, cal);} {@code pm PM}
{@code M}, {@code S}, {@code L}, {@code N} The minutes, seconds, milliseconds, and nanoseconds {@code format("%tM %tS %tL %tN", cal, cal, cal, cal);} {@code 08 17 359 359000000}
{@code Z}, {@code z} The time zone: its abbreviation or offset from GMT {@code format("%tZ %tz", cal, cal);} {@code CEST +0100}
{@code R}, {@code r}, {@code T} The complete time {@code format("%tR %tr %tT", cal, cal, cal);} {@code 16:15 04:15:32 PM 16:15:32}
{@code s}, {@code Q} The number of seconds or milliseconds from "the epoch" (1 January 1970 00:00:00 UTC) {@code format("%ts %tQ", cal, cal);} {@code 1207059412 1207059412656}
{@code c} The complete time and date {@code format("%tc", cal);} {@code Tue Apr 01 16:19:17 CEST 2008}
Other data types
{@code B}, {@code b} Boolean {@code format("%b, %B", true, false);} {@code true, FALSE}
{@code H}, {@code h} Hashcode {@code format("%h, %H", obj, obj);} {@code 190d11, 190D11}
{@code n} line separator {@code format("first%nsecond", "???");} {@code first
second}
Escape sequences
{@code %} Escape the % character {@code format("%d%%, %d", 50, 60);} {@code 50%, 60}

An instance of Formatter can be created to write the formatted output to standard types of output streams. Its functionality can also be accessed through the format methods of an output stream or of {@code String}:
{@code System.out.println(String.format("%ty\n", cal));}
{@code System.out.format("%ty\n", cal);}

The class is not multi-threaded safe. The user is responsible for maintaining a thread-safe design if a {@code Formatter} is accessed by multiple threads.

Nested Class Summary:
public enum class  Formatter.BigDecimalLayoutForm  The enumeration giving the available styles for formatting very large decimal numbers. 
Constructor:
 public Formatter() 
 public Formatter(Appendable a) 
    Constructs a {@code Formatter} whose output will be written to the specified {@code Appendable}. The locale for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    a - the output destination of the {@code Formatter}. If {@code a} is {@code null}, then a {@code StringBuilder} will be used.
 public Formatter(Locale l) 
    Constructs a {@code Formatter} with the specified {@code Locale}. The output is written to a {@code StringBuilder} which can be acquired by invoking #out() and whose content can be obtained by calling {@code toString()}.
    Parameters:
    l - the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null}, then no localization will be used.
 public Formatter(String fileName) throws FileNotFoundException 
    Constructs a {@code Formatter} whose output is written to the specified file. The charset of the {@code Formatter} is the default charset. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    fileName - the filename of the file that is used as the output destination for the {@code Formatter}. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the {@code Formatter} is buffered.
    Throws:
    FileNotFoundException - if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
    SecurityException - if there is a {@code SecurityManager} in place which denies permission to write to the file in {@code checkWrite(file.getPath())}.
 public Formatter(File file) throws FileNotFoundException 
    Constructs a {@code Formatter} whose output is written to the specified {@code File}. The charset of the {@code Formatter} is the default charset. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    file - the {@code File} that is used as the output destination for the {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File} exists, or else a new {@code File} will be created. The output of the {@code Formatter} is buffered.
    Throws:
    FileNotFoundException - if the {@code File} is not a normal and writable {@code File}, or if a new {@code File} cannot be created, or if any error rises when opening or creating the {@code File}.
    SecurityException - if there is a {@code SecurityManager} in place which denies permission to write to the {@code File} in {@code checkWrite(file.getPath())}.
 public Formatter(OutputStream os) 
    Constructs a {@code Formatter} whose output is written to the specified {@code OutputStream}. The charset of the {@code Formatter} is the default charset. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    os - the stream to be used as the destination of the {@code Formatter}.
 public Formatter(PrintStream ps) 
    Constructs a {@code Formatter} whose output is written to the specified {@code PrintStream}. The charset of the {@code Formatter} is the default charset. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    ps - the {@code PrintStream} used as destination of the {@code Formatter}. If {@code ps} is {@code null}, then a {@code NullPointerException} will be raised.
 public Formatter(Appendable a,
    Locale l) 
    Constructs a {@code Formatter} with the specified {@code Locale} and whose output will be written to the specified {@code Appendable}.
    Parameters:
    a - the output destination of the {@code Formatter}. If {@code a} is {@code null}, then a {@code StringBuilder} will be used.
    l - the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null}, then no localization will be used.
 public Formatter(String fileName,
    String csn) throws FileNotFoundException, UnsupportedEncodingException 
    Constructs a {@code Formatter} whose output is written to the specified file. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    fileName - the filename of the file that is used as the output destination for the {@code Formatter}. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the {@code Formatter} is buffered.
    csn - the name of the charset for the {@code Formatter}.
    Throws:
    FileNotFoundException - if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
    SecurityException - if there is a {@code SecurityManager} in place which denies permission to write to the file in {@code checkWrite(file.getPath())}.
    UnsupportedEncodingException - if the charset with the specified name is not supported.
 public Formatter(File file,
    String csn) throws FileNotFoundException, UnsupportedEncodingException 
    Constructs a {@code Formatter} with the given charset, and whose output is written to the specified {@code File}. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    file - the {@code File} that is used as the output destination for the {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File} exists, or else a new {@code File} will be created. The output of the {@code Formatter} is buffered.
    csn - the name of the charset for the {@code Formatter}.
    Throws:
    FileNotFoundException - if the {@code File} is not a normal and writable {@code File}, or if a new {@code File} cannot be created, or if any error rises when opening or creating the {@code File}.
    SecurityException - if there is a {@code SecurityManager} in place which denies permission to write to the {@code File} in {@code checkWrite(file.getPath())}.
    UnsupportedEncodingException - if the charset with the specified name is not supported.
 public Formatter(OutputStream os,
    String csn) throws UnsupportedEncodingException 
    Constructs a {@code Formatter} with the given charset, and whose output is written to the specified {@code OutputStream}. The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
    Parameters:
    os - the stream to be used as the destination of the {@code Formatter}.
    csn - the name of the charset for the {@code Formatter}.
    Throws:
    UnsupportedEncodingException - if the charset with the specified name is not supported.
 public Formatter(String fileName,
    String csn,
    Locale l) throws FileNotFoundException, UnsupportedEncodingException 
    Constructs a {@code Formatter} with the given {@code Locale} and charset, and whose output is written to the specified file.
    Parameters:
    fileName - the filename of the file that is used as the output destination for the {@code Formatter}. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the {@code Formatter} is buffered.
    csn - the name of the charset for the {@code Formatter}.
    l - the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null}, then no localization will be used.
    Throws:
    FileNotFoundException - if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
    SecurityException - if there is a {@code SecurityManager} in place which denies permission to write to the file in {@code checkWrite(file.getPath())}.
    UnsupportedEncodingException - if the charset with the specified name is not supported.
 public Formatter(File file,
    String csn,
    Locale l) throws FileNotFoundException, UnsupportedEncodingException 
    Constructs a {@code Formatter} with the given {@code Locale} and charset, and whose output is written to the specified {@code File}.
    Parameters:
    file - the {@code File} that is used as the output destination for the {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File} exists, or else a new {@code File} will be created. The output of the {@code Formatter} is buffered.
    csn - the name of the charset for the {@code Formatter}.
    l - the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null}, then no localization will be used.
    Throws:
    FileNotFoundException - if the {@code File} is not a normal and writable {@code File}, or if a new {@code File} cannot be created, or if any error rises when opening or creating the {@code File}.
    SecurityException - if there is a {@code SecurityManager} in place which denies permission to write to the {@code File} in {@code checkWrite(file.getPath())}.
    UnsupportedEncodingException - if the charset with the specified name is not supported.
 public Formatter(OutputStream os,
    String csn,
    Locale l) throws UnsupportedEncodingException 
    Constructs a {@code Formatter} with the given {@code Locale} and charset, and whose output is written to the specified {@code OutputStream}.
    Parameters:
    os - the stream to be used as the destination of the {@code Formatter}.
    csn - the name of the charset for the {@code Formatter}.
    l - the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null}, then no localization will be used.
    Throws:
    UnsupportedEncodingException - if the charset with the specified name is not supported.
Method from java.util.Formatter Summary:
close,   flush,   format,   format,   ioException,   locale,   out,   toString
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.util.Formatter Detail:
 public  void close() 
    Closes the {@code Formatter}. If the output destination is Closeable , then the method {@code close()} will be called on that destination. If the {@code Formatter} has been closed, then calling the this method will have no effect. Any method but the #ioException() that is called after the {@code Formatter} has been closed will raise a {@code FormatterClosedException}.
 public  void flush() 
    Flushes the {@code Formatter}. If the output destination is Flushable , then the method {@code flush()} will be called on that destination.
 public Formatter format(String format,
    Object args) 
    Writes a formatted string to the output destination of the {@code Formatter}.
 public Formatter format(Locale l,
    String format,
    Object args) 
    Writes a formatted string to the output destination of the {@code Formatter}.
 public IOException ioException() 
    Returns the last {@code IOException} thrown by the {@code Formatter}'s output destination. If the {@code append()} method of the destination does not throw {@code IOException}s, the {@code ioException()} method will always return {@code null}.
 public Locale locale() 
    Returns the {@code Locale} of the {@code Formatter}.
 public Appendable out() 
    Returns the output destination of the {@code Formatter}.
 public String toString() 
    Returns the content by calling the {@code toString()} method of the output destination.