FORMAT

Synopsis

HELP:   Defines a format string to convert numbers
TYPE:   STRING
SYNTAX: FORMAT='str'

Description

Provides formatting of strings containing decimal numbers to another string matching the specified format string. When converting a floating point number, conversion depends on the locale. For the conversion to be successful, the in-memory representation must be in the local character set. Use CCSID=DEFAULT to ensure this. If no character conversion is requested, the local character set will be assumed. Other kinds of character conversions mainly result in an error or strange data. The resulting formatted string is truncated if the output buffer is too small.

The format string specifies the format of the number in the output string. Numbers may be decimal integers or real numbers, signed or unsigned.

The conversion ignores leading whitespace and parses the number up to the first character not part of the number. If this is not the last character, an error will occur unless the 'IGNREST' switch is set (may be used e.g. to ignore currency signs).

Input number format

The input numbers must match one of the following regular expressions in order to be processed successfully. Internally, the numbers are converted to a 64 bit integer or floating point value.

Floating point (f,g,G,e,E):
   [:space:]*[+|-][:digit:]+.[:digit:]+e|E[:digit:]+
   [:space:]*[+|-][:digit:]+,[:digit:]+e|E[:digit:]+
Integer (i,d,u,x,X):
   [:space:]*[+|-][:digit:]+

Format string

A format string must start with the % character, otherwise the format string is ignored. The percent character is followed by optional flags, an optional width, an optional precision and a format specifier. Precision and width are separated by a period:

Format string:
   %[flags][width][.precision]specifier
As regular expression:
   %[-|+| |0][:digit:]*[.[:digit:]+]u|d|i|x|X|e|E|F|g|G

Specifier

The specifier is the type of the output number and tells the string converter how to parse the input. A real number is parsed and stored in a 64 bit floating point value. An integer is stored in a 64 bit integer value.

• u Unsigned decimal integer
• d or i Signed decimal integer
• x Unsigned hexadecimal integer
• X Unsigned hexadecimal integer (capital letters)
• e Scientific notation (mantissa/exponent) using e character
• E Scientific notation (mantissa/exponent) using E character
• f Decimal floating point
• g Uses the shorter of %e or %f.
• G Uses the shorter of %E or %f

Flags

• - Left-justify within the given field width; Right justification is the default (see width sub-specifier).
• + Forces to precede the result with a plus or minus sign (+ or -) even for positive numbers (not valid for unsigned). By default, only negative numbers are preceded with a '-' sign.
• SPACE If no sign is going to be written, a blank space is inserted before the value.
• 0 Left-pads the number with zeros (0) instead of whitespace, where padding is specified (see width sub-specifier).

Width

Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with whitespace. The value is not truncated even if the result is larger.

Precision

For integer specifiers (d, i, u, x), precision specifies the minimum number of digits to be written. If the value to be written is shorter than this number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is written for the value 0. For e, E and f specifiers, this is the number of digits to be printed after the decimal point. For g and G specifiers, this is the maximum number of significant digits to be printed. When no precision is specified, the default is 1. If the period is specified without an explicit value for precision, 0 is assumed.