Creates a custom-formatted number value. If no mask is specified, returns the value as an integer with a thousands separator. NumberFormat
supports the numeric formatting used in the U.S. For international number formatting, see LSNumberFormat.
Display and formatting functions
NumberFormat(number [, mask ])
DecimalFormat,
DollarFormat,
IsNumeric,
LSNumberFormat
Parameter |
Description |
---|---|
number |
The number to format. |
mask |
Set of characters that show how ColdFusion should display the number |
The following table displays the mask character and its meaning
Note If you do not specify a sign for the mask, positive and negative numbers do not align in columns. If you expect to display positive and negative numbers in your application, use the space or - (minus sign) to force a space in front of positive numbers and a minus sign in front of negative numbers. |
The position of codes in format masks determines where those codes will have effect. For example, if you place a dollar sign character at the far left of a format mask, ColdFusion displays a dollar sign at the very left edge of the formatted number. If you separate the dollar sign on the left edge of the format mask by at least one underscore, ColdFusion displays the dollar sign just to the left of the digits in the formatted number.
In the examples below, the numbers under the masks and the formatted output are used to clearly show the positions of characters.
Number |
Mask |
Result |
---|---|---|
4.37 |
$____.__ |
"$ 4.37" |
4.37 |
_$___.__ |
" $4.37" |
12345678 |
12345678 |
This positioning idea can also be used to show where to place the - (minus sign) for negative numbers:
Number |
Mask |
Result |
---|---|---|
-4.37 |
-____.__ |
"- 4.37" |
-4.37 |
_-___.__ |
" -4.37" |
12345678 |
12345678 |
There are four positions for a code character: far left, near left, near right, and far right. The left and right positions are determined by the side of the decimal point the code character is shown on. For formats that do not have a fixed number of decimal places, you can use a ^ (caret) to separate the left fields from the right.
Whether the code is placed in the far or near position is determined by the use of _ (underscore). Most code characters have their effect determined by the field they are located in. The following example shows how to use the field to determine exactly where to place parentheses to display negative numbers:
Number |
Mask |
Result |
---|---|---|
3.21 |
C(__^__) |
"( 3.21 )" |
3.21 |
C__(^__) |
" (3.21 )" |
3.21 |
C(__^)__ |
"( 3.21) " |
3.21 |
C__(^)__ |
" (3.21) " |
12345678 |
12345678 |
When converting string to double, this function adds a rounding factor of 1.5543122344752E-014 to the converted number to prevent rounding errors. For example, without adding the rounding factor, converting the string value 1.275 to double with two digits of precision results in a value of 1.27499999999999999 which would be rounded up to 1.27. By adding the rounding factor, the conversion correctly results in a value of 1.28.
The only problem is when you round off a double such as 1.99499999999999999999999999999 where the last decimal is 10E-14. In this case, the rounding factor can cause an incorrect result.
<!--- This example shows the use of NumberFormat ---> <html> <head> <title> NumberFormat Example </title> </head> <body bgcolor = silver> <H3>NumberFormat Example</H3> <CFLOOP FROM = 1000 TO = 1020 INDEX = "counter"> <cfset CounterRoot2 = Evaluate(counter * sqr(2))> <!--- Show the result in default format, adding the comma for the thousands place, and also in custom format, displaying to two decimal places ---> <cfoutput> <PRE>#counter# * Square Root of 2: #NumberFormat(CounterRoot2, '_____.__')#</PRE> <PRE>#counter# * Square Root of 2: #NumberFormat(CounterRoot2)#</PRE> </cfoutput> </CFLOOP> </body> </html>