7.4.33. FORMAT

Returns number, rounded and formatted.

The number is first rounded according to standard Rexx rules, as though the operation number+0 had been carried out. The result is precisely that of this operation if you specify only number. If you specify any other options, the number is formatted as described in the following.

The before and after options describe how many characters are used for the integer and decimal parts of the result, respectively. If you omit either or both of them, the number of characters used for that part is as needed.

If before is not large enough to contain the integer part of the number (plus the sign for a negative number), an error results. If before is larger than needed for that part, the number is padded on the left with blanks. If after is not the same size as the decimal part of the number, the number is rounded (or extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer.

Example 7.45. Builtin function FORMAT

FORMAT("3",4)            -->    "   3"
FORMAT("1.73",4,0)       -->    "   2"
FORMAT("1.73",4,3)       -->    "   1.730"
FORMAT("-.76",4,1)       -->    "  -0.8"
FORMAT("3.03",4)         -->    "   3.03"
FORMAT(" - 12.73", ,4)   -->    "-12.7300"
FORMAT(" - 12.73")       -->    "-12.73"
FORMAT("0.000")          -->    "0"

The first three arguments are as described previously. In addition, expp and expt control the exponent part of the result, which, by default, is formatted according to the current NUMERIC settings of DIGITS and FORM. expp sets the number of places for the exponent part; the default is to use as many as needed (which can be zero). expt specifies when the exponential expression is used. The default is the current setting of NUMERIC DIGITS.

If expp is 0, the number is not in exponential notation. If expp is not large enough to contain the exponent, an error results.

If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, the exponential notation is used. If expt is 0, the exponential notation is always used unless the exponent would be 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent would be 0 when a nonzero expp is specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent would be 0 and expp is not specified, the number is not an exponential expression.

Example 7.46. Builtin function FORMAT

FORMAT("12345.73", , ,2,2)  -->    "1.234573E+04"
FORMAT("12345.73", ,3, ,0)  -->    "1.235E+4"
FORMAT("1.234573", ,3, ,0)  -->    "1.235"
FORMAT("12345.73", , ,3,6)  -->    "12345.73"
FORMAT("1234567e5", ,3,0)   -->    "123456700000.000"