Java: Format String Syntax

Every method which produces formatted output requires a format string and an argument list. The format string is a String which may contain fixed text and one or more embedded format specifiers. Consider the following example:

   Calendar c = ...;
   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
 

This format string is the first argument to the format method. It contains three format specifiers "%1$tm", "%1$te", and "%1$tY" which indicate how the arguments should be processed and where they should be inserted in the text. The remaining portions of the format string are fixed text including "Dukes Birthday: " and any other spaces or punctuation. The argument list consists of all arguments passed to the method after the format string. In the above example, the argument list is of size one and consists of the Calendar object c.

• The format specifiers for general, character, and numeric types have the following syntax:

     %[argument_index$][flags][width][.precision]conversion
   

  The optional argument_index is a decimal integer indicating the position of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc.

  The optional flags is a set of characters that modify the output format. The set of valid flags depends on the conversion.

  The optional width is a positive decimal integer indicating the minimum number of characters to be written to the output.

  The optional precision is a non-negative decimal integer usually used to restrict the number of characters. The specific behavior depends on the conversion.

  The required conversion is a character indicating how the argument should be formatted. The set of valid conversions for a given argument depends on the argument's data type.

• The format specifiers for types which are used to represents dates and times have the following syntax:

     %[argument_index$][flags][width]conversion
   

  The optional argument_index, flags and width are defined as above.

  The required conversion is a two character sequence. The first character is 't' or 'T'. The second character indicates the format to be used. These characters are similar to but not completely identical to those defined by GNU date and POSIX strftime(3c).

• The format specifiers which do not correspond to arguments have the following syntax:

     %[flags][width]conversion
   

  The optional flags and width is defined as above.

  The required conversion is a character indicating content to be inserted in the output.