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 ]
think 10
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. 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 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 Hardware implementations Software with hardware support Software implementations Partial/subset Implementations Standards and Specifications Bibliography Related Decimal Links Floating-point starter links Multi-precision floating-point Conversions History Links ... and finally ...


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.