Java Specification Request - Decimal Arithmetic Enhancements

Section 1. Identification

This JSR is being submitted by the International Business Machines Corporation (IBM).

Primary contact:

Karl Gottschalk IBM Java Technical Strategist e-mail: karlgott@us.ibm.com voice: +1-919-543-9611

Technology contact:

Mike Cowlishaw IBM Fellow e-mail: mfc@speleotrove.com voice: +44-1962-815349

This JSR has been formally endorsed by:

Company	Contact
Amadeus LLC 9250 NW 36th St. Miami, FL 33317, USA	Russell Kneebone e-mail: rkneebone@amadeuslink.com voice: +1-305-499-6344
MERANT (Micro Focus+INTERSOLV) The Lawn, Old Bath Road Newbury RG14 1QN England	Eric Frey MERANT Fellow e-mail: Eric.Frey@merant.com voice: +1-307-739-0320
Minimal Business Objects Lda R. Prof. Vitor Fontes 11 B Lisboa, Portugal	Carlos Costa e Silva e-mail: ccs@minimal.pt voice: +351-1-7575772
The Mutual Group 227 King St. South Waterloo, ON, N2J 4C5 Canada	Mike Toohey Technology Solutions Specialist e-mail: Mike.Toohey@TheMutualGroup.com voice: +1-519-888-3900, x6935
Netscape Communications (AOL) 501 E. Middlefield Road Mountain View, CA 94043, USA	Clayton Lewis JavaScript Development Manager e-mail: clayton@netscape.com voice: +1-650-937-2471
Ringlord Technologies Greenbelt Maryland, USA	Udo Schuermann Founder e-mail: us@ringlord.com
SHARE Inc. 401 N Michigan Avenue, Suite 2400 Chicago, IL 60611, USA	Pamela J. Taylor Deputy Director, Industry Relations e-mail: pamela_taylor@stercomm.com voice: +1-972-868-5466

Section 2. Request

Target Java Platform: All platforms which include the package java.math.

Need that the work addresses: The proposed enhancements to the BigDecimal class primarily add floating point arithmetic to the existing class, allowing the use of decimal numbers for general-purpose arithmetic (especially financial and user-centric applications) without the overheads and potential errors resulting from conversions to and from another type. In addition, safe conversion methods are added to protect programmers from inadvertent data loss.

Why the existing specification does not meet the need: The current BigDecimal class lacks several operations required for common calculations, and the numbers it can manipulate are in practice limited to those which can be represented conveniently as 'plain' numbers, with no exponent. The limitations are severe:

1. The fixed point (integer + scale) arithmetic is suitable for some tasks (such as calculating taxes or balancing a check book), but is inconvenient and awkward for many common applications.
   For example, calculating the total amount repaid on a mortgage over 20 years is difficult, requiring several steps which do not involve exact arithmetic and which may require explicit rounding. For this task (and many others) an arithmetic that allows working to a chosen precision is both simpler and more convenient.
2. Several operators commonly used in applications are missing, specifically integer division, remainder, and exponentiation to an integer power (as required for straightforward calculation of the mortgage repayment just described, for example).
3. The constructors for BigDecimal do not accept exponential notation. This means that results with exponents from other sources (for example, spreadsheets and calculators, or the Java Double.toString() method) cannot easily be used.
4. The string form of a BigDecimal is always a plain number. This means that very large or very small numbers are expressed using many digits -- this makes them expensive and difficult to handle. For many calculations an exponential or floating point representation is desirable (and is potentially more efficient).
5. The conversion methods from BigDecimal to Java integer types are dangerous. Specifically, they are treated as a narrowing primitive conversion. This means that decimal fractional parts can be dropped without warning, and high order significant bits can also be lost without warning (an error sometimes called "decapitation").

Specification to be developed: We propose addressing the primary requirements by adding support for decimal floating point arithmetic to the BigDecimal class. This can be achieved without altering the existing behavior of the BigDecimal class by simply adding an optional context parameter to the existing operator methods. We also propose adding the missing operator methods, and a small number of improved constructors and conversion methods. The expert group may also wish to consider adding additional mathematical functions, equivalent to those in the class java.lang.Math.

Underlying technologies: It is proposed that the decimal arithmetic algorithms implemented by the augmented class be those defined in the ANSI standard X3.274-1996 (Programming Language REXX, 1996) which provide the necessary function in a form which is compatible with existing BigDecimal numbers.

Proposed package name: It is proposed that the existing java.math package be enhanced.

Possible platform dependencies: None.

Security implications: None. The existing characteristics of the BigDecimal class are preserved.

Internationalization and localization dependencies: It is expected that the expert group will define suitable additions to the java.text.DecimalFormat class to support the enhanced capabilities of the BigDecimal class.

Risk assessment: Apart from the DecimalFormat class just described, the proposed enhancements have no interdependencies with other classes. If the enhancements are not made, the Java platform will continue to be inadequate for commercial, financial, and user-centric data processing. A potential Reference Implementation (RI) and Compatibility Test Suite (CTS) already exist.

Existing specifications that might be deprecated: We propose deprecating the BigDecimal(double) constructor, which currently gives results that are different to the Double.toString() method.

Existing specifications that might need revision: The java.math.BigDecimal class will need revision. The java.text.DecimalFormat class would benefit from revision. A very small java.math.MathContext class is added.

Section 3. Contributions

IBM has a complete implementation of the proposed enhancements to the BigDecimal class, along with testcases that test compatibility with both the existing JCK and ANSI X3.274. This implementation could form the basis for the Reference Implementation.

The most recent documentation and binaries (.class files) for the IBM implementation, including background material, may be found at http://speleotrove.com/decimal.

The underlying technology, including algorithms for the arithmetic, is published in: American National Standard for Information Technology -- Programming Language REXX, X3.274-1996, American National Standards Institute, New York, 1996. Additional details and any errata are available at the Rexx Language Association web site.