Name: rmT116609 Date: 06/02/2003


A DESCRIPTION OF THE PROBLEM :
The javadoc for this constructor for java.math.BigDecimal
   public BigDecimal(String val)
contains the advice:
"This is generally the preferred way to convert a float or double into a BigDecimal, as it doesn't suffer from the unpredictability of the BigDecimal(double) constructor."

However, that advice is wrong. If you have a float or double, then you must convert it into a String in order to use that constructor. That conversion is subject to exactly the same conversion errors as the use of the BigDecimal(double) constructor. So you don't gain anything.

Programmers are reading and blindly following this advice thinking they are getting more accurate conversions when they are not.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
I suggest changing the advice to "If you have the same value available as a String, and as float or double (e.g. it was entered from the terminal and converted to double), use the String version of the constructor, as it will be more accurate. The double version of the constructor will involve another conversion, which introduces minute inaccuracy when the number cannot be exactly represented as the sum of powers of two. See "What Every Computer Scientist Should Know About Floating Point" for more details."

ACTUAL -
"This is generally the preferred way to convert a float or double into a BigDecimal, as it doesn't suffer from the unpredictability of the BigDecimal(double) constructor."


URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.4.2/docs/api/java/math/BigDecimal.html#BigDecimal(double)
(Review ID: 186931)
======================================================================