General Decimal Arithmetic [ FAQ | Bibliography | Arithmetic specification | Formats (encodings) | decNumber C implementation and C++ implementation | DFPAL | Testcases | Summary | Densely Packed Decimal | Decimal web links ]

Most computers today support binary floating-point in hardware. While suitable for many purposes, binary floating-point arithmetic should not be used for financial, commercial, and user-centric applications or web services because the decimal data used in these applications cannot be represented exactly using binary floating-point. (See the Frequently Asked Questions pages for an explanation of this, and several examples.)

The problems of binary floating-point can be avoided by using base 10 (decimal) exponents and preserving those exponents where possible. This site describes a decimal arithmetic which achieves the necessary results and is suitable for both hardware and software implementation. It brings together the relevant concepts from a number of ANSI, IEEE, ECMA, and ISO standards, and conforms to the decimal formats and arithmetic in the revised IEEE 754 standard (‘754r’), which was approved in June 2008.

The decimal-encoded formats and arithmetic described in the new IEEE 754 standard now have many implementations in hardware and software (see links below), including:

• the hardware decimal floating-point unit in the IBM Power6 processor, the firmware (with assists) in the IBM System z9 (mainframe) processor, and the the hardware decimal floating-point unit in the IBM System z10 mainframe (see the microprocessor charts for some details)
• IBM XL C/C++ for AIX, Linux and z/OS, DB2 for z/OS, Linux, UNIX, and Windows, and Enterprise PL/I for z/OS; IBM is also adding support to many other software products including z/VM V5.2, System i/OS, the dbx debugger, and Debug Tool Version 8.1
• SAP NetWeaver 7.1, which includes the new DECFLOAT datatype in ABAP, with support for hardware decimal floating-point on Power6
• GCC 4.2 was released in July 2007; this is the first GCC release with support for the proposed ISO C extensions for decimal floating point.

The combination of formats and arithmetic defined here and in the IEEE 754 standard describe a new decimal data type, in various sizes. Notably, this single data type can be used for integer, fixed-point, and floating-point decimal arithmetic, and the design permits compatible fixed-size and arbitrary-precision implementations. Further, most numeric data in commercial databases are stored in a decimal form (one or two digits per byte), which can be converted to and from the decimal-encoded formats efficiently and easily.

The main features of the arithmetic are summarized below. For the background and rationale for the design of the arithmetic, see Decimal Floating-Point: Algorism for Computers in the Proceedings of the 16th IEEE Symposium on Computer Arithmetic (Cowlishaw, M. F., 2003).

Here you will find our primary documentation and downloads for decimal arithmetic, fixed-size decimal formats (encodings) and their performance, the decNumber reference implementation, the decNumber++ implementation for C++, the DFPAL PowerPC abstraction layer, and the language-independent testcases.

1. This first document describes the decimal arithmetic in a language-independent and encoding-independent manner:

   Arithmetic	Version	Description
   Specification [.html | .pdf | .ps]	1.66 2007.03.13	Decimal floating-point arithmetic, with unrounded and integer arithmetic as a subset (IEEE 754r + IEEE 854 + ANSI X3.274 + ECMA 334 + Java[TM] 5).
   This specification forms the basis for a number of implementations, and also describes the decimal arithmetic in the revised IEEE 754 standard.

2. The next document describes the decimal-encoded formats designed by the IEEE 754 Revision Committee, accepted in January 2003 (‘Strawman 4d’), and now part of the revised IEEE 754 standard. Also here are some performance measurements comparing operations using the encodings.

   Formats	Version	Description
   Specification [.html | .pdf | .ps]	0.96 2003.02.21	Concrete formats (bit encodings) suitable for hardware or software implementation of native decimal datatypes; these provide up to 7, 16, or 34 digits of precision.
   Performance [.html | .pdf | .ps]	1.10 2007.10.19	Performance measurements on three implementations that support the encodings described in the IEEE 754 revision.
   Sample code [.html]	1.00 2003.04.10	Java[TM] classes which illustrate the decimal encoding of decimal floating-point numbers, and the corresponding decoding.
   (The earlier ‘Strawman 1’ proposal, implemented as decSingle and decDouble in early versions of the decNumber package, is available for historical interest in PDF form. See also: A Decimal Floating-Point Specification, Schwarz et al., 15th IEEE Symposium on Computer Arithmetic [presentation charts].)

3. The decNumber package, an implementation of the specifications in ANSI C, provides a reference implementation for both the arithmetic and the encodings. It includes both an arbitrary-precision implementation and (much faster) implementations that use the IEEE 754 decimal encodings directly.

   The package is available under a variety of open source and commercial licenses (the ICU license is the least restrictive), and is suitable for little-endian or big-endian systems which support 32-bit (or wider) integers. It is currently in use on dozens of different platforms, including mainframes, PowerPC, x86, and over 20 varieties of Unix.

   decNumber	Version	Description
   Documentation [.html | .pdf | .ps]	3.56 2007.10.12	Describes the decNumber package, including a User’s Guide section with several examples. (Note that the documentation here may be a more recent version than the downloadable code. If such is the case, check the changes list in the Appendix to determine if this document applies.)
   International Components for Unicode (ICU) decNumber C code [errata]	3.56 2007.10.12	The source code (.h and .c files), together with the examples, the ICU license, and the documentation in PDF format. (The package is also mirrored here.)
   IBM alphaWorks decNumber C code [errata]	3.56 2007.10.12	The source code (.h and .c files), together with the examples, the alphaWorks license, and the documentation in PDF format. (This download is on the IBM alphaWorks site. A commercial license for this software is also available there.)
   GPL open source decNumber C code decExamples.zip [errata]	3.53 2007.09.07	‘decNumber C code’ links to the open source code (.h and .c files), part of the GCC project (GPL license). ‘decExamples.zip’ contains the example files referred to in the documentation and also the readme.txt file which has suggestions on how to compile and run the examples.
   More implementations of the arithmetic are listed below.

4. The decNumber++ package extends the decNumber package to C++:

   decNumber++	Version	Description
   IBM alphaWorks decNumber++	1.00 2006.07.11	Robert Klarer’s decNumber++, which implements the interfaces specified in the forthcoming ISO Technical Report on decimal arithmetic types in C++: ISO/IEC TR 24733: C++ Decimal Floating-Point Arithmetic Extensions. (This download is on the IBM alphaWorks site.)
   More implementations of the arithmetic are listed below.

5. Punit Shah’s DFPAL package provides an abstraction layer for AIX, i5/OS (under PASE), and Linux on Power that will automatically use PowerPC (Power6) Decimal Floating-Point hardware if available (or will otherwise use decNumber for decimal calculations).

   DFPAL	Version	Description
   Documentation [.html | as .zip]	2.20 2008.01.03	The DFPAL User’s guide with overview, examples, compilation instructions, FAQ, etc.
   Download DFPAL.zip DFPAL.tar.gz	2.20 2008.01.03	The DFPAL source code (.h and .c files), together with the examples, the International Components for Unicode (ICU) license, the documentation in HTML format, etc.

6. Finally, the following language-independent testcases can be used for testing implementations:

   Testcases	Version	Description
   Documentation [.html | .pdf | .ps]	2.42 2008.06.21	Describes the testcase file format, testcase coverage, and testcase sources.
   Download dectest.zip dectest0.zip	2.57 2007.10.12	The extended (dectest.zip) and subset (dectest0.zip) testcase files (containing approximately 81,300 tests). These cover all the operations and conversions described in the specifications, and include tests for the decimal encodings.

The decimal arithmetic described here combines the requirements of both fixed-point and floating-point arithmetic, giving the following advantages:

The arithmetic permits a single representation of decimal numbers, whether they be integers, fixed-point (scaled), or floating-point; this minimizes conversion overheads. The arithmetic was designed as a decimal extended floating-point arithmetic, directly implementing the rules that people are taught at school. Up to a given working precision, exact unrounded results are given when possible (for instance, 0.9 ÷ 10 gives 0.09, not 0.089999996), and trailing zeros are correctly preserved in most operations (1.23 + 1.27 gives 2.50, not 2.5). Where results would exceed the working precision, floating-point rules apply. The working precision of the arithmetic is not necessarily determined by the representation, but may be freely selectable within the limits of the representation as required for the problem being solved. Implementations may provide very high precision if they wish. The arithmetic operations are robust; integers will never ‘wrap’ from positive to negative when being incremented, and, if required, ill-defined or out-of-range results immediately throw exceptions.

The concept of a context for operations is explicit. This allows application-global rules (such as precision, rounding mode, and exception handling) to be easily implemented and modified. This aids testing and error analysis, as well as simplifying programming. The core arithmetic was developed in 1980–1981, based directly on user feedback and requirements, and in consultation with professional mathematicians and data processing experts. It has been heavily used for over 26 years without problems, and was reviewed in depth and published by the X3J18 committee for the ANSI X3.274–1996 standard. The same arithmetic has been included in Java[TM] 5, through JSR 13, and in several other languages. More recently, the core arithmetic has been extended to include the special values and other requirements of IEEE 854 (the radix-independent generalization of IEEE 754-1985). This combined arithmetic meets commercial, scientific, mathematical, and enginering requirements, and is now part of the revised IEEE 754.

The links below provide background and related information.

Background & Rationale Frequently Asked Questions (FAQ) about decimal arithmetic and decimal data Decimal Floating-Point: Algorism for Computers [PDF]  (Presented at the 16th IEEE Symposium on Computer Arithmetic [Arith16], June 2003.) Also available as presentation charts or handouts A Decimal Floating-Point Specification [PDF]  (Presented at the 15th IEEE Symposium on Computer Arithmetic [Arith15], June 2001.) Also available as presentation charts Support for Decimal Floating-Point in C (presentation) The ‘telco’ benchmark Hardware implementations Charles Webb’s IBM z6 – The Next-Generation Mainframe Microprocessor presentation at Hot Chips 19, August 2007 – decribes the microprocessor in the new IBM System z10 mainframe (details of the decimal floating-point unit in the z6 are on charts 7, 19, and 20) Power PC (Power6) announcement; see also the Power Instruction Set Architecture Decimal Floating Point (Book 1, Chapter 5), and Bradley McCredie’s Microprocessor Forum Power Roadmap (details of the decimal floating-point unit in Power6 are on charts 12–14) IBM System z9 announcement; see also Decimal floating-point in z9: An implementation and testing perspective and the Preliminary Decimal-Floating-Point Architecture for IBM System z processors Software with hardware support IBM XL C/C++ for AIX and Linux IBM XL C/C++ for z/OS IBM DB2 for z/OS IBM DB2 for Linux, UNIX, and Windows IBM Enterprise PL/I for z/OS IBM High-Level Assembler (HLASM PK18170: Support for z9 Business Class D/T2094.) IBM DFPAL; an abstraction layer for AIX, i5/OS, and Linux SAP NetWeaver 7.1, which includes the new DECFLOAT datatype in ABAP with support for hardware decimal floating-point on Power6. For details, see the white paper Decimal Floating Point Computations in SAP NetWeaver 7.10. Software implementations The decNumber reference implementation, in ANSI C GCC 4.2 (July 2007) is the first GCC release with support for the proposed ISO C extensions for decimal floating point. Eric Price and and Facundo Batista’s Python Decimal Class is in Python 2.4. Robert Klarer’s decNumber++, which implements the interfaces specified in the forthcoming ISO Technical Report on decimal arithmetic types in C++: ISO/IEC TR 24733: C++ Decimal Floating-Point Arithmetic Extensions. Richard Kaiser’s C++ wrapper class for decNumber Gunnar Degnbol’s Java Stak – a Calculator for Mobile Phones etc. Dave Clark’s sample Java code for encoding and decoding decimal floating-point numbers Three Java[TM] implementations: The Java 5 enhanced java.math.BigDecimal, and the Dr. Dobb’s Journal article about it Decimal arithmetic for Java (part of ICU4J) – a prototype, with Java open source Dirk Bosmans’ decimal arithmetic for Java The Groovy BigDecimal Math package Doug Currie’s Lua decNumber, a decimal package for the Lua programming language The proposed decimal datatype for ECMAScript 4 (JavaScript, JScript, and ActionScript) Paul G. Crismer’s open source EDA – Eiffel Decimal Arithmetic library. Partial/subset Implementations Gjermund Skailand’s implementation for recent HP calculators (HP49g & HP50g), using decNumber (“this implementation is actually faster than using HP’s floating-point calculations on the calculator”) Javier Goizueta’s Float-Formats for Ruby, a library that supports conversions between a variety of floating point representations, including the decimal encodings described above. The Perl 6 decimal BigNum library The Microsoft Decimal class for C#, Visual Basic, and .Net The BigFloat Variable Precision Floating Library for Ruby, Shigeo Kobayashi (now superseded by Ruby BigDecimal) Some Rexx implementations IBM Rexx and Object Rexx Open Object Rexx (open source Object Rexx) NetRexx (Rexx for Java) Regina Rexx (includes C open source) Standards and Specifications The ANSI/IEEE 854-1987 [Radix-independent floating-point] standard is available from IEEE Standards Online or from the ANSI online store; the minutes of the working group 1981–1985 are also available IEEE 854 and the earlier IEEE 754-1985 (Binary Floating-Point) standards have been merged in the IEEE 754 revision, known as 754r, which was approved as the new IEEE 754 Standard for Floating-Point Arithmetic in June 2008. The working group draft includes decimal-encoding floating-point formats (as described above) and arithmetic on those formats (also described above). The ISO/IEC JTC1/SC22/WG14 – Programming Language C and and ISO/IEC JTC1/SC22/WG21 – Programming Language C++ committees are jointly working on decimal-floating point additions; the work items are TR 24732 and TR 24733, respectively (slides, Draft Technical Report, and Rationale) The DB2 DECFLOAT Decimal floating-point data type Java Specification Request 13 Decimal Arithmetic Enhancement for Java implements most of the 754r arithmetic, and extends it to arbitrary precision The ANSI X3.274-1996 [Rexx] standard, errata, etc. includes the decimal arithmetic which was the inspiration for much of the work described on this page; the final version is available from the ANSI online store The C# Language Specification standard [ECMA 334, with decimal floating-point data type] and the Common Language Infrastructure (CLI) standard [ECMA 335, with the System.Decimal class]; these define a subset of the 754r arithmetic; recent work has extended these standards to permit the use of the full IEEE 754r decimal-encoded 34-digit format The ISO/IEC 1989:2002 – COBOL standard (this specifies 32-digit decimal floating-point for calculations) The Python 2.4 Decimal Class Ada 95 decimal types (Part 1, 3.3.3), and Ada 95 decimal arithmetic (Part 3, Annex F.1) The Perl 6 decimal BigNum definition XML Schema Part 2: Datatypes (see §3.2.5, decimal data type), and the precisionDecimal type in XML Schema 1.1 Part 2: Datatypes (see §3.3.4) IBM System z Preliminary Decimal-Floating-Point Architecture Power.org Power Instruction Set Architecture Decimal Floating Point (see Book 1, Chapter 5) IBM ESA/390 Principles of Operation, Decimal Arithmetic Instructions (BCD integer arithmetic) A summary of the Densely Packed Decimal encoding used in the decimal-encoded formats described above A summary of Chen-Ho decimal encoding European Commission: The Introduction of the Euro and the Rounding of Currency Amounts; also Council Regulation (EC) No 1103/97 of 17 June 1997 on certain provisions relating to the introduction of the euro

Bibliography Categorized Bibliography Alphabetic Bibliography Bibliography by Year Related Decimal Links Chris Pine’s Why I love ECMAScript 4 real decimals article Naresh Chainani’s DECFLOAT: The data type of the future article, which explains the new decimal floating-point data type in DB2 for Linux, UNIX, and Windows Nigel Griffith’s POWER6 Decimal Floating Point article, with examples and code Janis Johnson and Steve Carlough’s POWER6 and Decimal Floating Point presentation (Power Architecture Developer Conference, September 2007) Joe Darcy’s Compatibly evolving BigDecimal in Java Chris Eaton’s blog on DB2 Hardware Exploitation of Decimal Arithmetic on POWER6 Birke Heeren’s mutable Decimal classes for Java The Univerity of Wisconsin at Madison Decimal Floating-Point Arithmetic Research page A press article referring to decimal floating-point hardware in the IBM Power6 processor (find more articles) Worst Cases for the Exponential Function in the IEEE 754r decimal64 Format, Zimmermann et al. (pre-print; also see here for the latest results) A Decimal Floating-Point Specification, Eric Schwarz et al., from Arith15 Mozilla ‘rounding bug’ (note the duplicates) Search for decimal bug or rounding bug The Patriot Missile Failure (tenths of a second × 0.1) Arithmetic calculations with decimals, Encyclopaedia Britannica A Calculated Look at Fixed-Point Arithmetic, Robert Gordon BCD Arithmetic, a tutorial, Douglas W. Jones (includes 6-bit algorithms) Decimal Arithmetic chapter from The Art of [8086] Assembly Language Programming by Randall Hyde Jon Skeet’s Decimal floating point in .Net article Jo Bonten’s Arithmetic Computer Formats pages Benjamin White’s Java routines for System z packed decimal data The Hewlett Packard 71B Calculator (IEEE 854 compliant) Gary Darby’s Delphi Big [decimal] Floating Point package Richard Brent’s MP User’s Guide, Fourth edition, 1981. Ada Decimal Arithmetic and Representations, Ada Information Clearinghouse (AdaIC) Rogue Wave decimal Java support JScience Money and Currency for Java Clive “Max” Maxfield’s articles and book: Mind-boggling math: BCD (binary coded decimal) How Computers Do Math  [book] Rounding 101 Binary Coded Decimal (BCD) 101 – Part 1 Bill Rossi’s Decimal Floating Point Java class library (base 10000) The [Atari Decimal] Floating Point Arithmetic Package, C. Lisowski. The Microsoft Decimal class Atmel’s BCD Arithmetics for AVR 8-bit RISC John Savard’s Base-26 Armor decimal representations page Harry J. Smith’s VPCalc variable precision calculator Touch Technologies Inc’s Perfect Precision Math in SheerPower 4GL (doc.). The World’s Smallest Abacus Tim Robinson’s Meccano model Difference Engine #1 Florida State University’s Powers of Ten Henry Baker’s How to Steal from a Limited Private Account cautionary tale The Apple WebObjects NSDecimalNumber class The Apache Derby database sub-project numeric datatypes and scale rules Xencraft’s Currency and Foreign Exchange page, and currency links Don North’s post on PDP 11 decimal hardware (Commercial Instruction Set, CIS) Decimalisation table attacks for PIN cracking Jim Horning’s page about Binary to Decimal Conversion on the Bendix G-15. Floating-point starter links Professor Kahan’s page (many seminal papers and documents on floating-point arithmetic, including his Arith17 keynote) Norbert Juffa and Nelson H. F. Beebe’s fparith bibliography of material on floating-point arithmetic Robert Munafo’s Survey of Floating-Point Formats IEEE 754 References, C. Vickery What every computer scientist should know about floating-point arithmetic, David Goldberg Multi-precision binary floating-point The Number Theory Library (NTL) – includes arbitrary-precision binary floating-point arithmetic, Victor Shoup Arithmos: a reliable integrated computational environment, University of Antwerp The MPFR (multiprecision floating-point with rounding) library, Loria (Lorraine Laboratory for Research into Information Technology and its Applications) The GMP (GNU MP) multi-precision library The MAPM library (A Portable Arbitrary Precision Math Library in C) David Ireland’s BigDigits multi-precision library in ANSI C David M. Smith’s FMLIB multi-precision and arbitrary-base FORTRAN library Conversions Javier Goizueta’s Float-Formats for Ruby, a library that supports conversions between a variety of floating point representations, including the decimal encodings described above. Correctly Rounded Binary-Decimal and Decimal-Binary Conversions, David M. Gay (code) How to Read Floating Point Numbers Accurately, William D. Clinger (decimal to binary) How to Print Floating Point Numbers Accurately, Guy L. Steele & Jon L. White (binary to decimal) Architecture and software support in IBM S/390 Parallel Enterprise Servers for IEEE Floating-Point arithmetic, Paul H. Abbott et al Microsoft’s Functions to Convert BCD (DECMATH.LIB) Format to IEEE (FORTRAN source code) Converting p to binary: Don’t do it!, Keith F. Lynch [Risks Digest, Volume 21, Issue 42] History Links Decimal or Binary?, in the Manchester Mark 1 computer (1947/8) Timeline of Computing History, IEEE Computer Society A History of Computers, Maxfield & Montrose Interactive Inc. Some History of Numbers and Number Base Systems, Poseidon Software and Invention ... and finally ... Tom Lehrer’s song New Math 10 (the movie)

Please send any comments or corrections to Mike Cowlishaw (mfc), mfc@uk.ibm.com
Copyright © IBM Corporation 2000, 2008. All rights reserved. Java is a trademark of Sun Microsystems Inc.
[ IBM home page | Search | Contact IBM | Help | Terms of use | Privacy ]
IBM United Kingdom Limited – Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU