home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / calc.info-26 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  46KB  |  805 lines
  1. This is Info file calc.info, produced by Makeinfo-1.55 from the input
  2. file calc.texinfo.
  3.    This file documents Calc, the GNU Emacs calculator.
  4.    Copyright (C) 1990, 1991 Free Software Foundation, Inc.
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the section entitled "GNU General Public License" is included
  11. exactly as in the original, and provided that the entire resulting
  12. derived work is distributed under the terms of a permission notice
  13. identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions, except that the section entitled "GNU General Public License"
  17. may be included in a translation approved by the author instead of in
  18. the original English.
  19. File: calc.info,  Node: Argument Qualifiers,  Next: Example Definitions,  Prev: Defining Stack Commands,  Up: Lisp Definitions
  20. Argument Qualifiers
  21. -------------------
  22. Anywhere a parameter name can appear in the parameter list you can also
  23. use an "argument qualifier".  Thus the general form of a definition is:
  24.      (defmath NAME (PARAM PARAM...
  25.                     &optional PARAM PARAM...
  26.                     &rest PARAM)
  27.        BODY)
  28. where each PARAM is either a symbol or a list of the form
  29.      (QUAL PARAM)
  30.    The following qualifiers are recognized:
  31. `complete'
  32.      The argument must not be an incomplete vector, interval, or
  33.      complex number.  (This is rarely needed since the Calculator
  34.      itself will never call your function with an incomplete argument.
  35.      But there is nothing stopping your own Lisp code from calling your
  36.      function with an incomplete argument.)
  37. `integer'
  38.      The argument must be an integer.  If it is an integer-valued float
  39.      it will be accepted but converted to integer form.  Non-integers
  40.      and formulas are rejected.
  41. `natnum'
  42.      Like `integer', but the argument must be non-negative.
  43. `fixnum'
  44.      Like `integer', but the argument must fit into a native Lisp
  45.      integer, which on most systems means less than 2^23 in absolute
  46.      value.  The argument is converted into Lisp-integer form if
  47.      necessary.
  48. `float'
  49.      The argument is converted to floating-point format if it is a
  50.      number or vector.  If it is a formula it is left alone.  (The
  51.      argument is never actually rejected by this qualifier.)
  52. `PRED'
  53.      The argument must satisfy predicate PRED, which is one of the
  54.      standard Calculator predicates.  *Note Predicates::.
  55. `not-PRED'
  56.      The argument must *not* satisfy predicate PRED.
  57.    For example,
  58.      (defmath foo (a (constp (not-matrixp b)) &optional (float c)
  59.                    &rest (integer d))
  60.        BODY)
  61. expands to
  62.      (defun calcFunc-foo (a b &optional c &rest d)
  63.        (and (math-matrixp b)
  64.             (math-reject-arg b 'not-matrixp))
  65.        (or (math-constp b)
  66.            (math-reject-arg b 'constp))
  67.        (and c (setq c (math-check-float c)))
  68.        (setq d (mapcar 'math-check-integer d))
  69.        BODY)
  70. which performs the necessary checks and conversions before executing the
  71. body of the function.
  72. File: calc.info,  Node: Example Definitions,  Next: Calling Calc from Your Programs,  Prev: Argument Qualifiers,  Up: Lisp Definitions
  73. Example Definitions
  74. -------------------
  75. This section includes some Lisp programming examples on a larger scale.
  76. These programs make use of some of the Calculator's internal functions;
  77. *note Internals::..
  78. * Menu:
  79. * Bit Counting Example::
  80. * Sine Example::
  81. File: calc.info,  Node: Bit Counting Example,  Next: Sine Example,  Prev: Example Definitions,  Up: Example Definitions
  82. Bit-Counting
  83. ............
  84. Calc does not include a built-in function for counting the number of
  85. "one" bits in a binary integer.  It's easy to invent one using `b u' to
  86. convert the integer to a set, and `V #' to count the elements of that
  87. set; let's write a function that counts the bits without having to
  88. create an intermediate set.
  89.      (defmath bcount ((natnum n))
  90.        (interactive 1 "bcnt")
  91.        (let ((count 0))
  92.          (while (> n 0)
  93.            (if (oddp n)
  94.                (setq count (1+ count)))
  95.            (setq n (lsh n -1)))
  96.          count))
  97. When this is expanded by `defmath', it will become the following Emacs
  98. Lisp function:
  99.      (defun calcFunc-bcount (n)
  100.        (setq n (math-check-natnum n))
  101.        (let ((count 0))
  102.          (while (math-posp n)
  103.            (if (math-oddp n)
  104.                (setq count (math-add count 1)))
  105.            (setq n (calcFunc-lsh n -1)))
  106.          count))
  107.    If the input numbers are large, this function involves a fair amount
  108. of arithmetic.  A binary right shift is essentially a division by two;
  109. recall that Calc stores integers in decimal form so bit shifts must
  110. involve actual division.
  111.    To gain a bit more efficiency, we could divide the integer into
  112. n-bit chunks, each of which can be handled quickly because they fit
  113. into Lisp integers.  It turns out that Calc's arithmetic routines are
  114. especially fast when dividing by an integer less than 1000, so we can
  115. set n = 9 bits and use repeated division by 512:
  116.      (defmath bcount ((natnum n))
  117.        (interactive 1 "bcnt")
  118.        (let ((count 0))
  119.          (while (not (fixnump n))
  120.            (let ((qr (idivmod n 512)))
  121.              (setq count (+ count (bcount-fixnum (cdr qr)))
  122.                    n (car qr))))
  123.          (+ count (bcount-fixnum n))))
  124.      
  125.      (defun bcount-fixnum (n)
  126.        (let ((count 0))
  127.          (while (> n 0)
  128.            (setq count (+ count (logand n 1))
  129.                  n (lsh n -1)))
  130.          count))
  131. Note that the second function uses `defun', not `defmath'.  Because
  132. this function deals only with native Lisp integers ("fixnums"), it can
  133. use the actual Emacs `+' and related functions rather than the slower
  134. but more general Calc equivalents which `defmath' uses.
  135.    The `idivmod' function does an integer division, returning both the
  136. quotient and the remainder at once.  Again, note that while it might
  137. seem that `(logand n 511)' and `(lsh n -9)' are more efficient ways to
  138. split off the bottom nine bits of `n', actually they are less efficient
  139. because each operation is really a division by 512 in disguise;
  140. `idivmod' allows us to do the same thing with a single division by 512.
  141. File: calc.info,  Node: Sine Example,  Prev: Bit Counting Example,  Up: Example Definitions
  142. The Sine Function
  143. .................
  144. A somewhat limited sine function could be defined as follows, using the
  145. well-known Taylor series expansion for `sin(x)':
  146.      (defmath mysin ((float (anglep x)))
  147.        (interactive 1 "mysn")
  148.        (setq x (to-radians x))    ; Convert from current angular mode.
  149.        (let ((sum x)              ; Initial term of Taylor expansion of sin.
  150.              newsum
  151.              (nfact 1)            ; "nfact" equals "n" factorial at all times.
  152.              (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2.
  153.          (for ((n 3 100 2))       ; Upper limit of 100 is a good precaution.
  154.            (working "mysin" sum)  ; Display "Working" message, if enabled.
  155.            (setq nfact (* nfact (1- n) n)
  156.                  x (* x xnegsqr)
  157.                  newsum (+ sum (/ x nfact)))
  158.            (if (~= newsum sum)    ; If newsum is "nearly equal to" sum,
  159.                (break))           ;  then we are done.
  160.            (setq sum newsum))
  161.          sum))
  162.    The actual `sin' function in Calc works by first reducing the problem
  163. to a sine or cosine of a nonnegative number less than `pi/4'.  This
  164. ensures that the Taylor series will converge quickly.  Also, the
  165. calculation is carried out with two extra digits of precision to guard
  166. against cumulative round-off in `sum'.  Finally, complex arguments are
  167. allowed and handled by a separate algorithm.
  168.      (defmath mysin ((float (scalarp x)))
  169.        (interactive 1 "mysn")
  170.        (setq x (to-radians x))    ; Convert from current angular mode.
  171.        (with-extra-prec 2         ; Evaluate with extra precision.
  172.          (cond ((complexp x)
  173.                 (mysin-complex