Return to ch3.r CVS log

Up to [CSRG BSD Unix] / 43BSD / ucb / lisp / lisplib / manual

Annotation of 43BSD/ucb/lisp/lisplib/manual/ch3.r, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3: 
        !             4: 
        !             5: 
        !             6: 
        !             7: 
        !             8:                          CHAPTER  3
        !             9: 
        !            10: 
        !            11:                     Arithmetic Functions
        !            12: 
        !            13: 
        !            14: 
        !            15: 
        !            16:      This chapter describes FRANZ LISP's functions for doing
        !            17: arithmetic.  Often the same function is known by many names.
        !            18: For example, _a_d_d is also _p_l_u_s, and _s_u_m.  This is  caused  by
        !            19: our  desire  to  be  compatible with other Lisps.  The FRANZ
        !            20: LISP user should avoid using functions with names such as  +
        !            21: and * unless their arguments are fixnums.  The Lisp compiler
        !            22: takes advantage of these implicit declarations.
        !            23: 
        !            24:      An attempt to divide or to generate  a  floating  point
        !            25: result  outside  of the range of floating point numbers will
        !            26: cause a floating exception signal from  the  UNIX  operating
        !            27: system.   The  user  can catch and process this interrupt if
        !            28: desired (see the description of the _s_i_g_n_a_l function).
        !            29: 
        !            30: 
        !            31: 
        !            32:    3.1.  Simple Arithmetic Functions
        !            33: 
        !            34: (add ['n_arg1 ...])
        !            35: (plus ['n_arg1 ...])
        !            36: (sum ['n_arg1 ...])
        !            37: (+ ['x_arg1 ...])
        !            38: 
        !            39:      RETURNS: the sum of the arguments. If no arguments  are
        !            40:               given, 0 is returned.
        !            41: 
        !            42:      NOTE: if the size of the partial sum exceeds the  limit
        !            43:            of a fixnum, the partial sum will be converted to
        !            44:            a bignum.  If any of the arguments  are  flonums,
        !            45:            the  partial  sum  will  be converted to a flonum
        !            46:            when that argument is processed  and  the  result
        !            47:            will thus be a flonum.  Currently, if in the pro-
        !            48:            cess of doing the addition a bignum must be  con-
        !            49:            verted  into  a  flonum  an  error  message  will
        !            50:            result.
        !            51: 
        !            52: 
        !            53: 
        !            54: 
        !            55: 
        !            56: 
        !            57: 
        !            58: 
        !            59: 
        !            60: 9
        !            61: 
        !            62: 9Arithmetic Functions                                     3-1
        !            63: 
        !            64: 
        !            65: 
        !            66: 
        !            67: 
        !            68: 
        !            69: 
        !            70: Arithmetic Functions                                     3-2
        !            71: 
        !            72: 
        !            73: (add1 'n_arg)
        !            74: (1+ 'x_arg)
        !            75: 
        !            76:      RETURNS: its argument plus 1.
        !            77: 
        !            78: (diff ['n_arg1 ... ])
        !            79: (difference ['n_arg1 ... ])
        !            80: (- ['x_arg1 ... ])
        !            81: 
        !            82:      RETURNS: the result of subtracting from n_arg1 all sub-
        !            83:               sequent  arguments. If no arguments are given,
        !            84:               0 is returned.
        !            85: 
        !            86:      NOTE: See the description of add for  details  on  data
        !            87:            type conversions and restrictions.
        !            88: 
        !            89: (sub1 'n_arg)
        !            90: (1- 'x_arg)
        !            91: 
        !            92:      RETURNS: its argument minus 1.
        !            93: 
        !            94: (minus 'n_arg)
        !            95: 
        !            96:      RETURNS: zero minus n_arg.
        !            97: 
        !            98: (product ['n_arg1 ... ])
        !            99: (times ['n_arg1 ... ])
        !           100: (* ['x_arg1 ... ])
        !           101: 
        !           102:      RETURNS: the product  of  all  of  its  arguments.   It
        !           103:               returns 1 if there are no arguments.
        !           104: 
        !           105:      NOTE: See the  description  of  the  function  _a_d_d  for
        !           106:            details  and  restrictions  to the automatic data
        !           107:            type coercion.
        !           108: 
        !           109: (quotient ['n_arg1 ...])
        !           110: (/ ['x_arg1 ...])
        !           111: 
        !           112:      RETURNS: the result of dividing the first  argument  by
        !           113:               succeeding ones.
        !           114: 
        !           115:      NOTE: If there are no arguments, 1  is  returned.   See
        !           116:            the  description  of the function _a_d_d for details
        !           117:            and restrictions of data type coercion.  A divide
        !           118:            by zero will cause a floating exception interrupt
        !           119:            -- see the description of the _s_i_g_n_a_l function.
        !           120: 
        !           121: 
        !           122: 
        !           123: 
        !           124: 
        !           125: 9
        !           126: 
        !           127: 9                                   Printed: January 31, 1984
        !           128: 
        !           129: 
        !           130: 
        !           131: 
        !           132: 
        !           133: 
        !           134: 
        !           135: Arithmetic Functions                                     3-3
        !           136: 
        !           137: 
        !           138: (*quo 'i_x 'i_y)
        !           139: 
        !           140:      RETURNS: the integer part of i_x / i_y.
        !           141: 
        !           142: (Divide 'i_dividend 'i_divisor)
        !           143: 
        !           144:      RETURNS: a list whose car is  the  quotient  and  whose
        !           145:               cadr  is  the  remainder  of  the  division of
        !           146:               i_dividend by i_divisor.
        !           147: 
        !           148:      NOTE: this is restricted to integer division.
        !           149: 
        !           150: (Emuldiv 'x_fact1 'x_fact2 'x_addn 'x_divisor)
        !           151: 
        !           152:      RETURNS: a list of the quotient and remainder  of  this
        !           153:               operation:
        !           154:               ((x_fact1 * x_fact2) + (sign extended) x_addn) / x_divisor.
        !           155: 
        !           156:      NOTE: this  is  useful for creating a bignum arithmetic
        !           157:            package in Lisp.
        !           158: 
        !           159: 
        !           160: 
        !           161:    3.2.  predicates
        !           162: 
        !           163: (numberp 'g_arg)
        !           164: 
        !           165: (numbp 'g_arg)
        !           166: 
        !           167:      RETURNS: t iff g_arg is a  number  (fixnum,  flonum  or
        !           168:               bignum).
        !           169: 
        !           170: (fixp 'g_arg)
        !           171: 
        !           172:      RETURNS: t iff g_arg is a fixnum or bignum.
        !           173: 
        !           174: (floatp 'g_arg)
        !           175: 
        !           176:      RETURNS: t iff g_arg is a flonum.
        !           177: 
        !           178: (evenp 'x_arg)
        !           179: 
        !           180:      RETURNS: t iff x_arg is even.
        !           181: 
        !           182: 
        !           183: 
        !           184: 
        !           185: 
        !           186: 
        !           187: 
        !           188: 
        !           189: 
        !           190: 9
        !           191: 
        !           192: 9                                   Printed: January 31, 1984
        !           193: 
        !           194: 
        !           195: 
        !           196: 
        !           197: 
        !           198: 
        !           199: 
        !           200: Arithmetic Functions                                     3-4
        !           201: 
        !           202: 
        !           203: (oddp 'x_arg)
        !           204: 
        !           205:      RETURNS: t iff x_arg is odd.
        !           206: 
        !           207: (zerop 'g_arg)
        !           208: 
        !           209:      RETURNS: t iff g_arg is a number equal to 0.
        !           210: 
        !           211: (onep 'g_arg)
        !           212: 
        !           213:      RETURNS: t iff g_arg is a number equal to 1.
        !           214: 
        !           215: (plusp 'n_arg)
        !           216: 
        !           217:      RETURNS: t iff n_arg is greater than zero.
        !           218: 
        !           219: (minusp 'g_arg)
        !           220: 
        !           221:      RETURNS: t iff g_arg is a negative number.
        !           222: 
        !           223: (greaterp ['n_arg1 ...])
        !           224: (> 'fx_arg1 'fx_arg2)
        !           225: (>& 'x_arg1 'x_arg2)
        !           226: 
        !           227:      RETURNS: t iff the arguments are in a strictly decreas-
        !           228:               ing order.
        !           229: 
        !           230:      NOTE: In functions _g_r_e_a_t_e_r_p and > the function  _d_i_f_f_e_r_-
        !           231:            _e_n_c_e  is  used to compare adjacent values. If any
        !           232:            of the arguments are non-numbers, the error  mes-
        !           233:            sage will come from the _d_i_f_f_e_r_e_n_c_e function.  The
        !           234:            arguments to > must  be fixnums or both  flonums.
        !           235:            The arguments to >& must both be fixnums.
        !           236: 
        !           237: (lessp ['n_arg1 ...])
        !           238: (< 'fx_arg1 'fx_arg2)
        !           239: (<& 'x_arg1 'x_arg2)
        !           240: 
        !           241:      RETURNS: t iff the arguments are in a strictly increas-
        !           242:               ing order.
        !           243: 
        !           244:      NOTE: In functions _l_e_s_s_p and < the function  _d_i_f_f_e_r_e_n_c_e
        !           245:            is used to compare adjacent values. If any of the
        !           246:            arguments are non numbers, the error message will
        !           247:            come from the _d_i_f_f_e_r_e_n_c_e function.  The arguments
        !           248:            to < may be either fixnums or flonums but must be
        !           249:            the  same type.  The arguments to <& must be fix-
        !           250:            nums.
        !           251: 
        !           252: 
        !           253: 
        !           254: 
        !           255: 9
        !           256: 
        !           257: 9                                   Printed: January 31, 1984
        !           258: 
        !           259: 
        !           260: 
        !           261: 
        !           262: 
        !           263: 
        !           264: 
        !           265: Arithmetic Functions                                     3-5
        !           266: 
        !           267: 
        !           268: (= 'fx_arg1 'fx_arg2)
        !           269: 
        !           270: (=& 'x_arg1 'x_arg2)
        !           271: 
        !           272:      RETURNS: t iff the arguments have the same value.   The
        !           273:               arguments to = must be the either both fixnums
        !           274:               or both flonums.  The arguments to =& must  be
        !           275:               fixnums.
        !           276: 
        !           277: 
        !           278: 
        !           279:    3.3.  Trignometric Functions
        !           280: 
        !           281:            Some of these funtcions are taken from  the  host
        !           282:       math  library,  and  we take no further responsibility
        !           283:       for their accuracy.
        !           284: 
        !           285: (cos 'fx_angle)
        !           286: 
        !           287:      RETURNS: the (flonum)  cosine  of  fx_angle  (which  is
        !           288:               assumed to be in radians).
        !           289: 
        !           290: (sin 'fx_angle)
        !           291: 
        !           292:      RETURNS: the sine of fx_angle (which is assumed  to  be
        !           293:               in radians).
        !           294: 
        !           295: (acos 'fx_arg)
        !           296: 
        !           297:      RETURNS: the (flonum) arc cosine of fx_arg in the range
        !           298:               0 to J.
        !           299: 
        !           300: (asin 'fx_arg)
        !           301: 
        !           302:      RETURNS: the (flonum) arc sine of fx_arg in  the  range
        !           303:               -J/2 to J/2.
        !           304: 
        !           305: (atan 'fx_arg1 'fx_arg2)
        !           306: 
        !           307:      RETURNS: the (flonum) arc tangent of fx_arg1/fx_arg2 in
        !           308:               the range -J to J.
        !           309: 
        !           310: 
        !           311: 
        !           312:    3.4.  Bignum/Fixnum Manipulation
        !           313: 
        !           314: 
        !           315: 
        !           316: 
        !           317: 
        !           318: 
        !           319: 
        !           320: 9
        !           321: 
        !           322: 9                                   Printed: January 31, 1984
        !           323: 
        !           324: 
        !           325: 
        !           326: 
        !           327: 
        !           328: 
        !           329: 
        !           330: Arithmetic Functions                                     3-6
        !           331: 
        !           332: 
        !           333: (haipart bx_number x_bits)
        !           334: 
        !           335:      RETURNS: a fixnum (or bignum) which contains the x_bits
        !           336:               high  bits  of  (_a_b_s _b_x__n_u_m_b_e_r)  if  x_bits is
        !           337:               positive,    otherwise    it    returns    the
        !           338:               (_a_b_s _x__b_i_t_s) low bits of (_a_b_s _b_x__n_u_m_b_e_r).
        !           339: 
        !           340: (haulong bx_number)
        !           341: 
        !           342:      RETURNS: the number of significant bits in bx_number.
        !           343: 
        !           344:      NOTE: the result is equal to the least integer  greater
        !           345:            to or equal to the base two logarithm of one plus
        !           346:            the absolute value of bx_number.
        !           347: 
        !           348: (bignum-leftshift bx_arg x_amount)
        !           349: 
        !           350:      RETURNS: bx_arg shifted left by x_amount.  If  x_amount
        !           351:               is  negative,  bx_arg will be shifted right by
        !           352:               the magnitude of x_amount.
        !           353: 
        !           354:      NOTE: If bx_arg is shifted right, it will be rounded to
        !           355:            the nearest even number.
        !           356: 
        !           357: (sticky-bignum-leftshift 'bx_arg 'x_amount)
        !           358: 
        !           359:      RETURNS: bx_arg shifted left by x_amount.  If  x_amount
        !           360:               is  negative,  bx_arg will be shifted right by
        !           361:               the magnitude of x_amount and rounded.
        !           362: 
        !           363:      NOTE: sticky rounding is done this way: after shifting,
        !           364:            the low order bit is changed to 1 if any 1's were
        !           365:            shifted off to the right.
        !           366: 
        !           367: 
        !           368: 
        !           369:    3.5.  Bit Manipulation
        !           370: 
        !           371: (boole 'x_key 'x_v1 'x_v2 ...)
        !           372: 
        !           373:      RETURNS: the result of the bitwise boolean operation as
        !           374:               described in the following table.
        !           375: 
        !           376:      NOTE: If there are more than 3 arguments, then  evalua-
        !           377:            tion  proceeds  left  to  right with each partial
        !           378:            result becoming the new value of x_v1.  That is,
        !           379:                 (_b_o_o_l_e '_k_e_y '_v_1 '_v_2 '_v_3) =_ (_b_o_o_l_e '_k_e_y (_b_o_o_l_e '_k_e_y '_v_1 '_v_2) '_v_3).
        !           380:            In the following table, * represents bitwise and,
        !           381:            + represents bitwise or, O+ represents bitwise xor
        !           382:            and  _  represents  bitwise  negation  and is the
        !           383:            highest precedence operator.
        !           384: 
        !           385: 
        !           386: 
        !           387: 
        !           388: 
        !           389: 
        !           390: 
        !           391: 
        !           392: 
        !           393: 
        !           394: 
        !           395: 
        !           396: Arithmetic Functions                                     3-7
        !           397: 
        !           398: 
        !           399: 8____________________________________________________________________________________________
        !           400:                                      (boole 'key 'x 'y)
        !           401: 
        !           402: 8________________________________________________________________________________________________________________________________________________________________________________________
        !           403:   key         0          1          2         3         4          5          6         7
        !           404:  result       0        x * y     _ x * y      y      x * _ y       x        x O+ y     x + y
        !           405: 
        !           406:  common
        !           407:  names                  and                          bitclear                xor       or
        !           408: 
        !           409: 8____________________________________________________________________________________________
        !           410: 
        !           411:   key         8          9         10        11         12        13         14        15
        !           412:  result   _ (x + y)   _(x O+ y)     _ x     _ x + y     _ y      x + _ y   _ x + _ y    -1
        !           413:  common
        !           414:  names       nor       equiv               implies                          nand
        !           415: 8____________________________________________________________________________________________
        !           416: 7|8|7|7|7|7|7|7|7|7|7|7|7|7|7|
        !           417: 
        !           418: 
        !           419: 
        !           420: 
        !           421: 
        !           422: 
        !           423: 
        !           424: 
        !           425: 
        !           426: 
        !           427: 
        !           428: 
        !           429: 9                                                                                           |8|7|7|7|7|7|7|7|7|7|7|7|7|7|
        !           430: 
        !           431: 
        !           432: 
        !           433: 
        !           434: 
        !           435: 
        !           436: 
        !           437: 
        !           438: 
        !           439: 
        !           440: 
        !           441: 
        !           442: 
        !           443: 
        !           444: 9
        !           445: (lsh 'x_val 'x_amt)
        !           446: 
        !           447:      RETURNS: x_val shifted left by x_amt if x_amt is  posi-
        !           448:               tive.   If x_amt is negative, then _l_s_h returns
        !           449:               x_val shifted right by the magnitude if x_amt.
        !           450: 
        !           451:      NOTE: This always  returns  a  fixnum  even  for  those
        !           452:            numbers  whose  magnitude  is  so large that they
        !           453:            would normally be represented as a  bignum,  i.e.
        !           454:            shifter  bits  are  lost.   For  more general bit
        !           455:            shifters,  see   _b_i_g_n_u_m-_l_e_f_t_s_h_i_f_t   and   _s_t_i_c_k_y-
        !           456:            _b_i_g_n_u_m-_l_e_f_t_s_h_i_f_t.
        !           457: 
        !           458: (rot 'x_val 'x_amt)
        !           459: 
        !           460:      RETURNS: x_val rotated left by x_amt if x_amt is  posi-
        !           461:               tive.  If  x_amt  is  negative,  then x_val is
        !           462:               rotated right by the magnitude of x_amt.
        !           463: 
        !           464: 
        !           465: 
        !           466:    3.6.  Other Functions
        !           467: 
        !           468:            As noted above, some of the  following  functions
        !           469:       are  inherited  from  the  host math library, with all
        !           470:       their virtues and vices.
        !           471: 
        !           472: 
        !           473: 
        !           474: 
        !           475: 
        !           476: 
        !           477: 
        !           478: 
        !           479: 
        !           480: 9
        !           481: 
        !           482: 9                                   Printed: January 31, 1984
        !           483: 
        !           484: 
        !           485: 
        !           486: 
        !           487: 
        !           488: 
        !           489: 
        !           490: Arithmetic Functions                                     3-8
        !           491: 
        !           492: 
        !           493: (abs 'n_arg)
        !           494: (absval 'n_arg)
        !           495: 
        !           496:      RETURNS: the absolute value of n_arg.
        !           497: 
        !           498: (exp 'fx_arg)
        !           499: 
        !           500:      RETURNS: _e raised to the fx_arg power (flonum) .
        !           501: 
        !           502: (expt 'n_base 'n_power)
        !           503: 
        !           504:      RETURNS: n_base raised to the n_power power.
        !           505: 
        !           506:      NOTE: if either of the arguments are flonums, the  cal-
        !           507:            culation will be done using _l_o_g and _e_x_p.
        !           508: 
        !           509: (fact 'x_arg)
        !           510: 
        !           511:      RETURNS: x_arg factorial. (fixnum or bignum)
        !           512: 
        !           513: (fix 'n_arg)
        !           514: 
        !           515:      RETURNS: a fixnum as close as we can get to n_arg.
        !           516: 
        !           517:      NOTE: _f_i_x will round down.  Currently, if  n_arg  is  a
        !           518:            flonum  larger  than  the  size of a fixnum, this
        !           519:            will fail.
        !           520: 
        !           521: (float 'n_arg)
        !           522: 
        !           523:      RETURNS: a flonum as close as we can get to n_arg.
        !           524: 
        !           525:      NOTE: if n_arg is a bignum larger than the maximum size
        !           526:            of  a  flonum,  then  a  floating  exception will
        !           527:            occur.
        !           528: 
        !           529: (log 'fx_arg)
        !           530: 
        !           531:      RETURNS: the natural logarithm of fx_arg.
        !           532: 
        !           533: (max 'n_arg1 ... )
        !           534: 
        !           535:      RETURNS: the maximum value in the list of arguments.
        !           536: 
        !           537: 
        !           538: 
        !           539: 
        !           540: 
        !           541: 
        !           542: 
        !           543: 
        !           544: 
        !           545: 9
        !           546: 
        !           547: 9                                   Printed: January 31, 1984
        !           548: 
        !           549: 
        !           550: 
        !           551: 
        !           552: 
        !           553: 
        !           554: 
        !           555: Arithmetic Functions                                     3-9
        !           556: 
        !           557: 
        !           558: (min 'n_arg1 ... )
        !           559: 
        !           560:      RETURNS: the minimum value in the list of arguments.
        !           561: 
        !           562: (mod 'i_dividend 'i_divisor)
        !           563: (remainder 'i_dividend 'i_divisor)
        !           564: 
        !           565:      RETURNS: the remainder when i_dividend  is  divided  by
        !           566:               i_divisor.
        !           567: 
        !           568:      NOTE: The sign of the result will have the same sign as
        !           569:            i_dividend.
        !           570: 
        !           571: (*mod 'x_dividend 'x_divisor)
        !           572: 
        !           573:      RETURNS: the  balanced  representation  of   x_dividend
        !           574:               modulo x_divisor.
        !           575: 
        !           576:      NOTE: the  range  of  the  balanced  representation  is
        !           577:            abs(x_divisor)/2    to    (abs(x_divisor)/2)    -
        !           578:            x_divisor + 1.
        !           579: 
        !           580: (random ['x_limit])
        !           581: 
        !           582:      RETURNS: a fixnum between 0 and x_limit - 1 if  x_limit
        !           583:               is  given.   If x_limit is not given, any fix-
        !           584:               num, positive or negative, might be returned.
        !           585: 
        !           586: (sqrt 'fx_arg)
        !           587: 
        !           588:      RETURNS: the square root of fx_arg.
        !           589: 
        !           590: 
        !           591: 
        !           592: 
        !           593: 
        !           594: 
        !           595: 
        !           596: 
        !           597: 
        !           598: 
        !           599: 
        !           600: 
        !           601: 
        !           602: 
        !           603: 
        !           604: 
        !           605: 
        !           606: 
        !           607: 
        !           608: 
        !           609: 
        !           610: 9
        !           611: 
        !           612: 9                                   Printed: January 31, 1984
        !           613: 
        !           614: 
        !           615: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.