home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 105_01 / float.doc < prev    next >
Text File  |  1984-06-05  |  6KB  |  186 lines
  1.  
  2.         The Incredible Superpowerful 
  3.         Floating Point Package for BDS C v1.4
  4.         *************************************
  5.         software written by: Bob Mathias
  6.         this documentation by: Leor Zolman
  7.  
  8.     Components of the floating point package:
  9.  
  10.         1)    FLOAT.DOC:    This documentation file
  11.         2)    FLOAT.C:    File of support functions, written in C
  12.         3)    FP:        The workhorse function (in DEFF2.CRL)
  13.         4)  FLOATSUM.C    A Sample use of all this stuff
  14.  
  15.     This floating point package is as close as BDS C
  16. version 1.x is ever gonna come to manipulating floating point
  17. numbers. And it ain't too bad, actually...Bob did a nice neat
  18. job, and the new formatted printout support in a special version
  19. of the "_spr" library function (source is in FLOAT.C) means that
  20. floating point output is no longer limited to scientific notation.
  21.  
  22.     Here's how it works: for every floating point number
  23. you wish to work with, you must declare a five (5) element
  24. character array. Then, pass a pointer to the array whenever
  25. you need to specify it in a function call. Each of Bob's
  26. functions expects its arguments to be pointers to such 
  27. character arrays.
  28.  
  29.     The four basic arithmetic functions are: fpadd,
  30. fpsub, fpmul and fpdiv. They each take three arguments: a
  31. pointer to a five character array where the result will go,
  32. and the two operands (each a pointer to a five character array
  33. representing a floating point operand.)
  34.  
  35. NOTE THAT THE RESULT MAY BE PLACED INTO EITHER OF THE ARGUEMENTS
  36. WITH NO ILL EFFECTS. I.e., the operation:
  37.      fpmult(foo,foo,foo);
  38. will successfully square 'foo' and place the result in 'foo'.
  39.  
  40.     To initialize the floating point character arrays to the
  41. values you desire and print out the values in a human-readable form,
  42. the following functions are included:
  43.  
  44.     ftoa: converts a floating point number to an ASCII
  45.           string (which you can then print out with "puts")
  46.           NOTE: explicit use of this function has been made
  47.             obsolete by the new "sprintf." See FLOAT.C.
  48.  
  49.     atof: converts an ASCII string (null terminated) to
  50.           a floating point number
  51.  
  52.     itof: converts integer to floating point.
  53.  
  54. Here are Bob's descriptions of the functions:
  55.  
  56.         -----------------------------------
  57.  
  58. The following functions allow BDS C compiler users to access
  59. and manipulate real numbers. Each real number must be allocated
  60. a five (5) byte character array (char fpno[5]).  The first four
  61. bytes contain the mantissa with the first byte being the least
  62. significant byte.  The fifth byte is the exponent.
  63.  
  64. fpcomp(op1,op2)
  65. char op1[5],op2[5];
  66.             Returns:
  67.             an integer 1 if op1 > op2
  68.             an integer -1 if op1 < op2
  69.             a zero if op1 = op2
  70.         As with most floating point packages, it is not
  71.         a good practice to compare for equality when
  72.         dealing with floating point numbers.
  73.  
  74. char *fpadd(result,op1,op2)
  75. char result[5], op1[5], op2[5];
  76.         Stores the result of op1 + op2 in result. op1
  77.         and op2 must be floating point numbers.
  78.         Returns a pointer to the beginning of result.
  79.  
  80.  
  81. char *fpsub(result,op1,op2)
  82. char result[5],op1[5],op2[5];
  83.         Stores the result of op1 - op2 in result.  op1
  84.         and op2 must be floating point numbers.  
  85.         Returns a pointer to the beginning of result.
  86.  
  87. char *fpmult(result,op1,op2)
  88. char result[5],op1[5],op2[5];
  89.         Stores the result of op1 * op2 in result.  op1
  90.         and op2 must be floating point numbers. Returns
  91.         a pointer to the beginning of result.
  92.  
  93. char *fpdiv(result,op1,op2)
  94. char result[5],op1[5],op2[5];
  95.         Stores the result of op1 / op2 in result.  op1
  96.         and op2 must be floating point numbers.  
  97.         A divide by zero will return zero as result.
  98.         Returns a pointer to the beginning of result.
  99.  
  100. char *atof(op1,s1)
  101. char op1[5],*s;
  102.         Converts the ASCII string s1 into a floating
  103.         point number and stores the result in op1.  
  104.         The function will ignore leading white space 
  105.         but NO white space is allowed to be embedded
  106.         withing the number. The following are legal
  107.         examples:
  108.         "2", "22022222222383.333", "2.71828e-9",
  109.         "334.3333E32".
  110.         "3443.33 E10" would be ILLEGAL because
  111.         it contains an embedded space.
  112.         The value of the exponent must be within the
  113.         range: -38 <= exponent <= 38.
  114.         A pointer to the result is returned.
  115.  
  116.  
  117. char *ftoa(s1,op1)
  118. char *s1,op1[5];
  119.         Converts the floating point number op1 to an 
  120.         ASCII string.  It will be formatted in 
  121.         scientific notation with seven (7) digits of
  122.         precision. The string will be terminated by
  123.         a null.
  124.         Returns a pointer to the beginning of s1.
  125.  
  126. char *itof(op1, n)
  127. char op1[5];
  128. int n;
  129.         Sets the floating pt. number op1 to the value
  130.         of integer n. n is assumed to be a SIGNED
  131.         integer.
  132.  
  133.  
  134. General observations:
  135.  
  136.     Because floating point operations must be thought of
  137. in terms of FUNCTION CALLS rather than simple in-line
  138. expressions, special care must be taken not to confuse the
  139. abilities of the compiler with the abilities of the floating
  140. point package. To give a floating point number an initail
  141. value, for instance, you cannot say:
  142.  
  143.     char fpno[5];
  144.     fpno = "2.236";
  145.  
  146. To achieve the desired result, you'd have to say:    
  147.  
  148.     char fpno[5];
  149.     atof(fpno,"2.236");
  150.  
  151. Moreover, let's say you want to set a floating point number
  152. to the value of an integer variable called "ival". Saying:
  153.  
  154.     char fpno[5];
  155.     int ival;
  156.     ...
  157.     fpno = ival;
  158.  
  159. will not work; you have to change that last line to:
  160.  
  161.     itof(fpno,ival);
  162.  
  163.     Some more examples:
  164.  
  165.     The following will add 100.2 & -7.99 and store the
  166.     result at the five character array location 'a':
  167.         fpadd(a,atof(b,"100.2"), atof(c,"-7.99"));
  168.     (note that "b" and "c" must also be five character
  169.     arrays)
  170.  
  171.     The following would NOT add 1 to 'a' as both op1 and 
  172.     op2 must be floating point numbers (actually pointers
  173.     to characters...):
  174.  
  175.         fpadd(a,a,1);  /* bad use of "fpadd" */
  176.  
  177.     Thus, it can get a bit hairy when all floating
  178. point numbers are really character arrays; but still, it's
  179. better than nothing.
  180.  
  181.     All of the above functions are written in C, but
  182. most of them call a single workhorse function called "fp"
  183. to do all the really hairy work. This function has been placed
  184. into the DEFF2.CRL; it is the only machine-coded part of the
  185. package.
  186.