General Decimal Arithmetic
[ FAQ | Decimal web links | Bibliography | Arithmetic specification | Formats (encodings) | decNumber C implementation and C++ implementation | DFPAL | Testcases | Summary | Densely Packed Decimal | Speleotrove ]
think 10
Welcome to the new 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 new IEEE 754 standard (‘754-2008’), which was published by the IEEE in August 2008.

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

Reproduced with permission from IBM © Copyright 1997, 2008 by International Business Machines Corporation. Copyright © Mike Cowlishaw 1981, 2009.


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 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]
    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. recently updated
    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 a variety of free, open source, and commercial licenses (the ICU license is the simplest and 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]
    3.61
    2009.03.23
    Describes the decNumber package, including a User’s Guide section with several examples. recently updated
    Errata (known bugs and fixes since 3.56, 2007.10.12).
    International Components for Unicode (ICU)
    decNumber package
    3.61
    2008.07.09
    The source code (.h and .c files), together with the examples, the ICU license, and the documentation in PDF format. recently updated
    (The latest package is also mirrored here.)
    IBM alphaWorks
    decNumber package
    3.61
    2008.07.09
    The source code (.h and .c files), together with the examples, the alphaWorks license, and the documentation in PDF format. recently updated (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
    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]
    2.44
    2009.03.24
    Describes the testcase file format, testcase coverage, and testcase sources. recently updated
    Download
    dectest.zip
    dectest0.zip
    2.59
    2009.10.07
    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).


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.

    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 new IEEE 754 standard.


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 binary floating-point Conversions History Links ... and finally ...


Please send any comments or corrections to Mike Cowlishaw (mfc), mfc@uk.ibm.com; see also speleotrove.com.
Reproduced with permission from IBM © Copyright 1997, 2008 by International Business Machines Corporation. Parts © Mike Cowlishaw 1997, 2009.
Java is a trademark of Sun Microsystems Inc.