home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxxmath.zip / rxxmath.doc < prev    next >
Text File  |  1996-11-19  |  13KB  |  294 lines
  1.       RXXMATH v1.3 -- Arbitrary Precision Math Functions for REXX
  2.                    Copyright 1992, 1996 by John Brock
  3.  
  4.  
  5. RXXMATH is an extremely easy-to-use math package which may be called as
  6. an external routine from REXX or invoked from the command line.  RXXMATH
  7. is true to the spirit of REXX math in that it will calculate results to
  8. arbitrary precision.  Because RXXMATH is itself written entirely in REXX
  9. it should port essentially unchanged to any environment which supports
  10. REXX.  (RXXMATH was originally written for VM/CMS, but the author has
  11. also run it under MVS/TSO, IBM PC DOS 7, and OS/2).  Note that along
  12. with the basic math functions RXXMATH has an interpretative calculator
  13. function which may be used to evaluate complex mathematical expressions,
  14. or even used as a interactive "REXX shell".
  15.  
  16.  
  17. This RXXMATH distribution is for OS/2, and includes the files:
  18.  
  19. RXXMATH.CMD  -- the main program
  20. RXXMATHI.CMD -- support for the interpretative REXX calculator function
  21. RXXMATH.DOC  -- this documentation file
  22.  
  23.  
  24. RXXMATH is unsupported freeware, and is provided "as is", with no
  25. warranties of any sort, express or implied.  RXXMATH may be freely
  26. distributed in any format, provided no alterations are made to the files
  27. (other than what may be necessary to port RXXMATH to a new environment)
  28. and no restrictions are placed on further distribution.  Users may
  29. modify RXXMATH at their convenience, as long as the copyright notices
  30. are retained and the modified version is not distributed publicly.
  31. Comments are welcome, and may be sent to jbrock@panix.com.
  32.  
  33.  
  34. The following functions are supported:
  35.  
  36.             FACT(x)    --  Factorial of x
  37.             PERM(x,y)  --  Permutations of x by y
  38.             COMB(x,y)  --  Combinations of x by y
  39.             SQRT(x)    --  Square root of x
  40.             POW(x,y)   --  x to the power of y
  41.             LOG(x,y)   --  Log of y base x
  42.             EXP(x)     --  e to the power of x
  43.             LN(x)      --  Natural log of x
  44.             PI()       --  Value of pi
  45.             SIN(x)     --  Sine of x
  46.             COS(x)     --  Cosine of x
  47.             TAN(x)     --  Tangent of x
  48.             COT(x)     --  Cotangent of x
  49.             SEC(x)     --  Secant of x
  50.             CSC(x)     --  Cosecant of x
  51.             ARCSIN(x)  --  Inverse sine of x
  52.             ARCCOS(x)  --  Inverse cosine of x
  53.             ARCTAN(x)  --  Inverse tangent of x
  54.             ARCCOT(x)  --  Inverse cotangent of x
  55.             ARCSEC(x)  --  Inverse secant of x
  56.             ARCCSC(x)  --  Inverse cosecant of x
  57.             CALC(x)    --  Calculate the value of an expression
  58.                              (e.g. '1 + exp(pi() / 2)')
  59.  
  60.  
  61. When invoked from the command line, RXXMATH has the format:
  62.  
  63. +----------------------------------------------------------------------+
  64. | RXXMATH [digits] function [x [y]]                                    |
  65. +----------------------------------------------------------------------+
  66.  
  67. When called as a function from REXX, RXXMATH has the format:
  68.  
  69. +----------------------------------------------------------------------+
  70. | RXXMATH([digits,] function [,x [,y]])                                |
  71. +----------------------------------------------------------------------+
  72.  
  73. Where:      digits     is the desired precision of the result
  74.                          (if omitted or zero the NUMERIC DIGITS
  75.                           default, which should be 9, is used)
  76.  
  77.             function   is the name of a supported function
  78.  
  79.             x, y       are arguments to the function
  80.  
  81.  
  82. Examples:
  83.  
  84. 1. From the command line, find the square root of 2 to 40 places:
  85.  
  86.        rxxmath 40 sqrt 2  (or rxxmath 40 pow 2 0.5)
  87.  
  88.    result: 1.41421356237309504880168872420969807857
  89.  
  90. 2. Find the square root of 2 to 9 places (the default):
  91.  
  92.        rxxmath sqrt 2
  93.  
  94.    result: 1.41421356
  95.  
  96. 3. From within REXX, print the base 10 log of 5 to 40 places:
  97.  
  98.        say rxxmath(40, "LOG", 10, 5)
  99.  
  100.    result: 0.6989700043360188047862611052755069732318
  101.  
  102. 4. From REXX, print the base 10 log of 5 to 9 places:
  103.  
  104.        say rxxmath("LOG", 10, 5)
  105.  
  106.    result: 0.698970004
  107.  
  108. 5. From REXX, print 1 plus e to the power of pi/2, to 50 places:
  109.  
  110.        say rxxmath(50, "CALC", "1 + exp(pi() / 2)")
  111.  
  112.    result: 5.8104773809653516554730356667038331263901708746645
  113.  
  114. 6. From the command line, find "1 + exp(pi() / 2)" to 9 places:
  115.  
  116.        rxxmath calc 1 + exp(pi() / 2)
  117.  
  118.    result: 5.81047738
  119.  
  120. 7. Enter interactive REXX calculator mode (a "REXX shell"):
  121.  
  122.        rxxmath calc
  123.  
  124.    result: RXXMATH interactive mode -- enter any valid REXX instruction:
  125.            a = 1 + exp(pi() / 2)
  126.            RXXMATH interactive mode -- enter any valid REXX instruction:
  127.            say a
  128.            5.8104774
  129.            RXXMATH interactive mode -- enter any valid REXX instruction:
  130.            numeric digits 50
  131.            RXXMATH interactive mode -- enter any valid REXX instruction:
  132.            b = 1 + exp(pi() / 2); say b
  133.            5.8104773809653516554730356667038331263901708746648
  134.            RXXMATH interactive mode -- enter any valid REXX instruction:
  135.            prompt = "New prompt:"
  136.            New prompt:
  137.            numeric digits 9
  138.            New prompt:
  139.            say pi() - ln(23)
  140.            0.00609843
  141.            New prompt:
  142.            say calc("pi() - ln(23)")
  143.            0.00609843766
  144.            New prompt:
  145.            say calc(pi() - ln(23))
  146.            0.00609843
  147.            New prompt:
  148.            exit
  149.  
  150.  
  151. Notes:
  152.  
  153. If invoked without arguments from the command line, RXXMATH will print a
  154. help message.
  155.  
  156. When invoked as a command RXXMATH normally prints its result to the
  157. screen and returns 0. If there is an error it prints an error message
  158. and returns 1. When called as a REXX function RXXMATH normally returns
  159. its result to REXX and prints nothing.  If there is an error RXXMATH
  160. prints an error message and returns no value to REXX.  This will cause
  161. the SYNTAX condition to be raised, which is consistent with the behavior
  162. of REXX built-in functions when given bad arguments.  However if
  163. necessary you can avoid raising the SYNTAX condition on error by calling
  164. RXXMATH as a subroutine, rather than a function.
  165.  
  166. All trigonometric function arguments are in radians.
  167.  
  168. In general the numeric arguments to an RXXMATH function may be any legal
  169. REXX numbers, of any size and precision.  If an argument has more
  170. significant digits than the requested precision of the result the
  171. argument will be rounded before use.  Of course an attempt to use a
  172. number outside the range of a given function (e.g., SQRT(-2) or
  173. FACT(3.3)) will result in an error.  Arguments to the trigonometric
  174. functions may not be of arbitrary size, but must have an absolute value
  175. which is < 10 ** (precision % 2).  So, for example, using a precision of
  176. 9 you could calculate sin(9999), but trying to calculate sin(10000)
  177. would result in an error.  In the unlikely event that you really need to
  178. calculate the sine or cosine of a very large number it can be done by
  179. increasing the size of the of the precision argument until the above
  180. condition is met (which may however result in an unacceptably long
  181. execution time).
  182.  
  183. RXXMATH uses REXX's arbitrary precision arithmetic to calculate its
  184. results, so naturally if an implementation of REXX does not support this
  185. feature of the language then RXXMATH's ability to return high precision
  186. results will be limited.  RXXMATH sets its internal precision twice as
  187. high as requested by the user, so if, for example, the highest precision
  188. a given implementation of REXX will support is 100, then the highest
  189. precision the user may request from RXXMATH is 50.
  190.  
  191. Some performance considerations.  When the precision is <= 25 RXXMATH
  192. can use hard coded values for e and pi (which are used internally a
  193. lot), and ln(10) (which provides a special boost for log base 10
  194. calculations).  The POW function knows when it is being asked to take a
  195. square root (e.g., RXXMATH("POW", 0.25, -1.5) = 8), and uses the
  196. considerably faster SQRT function when appropriate.  And RXXMATH can
  197. recognize situations that REXX can deal with directly, such as integer
  198. powers, so that, for example, RXXMATH("POW", 2.5, 10) will execute much
  199. faster than RXXMATH("POW", 2.5, 10.1).
  200.  
  201. All calculations are done in the main program, RXXMATH, which may be
  202. compiled if a REXX compiler is available.  RXXMATHI (which is called
  203. only by RXXMATH, never by the user) supports the interpretative REXX
  204. calculator function ("CALC"), and because it uses the "interpret"
  205. statement it may not be compiled.  Note that RXXMATH and RXXMATHI call
  206. each other when the CALC function is used, so this function will not
  207. work unless they are placed in locations where they can find each other
  208. automatically.
  209.  
  210. The CALC function takes a character string and interprets it as a REXX
  211. expression, using the RXXMATH math functions with names and arguments as
  212. listed above (e.g., "exp(4)" is replaced by the appropriate call to
  213. RXXMATH itself).  In addition to the math functions supplied by RXXMATH,
  214. the expression may contain any REXX built-in functions or any external
  215. functions which return a numeric result.
  216.  
  217. If you call the CALC function without any arguments you will go into the
  218. interactive REXX calculator mode ("REXX shell").  From there you can
  219. issue any valid REXX instructions, using any of the math functions
  220. supported by RXXMATH, as well as any other functions or commands usable
  221. from within REXX.  When you enter interactive mode you will be prompted
  222. for input.  The prompt string is contained in the REXX variable
  223. "prompt", and may be altered or suppressed by changing or dropping that
  224. variable.  In addition, if there are lines in the external data queue
  225. the prompt is suppressed while those lines are read and executed.  The
  226. "return" or "exit" instructions will take you out of interactive mode,
  227. and may be used to return a value if desired.
  228.  
  229. The basic RXXMATH math functions are all highly accurate, and the CALC
  230. function inherits their accuracy, but because the CALC function
  231. evaluates arbitrary mathematical expressions in a straightforward
  232. numerical way (rather than symbolically) the need for error analysis is
  233. not eliminated.  Consider the following methods for calculating the
  234. expression "pi() - ln(23)", using the default precision of 9.
  235.  
  236. 1.  a = rxxmath("PI") - rxxmath("LN", 23) /* CALC is avoided. */
  237.  
  238. 2.  queue 'a = pi() - ln(23)'
  239.     queue 'return a'
  240.     b = rxxmath("CALC") /* Interactive CALC (queued instructions). */
  241.  
  242. 3.  c = rxxmath("CALC", "pi() - ln(23)") /* Non-interactive CALC. */
  243.  
  244. Methods 1 and 2 are exactly equivalent, and set a = b = 0.00609843.
  245. Method 3 gives more precision, setting c = 0.00609843766.  In the first
  246. two cases pi() and ln(23) are both calculated (accurately) to 9 places,
  247. and their difference is taken, giving a result with fewer than 9 digits
  248. of precision.  In case 3 RXXMATH calculates both pi() and ln(23) to 18
  249. places, takes the difference, and then rounds the final result to 9
  250. significant digits before returning it, which gives a better result.
  251.  
  252. Note that CALC is itself a perfectly legitimate RXXMATH function, and
  253. therefore can be evaluated by CALC.  For example, you can call CALC
  254. non-interactively while in RXXMATH interactive mode, as was done in
  255. Example 7 above.  Just make sure the argument is a quoted string, or
  256. your expression will be evaluated too early and the benefit lost.
  257.  
  258.  
  259. History:
  260.  
  261. v1.3 (19 Nov 1996)
  262.  
  263. The name of the package was changed from RXMATH to RXXMATH to avoid a
  264. name conflict with an unrelated package of math functions for REXX.
  265.  
  266. The negation operator was changed from "^" (caret) to "\" (backslash).
  267.  
  268. The code that prints a help message when RXXMATH is invoked without
  269. arguments was changed so that it no longer reads the message from the
  270. leading comment using SOURCELINE().  This means the the message will
  271. still print even if RXXMATH is compiled and the comments stripped out.
  272.  
  273. Some built-in REXX functions -- DIGITS(), WORDPOS(), and LINES() -- were
  274. not available when the code was first written, and so were coded
  275. explicitly into the program.  These have been stripped out, on the
  276. assumption that these functions should be included as built-ins in all
  277. current REXX implementations.
  278.  
  279. The documentation was partially rewritten.
  280.  
  281. Other minor changes, mostly for readability.
  282.  
  283. v1.2 (15 Oct 1992)
  284.  
  285. Various changes to make the code SAA compliant.
  286.  
  287. v1.1 (7 Sep 1990)
  288.  
  289. Minor changes for running under MVS/TSO.
  290.  
  291. v1.0 (8 Sep 1989)
  292.  
  293. Original version for VM/CMS.
  294.