Number Formatting in Coldfusion - a look "Under the Hood"
Formatting numbers is a pain. It would be great if our little human pea brains could read a number without commas in it to group the hundreds (or periods for my European readers). Sadly, we find ourselves unable to cope without the commas, so a good deal of display code regarding numbers is written to simply output them in the correct format. Most CF programmers use numberFormat( ) or decimalFormat( ) to control the output. Decimal format seems handy because it doesn't require a mask and produces the typical format you would expect. The 2 functions are quite different however and it may cause some perplexity when you are working with large numbers. Let me explain.
Note: Examples provided by Russ "Snake" Michaels from the CFGURU list :)
The decimalFormat() Function
The decimalFormat() seems to convert the argument into an actual Java data type like double or float, then it applies a specific mask to it and returns the result. That works fine, except that there is a maximum size for decimal notation of 18 with a scale of 2 for this function. That means if you get beyond 18 characters the number object (for the function) will not contain the expected data. Instead, it will contain scientific notation. You can use the javaCast() function to demonstrate what is happening behind the scenes. Check out this example:
<cfset javaNum = Javacast("float",num)>
<cfoutput>
Java casted Number: #javanum#
</cfoutput>
Result is: 1.23456791E17
<cfset num = 123456789123456789.12>
<cfset javaNum = Javacast("float",num)>
<cfoutput>
Java casted Number: #javanum#
</cfoutput>
Result is: 1.23456789123E+017
<cfoutput>
decimal format: #decimalformat(num)#
</cfoutput>
Result is: 92,233,720,368,547,760.00
The numberFormat() Function
The numberFormat() function isn't exempt from this problem either. Internally it is doing something very similar, but it has a different approach. numberFormat() simply takes the first 18 digits starting at the left and formats them with the mask. So this code:
<cfoutput>
numberformat: #numberformat(num,'999,999,999,999,999,999,999.99')#
</cfoutput>
<cfset num = 9123456789123456789.123>
<cfoutput>
numberformat: #numberformat(num,'999,999,999,999,999,999,999.99')#
</cfoutput>
Result is: 9,123,456,789,123,457,000.00
Adding two 9s to the left side:
<cfset num = 99123456789123456789.123>
<cfoutput>
numberformat: #numberformat(num,'999,999,999,999,999,999,999.99')#
</cfoutput>
Result is: 99,123,456,789,123,450,000.00
Obviously if you are working with such large numbers it's time to consider a different approach anyway - scientific notation is a good place to start. Still, it's worth remembering that outputting numbers using these 2 functions does have it's limitations. I will leave you with a neat trick I just learned from Jacob Munson on CF Talk.
numberFormat() Mask Tip
If the reason you choose decimalFormat( ) over numberFormat() is because you don't like typing out long masks, this tip is worth it's weight in Gold. Instead of typing out a long mask, try a comma, a period and two 9s - as in ",.99". This code:
<cfoutput>
number format ',.99': #numberformat(num,',.99')#
</cfoutput>
5 Comments
-
fortunately icu4j's number formatter understands big decimals, etc. where core java's formatter doesn't (though it has BigDecimal, etc. as part of its math bits, go figure):
<cfscript>
theNumber="123456789123456789.12";
// using default server locale
nF=createObject("java","com.ibm.icu.text.NumberFormat").getInstance();
bigDecimal=createObject("java","java.math.BigDecimal").init(theNumber);
formattedNumber=nf.format(bigDecimal);
writeoutput("original number:=#theNumber#<br>
big decimal representation:=#bigDecimal#<br>
number Formated:=#formattedNumber#<br>");
</cfscript>
which yields:
original number:=123456789123456789.12
big decimal representation:=123456789123456789.12
number Formated:=123,456,789,123,456,789.12
i really wish cf used icu4j. would make i18n work much simpler & also help solve problems like these..... -
The problem here is that the number is being converted to a Java float under the covers and float simply doesn't have sufficient precision to hold that many significant digits. It's nothing to do with the formatting functions. This is a basic issue that people encounter whenever you are dealing with floating point numbers. It's why currency values should never be represented as floating point but as integers (as a number of pennies) and care taken not to convert the value via floating point data types.
The example Paul shows relies on a specific Java data type (BigDecimal) that supports much larger precisions (hence the name).
It's a trade off between the efficiency of using a native floating point type for calculations (float is much faster than BigDecimal) and the precision necessary for large numbers of significant digits. -
sean, for me the funny thing is that core java's formatting classes don't understand any of it's own "Big" math classes. icu4j was all over that several versions ago.
and since this is basically a display function, i don't understand why cf concerned is w/calculation speed? when does the conversion to float take place? immediately that the var is assigned a value or when it's pumped into the format function? or are you just doing a NumberFormat under the covers anyway? -
Paul, Thanks for the icu4j example. As I was preparing this post I considered whether colfusion might be using that math.BigDecimal object to handle this function. It seemed like an appropriate choice and it appeared to handle very large numbers with precision. I came to the conclusion that CF was converting to a primitive type - either double or float.
Sean, thanks for your comments. I take your currency comment to mean that 10 dollars and 12 cents should be represented as 1012 (1012 pennies). Sure makes display code more tedious to have to divide all those numbers by 100 - but I have worked with financial systems that store all financial values exactly like that - for the same reason I suppoe.
Anyway, thanks as always for the input. -
Thanks Mark. I had to round a number and add commas so your entry helped to make it cleaner then what I may have done.
#numberformat(round(variables.box5),',')#
Sites to Watch
Aggregators
RSS
