Llosa de Viango Tollos – miniDec.c

Introduction

Features

Getting started

Download


Libraries

  Tollos libraries

  Device libraries

    boards

    microcontrollers

    peripherals


Background

  Sample application

  Troubleshooting

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.

Tollos and these web pages were written by Mike Cowlishaw; Please send me any corrections, suggestions, etc.
All content © Mike Cowlishaw, 2010–2012, except where marked otherwise. All rights reserved. The pages here are for non-commercial use only (see the separate licence for Tollos source code). Privacy policy: the Speleotrove website records no personal information and sets no ‘cookies’. However, statistics, etc. might be recorded by the web hosting service.

This page was last updated on 2011-11-18 by c2wiki.