The decNumber Library, version 3.68
Copyright (c) IBM Corporation, 2010. All rights reserved. ©
|23 Jan 2010|
|[previous | contents | next]|
Packed Decimal numbers are held as a sequence of Binary Coded Decimal digits, most significant first (at the lowest offset into the byte array) and one per 4 bits (that is, each digit taking a value of 0–9, and two digits per byte), with optional leading zero digits. The final sequence of 4 bits (called a ‘nibble’) will have a value greater than nine which is used to represent the sign of the number. The sign nibble may be any of the six possible values:
Packed Decimal numbers therefore represent decimal integers. They often have associated with them a second integer, called a scale. The scale of a number is the number of digits that follow the decimal point, and hence, for example, if a Packed Decimal number has the value -123456 with a scale of 2, then the value of the combination is -1234.56.
It includes the decNumber.h header file, to simplify use, and (if not already defined) it sets the DECNUMDIGITS constant to 32, to allow for most common uses of Packed Decimal numbers. If you wish to work with higher (or lower) precisions, define DECNUMDIGITS to be the desired precision before including the decPacked.h header file.
The decPacked.h header file also contains:
The arguments are:
Returns bytes unless the decNumber has too many digits to fit in length bytes (allowing for the sign) or is a special value (an infinity or NaN), in which cases NULL is returned and the bytes and scale values are unchanged.
The number is converted to bytes in Packed Decimal format, right aligned in the bytes array, whose length is given by the second parameter. The final 4-bit nibble in the array will be one of the preferred sign nibbles, 1100 (0x0c) for + or 1101 (0x0d) for –. The maximum number of digits that will fit in the array is therefore length×2–1. Unused bytes and nibbles to the left of the number are set to 0.
The scale is set to the scale of the number (this is the exponent, negated). To force the number to a particular scale, first use the decNumberRescale function on the number, negating the required scale in order to adjust its exponent and coefficient as necessary.
The arguments are:
Returns number, unless the effective exponent was out of range or the format of the bytes array was invalid (the final nibble was not a sign, or an earlier nibble was not in the range 0–9). In these error cases, NULL is returned and number will have the value 0.
Note that –0 and zeros with non-zero exponents are possible resulting numbers.
|||Conventionally, this sign code can also be used to indicate that a number was originally unsigned.|