============================================================================
This file describes the format of the internal representation
of an MAPM number in the M_APM data structure
M. Ring Nov 10, 2002
============================================================================
struct M_APM_struct {
UCHAR *m_apm_data;
long m_apm_id;
int m_apm_refcount;
int m_apm_malloclength;
int m_apm_datalength;
int m_apm_exponent;
int m_apm_sign;
};
The internal representation of the number is in base 100. Each byte in
'm_apm_data' can store the values 0-99 (out of a possible 0-255). All
numbers mentioned here will be in decimal unless otherwise noted. Base 100
was used since that is the largest power of 10 that will fit in one byte.
A base that is a power of 10 was chosen since it is real convienent when
translating to/from the internal format.
All math operations will result in a 'normalized' number. In this context,
normalized means 2 things; the first nibble of the first byte of data will
be non-zero, and all trailing zero's will be ignored. As an example, 25 * 4
would normally yield 100, or the digits '1', '0', '0' an have a 'datalength'
of 3. Since the trailing zeros carry no information, the datalength will
simply be truncated to 1. Note that this assumes the exponent is adjusted
accordingly, which we of course do.
The decimal point of the number is implied to be before the first byte of
data. See the examples below.
'm_apm_data' : An array to hold the digits. The byte at offset 0 will
contain the the first 2 (base 10) digits of the number
(or 1 base 100 digit), the next byte will contain the
3rd and 4th digits, etc. If the number has an odd
number of digits, the least significant nibble in the
last byte of data will be 0.
'm_apm_id' : Set during m_apm_init to M_APM_IDENT. Used to
validate the structure before the call to 'free'.
'm_apm_refcount' : NOT used by the basic M_APM. It was added to support
the C++ MAPM wrapper class. (However, we do initialize
this element to 1).
'm_apm_malloclength' : Keeps track of how many bytes were allocated in the
malloc call to m_apm_data. If a given math operation
will yield a result that won't fit into the existing
m_apm_data array, we will realloc m_apm_data so it
will be guaranteed to hold the result.
'm_apm_datalength' : The number of base 10 digits in the number. In other
words, the number 5678 will have a datalength of 4
(which will fit into 2 bytes). The number 1234567 will
have a datalength of 7 (which requires 4 bytes to
store).
'm_apm_exponent' : The exponent of the number, can be up to sizeof(int)
'm_apm_sign' : The sign of the number. sign = -1 is a negative
number. sign = +1 is a positive number. sign = 0 is
a number that is exactly 0. This feature is used
extensively in the library for fast comparisons to 0.
--------
Examples
--------
number sign datalength exponent data: [byte 0,1,2, etc]
-----------------------------------------------------------------------
0 0 1 0 00
4.0 +1 1 +1 40 (data = 28h)
-0.07 -1 1 -1 70 (data = 46h)
31.6 +1 3 +2 31, 60 (data = 1Fh, 3Ch)
-52338.226 -1 8 +5 52, 33, 82, 26
0.0007621 +1 4 -3 76, 21
3.75900064E+18 +1 9 +19 37, 59, 00, 06, 40
-6.1289E-7 -1 5 -6 61, 28, 90
0.872394 +1 6 0 87, 23, 94