The decNumber Library, version 3.36
Copyright (c) IBM Corporation, 2006. All rights reserved. ©
| 6 Jul 2006 |
[previous | contents | next]
|
The decimal32, decimal64, and decimal128 modules define the data structures
and functions for compressed formats which are 32, 64, or 128 bits (4,
8, or 16 bytes) long, respectively. These provide up to 7, 16, or 34
digits of decimal precision in a compact and machine-independent form.
Details of the formats are available at:
http://www2.hursley.ibm.com/decimal/decbits.html
Apart from the different lengths and ranges of the numbers, the three
modules are identical, so this section just describes the decimal64
format.
The definitions and functions for the other two formats are identical,
except for the obvious name and value changes.
Note that these formats are now included in the draft of the
proposed IEEE-SA 754 standard (‘754r’). However, they are still
subject to change; use at your own risk.
In this implementation each format is represented as an array of
unsigned bytes.
There is therefore just one field in the decimal64 structure:
- bytes
-
The bytes field represents the eight bytes of a decimal64
number, using Densely Packed Decimal encoding for the coefficient.[1]
The storage of a number in the bytes array may be chosen to either follow
the byte ordering (‘endianness’) of the computing platform or to
use fixed ordering (big-endian, with bytes[0] containing the
sign bit of the format). This choice is made at compile time by
setting the DECENDIAN tuning parameter.
The decimal64 module includes private functions for coding and decoding
Densely Packed Decimal data; these functions are shared by the other
compressed format modules.
Definitions
The decimal64.h header file defines the decimal64 data structure
described above.
It includes the decNumber.h header file, to simplify use, and (if
not already defined) it sets the DECNUMDIGITS constant to 16, so
that any declared decNumber will be the right size to contain any
decimal64 number.
If more than one of the three decimal format header files are used in
a program, they must be included in decreasing order of size so that
the largest value of DECNUMDIGITS will be used.
The decimal64.h header file also contains:
- Constants defining aspects of decimal64 numbers, including the
maximum precision, the minimum and maximum (adjusted) exponent
supported, the bias applied to the exponent, the length of the number in
bytes, and the maximum number of characters in the string form of the
number (including terminator).
-
Macros for accessing the leading fields of the number (comprising the
sign, combination field, and exponent continuation).
-
Definitions of the public functions in the decimal64 module.
The decimal64 module also contains the shared routines for compressing
and expanding Densely Packed Decimal data, and uses the decDPD.h
header file. The latter contains look-up tables which are used for
encoding and decoding Densely Packed Decimal data (only two tables
of the four tables are used in a given compilation). These tables
are automatically generated and should not need altering.
Functions
The decimal64.c source file contains the public functions
defined in the header file. These comprise conversions to and from
strings, and to and from decNumber form.
When a decContext structure is used to report errors, the same rules are
followed as for other modules. That is, a trap may be raised, etc.
This function is used to convert a character string to decimal64 format.
It implements the to-number conversion in the arithmetic
specification (that is, it accepts subnormal numbers, NaNs, and
infinities, and it preserves the sign and exponent of 0). If
necessary, the value will be rounded to fit.
The arguments are:
- decimal64
- (decimal64 *) Pointer to the structure to be set from the
character string.
- string
- (char *) Pointer to the input character string. This must
be a valid numeric string, as defined in the specification.
The string will not be altered.
- context
- (decContext *) Pointer to the context structure whose
status field is used to control the conversion and report any
error, as for the decNumberFromString function except
that the precision and exponent range are fixed for each format.
Returns decimal64.
Possible errors are DEC_Conversion_syntax
(the string does not have the syntax of a
number), DEC_Overflow
(the adjusted exponent of the number is positive and is greater
than context.emax),
or DEC_Underflow
(the adjusted exponent of the number is negative and is less
than context.emin and the conversion is not exact).
If one of these conditions is set, the decimal64 structure will
have the value NaN, Infinity, or a finite (possibly
subnormal) number respectively, with the same sign as the converted
number after overflow or underflow.
decimal64ToString(decimal64, string)
This function is used to convert a decimal64 number to a character string,
using scientific notation if an exponent is needed (that is, there will
be just one digit before any decimal point).
It implements the to-scientific-string conversion in the
arithmetic specification.
The arguments are:
- decimal64
- (decimal64 *) Pointer to the structure to be converted to a
string.
- string
- (char *) Pointer to the character string buffer which will
receive the converted number.
It must be at least DECIMAL64_String (24) characters
long.
Returns string.
No error is possible from this function.
decimal64ToEngString(decimal64, string)
This function is used to convert a decimal64 number to a character string,
using engineering notation (where the exponent will be a multiple of
three, and there may be up to three digits before any decimal point) if
an exponent is needed. It implements the to-engineering-string
conversion in the arithmetic specification.
The arguments and result are the same as for the decimal64ToString
function, and similarly no error is possible from this function.
decimal64FromNumber(decimal64, number, context)
This function is used to convert a decNumber to decimal64 format.
The arguments are:
- decimal64
- (decimal64 *) Pointer to the structure to be set from the
decNumber. This may receive a numeric value (including subnormal
values and –0) or a special value.
- number
- (decNumber *) Pointer to the input structure.
The decNumber structure will not be altered.
- context
- (decContext *) Pointer to a context structure whose
status field is used to report any error and whose
other fields are used to control rounding, etc., as required.
Returns decimal64.
The possible errors are as for the decimal64FromString
function, except that DEC_Conversion_syntax
is not possible.
decimal64ToNumber(decimal64, number)
This function is used to convert a decimal64 number to decNumber form
in preparation for arithmetic or other operations.
The arguments are:
- decimal64
- (decimal64 *) Pointer to the structure to be converted to a
decNumber.
The decimal64 structure will not be altered.
- number
- (decNumber *) Pointer to the result structure.
It must have space for 16 digits of precision.
Returns number.
No error is possible from this function.
Footnotes:
[previous | contents | next]