Libraries
Background
miniDec.c – a decimal package for small systems
This package supports a simple decimal format, intended for the storage, management, and display of decimal data. As such, it provides conversions to and from ints, doubles, and strings in various forms, along with decQuantize to ‘shape’ decimal data.
Arithmetic operations are currently not included, but the bounds of the format conform to IEEE 754 rules (section 3) and IEEE 754 arithmetic functions could be added later.
Overflows or bad conversions result in a Infinities or quiet NaNs (decNaN), as appropriate. For details not covered in the function descriptions, see the General Decimal Arithmetic Specification.
Decimal numbers are passed by copy since they are smaller than two words (assuming a 32-bit system).
The maximum coefficient is 9 digits and emax is 999.
| Functions | |
|---|---|
| decFromDouble | double to decimal |
| decFromInt | int to decimal |
| decFromInts | int coefficent and exponent to decimal |
| decFromString | string to decimal |
| decGetCoeff | return the coefficient of a decimal as an int |
| decGetDigits | return the number of digits in a decimal |
| decGetExp | return the exponent of a decimal as an int |
| decGetSign | return the sign of a decimal as an int |
| decIdentical | test if two decimals are identical |
| decIsFinite | test if a decimal is finite |
| decIsInf | test if a decimal is infinite |
| decIsNaN | test if a decimal is a NaN |
| decIsNegative | test if a decimal is a number and negative |
| decIsPositive | test if a decimal is a number and positive |
| decIsQNaN | test if a decimal is a quiet NaN |
| decIsSigned | test if a decimal has a sign bit of 1 |
| decIsSNaN | test if a decimal is signalling NaN |
| decIsSpecial | test if a decimal is a NaN or Infinity |
| decIsZero | test if a decimal is a number with value 0 |
| decQuantize | round or extend a decimal to match another |
| decSetCoeff | set the coefficient of a decimal from an int |
| decSetExp | set the exponent of a decimal |
| decSetSign | set the sign of a decimal |
| decToDouble | convert a decimal to a double |
| decToInt | convert a decimal to int |
| decToString | decimal to string |
decFromDouble – double to decimal
dec decFromDouble(double dub);
dub – double (IEEE 754 binary64) to convert
returns decimal conversion of dub
Finite numbers will always be in range, but will be rounded to 9 decimal digits (or one, for zeros). All NaNs return decNaN.
decFromInt – int to decimal
dec decFromInt(int i);
i – int to convert [DECMINCOE <= i <= DECMAXCOE]
returns decimal with the value of the int, or decNaN if out of range
decFromInts – int coefficent and exponent to decimal
dec decFromInts(int coe, int exp);
coe – coefficient to convert [DECMINCOE <= coe <= DECMAXCOE]
exp – exponent to use
returns decimal constructed from coe and exp, or decNaN if the resulting number would be out of range
The number is in range if it is zero, or it is non-zero and its magnitude is in the range 0.00000001*10**−998 through 9.99999999*10**999, provided that the exponent needed to represent it exactly with the coefficient as an integer (including trailing zeros) is in the range −1006 through 999.
decFromString – string to decimal
dec decFromString(const char * str);
str – string to convert
returns decimal holding the converted string
If the coefficient has more than 9 digits, or the number represented by the string is out of range, or the syntax is invalid, then a quiet NaN is returned. No rounding takes place; for finite numbers this conversion is exact if it succeeds.
The number is in range if it is zero, or it is non-zero and its magnitude is in the range 0.00000001*10**−998 through 9.99999999*10**999, provided that the exponent needed to represent it exactly with the coefficient as an integer (including trailing zeros) is in the range −1006 through 999.
The spellings for the special values are as recommended by IEEE 754, and are independent of case; the following are accepted: “infinity”, “inf”, “nan”, or “snan”.
See the General Arithmetic Specification for a formal description of allowed syntax.
decGetCoeff – return the coefficient of a decimal as an int
int decGetCoeff(dec num);
num – decimal to process
returns the unsigned coefficient of num, as an int
The result will be in the range 0 .. 999999999
decGetDigits – return the number of digits in a decimal
int decGetDigits(dec num);
num – decimal to check
returns the number of significant digits in the coefficient of num (or returns 1 if the coefficient is 0, or num is infinite or a NaN)
decGetExp – return the exponent of a decimal as an int
int decGetExp(dec num);
num – decimal to process
returns the signed exponent of num
The result will be in the range −1006 .. 999
decGetSign – return the sign of a decimal as an int
int decGetSign(dec num);
num – decimal to process
returns the sign of num
The result will be 1 if num is signed or 0 if it is not. The sign indicates negative for non-zero numbers and infinity.
decIdentical – test if two decimals are identical
int decIdentical(dec num1, dec num2);
num1 – first decimal to test
num2 – second decimal to test
returns 1 the two decimals are identical in all respects
Decimals are identical if they have the same sign, and also if finite they have the same exponent and coefficient, or if not finite they are the same kind of NaN or they are both infinite. Note that decimals that are not identical might be numerically equal (for example, 2.50 is numerically equal to 2.5).
decIsFinite – test if a decimal is finite
int decIsFinite(dec num);
num – decimal to test
returns 1 if num is neither a NaN nor an Infinity, 0 in all other cases.
decIsInf – test if a decimal is infinite
int decIsInf(dec num);
num – decimal to test
returns 1 if num is an Infinity, 0 in all other cases.
decIsNaN – test if a decimal is a NaN
int decIsNaN(dec num);
num – decimal to test
returns 1 if num is a qNaN or an sNaN, 0 in all other cases.
decIsNegative – test if a decimal is a number and negative
int decIsNegative(dec num);
num – decimal to test
returns 1 if num is a number (finite or infinite) and negative (<0), 0 in all other cases.
decIsPositive – test if a decimal is a number and positive
int decIsPositive(dec num);
num – decimal to test
returns 1 if num is a number (finite or infinite) and positive (>0), 0 in all other cases.
decIsQNaN – test if a decimal is a quiet NaN
int decIsQNaN(dec num);
num – decimal to test
returns 1 if num is a qNaN, 0 in all other cases.
decIsSigned – test if a decimal has a sign bit of 1
int decIsSigned(dec num);
num – decimal to test
returns 1 if the sign bit of num is 1, and 0 if it is not.
This may be used to test the sign of a zero or a NaN.
decIsSNaN – test if a decimal is signalling NaN
int decIsSNaN(dec num);
num – decimal to test
returns 1 if num is an sNaN, 0 in all other cases.
decIsSpecial – test if a decimal is a NaN or Infinity
int decIsSpecial(dec num);
num – decimal to test
returns 1 if num is not a finite number, 0 in all other cases.
decIsZero – test if a decimal is a number with value 0
int decIsZero(dec num);
num – decimal to test
returns 1 if num is a finite number with a value of 0, 0 in all other cases.
This test is independent of the sign and exponent of num.
decQuantize – round or extend a decimal to match another
dec decQuantize(dec a, dec b);
a – decimal to be modified
b – pattern to match
returns the decimal with the closest value to a which has the exponent of b
If either value is a NaN then a quiet NaN is returned. If both are infinite, then a is returned.
Otherwise, the returned value will have the same exponent as a; if this is not possible (not enough digits, or either a or b is infinite) then this is an error and a quiet NaN is returned. If rounding is needed then round half up is used.
decSetCoeff – set the coefficient of a decimal from an int
void decSetCoeff(dec *num, int coe);
num – target decimal
coe – int to use to set the coefficient (0 .. 999999999)
The coefficient of the decimal will be set; no checking is carried out so it must be in range. This does not set or change the sign or exponent of num.
decSetExp – set the exponent of a decimal
void decSetExp(dec *num, int exp);
num – target decimal
exp – sign to be set (−1006 .. 991)
The exponent of the decimal will be set; no checking is carried out so it must be in range. This does not set or change the sign or coefficient of num.
decSetSign – set the sign of a decimal
void decSetSign(dec *num, int sign);
num – target decimal
sign – sign to be set (0 or 1)
The sign of the decimal will be set to 0 if sign is 0, or 1 if sign has any other value. This does not set or change the coefficient or exponent of num.
decToDouble – convert a decimal to a double
void decToDouble(dec num, double *dub);
num – decimal to convert
dub – double (IEEE 754 binary64) to receive an approximation of num
Conventions vary for signalling NaNs, so all NaNs set dub to NAN.
decToInt – convert a decimal to int
int decToInt(dec num);
num – decimal to convert
returns int result with DECBADINT if error
This converts the decimal number to an integer. Fractional parts of a finite number are discarded. If the result is too large to fit in a 32-bit int, or is a special value, then DECBADINT is returned.
decToString – decimal to string
void decToString(dec num, char *str);
num – decimal to convert
str – string to receive converted decimal (char[17] +)
Converts the decimal to a string, using the conventions as recommended by IEEE 754 and specified by the General Decimal Arithmetic specification. For specials, the strings “NaN” and “Infinity” are used. The string is terminated by ‘\0’; up to 17 characters (including the terminator) might be needed.