 Operator Type:

Operator Scope of Action:

Operator Purpose:

Operator Altered:

Function   [other Function type actions]

Item   [operators of similar scope]

Formatting   [other Formatting operators]

Baseline

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)<;/code> 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'. ```
``` Up: Full Operator List Previous: notify(headline[, details, deliveryTime ])  Next: Number.precision(N)  A Tinderbox Reference File : Actions & Rules : Operators : Full Operator List : Number.format(decimalsN[,widthN][,padStr]) ```
``` Quicklinks: Attributes | Action Codes | Export Codes | Designators | Date Formats | aTbRef Site Map | Here [Last exported: 10 Sep 2020, using v8.7.2] Search within aTbRef8 website: Using DuckDuckGo (Cmd+click for results in new window/tab): Using Google (uses pop-up results window) // cx var requires updating for each new baseline site. (function() { var cx = '000400443220506600232:6xzpipvlgws'; var gcse = document.createElement('script'); gcse.type = 'text/javascript'; gcse.async = true; gcse.src = 'https://cse.google.com/cse.js?cx=' + cx; var s = document.getElementsByTagName('script'); s.parentNode.insertBefore(gcse, s); })(); A Tinderbox Reference File ('aTbRef') by Mark Anderson is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. Based on a work at atbref.com/. [Also see aTbRef CC licence Attribution & Waiver information] Made in Tinderbox 8. Content, Tinderbox export and web template design all by Mark Anderson, (Shoantel Limited). (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o);a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-4131952-2', 'auto'); ga('send', 'pageview'); function googleTranslateElementInit() { new google.translate.TranslateElement({ pageLanguage: 'en', layout: google.translate.TranslateElement.InlineLayout.SIMPLE }, 'google_translate_element'); } ```