Number.format(decimalsN[,widthN][,padStr])

---

---

Number.format(decimalsN[,widthN][,padstr])

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 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 (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 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:

[the number].format(2,$MaxLenNum) 

There is no easy way 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:

$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 widthN might save a lot of messing about!

If the optional padStr is given, this specifies the character used for padding. 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"

Number.format("formatString")

An alternate usage is to supply a quoted formatString. Currently only one such string is supported: "l" (lowercase letter '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. 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

Building on the above there are two format strings that can be used, again locale-based, to turn a Number into number string with a currency symbol prefix. Format string "$" formats the number to the local currency to two decimal points. Thus if $MyNumber is 1246.878:

$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.

If such a currency string is needed rounded to the neared whole major unit, e.g. dollars and not cents, use format string "$0":

$MyString=$MyNumber.format("$0"); 

which sets $MyString to "$1,247" isn the US, "£1,247" in UK, "€1,247" in France, etc.