General Decimal Arithmetic (original) (raw)

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 ofANSI, IEEE, ECMA, and ISO standards, and conforms to the decimal formats and arithmetic in theIEEE 754 standard (‘754-2008’)published by the IEEE in August 2008, and theISO/IEC/IEEE 60559:2011standard, 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 fordecimal 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 formatsdesigned by theIEEE 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 inPDF 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.recently updated
    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 thereadme.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’sdecNumber github page for more information.
    More implementations of the arithmetic are listedbelow.
  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.
  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 theICU 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 theIBM Haifa test suite (FPGen), and Hossam Fahmy’sArithmetic 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 theIEEE 754-2008 and theISO/IEC/IEEE 60559:2011 standards.

Web links

The links below provide background and related information.

Some of the links below may be 'broken' (that is, no longer correct, or invalid).My current strategy is to leave these here because in most cases the original and/or most recent version of the page can be found at the 'Wayback machine' at the Internet Archive ‐ just copy the URL to the search field there.

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 aspresentation charts orhandouts A Decimal Floating-Point Specification [PDF] (Presented at the 15th IEEE Symposium on Computer Arithmetic [Arith15], June 2001.)Also available aspresentation 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 ArithmeticIP Cores Family product page andIP Cores Family presentation, and also theirDecTool 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 thePower Instruction Set Architecture Decimal Floating Point (Book 1, Chapter 5), and Bradley McCredie’s Microprocessor ForumPower Roadmap (details of the decimal floating-point unit in Power6 are on charts 12–14) IBM System z9 announcement; see alsoDecimal floating-point in z9: An implementation and testing perspective and thePreliminary 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 instructionsIBM 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 (HLASMPK18170: Support for z9 Business Class D/T2094.) IBM DFPAL; an abstraction layer for AIX, i5/OS, and LinuxSAP 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 anddecFloats 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.new addition For more information and details of later versions, etc., seeNelson H.F.Beebe's Decimal-arithmetic support in gcc compilers page.new addition Stefan Krah’smpdecimal 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’sPython Decimal Class has been in Python since Python 2.4, and was significantly extended forPython 2.6 and faster 3.3. new addition Semih Cemiloglu’sCppDecimal, a C++ library which encapsulates and augments the decNumber library for the C++ language. recently updated Semih Cemiloglu’sqdecimal, a C++ decimal arithmetic library for decNumber and the Qt framework. Mark Alston’s Tcl Decimal Arithmetic Library (and its code). Javier Goizueta’sruby-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’sLua decNumber, a decimal package for theLua programming language Richard Kaiser’s**C++**wrapper class for decNumberrecently updated Gunnar Degnbol’s JavaStak – a Calculator for Mobile Phones etc. Dave Clark’ssample Java code for encoding and decoding decimal floating-point numbersThree Java[TM] implementations: The Java 5 enhanced java.math.BigDecimal, and theDr. Dobb’s Journal article about itDecimal arithmetic for Java (part of ICU4J) – a prototype, withJava andNetRexx open source.Dirk Bosmans’ decimal arithmetic for Java (See also:Decimal floating-point in Java 6 – Best practices.)The proposeddecimal datatype for ECMAScript 4 (JavaScript, JScript, and ActionScript)Paul G. Crismer’s open sourceEDA –Eiffel Decimal Arithmetic library. Partial/subset Implementations Standards and Specifications The new IEEE 754 standard (‘754-2008’) was published by the IEEE in August 2008, and is available fromIEEE Xplore. It includes decimal floating-point formats (as described above) and arithmetic on those formats (also describedabove). This replaces the earlier IEEE 754-1985 (Binary Floating-Point) and IEEE 854 (Radix-independent Floating-Point) standards. This became an international standard asISO/IEC/IEEE 60559:2011, published by ISO in July 2011. IEEE 754-2008 is currently undergoing a minor revision.recently updated new addition 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. This follows on from joint work by the ISO/IEChref="" title="undefined" rel="noopener noreferrer">http://www.open-std.org/jtc1/sc22/wg14/"> JTC1/SC22/WG14 – Programming Language C and and ISO/IEC JTC1/SC22/WG21 – Programming Language C++ committees; thosework items were TR 24732 and TR 24733, respectively (slides, Draft Technical Report, and Rationale)TheDB2 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 storeThe 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 formatThe 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), andAda 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 thenew addition 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 describedabove; see alsoJ.H.M. Bonten’s summary for a different descriptionA summary of Chen-Ho decimal encodingEuropean 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 new addition 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 here. new addition Anthony Davis’s page onthe langur scripting language, which used decQuad for arithmetic. new addition Hossam Fahmy’s page onArithmetic 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’sHow to Leverage Decimal Floating-Point unit on POWER6 for Linux article Chris Pine’sWhy I love ECMAScript 4 real decimals article Naresh Chainani’sDECFLOAT: 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’sPOWER6 Decimal Floating Point article, with examples and code Janis Johnson and Steve Carlough’sPOWER6 and Decimal Floating Point presentation(Power Architecture Developer Conference, September 2007) TheIBM Haifa test suite (FPGen) for IEEE 754 decimal floating-point SilMinds’ DecTool Parser-Coder for parsing theIBM Haifa FPGen testcases Chris Eaton’sblog on DB2 Hardware Exploitation of Decimal Arithmetic on POWER6 Joe Darcy’sCompatibly evolving BigDecimal in Java new addition Marco Terzer’sJava library for fast fixed-point arithmetic based on longs with support for up to 18 decimal places. Birke Heeren’smutable Decimal classes for Java The Univerity of Wisconsin at MadisonDecimal 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 seehere for the latest results)recently updated A Decimal Floating-Point Specification, Eric Schwarz et al., from Arith15Mozilla ‘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’sDecimal floating point in **.**Net article Jo Bonten’sArithmetic Computer Formats pages Benjamin White’sJava routines for System z packed decimal data The Hewlett Packard 71B Calculator (IEEE 854 compliant)Gary Darby’sDelphi Big [decimal] Floating Point packageRichard Brent’sMP User’s Guide, Fourth edition, 1981. Ada Decimal Arithmetic and Representations, Ada Information Clearinghouse (AdaIC)Rogue Wave decimal Java support JScienceMoney and Currency for JavaClive “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’sDecimal Floating Point Java class library (base 10000) The [Atari Decimal] Floating Point Arithmetic Package, C. Lisowski. The Microsoft Decimal class Atmel’sBCD Arithmetics for AVR 8-bit RISC John Savard’s Base-26 Armor decimal representations pagerecently updated Harry J. Smith’sVPCalc variable precision calculatorTouch Technologies Inc’sPerfect Precision Math in SheerPower 4GL (doc.).The World’s Smallest Abacus Tim Robinson’s Meccano modelDifference Engine #1 Florida State University’sPowers of Ten Henry Baker’s How to Steal from a Limited Private Account cautionary taleThe Apple WebObjectsNSDecimalNumber class The Apache Derby database sub-projectnumeric datatypes and scale rulesXencraft’sCurrency and Foreign Exchange page, and currency linksDon North’s post onPDP 11 decimal hardware (Commercial Instruction Set, CIS) Decimalisation table attacks for PIN cracking Jim Horning’s page aboutBinary 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 hisArith17 keynote)Norbert Juffa and Nelson H. F. Beebe’s fparith bibliography of material on floating-point arithmetic Robert Munafo’sSurvey of Floating-Point Formats IEEE 754 References, C. VickeryWhat every computer scientist should know about floating-point arithmetic, David Goldberg Multi-precision floating-point The Number Theory Library (NTL) – includesarbitrary-precision binary floating-point arithmetic, Victor ShoupThe 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 new addition Richard Fateman’sdecfp.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’sBigDigits multi-precision library in ANSI CDavid M. Smith’sFMLIB multi-precision and arbitrary-base FORTRAN library Conversions new addition Javier Goizueta’sFloat-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 songNew Math 10-codes 10 (the movie)
Please send any comments or corrections toMike Cowlishaw (mfc),mfc@speleotrove.com; see alsospeleotrove.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.