General Decimal Arithmetic [ FAQ | Decimal web links | Bibliography | Arithmetic specification | Formats (encodings) | decNumber C implementation | DFPAL | Testcases | Summary | Web links | Densely Packed Decimal | Speleotrove | Contact ]
 Welcome to the General Decimal Arithmetic website, which is now hosted at speleotrove.com. The page and file names here have not been changed from the names used on the previous website, www2.hursley.ibm.com.

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 IEEE 754 standard (‘754-2008’) published by the IEEE in August 2008, and the ISO/IEC/IEEE 60559:2011 standard, published by ISO in July 2011. IEEE 754-2008 is currently undergoing a minor revision.

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

The combination of formats and arithmetic defined here and in the IEEE 754 and ISO/IEC/IEEE 60559:2011 standards 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 existing 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).

Parts of these decimal arithmetic pages are reproduced with permission from IBM © Copyright 1997, 2008 by International Business Machines Corporation. Copyright © Mike Cowlishaw 1981, 2015.

Documentation and downloads

Here you will find documentation and downloads for decimal arithmetic, fixed-size decimal formats (encodings) and their performance, the decNumber reference implementation, 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] 1.70 2009.03.25 Decimal floating-point arithmetic, with unrounded and integer arithmetic as a subset (IEEE 754 + 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 new IEEE 754 standard.

2. The next document describes three 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 various encodings.

 Formats Version Description Specification [.html | .pdf] 1.01 2009.03.20 Concrete decimal 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] 1.12 2009.03.21 Performance measurements on three implementations that support the IEEE 754 decimal formats. 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 a (much faster) decFloats implementation that uses the IEEE 754 decimal encodings directly to implement decSingle, decDouble, and decQuad datatypes.

The package is available under two free open source licenses (the ICU license is the simpler and the less 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, ARM-based microcontrollers and tablets, x86, and over 20 varieties of Unix.

 decNumber Version Description Documentation [.html | .pdf] 3.68 2010.01.23 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 some versions of downloadable code. If such is the case, check the changes list in the Appendix to determine if this document applies.) Errata Known bugs and fixes since 3.56, 2007.10.12. International Components for Unicode (ICU) decNumber package in ICU decNumber .zip download 3.68 2010.02.10 The ‘decNumber .zip download’ includes the source code (.h and .c files), together with the examples, the ICU license, and the documentation in PDF format. GPL open source decNumber C code in GCC decNumber .zip download decExamples.zip 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). The ‘decNumber .zip download’ also includes the source code, etc. ‘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. Patches decNumber368-patches-20210522.zip 3.68 2021.05.22 The decNumber368-patches-20210522.zip file contains three .patch files, contributed by Matthew Hagerty. The patches are needed for the decNumber 3.68 code to compile cleanly with gcc 10.2.0. See the included .txt file and also Matthew Hagerty’s decNumber github page for more information. More implementations of the arithmetic are listed below.

4. 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).

In addition to arithmetic operations and various utilities, DFPAL also provides conversions between decimal floating point formats and many other programming language intrinsic data types such as binary floating point and integers.

 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.

5. Finally, the following language-independent testcases can be used for testing implementations; these are part of the decNumber package documentation, and are also covered by the ICU license:

 Testcases Version Description Documentation [.html | .pdf] 2.44 2009.03.24 Describes the testcase file format, testcase coverage, and testcase sources. Download dectest.zip dectest0.zip 2.62 2010.04.19 The extended (dectest.zip) and subset (dectest0.zip) testcase files (containing more than 81,300 tests). These cover all the operations and conversions described in the specifications, and include tests for the decimal encodings. See also the IBM Haifa test suite (FPGen), and Hossam Fahmy’s Arithmetic operations debugging and verification page.

Summary of the arithmetic

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 27 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 (see the links below). 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 included in the IEEE 754-2008 and the ISO/IEC/IEEE 60559:2011 standards.

Web links

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 Fujitsu’s decimal Densely Packed Decimal and NUMBER support instructions in the SPARC64 X processor announced at Hot Chips 24, August 2012. (See charts 5 & 6 of this presentation.) SilMinds’ Decimal Floating Point Arithmetic IP Cores Family product page and IP Cores Family presentation, and also their DecTool Parser-Coder software tool The paper: Decimal floating-point support on the IBM System z10 processor – by Eric Schwarz, John Kapernick, and Mike Cowlishaw (January 2009) – describes decimal floating-point hardware in, and supporting software for, the new IBM System z10 mainframe. See also Charles Webb’s IBM z6 – The Next-Generation Mainframe Microprocessor presentation at Hot Chips 19, August 2007 (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 GCC 4.3 includes the proposed ISO C extensions for decimal floating point, with hardware support for IBM Power and System z decimal instructions 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 and decFloats 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. For more information and details of later versions, etc., see Nelson H.F.Beebe's Decimal-arithmetic support in gcc compilers page. Stefan Krah’s mpdecimal package (libmpdec): a complete implementation of the General Decimal Arithmetic Specification that will – with minor restrictions – also conform to the IEEE 754-2008 Standard for Floating-Point Arithmetic. Starting from Python-3.3, libmpdec is the basis for Python's decimal module. Eric Price and Facundo Batista’s Python Decimal Class has been in Python since Python 2.4, and was significantly extended for Python 2.6 and faster 3.3. Semih Cemiloglu’s qdecimal, a a C++ decimal arithmetic library for decNumber and the Qt framework. Mark Alston’s Tcl Decimal Arithmetic Library (and its code). Javier Goizueta’s ruby-decimal, a Decimal class based on Eric Price and Facundo Batista’s library for Python, with some enhancements and adaptations to Ruby The Groovy BigDecimal Math package Doug Currie’s Lua decNumber, a decimal package for the Lua programming language 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 and NetRexx open source. Dirk Bosmans’ decimal arithmetic for Java (See also: Decimal floating-point in Java 6 – Best practices.) 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 Gustavo Henrique Milaré’s Decimal floats for Common Lisp 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 new IEEE 754 standard (‘754-2008’) was published by the IEEE in August 2008, and is available from IEEE Xplore. It includes decimal floating-point formats (as described above) and arithmetic on those formats (also described above). This replaces the earlier IEEE 754-1985 (Binary Floating-Point) and IEEE 854 (Radix-independent Floating-Point) standards. This became an international standard as ISO/IEC/IEEE 60559:2011, published by ISO in July 2011. IEEE 754-2008 is currently undergoing a minor revision. The ISO/IEC JTC1/SC22/WG14 – Programming Language C committe has recently completed the ISO C extensions (ISO/IEC TS 18661-2) Technical Specification for decimal floating point. This was published in May 2015. The DB2 DECFLOAT Decimal floating-point data type Java Specification Request 13 Decimal Arithmetic Enhancement for Java implements most of the IEEE 754 decimal arithmetic, and extends it to arbitrary precision (see also: Decimal floating-point in Java 6 – Best practices) 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 IEEE 754 arithmetic; recent work has extended these standards to permit the use of the full IEEE 754 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; see also J.H.M. Bonten’s summary for a different description 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 Related Decimal Links Anthony Davis’s page on the langur scripting language, which used decQuad for arithmetic. Hossam Fahmy’s page on Arithmetic operations debugging and verification – Amr Abdel-Fatah Sayed-Ahmed’s research, papers, and decimal arithmetic test vectors. Paul Dale’s decimal scientific firmware source code for some recent HP business calculators, including a real and complex mathematics library. Mark Erle’s dissertation: Algorithms and Hardware Designs for Decimal Multiplication (simplex) Decimal floating-point in Java 6 – Best practices, by Marcel Mitran, Ivan Sham, and Levon Stepanian Chakarat Skawratananond’s How to Leverage Decimal Floating-Point unit on POWER6 for Linux article 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) The IBM Haifa test suite (FPGen) for IEEE 754 decimal floating-point SilMinds’ DecTool Parser-Coder for parsing the IBM Haifa FPGen testcases Chris Eaton’s blog on DB2 Hardware Exploitation of Decimal Arithmetic on POWER6 Joe Darcy’s Compatibly evolving BigDecimal in Java Marco Terzer’s Java library for fast fixed-point arithmetic based on longs with support for up to 18 decimal places. 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: 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 floating-point The Number Theory Library (NTL) – includes arbitrary-precision binary floating-point arithmetic, Victor Shoup 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 Richard Fateman’s decfp.lisp decimal package in Lisp. The apfloat arbitrary-precision library. The CLN arbitrary-precision Class Library for Numbers. 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 Computer History, Computer History Museum ... and finally ... Tom Lehrer’s song New Math 10-codes 10 (the movie)

 Please send any comments or corrections to Mike Cowlishaw (mfc), mfc@speleotrove.com; see also speleotrove.com. Parts of these decimal arithmetic pages are reproduced with permission from IBM © Copyright 1997, 2008 by International Business Machines Corporation. Copyright © Mike Cowlishaw 1981, 2015. Java is a trademark of Sun Microsystems Inc. and Oracle.