5.1.7.67. format

Returns a copy of the receiving string, a number, rounded and formatted.

The number is first rounded according to standard Rexx rules, as though the operation receiving_string+0 had been carried out. If you specify no arguments the result of the method is the same as the result of this operation. If you specify any options, the number is formatted as described in the following.

The before and after options describe how many characters are to be used for the integer and decimal parts of the result. If you omit either or both of them, the number of characters 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 5.104. String class — format method

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

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 an exponential expression. 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, exponential notation is used. If expt is 0, 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 5.105. String class — format method

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