                        README

The com.ibm.math.BigDecimal class provides the same functionality as the
java.math.BigDecimal class but adds ANSI X3.274 floating point arithmetic.
Particular attention has been paid to performance: the com.ibm.math.BigDecimal
class is generally much faster than the java.math.BigDecimal class, for common
operations.

The com.ibm.math.BigDecimal class is compatible with the java.math.BigDecimal
class. All the methods from the java.lang.BigDecimal class are available, and
work in the same way. If you already use the java.lang.BigDecimal class then
you can probably simply change the import statement:

    import java.math.*;
to
    import com.ibm.math.*;

to access the new class, without changing any other code.

There are some very minor differences, as described in the detailed 
documentation. In particular, if high-order digits are lost when converting
to primitive types, then the com.ibm.math.BigDecimal class will throw an
exception, instead of quietly losing information.  Apart from the documented
differences, and the different package name, the new class passes the relevant
tests in the Java Compatibility Kit (JCK).

The sample program decdemo.java shows the results achieved using decimal
arithmetic as compared to binary floating point arithmetic. Compile the
program using the command:

    javac decdemo.java

The program starts with the number nine (9), and repeatedly divides it by ten
(10), and should display the following result:

    java decdemo
    0.9        0.9
    0.09       0.089999996
    0.009      0.0090
    0.0009     9.0E-4
    0.00009    9.0E-5
    0.000009   9.0E-6
    9E-7       9.0000003E-7
    9E-8       9.0E-8
    9E-9       9.0E-9
    9E-10      8.9999996E-10

The left-hand column shows the results obtained using the com.ibm.math.BigDecimal
class, and the right-hand column shows the results obtained using the float datatype.

