This version is out of date, covering development from v9.5.0 to v9.7.3. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

Number.format(decimalsNum[, widthNum, padStr]|formatStr)

Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

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:

[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 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"

Number.format("formatString")

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:

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

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

$MyString = $MyNumber.format("X") 

gives a $MyString value of "III".

Ordinals. From v9.5.0, formatString "o" (lowercase letter 'O') converts Number to a string of localised ordinal value. For example, if $MyNumber is 3:

$MyString = $MyNumber.format("o") 

gives a $MyString value of "3rd" in English but "3e" in French, etc.