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

Jump to the current version of aTbRef

TinderboxSix Icon


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]




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!


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.

A Tinderbox Reference File : Actions & Rules : Operators : Full Operator List : Number.format(decimalsN[,widthN])