Operator Type:
Operator Scope of Action:
Operator Purpose:
Operator First Added:
Operator Altered:
Function [other Function type actions]
Item [operators of similar scope]
Formatting [other Formatting operators]
5.8.0
5.10.3
Number.format(decimalsN[,widthN])
Returns Number as a string, formatted to decimalsN decimal places.
If widthN is supplied, Number returned additionally left padded with spaces so that widthN equals the sum of: [padding spaces]+[minus sign]+integer number(s)+decimal point+[decimal numbers]. Note that with widthN, decimal character is not counted as part of the number. The presence of a minus sign is
For example, if $MyNum is 3.1415927, then
$MyNum.format(2) is 3.14
$MyNum.format(0) is 3
$MyNum.format(2,7) is " 3.14" (3 left padding spaces + 1 integer number + decimal point + 3 decimal numbers = 7)
But if $MyNum is negative, e.g. -3.1415927, then
$MyNum.format(2,7) is " -3.14" (2 left padding spaces + minus sign + 1 integer number + decimal point + 3 decimal numbers = 7)
Literal numbers, e.g. 3.1415927, can also be worked with:
5.1415927.format(2) is 5.14
The above works but the following syntax may seem less ambiguous by using parentheses to delimit the literal number:
(5.1415927).format(2) is 5.14
(5.1415927).format(1,5) is ' 5.1' (two left padding spaces + 1 integer number + decimal point + 1 decimal number = 5)
If a group of numbers are being formatted so as to vertically decimal-point align as a column figures, e.g. financial data, it is necessary to know the widthN of 'longest' number to be used, remembering that a negative number adds one to its width count; 45 is width 2, -45 is width 3. In the example below the longest (widthN) number in a set of currency figures has been worked out stored in a user Number attribute $MaxNumLen. Being currency, 2 decimal places will be enforced, and each number can be evaluated by a common formatting:
[the number].format(2,$MaxLenNum)
If the widthN for a set of numbers can't easily be assessed, an alternate option is simply to use a number known to be bigger than all likely width valid. Thus every number, including the longest gets left-padded - but all end up correctly aligned. In the latter example if all numbers are always likely to be less than 20, then $MaxLenNum could be set to 20, or simply used directly:
[the number].format(2,$MaxLenNum)
There is no easy way in v5 to sort a list of numbers on size (i.e. their widthN), other than by looping the list via List.each() transforming each to a string (using zero decimal places!), saving the String.size of each of these as a number in a new list, then List.nsort() and take the last item, .at(-1). As .nsort() sorts on ascending numerical order, the latter will be the size of the longest string (including negative numbers) in the original list. Assuming $MySizeList has all the size strings:
$MaxLenNum = ($MySizeList.nsort).at(-1)
Why leave out decimal places when coercing the numbers to strings? 1234.56 is a bigger number than 12.34567, but the latter is the bigger size. However, 1234 is both a bagger and 'wider' than 12.
As can be seen, just setting a large arbitrary widthN might save a lot of messing about!
Number.format("formatString")
New to v5.10.3, an alternate usage is to supply a quoted formatString. Currently only one such string is supported: "L". This will return a string of the number formatted with (OS) locale-dependent group & decimal delimiters. For example, for the US locale these are a comma and a period; in other locales they may vary.
This function supplements the existing format() and Number.precision() functions.