ColdFusion 9.0 Resources |
NumberFormatDescriptionCreates a custom-formatted number value. Supports the numeric formatting used in the U.S. For international number formatting, see LSNumberFormat. ReturnsA formatted number value:
HistoryColdFusion MX: Changed behavior: if the mask format cannot correctly mask a number, this function returns the number unchanged. (It does not truncate the number nor throw an error.) (If no mask is selected, ColdFusion MX rounds the decimal part as ColdFusion 5 does. For example, it rounds 34.567 to 35.) Parameters
The following table explains mask characters:
Note: If you do not specify
a sign for the mask, positive and negative numbers do not align
in columns. To put a plus sign or space before positive numbers
and a minus sign before negative numbers, use the plus or minus
sign, respectively.
UsageThis function uses Java standard locale formatting rules on all platforms. The position of symbols in format masks determines where the codes take effect. For example, if you put a dollar sign at the far left of a format mask, ColdFusion displays a dollar sign at the 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. These examples show how symbols determine formats:
The positioning can also show where to place the minus sign for negative numbers:
The positions for a symbol are: far left, near left, near right, and far right. The left and right positions are determined by the side of the decimal point on which the code character is shown. 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. An underscore determines whether the code is placed in the far or near position. Most code characters’ effect is determined by the field in which they are located. This example shows how to specify where to put parentheses to display negative numbers:
When converting from string to double, to prevent rounding errors, this function adds a rounding factor of 1.5543122344752E-014 to the converted number. 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. If you round off a double such as 1.99499999999999999999999999999, where the last decimal is 10E-14, the rounding factor can cause an incorrect result. To set the default display format of date, time, number, and currency values, use the SetLocale function. Example<h3>NumberFormat Example</h3> <cfloop FROM = 1000 TO = 1020 INDEX = "counter"> <cfset CounterRoot2 = counter * sqr(2)> <!--- Show result in default format, adding comma for thousands place; and 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> |