The decNumber Library, version 3.36
Copyright (c) IBM Corporation, 2006. All rights reserved. ©
6 Jul 2006
[contents | next]

Overview

The decNumber library implements the General Decimal Arithmetic Specification[1]  in ANSI C. This specification defines a decimal arithmetic which meets the requirements of commercial, financial, and human-oriented applications.

The library fully implements the specification, and hence supports integer, fixed-point, and floating-point decimal numbers directly, including infinite, NaN (Not a Number), and subnormal values.

The code is optimized and tunable for common values (tens of digits) but can be used without alteration for up to a billion digits of precision and 9-digit exponents. It also provides functions for conversions between concrete representations of decimal numbers, including Packed Decimal (4-bit Binary Coded Decimal) and three compressed formats of decimal floating-point (4-, 8-, and 16-byte).

Library modules

The library comprises several modules (corresponding to classes in an object-oriented implementation). Each module has a header file (for example, decNumber.h) which defines its data structure, and a source file of the same name (e.g., decNumber.c) which implements the operations on that data structure. These correspond to the instance variables and methods of an object-oriented design.

The core of the library is the decNumber module. This uses a decimal number representation designed for efficient computation in software and implements the arithmetic operations, together with some conversions and utilities. Once a number is held as a decNumber, no further conversions are necessary to carry out arithmetic.

Most functions in the decNumber module take as an argument a decContext structure, which provides the context for operations (precision, rounding mode, etc.) and also controls the handling of exceptional conditions (corresponding to the flags and trap enablers in a hardware floating-point implementation).

The decNumber representation is machine-dependent (for example, it contains integers which may be big-endian or little-endian), and is optimized for speed rather than storage efficiency.

Four machine-independent (but optionally endian-dependent) compact storage formats are provided for interchange. These are:

decimal32
This is a 32-bit decimal floating-point representation, which provides 7 decimal digits of precision in a compressed format.[2] 

decimal64
This is a 64-bit decimal floating-point representation, which provides 16 decimal digits of precision in a compressed format.

decimal128
This is a 128-bit decimal floating-point representation, which provides 34 decimal digits of precision in a compressed format.

decPacked
The decPacked format is the classic packed decimal format implemented by IBM S/360 and later machines, where each digit is encoded as a 4-bit binary sequence (BCD) and a number is ended by a 4-bit sign indicator. The decPacked module accepts variable lengths, allowing for very large numbers (up to a billion digits), and also allows the specification of a scale.
The module for each format provides conversions to and from the core decNumber format. The decimal32, decimal64, and decimal128 modules also provide conversions to and from character string format (using the functions in the decNumber module).

Standards compliance

It is intended that the decNumber implementation complies with: Please advise the author of any discrepancies with these standards.
Footnotes:
[1] See http://www2.hursley.ibm.com/decimal for details.
[2] See http://www2.hursley.ibm.com/decimal/decbits.html for details of the compressed formats.
[3] American National Standard for Information Technology – Programming Language REXX, X3.274-1996, American National Standards Institute, New York, 1996.
[4] IEEE 854-1987 – IEEE Standard for Radix-Independent Floating-Point Arithmetic, The Institute of Electrical and Electronics Engineers, Inc., New York, 1987.
[5] See http://grouper.ieee.org/groups/754/

[contents | next]