decPacked module

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:

1010

(0x0a) plus

1011

(0x0b) minus

1100

(0x0c) plus (preferred)

1101

(0x0d) minus (preferred)

1110

(0x0e) plus

1111

(0x0f) plus^[1] 

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.

Definitions

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:

• Constants describing the six possible values of sign nibble, as described above.
• Definitions of the public functions in the decPacked module.

Functions

decPackedFromNumber(bytes, length, scale, number)

The arguments are:

bytes

(uint8_t *) Pointer to an array of unsigned bytes which will receive the number.

length

(int32_t) Contains the length of the byte array, in bytes.

scale

(int32_t *) Pointer to an int32_t which will receive the scale of the number.

number

(decNumber *) Pointer to the input structure. The decNumber structure will not be altered.

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.

decPackedToNumber(bytes, length, scale, number)

The arguments are:

bytes

(uint8_t *) Pointer to an array of unsigned bytes which contain the number to be converted.

length

(int32_t) Contains the length of the byte array, in bytes.

scale

(int32_t *) Pointer to an int32_t which contains the scale of the number to be converted. This must be set; use 0 if the number has no associated scale (that is, it is an integer). The effective exponent of the resulting number (that is, the number of significant digits in the number, less the scale, less 1) must fit in 9 decimal digits.

number

(decNumber *) Pointer to the decNumber structure which will receive the number. It must have space for length×2–1 digits.

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.