Operator Scope of Action:
Operator First Added:
Operator Last Altered:
Operator Has Optional Arguments:
Number.format(decimalsNum[, widthNum, padStr]|formatStr)
Number.format(decimalsNum, widthNum, padStr)
Returns Number as a String, formatted to decimalsN decimal places.
If widthNum is supplied, Number returned additionally left padded with spaces so that widthNum equals the sum of: [padding spaces]+[minus sign]+integer number(s)+decimal point+[decimal numbers]. Note that with widthNum, decimal character is not counted as part of the number. The presence of a minus sign is allowed for.
This function supplements the existing format() and Number.precision() functions.
For example, if $MyNumber is 3.1415927, then
$MyString = $MyNumber.format(2); is "3.14"
$MyString = $MyNumber.format(0); is "3"
$MyString = $MyNumber.format(2,7); is " 3.14" (3 left padding spaces + 1 integer number + decimal point + 3 decimal numbers = 7)
But if $MyNumber is negative, e.g. -3.1415927, then
$MyString = $MyNumber.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:
$MyString = 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:
$MyString = (5.1415927).format(2); is "5.14"
$MyString = (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 (widthNum) 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:
If the widthN for a set of numbers cannot 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 $MaxLenNumber could be set to 20, or simply used directly:
There is no easy way to sort a list of numbers on size (i.e. their widthNum), 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:
$MaxLenNumber = ($MySizeList.nsort).at(-);
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 bigger and 'wider' than 12.
As can be seen, just setting a large arbitrary widthNum might save a lot of messing about!
If the optional padStr is given, this specifies the character used for padding: use of a widthNum argument is expected. The default is a space:
$MyString = 7.format(0,3); gives " 7"
$MyString = 7.format(0,3,"0"); gives "007"
$MyString = 7.format(0,3,"#"); gives "##7"
An alternate usage is to supply a quoted formatString argument that is always enclosed in double quotes.
Supported formatString values (described in more detail further below) are:
"l"(lowercase letter 'L') gives Number as a string in (OS) locale-dependent group & decimal delimiters.
"$"formats Number to a string in the local currency to two decimal points.
"$0"formats Number to a string in the local currency rounded to the neared whole major unit (i.e. whole dollars only not dollars.cents.)
"X"converts Number to a string in Roman numerals
"o"(lowercase letter 'O') converts Number to a string in the localised ordinal
Localised, locale-dependent, numbers. Using formatString
"l" (lowercase letter 'L') will return a string of the source 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. For example, if $MyNumber is 4562781.4, and it is desired to display it as a string with thousands delimited:
$MyString = $MyNumber.format("l"); gives "4,562,781.4"
Of course, depending on the users local, the delimiter may be something else. For instance in a German locale setting, it would be "4.562.781,4". For more on such difference see Wikipedia's article on 'Decimal Separators'.
Currency formatting. Two currency-related format strings that can be used, again locale-based, to turn a Number into number string with a currency symbol prefix. Using formatString
"$" formats the number to the local currency to two decimal points. Thus if $MyNumber is
$MyString = $MyNumber.format("$");
sets $MyString to "$1,246.88" isn the US, "£1,246.88" in UK, "€1,246.88" in France, etc. Note how the format also respects the local thousands separate, adding a comma after the initial digit.
Use format string
"$0" if the currency string is needed rounded to the neared whole major unit, e.g. whole dollars and not dollars.cents, :
$MyString = $MyNumber.format("$0");
which sets $MyString to "$1,247" isn the US, "£1,247" in UK, "€1,247" in France, etc.
Roman Numerals. From v9.5.0, formatString
"X" converts Number to a string in Roman numerals. For example, if $MyNumber is
$MyString = $MyNumber.format("X")
gives a $MyString value of "
Ordinals. From v9.5.0, formatString
"o" (lowercase letter 'O') converts Number to a string of localised ordinal value. For example, if $MyNumber is
$MyString = $MyNumber.format("o")
gives a $MyString value of "
3rd" in English but "
3e" in French, etc.