The decNumber Library, version 3.36
Copyright (c) IBM Corporation, 2006. All rights reserved. ©
| 6 Jul 2006 |
[contents | next]
|
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).
It is intended that the decNumber implementation complies with:
-
the floating-point decimal arithmetic defined in ANSI X3.274-1996[3]
(including errata through 2001)
-
all requirements of IEEE 854-1987,[4]
as modified by the current IEEE 754r revision work,[5]
except that:
-
The values returned after overflow and underflow do not change when an
exception is trapped.
This is
because the IEEE 854 definition does not generalize to the power
and exp operations. Similarly, the criteria for underflow do not
depend on the setting of the underflow trap-enabler (the subnormal
condition may be tested or trapped, instead).
-
The IEEE remainder operator (decNumberRemainderNear) is
restricted to those values where the intermediate integer can be
represented in the current precision, because the conventional
implementation of this operator would be very long-running for the
range of numbers supported (up to ±101,000,000,000).
Note that all other requirements of IEEE 854 (such as subnormal
numbers and –0) are supported.
Please advise the author of any discrepancies with these standards.
Footnotes:
[contents | next]