See Also: Formatter Members
Formats arguments according to a format string (like printf in C).
It's relatively rare to use a Formatter directly. A variety of classes offer convenience methods for accessing formatter functionality. Of these, Java.Lang.String.format(java.lang.String, java.lang.Object...) is generally the most useful. Java.IO.PrintStream and Java.IO.PrintWriter both offer format and printf methods.
Format strings consist of plain text interspersed with format specifiers, such as "name: %s weight: %03dkg\n". Being a Java string, the usual Java string literal backslash escapes are of course available.
Format specifiers (such as "%s" or "%03d" in the example) start with a % and describe how to format their corresponding argument. It includes an optional argument index, optional flags, an optional width, an optional precision, and a mandatory conversion type. In the example, "%s" has no flags, no width, and no precision, while "%03d" has the flag 0, the width 3, and no precision.
Not all combinations of argument index, flags, width, precision, and conversion type are valid.
Argument index. Normally, each format specifier consumes the next argument to format. For convenient localization, it's possible to reorder arguments so that they appear in a different order in the output than the order in which they were supplied. For example, "%4$s" formats the fourth argument (4$) as a string (s). It's also possible to reuse an argument with . For example, format("%o %<d %<x", 64) results in "100 64 40".
Flags. The available flags are:
| Flags | |||
| , | Use grouping separators for large numbers. (Decimal only.) | format("%,d", 1024); | 1,234 |
| + | Always show sign. (Decimal only.) | format("%+d, %+4d", 5, 5); | java Example +5, +5 |
| A space indicates that non-negative numbers should have a leading space. (Decimal only.) | format("x% d% 5d", 4, 4); | java Example x 4 4 | |
| ( | Put parentheses around negative numbers. (Decimal only.) | format("%(d, %(d, %(6d", 12, -12, -12); | java Example 12, (12), (12) |
| - | Left-justify. (Requires width.) | format("%-6dx", 5); format("%-3C, %3C", 'd', 0x65); | java Example 5 x java Example D , E |
| 0 | Pad the number with leading zeros. (Requires width.) | format("%07d, %03d", 4, 5555); | 0000004, 5555 |
| # | Alternate form. (Octal and hex only.) | format("%o %#o", 010, 010); format("%x %#x", 0x12, 0x12); | 10 010 12 0x12 |
Width. The width is a decimal integer specifying the minimum number of characters to be used to represent the argument. If the result would otherwise be shorter than the width, padding will be added (the exact details of which depend on the flags). Note that you can't use width to truncate a field, only to make it wider: see precision for control over the maximum width.
Precision. The precision is a . followed by a decimal integer, giving the minimum number of digits for d, o, x, or X; the minimum number of digits after the decimal point for a, A, e, E, f, or F; the maximum number of significant digits for g or G; or the maximum number of characters for s or S.
Conversion type. One or two characters describing how to interpret the argument. Most conversions are a single character, but date/time conversions all start with t and have a single extra character describing the desired output.
Many conversion types have a corresponding uppercase variant that converts its result to uppercase using the rules of the relevant locale (either the default or the locale set for this formatter).
This table shows the available single-character (non-date/time) conversion types:
| String conversions All types are acceptable arguments. Values of type Java.Util.IFormattable have their formatTo method invoked; all other types use toString. | |||
| s | String. | format("%s %s", "hello", "Hello"); | hello Hello |
| S | Uppercase string. | format("%S %S", "hello", "Hello"); | HELLO HELLO |
| Character conversions Byte, Character, Short, and Integer (and primitives that box to those types) are all acceptable as character arguments. Any other type is an error. | |||
| c | Character. | format("%c %c", 'd', 'E'); | d E |
| C | Uppercase character. | format("%C %C", 'd', 'E'); | D E |
| Integer conversions Byte, Short, Integer, Long, and BigInteger (and primitives that box to those types) are all acceptable as integer arguments. Any other type is an error. | |||
| d | Decimal. | format("%d", 26); | 26 |
| o | Octal. | format("%o", 032); | 32 |
| x, X | Hexadecimal. | format("%x %X", 0x1a, 0x1a); | 1a 1A |
| Floating-point conversions Float, Double, and BigDecimal (and primitives that box to those types) are all acceptable as floating-point arguments. Any other type is an error. | |||
| f | Decimal floating point. | java Example
format("%f", 123.456f);
format("%.1f", 123.456f);
format("%1.5f", 123.456f);
format("%10f", 123.456f);
format("%6.0f", 123.456f); | java Example 123.456001 123.5 123.45600 123.456001 123 |
| e, E | Engineering/exponential floating point. | java Example
format("%e", 123.456f);
format("%.1e", 123.456f);
format("%1.5E", 123.456f);
format("%10E", 123.456f);
format("%6.0E", 123.456f); | java Example 1.234560e+02 1.2e+02 1.23456E+02 1.234560E+02 1E+02 |
| g, G | Decimal or engineering, depending on the magnitude of the value. | format("%g %g", 0.123, 0.0000123); | 0.123000 1.23000e-05 |
| a, A | Hexadecimal floating point. | format("%a", 123.456f); | 0x1.edd2f2p6 |
| Boolean conversion Accepts Boolean values. null is considered false, and instances of all other types are considered true. | |||
| b, B | Boolean. | format("%b %b", true, false); format("%B %B", true, false); format("%b", null); format("%b", "hello"); | true false TRUE FALSE false true |
| Hash code conversion Invokes hashCode on its argument, which may be of any type. | |||
| h, H | Hexadecimal hash code. | format("%h", this); format("%H", this); format("%h", null); | 190d11 190D11 null |
| Zero-argument conversions | |||
| % | A literal % character. | format("%d%%", 50); | 50% |
| n | Newline. (The value of Java.Lang.JavaSystem.LineSeparator.) | format("first%nsecond"); | first\nsecond |
It's also possible to format dates and times with Formatter, though you should use Java.Text.SimpleDateFormat (probably via the factory methods in Java.Text.DateFormat) instead. The facilities offered by Formatter are low-level and place the burden of localization on the developer. Using Java.Text.DateFormat.DateInstance, Java.Text.DateFormat.TimeInstance, and Java.Text.DateFormat.DateTimeInstance is preferable for dates and times that will be presented to a human. Those methods will select the best format strings for the user's locale.
The best non-localized form is , which you can get with "%tF" (2010-01-22), "%tF %tR" (2010-01-22 13:39), "%tF %tT" (2010-01-22 13:39:15), or "%tF %tT%z" (2010-01-22 13:39:15-0800).
This table shows the date/time conversions, but you should use Java.Text.SimpleDateFormat instead:
| Date/time conversions Calendar, Date, and Long (representing milliseconds past the epoch) are all acceptable as date/time arguments. Any other type is an error. The epoch is 1970-01-01 00:00:00 UTC. Use Java.Text.SimpleDateFormat instead. | |||
| ta | Localized weekday name (abbreviated). | format("%ta", cal, cal); | Tue |
| tA | Localized weekday name (full). | format("%tA", cal, cal); | Tuesday |
| tb | Localized month name (abbreviated). | format("%tb", cal); | Apr |
| tB | Localized month name (full). | format("%tB", cal); | April |
| tc | C library asctime(3)-like output. Do not use. | format("%tc", cal); | Tue Apr 01 16:19:17 CEST 2008 |
| tC | 2-digit century. | format("%tC", cal); | 20 |
| td | 2-digit day of month (01-31). | format("%td", cal); | 01 |
| tD | Ambiguous US date format (MM/DD/YY). Do not use. | format("%tD", cal); | 04/01/08 |
| te | Day of month (1-31). | format("%te", cal); | 1 |
| tF | Full date in ISO 8601 format (YYYY-MM-DD). | format("%tF", cal); | 2008-04-01 |
| th | Synonym for %tb. | ||
| tH | 2-digit 24-hour hour of day (00-23). | format("%tH", cal); | 16 |
| tI | 2-digit 12-hour hour of day (01-12). | format("%tI", cal); | 04 |
| tj | 3-digit day of year (001-366). | format("%tj", cal); | 092 |
| tk | 24-hour hour of day (0-23). | format("%tk", cal); | 16 |
| tl | 12-hour hour of day (1-12). | format("%tl", cal); | 4 |
| tL | Milliseconds. | format("%tL", cal); | 359 |
| tm | 2-digit month of year (01-12). | format("%tm", cal); | 04 |
| tM | 2-digit minute. | format("%tM", cal); | 08 |
| tN | Nanoseconds. | format("%tN", cal); | 359000000 |
| tp | a.m. or p.m. | format("%tp %Tp", cal, cal); | pm PM |
| tQ | Milliseconds since the epoch. | format("%tQ", cal); | 1207059412656 |
| tr | Full 12-hour time (%tI:%tM:%tS %Tp). | format("%tr", cal); | 04:15:32 PM |
| tR | Short 24-hour time (%tH:%tM). | format("%tR", cal); | 16:15 |
| ts | Seconds since the epoch. | format("%ts", cal); | 1207059412 |
| tS | 2-digit seconds (00-60). | format("%tS", cal); | 17 |
| tT | Full 24-hour time (%tH:%tM:%tS). | format("%tT", cal); | 16:15:32 |
| ty | 2-digit year (00-99). | format("%ty", cal); | 08 |
| tY | 4-digit year. | format("%tY", cal); | 2008 |
| tz | Time zone GMT offset. | format("%tz", cal); | +0100 |
| tZ | Localized time zone abbreviation. | format("%tZ", cal); | CEST |
As with the other conversions, date/time conversion has an uppercase format. Replacing %t with %T will uppercase the field according to the rules of the formatter's locale.
Number localization. Some conversions use localized decimal digits rather than the usual ASCII digits. So formatting 123 with %d will give 123 in English locales but ١٢٣ in appropriate Arabic locales, for example. This number localization occurs for the decimal integer conversion %d, the floating point conversions %e, %f, and %g, and all date/time %t or %T conversions, but no other conversions.
Thread safety. Formatter is not thread-safe.