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:

`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`.

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.

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.

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.

Footnotes:

[1] | Conventionally, this sign code can also be used to indicate that a number was originally unsigned. |

[previous | contents | next]