Applies 'printf' style formatting.
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
andLong
. -
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 |
1 Depends on the definition of Formattable
.
2 For 'd'
conversion only.
3 For 'o'
, 'x'
, and 'X'
conversions only.
4 For 'd'
, 'o'
, 'x'
, and
'X'
conversions applied to BigInteger
or 'd'
applied to Int
, and Long
.
5 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.
- Value Params
- args
the arguments to apply to the template
- in
the template
- Companion
- object