StringFormat

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.

==== Flags ====

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

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