home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 509.lha / apm / README.pp / README
Encoding:
Text File  |  1991-05-07  |  6.9 KB  |  140 lines
  1.  
  2.                 Arbitrary Precision Math Library
  3.  
  4. The Arbitrary Precision Math Library is a series of routines that
  5. allows the user to perform math to any level of accuracy that is
  6. desired.  These APM entities ("APM" == "Arbitrary Precision Math") can
  7. be initialized from character strings or from long integers, and they
  8. can be converted back into character strings by a routine that allows
  9. simple formatting.  With the exception of the routines that do
  10. division, the results of APM operations are guaranteed to contain
  11. enough precision to hold exact values.  The APM routines will
  12. automatically allocate enough space in their results to hold the
  13. proper number of digits.
  14.  
  15. The APM math is done on a new data type called "APM".  This is
  16. actually a pointer to a structure, but the contents of the structure
  17. should never be manipulated: all operations on APM entities are done
  18. through a functional interface.
  19.  
  20. APM items can be represented in any of 36 bases: 2 through 36 and
  21. 10000.  The latter is quite useful: numbers that are represented in
  22. bases that are powers of 10 are quite easy to accurately convert to
  23. and from character strings containing their decimal representation,
  24. and 10000 is the largest power of 10 that fits into a short integer
  25. (16 bits).  The base must fit into a short integer since calculations
  26. internal to the APM routines need up to twice as much storage as is
  27. needed to hold the base, and the largest unit we can deal with easily
  28. is a long integer (2 shorts).  It turns out that speed improves and
  29. memory usage decreases as the magnitude of the base increases, so base
  30. 10000 is a win in both counts.  I have done some informal benchmarks
  31. in which base 10000 is 6 to 10 times faster than base 10 for numbers
  32. with 15 - 20 decimal digits of precision.
  33.  
  34. Although there is a multitude of bases, there is as yet no provision
  35. for conversion from one base to another, except for the special case
  36. of converting between base-10 character strings and base-10000 APM
  37. values.  All the input APM parameters to any given APM routine must be
  38. of the same base.
  39.  
  40. The caller must initialize all APM values before the routines can
  41. operate on them (including the values intended to contain results of
  42. calculations).  Once this initialization is done, the user never needs
  43. to worry about resizing the APM values, as this is handled inside the
  44. APM routines and is totally invisible to the user.
  45.  
  46. The result of a APM operation cannot be one of the other APM operands.
  47. If you want this to be the case, you must put the result into a
  48. temporary variable and then assign it to the appropriate operand.
  49.  
  50. All of the routines set the value of a global integer called
  51. "apm_errno" to an error status: 0 means the operation succeeded, > 0
  52. means there was a warning but that there still is a result, and < 0
  53. means there was an error which prohibited the operation from
  54. completing.  Except where otherwise noted, the routines return this
  55. same status value.
  56.  
  57. The caller has the option of registering a handler for errors and
  58. warnings.  If this has been done, the handler will be invoked as each
  59. APM routine returns, and it will be passed appropriate information as
  60. to the status of the call to this APM routine.  With a registered
  61. error handler it is not necessary for the caller to check the error
  62. code after each call to a APM routine.
  63.  
  64. For ease of debugging, each APM routine is actually a macro that saves
  65. the file name and line number and then calls a function of a slightly
  66. different name.  This allows the error handler to report the exact
  67. location of the APM operation which caused the error.  The macros you
  68. will use have names of the form "apmRoutineName".  To get the
  69. corresponding actual function name (say, when using a debugger),
  70. replace all capital letters with an underbar ("_") followed by its
  71. lower-case counterpart.  For example, for a hypothetical routine
  72. called "apmRoutineName", the actual function will be named
  73. "apm_routine_name".  You should never explicitly call the actual
  74. function.
  75.  
  76. You should avoid using symbols that start with the characters "APM_"
  77. and "apm_", as they may clash with symbols that already exist in the
  78. APM Library.
  79.  
  80. There is one routine for each basic arithmetic operation such as
  81. adding, subtracting, etc.  This can become cumbersome when the result
  82. of a complicated expression is desired.  Therefore, I have added a
  83. routine that will perform a series of operations in the manner of an
  84. RPN ("Reverse Polish Notation") calculator.  See the routine 'apmCalc'
  85. (below) for more details.
  86.  
  87. In my original version of this library, I discovered that a great deal
  88. of system overhead was wasted allocating and deallocating APM values.
  89. So, I adopted what has turned out to be a noticibly faster allocation
  90. scheme: newly allocated APM values are stored in a list.  When the
  91. user disposes of one of these, it isn't really freed: its entry in the
  92. list is marked as unused.  Subsequent attempts to allocate a new APM
  93. value will make use of any existing entries in this list that are
  94. marked as unused instead of allocating a new entry.  Only when there
  95. are no unused entries in the list will a new entry be allocated.
  96. There is a routine that can be called which will perform a garbage
  97. collection: i.e., it actually frees all unused APM entries (see
  98. 'apmGarbageCollect', below).
  99.  
  100. A file called apm.h must be included in all programs that use the APM
  101. routines.  It defines the "APM" data type, the error codes, the
  102. apm_errno variable, and several other things.
  103.  
  104. This software was written in as portable a manner as possible.  I have
  105. gotten it running successfully under several environments: on a Sun
  106. 3/xxx using SunOS 3.5 and 4.0, on an IBM RT running under AIX, under
  107. MSDOS on an IBM PC using Microsoft C version 5.1 and Turbo C version
  108. 1.5 (or was it version 2.0?).  There are two makefiles: the one called
  109. "Makefile" is the unix version ... it works under SunOS 3.5 and I
  110. presume it would be easy to alter it to work under other unix
  111. environments; the one called "makefile.msc" will build the library
  112. under MSDOS using Microsoft C version 5.1 ... it is meant to run with
  113. the make program "PC/MAKE".
  114.  
  115. I'm sure that some of you will find ways of enhancing and speeding up
  116. the routines in this library.  Time permitting, I will be doing that
  117. as well.  I urge you to post your bug fixes and changes to the net and
  118. mail them to me at my address below, so they might be incorporated
  119. into a later version of this library.  Some suggested areas of
  120. enhancement and optimization are:
  121.  
  122. 1)    Somehow speeding up the memory allocation scheme.
  123.  
  124. 2)    Some sort of floating-point/APM conversion.  I left this out
  125.     because of the widely varying floating-point formats that
  126.     exist on the various machines these routines can and might run
  127.     on, and because I intended APM to *replace* floating-point,
  128.     not to work in conjunction with it.
  129.  
  130. 3)    Base conversion.
  131.  
  132. 4)    Roots, powers, logarithms, trig functions, exponential functions,
  133.     etc.
  134.  
  135. 5)      More productions in the makefiles ("install", "rdist", etc.).
  136.  
  137. 6)      A fancy installation script.
  138.  
  139. 7)    Writing a man page for all this.
  140.