Overview

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. Both arbitrary-precision and fixed-size representations are supported.

The arbitrary-precision 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 BCD (4-bit Binary Coded Decimal) and three fixed-size formats of decimal floating-point. called decFloats.

The three fixed-size formats are also supported by three modules called decFloats, which have an extensive set of functions that work directly from the formats and provide arithmetical, logical, and shifting operations, together with conversions to binary integers, Packed BCD, and 8-bit BCD. Most of the functions defined in the proposed IEEE 754 revision (‘754r’)^[2]  are included, together with other functions outside the scope of that standard but essential for a decimal-only language implementation.

Library structure

The core of the library is the decNumber module. This uses an arbitrary-precision decimal number representation designed for efficient computation in software and implements the arithmetic and logical operations, together with a number of 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 variable-length and machine-dependent (for example, it contains integers which may be big-endian or little-endian).

In addition to the arbitrary-precision decNumber format, three fixed-size compact storage formats are provided for conversions and interchange.^[3]  These formats are endian-dependent but otherwise are machine-independent:

decimal32

a 32-bit decimal floating-point representation which provides 7 decimal digits of precision in a compressed format

decimal64

a 64-bit decimal floating-point representation which provides 16 decimal digits of precision in a compressed format

decimal128

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

A fourth, machine-independent, Binary Coded Decimal (BCD) format is also provided:

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 decimal32, decimal64, and decimal128 formats are also supported directly by three modules which can be used stand-alone (that is, they have no dependency on the decNumber module). These are:

decSingle

a module that provides the functions for the decimal32 format; this format is the 754r storage format and so provides utilities and conversions only

decDouble

a module that provides the functions for the decimal64 format; this format is a 754r basic format and so a full set of arithmetic and other functions is included

decQuad

a module that provides the functions for the decimal128 format; this format is a 754r basic format; it contains the same set of functions as decDouble.^[4] 

Relevant standards

• the floating-point decimal arithmetic defined in ANSI X3.274-1996^[5]  (including errata through 2001)
• the decimal arithmetic requirements of IEEE 854-1987,^[6]  as modified by the current IEEE 754r revision work,^[7]  except that:
  1. The values returned on 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).
  2. 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 ±10^{1,000,000,000}).