Applies 'printf' style formatting.

The template string may contain fixed text and one or more embedded format specifiers. Consider the following example:

val n   = "name".attr[String]("?")
val tmp = "Duke's name: %1$s!"
PrintLn(tmp.format(n))

The template contains one format specifier "%1$s" which indicates how the argument should be processed and where it should be inserted in the text. The remaining portions of the template string are fixed text including "Duke's name: " and "!".

The argument list consists of all arguments passed to the formatter. In the above example, the argument list is of size one and consists of the string expression object n.

• 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 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.

Conversions

Conversions are divided into the following categories:

• General - may be applied to any argument type
• Numeric
• Integral - may be applied to integral types such as: Int and Long.
• Floating Point - may be applied to the floating-point type Double.
• Percent - produces a literal '%'
• Line Separator - produces the platform-specific line separator

The following table summarizes the supported conversions. Conversions denoted by an upper-case character (i.e. 'B', 'H', 'S', 'C', 'X', 'E', 'G', 'A', and 'T') are the same as those for the corresponding lower-case conversion characters except that the result is converted to upper case.

Conversion	Argument Category	Description
`'b'`, `'B'`	general	If arg is a `Boolean`, then the result is `"true"` or `"false"`. Otherwise, the result is "true".
`'s'`, `'S'`	general	The result is the string representation of the argument.
`'d'`	integral	The result is formatted as a decimal integer
`'o'`	integral	The result is formatted as an octal integer
`'x'`, `'X'`	integral	The result is formatted as a hexadecimal integer
`'e'`, `'E'`	floating point	The result is formatted as a decimal number in computerized scientific notation
`'f'`	floating point	The result is formatted as a decimal number
`'g'`, `'G'`	floating point	The result is formatted using computerized scientific notation or decimal format, depending on the precision and the value after rounding.
`'a'`, `'A'`	floating point	The result is formatted as a hexadecimal floating-point number with a significand and an exponent.
`'%'`	percent	The result is a literal `'%'` ('\u0025')
`'n'`	line separator	The result is the platform-specific line separator

==== Flags ==== The following table summarizes the supported flags. y means the flag is supported for the indicated argument types.

Flag	General	Character	Integral	Floating Point	Date/Time	Description
'-'	y	y	y	y	y	The result will be left-justified.
'#'	y1	-	y3	y	-	The result should use a conversion-dependent alternate form
'+'	-	-	y4	y	-	The result will always include a sign
'  '	-	-	y4	y	-	The result will include a leading space for positive values
'0'	-	-	y	y	-	The result will be zero-padded
','	-	-	y2	y5	-	The result will include locale-specific grouping separators
'('	-	-	y4	y5	-	The result will enclose negative numbers in parentheses

¹ Depends on the definition of `Formattable`. ² For `'d'` conversion only. ³ For `'o'`, `'x'`, and `'X'` conversions only. ⁴ For `'d'`, `'o'`, `'x'`, and `'X'` conversions applied to `BigInteger` or `'d'` applied to `Int`, and `Long`. ⁵ For `'e'`, `'E'`, `'f'`, `'g'`, and `'G'` conversions only. ==== Width ==== The width is the minimum number of characters to be written to the output. For the line separator conversion, width is not applicable; if it is provided, an exception will be thrown. ==== Precision ==== For general argument types, the precision is the maximum number of characters to be written to the output. For the floating-point conversions `'a'`, `'A'`, `'e'`, `'E'`, and `'f'` the precision is the number of digits after the radix point. If the conversion is `'g'` or `'G'`, then the precision is the total number of digits in the resulting magnitude after rounding. For character, integral, and date/time argument types and the percent and line separator conversions, the precision is not applicable; if a precision is provided, an exception will be thrown. ==== Argument Index ==== The 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. Another way to reference arguments by position is to use the `'<'` ('\u003c') flag, which causes the argument for the previous format specifier to be re-used.