Function: format()

Formats a string according to a template format and supplied arguments.

Syntax

format(formatString, arg1, ..., argN)

Examples

format("%10.3f", in.callTotal)

gives the output: "     2.718"

format("Value to 3 decimal places is: %1$10.3f, or rounded to a whole number and padded with zeroes is: %1$010.0f", in.callTotal)

The formatString can also contain plain text string elements as in this case which returns, with in.callTotal = 25.33256:

"Value to 3 decimal places is:     25.333, or rounded to a whole number and padded with zeroes is: 0000000025"

Format String Syntax

The following basic format specifiers are available:

• %s - string
• %t - date/time
• %f - floating point number
• (see below for more details and other types available)

Although it is possible to use dates in the format function, it is strongly recommended that you use the toString function instead.

More generally, format specifiers have the syntax:

• %[argument_index$][flags][width][.precision][data type]

Each component of this format specifier is described below:

argument_index

This optional value specifies which of the supplied arguments provided to replace into the format string. This is useful when the same data is used several times, in a single format string - possibly, formatted differently in each case.

format("Value to 3 decimal places is: %1$10.3f, or rounded to a whole number and padded with zeroes is: %1$010.0f", in.callTotal)
with in.callTotal = 25.33256, returns "Value to 3 decimal places is:     25.333, or rounded to a whole number and padded with zeroes is: 0000000025"

flags

For all data types:

• '-' - left justify

For numeric types:

• '+' - always include a sign
• ' ' - include a leading space for positive values
• '0' - pad with zeroes
• ',' - use local specified grouping operators, e.g. a comma rather than a point for a decimal separator in France
• '(' - put negative numbers in brackets, .e.g. for ledger reports

width & precision

The width is an optional parameter which specifies the minimum number of characters written to the output.
The precision is an optional parameter which specifies the maximum number of characters written to the output.
For data types 'e', 'E', and 'f' the precision is the number of digits after the decimal separator. For data types 'g' or 'G' the precision is the total number of digits in the resulting magnitude after rounding.
format("%10.3f", in.callTotal)
gives the output: "     2.718"

Data type

• 's' - string
• 'd' - integer
• 'e' - floating point number; the output is formatted as a decimal number in computerized scientific notation
• 'f' - floating point number
• 'g' - floating point number; the output is formatted using computerized scientific notation or decimal format, depending on the precision and the value after rounding
• 't' - date/time
• '%' - percent; gives a literal '%' sign in the output

Additional Examples:

• format("%.2f",_out.example), where _out.example = 12345678.468

The above example will output "12345678.47" as a string. This is useful as toString(12345678.468) will output 1.2345678468E7, i.e. scientific form. the "f" character in the function input: format("%.2f",_out.example) converts the number to string in non-scientific notation.

• do(
      $dps = 2,
      $variable = "%." + toString($dps) + "f",
      format($variable,_out.example )
  )
  
  The above example demonstrates putting a dollar variable into the first input to the format function. This allows the output to be more flexible, i.e. in this example the $dps can hold the number of decimal places.

See Also

• Functions