;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Introduction to Numbers =Text: 3INTRODUCTION TO NUMBERS* Zetalisp includes several types of numbers, with different characteristics. Most numeric functions accept any type of numbers as arguments and do the right thing. That is to say, they are 1generic*. In Maclisp, there are generic numeric functions (like 2plus*) and there are specific numeric functions (like 2+*) which only operate on a certain type of number, but are much more efficient. In Zetalisp, this distinction does not exist; both function names exist for compatibility but they are identical. The microprogrammed structure of the machine makes it possible to have only the generic functions without loss of efficiency. The types of numbers in Zetalisp are: 2fixnum* Fixnums are 25-bit twos-complement binary integers. These are the preferred, most efficient type of number. 2bignum* Bignums are arbitrary-precision binary integers. 2ratio* Ratios represent rational numbers exactly as the quotient of two integers, each of which can be a fixnum or a bignum. Ratios with a denominator of one are not normally created, as an integer is returned instead. 2single-float or full-size float* Full size floats are floating-point numbers. They have a mantissa of 31 bits and an exponent of 11 bits, providing a precision of about 9 digits and a range of about 10^300. Stable rounding is employed. 2short-float* Short floats are another form of floating-point number, with a mantissa of 17 bits and an exponent of 8 bits, providing a precision of about 5 digits and a range of about 10^38. Stable rounding is employed. Short floats are useful because, like fixnums, and unlike full-size floats, they don't require any storage. Computing with short floats is more efficient than with full-size floats because the operations are faster and consing overhead is eliminated. 2complexnum* Complexnums represent complex numbers with a real part and an imaginary part, which can be any type of number except complexnums. (They must be both rational or both floats of the same type). It is impossible to make a complexnum whose real part is rational and whose imaginary part is the intreger zero; it is always changed into a real number. However, it 1is* possible to create complexnums with an imaginary part of 0.0, and such numbers may result from calculations involving complexnums. In fact, 5.0 and 5.0+0.0i are 1always* distinct; they are not 2eql*, and arithmetic operations will never canonicalize a complexnum with floating-point zero imaginary part into a real number. Generally, Lisp objects have a unique identity; each exists, independent of any other, and you can use the 2eq* predicate to determine whether two references are to the same object or not. Numbers are the exception to this rule; they don't work this way. The following function may return either 2t* or 2nil*. Its behavior is considered undefined; as this manual is written, it returns 2t* when interpreted but 2nil* when compiled. 3(defun foo ()* 3 (let ((x (float 5)))* 3 (eq x (car (cons x nil)))))* This is very strange from the point of view of Lisp's usual object semantics, but the implementation works this way, in order to gain efficiency, and on the grounds that identity testing of numbers is not really an interesting thing to do. So the rule is that the result of applying 2eq* to numbers is undefined, and may return either 2t* or 2nil* on what appear to be two pointers to the same numeric object. The only reasonable ways to compare numbers are 2=* (see 4(NUMBERS-1)Numeric Comparisons*) and 2eql* (4(FLOWCTL-1)Comparison Predicates*), and other things (2equal* or 2equalp*) based on them. Conversely, fixnums and short floats have the unusual property that they are always 2eq* if they are equal in value. This is because they do not point to storage; the ``pointer'' field of a fixnum is actually its numeric value, and likewise for short floats. Stylisticly it is better to avoid depending on this, by using 2eql* rather than 2eq*. Also, comparing floats of any sort for exact equality, even with 2=* which is guaranteed to consider only the numeric values, is usually unwise since round-off error can make the answer unpredictable and meaningless. The distinction between fixnums and bignums is largely transparent to the user. The user simply computes with integers, and the system represents some as fixnums and the rest (less efficiently) as bignums. The system automatically converts back and forth between fixnums and bignums based solely on the size of the integer. There are a few low level functions which only work on fixnums; this fact is noted in their documentation. Also, when using 2eq* on numbers the user needs to be aware of the fixnum/bignum distinction. Integer computations cannot overflow, except for division by zero, since bignums can be of arbitrary size. Floating-point computations can get exponent overflow or underflow, if the result is too large or small to be represented. Exponent overflow always signals an error. Exponent underflow normally signals an error, and assumes 20.0* as the answer if the user says to proceed from the error. However, if the value of the variable 2zunderflow* is non-2nil*, the error is skipped and computation proceeds with 20.0* in place of the result that was too small. When an arithmetic function of more than one argument is given arguments of different numeric types, uniform 1coercion rules* are followed to convert the arguments to a common type, which is also the type of the result (for functions which return a number). When an integer meets a ratio, the result is a ratio. When an integer or ratio meets a float, the result is a float of the same sort. When a short-float meets a full-size float, the result is a full-size float. If any argument of the arithmetic function is complex, the other arguments are converted to complex. The components of a complex result must be both full-size floats, both small-floats, or both rational; if they differ, the one whose type comes last in that list is converted to match the other. Finally, if the components of the result are rational and the imaginary part is zero, the result is simply the real part. If, however, the components are floats, the value is always complex even if the imaginary part is zero. Thus if the constants in a numerical algorithm are written as short floats (assuming this provides adequate precision), and if the input is a short float, the computation is done with short floats and the result is a short float, while if the input is a full-size float the computation is done in full precision and the result is a full-size float. Zetalisp never automatically converts between full-size floats and short floats in the same way as it automatically converts between fixnums and bignums since this would lead either to inefficiency or to unexpected numerical inaccuracies. (When a short float meets a full-size float, the result is a full-size float, but if you use only one type, all the results are of the same type too.) This means that a short float computation can get an exponent overflow error even when the result could have been represented as a full-size float. Floating-point numbers retain only a certain number of bits of precision; therefore, the results of computations are only approximate. Full-size floats have 31 bits and short floats have 17 bits, not counting the sign. The method of approximation is ``stable rounding''. The result of an arithmetic operation is the float which is closest to the exact value. If the exact result falls precisely halfway between two representable floats, the result is rounded down if the least-significant bit is 0, or up if the least-significant bit is 1. This choice is arbitrary but insures that no systematic bias is introduced. Unlike Maclisp, Zetalisp does not have number declarations in the compiler. Note that because fixnums and short floats require no associated storage they are as efficient as declared numbers in Maclisp. Bignums and full-size floats are less efficient; however, bignum and float intermediate results are garbage-collected in a special way that avoids the overhead of the full garbage collector. The different types of numbers can be distinguished by their printed representations. If a number has an exponent separated by `2s*', it is a short float. If a number has an exponent separated by `2f*', it is a full-size float. A leading or embedded (but 1not* trailing) decimal point, and/or an exponent separated by `2e*', indicates a float; which kind is controlled by the variable 2*read-default-float-format**, which is usually set to specify full-size floats. Short floats require a special indicator so that naive users will not accidentally compute with the lesser precision. Fixnums and bignums have similar printed representations since there is no numerical value that has a choice of whether to be a fixnum or a bignum; an integer is a bignum if and only if its magnitude is too big for a fixnum. See the examples on 4(READPRINT-2)What The Reader Accepts*, in the description of what the reader understands. 3zunderflow* 1Variable* When this is 2nil*, floating point exponent underflow is an error. When this is 2t*, exponent underflow proceeds, returning zero as the value. The same thing could be accomplished with a condition handler. However, 2zunderflow* is useful for Maclisp compatibility, and is also faster. 3sys:floating-exponent-overflow* (3sys:arithmetic-error* 3error*) 1Condition* 3sys:floating-exponent-underflow* (3sys:arithmetic-error* 3error*) 1Condition* 2sys:floating-exponent-overflow* is signaled when the result of an arithmetic operation should be a floating point number, but the exponent is too large to be represented in the format to be used for the value. 2sys:floating-exponent-underflow* is signaled when the exponent is too small. The condition instance provides two additional operations: 2:function*, which returns the arithmetic function that was called, and 2:small-float-p*, which is 2t* if the result was supposed to be a short float. 2sys:floating-exponent-overflow* provides the 2:new-value* proceed type. It expects one argument, a new value. 2sys:floating-exponent-underflow* provides the 2:use-zero* proceed type, which expects no argument. Unfortunately, it is not possible to make the arguments to the operation available. Perhaps someday they will be. =Node: Numeric Predicates =Text: 3NUMERIC PREDICATES zerop* 1x* Returns 2t* if 1x* is zero. Otherwise it returns 2nil*. If 1x* is not a number, 2zerop* causes an error. For floats, this only returns 2t* for exactly 20.0* or 20.0s0*. For complex numbers, it returns 2t* if both real and imaginary parts are zero. 3plusp* 1x* Returns 2t* if its argument is a positive number, strictly greater than zero. Otherwise it returns 2nil*. If 1x* is not a number, 2plusp* causes an error. 3minusp* 1x* Returns 2t* if its argument is a negative number, strictly less than zero. Otherwise it returns 2nil*. If 1x* is not a number, 2minusp* causes an error. 3oddp* 1number* Returns 2t* if 1number* is odd, otherwise 2nil*. If 1number* is not a fixnum or a bignum, 2oddp* causes an error. 3evenp* 1number* Returns 2t* if 1number* is even, otherwise 2nil*. If 1number* is not a fixnum or a bignum, 2evenp* causes an error. 3signp* 1test* 1x* 1Special Form* Tests the sign of a number. 2signp* is present only for Maclisp compatibility and is not recommended for use in new programs. 2signp* returns 2t* if 1x* is a number which satisfies the 1test*, 2nil* if it is not a number or does not meet the test. 1test* is not evaluated, but 1x* is. 1test* can be one of the following: 2l* x < 0 2le* x 2* 0 2e* x = 0 2n* x 2* 0 2ge* x 2* 0 2g* x > 0 Examples: 3(signp ge 12) => t* 3(signp le 12) => nil* 3(signp n 0) => nil* 3(signp g 'foo) => nil* See also the data-type predicates 2integerp*, 2rationalp*, 2realp*, 2complexp*, 2floatp*, 2bigp*, 2small-floatp*, and 2numberp* (4(PRIMOBJTYPE-1)Data Type Predicates*). =Node: Numeric Comparisons =Text: 3NUMERIC COMPARISONS* All of these functions require that their arguments be numbers; they signal an error if given a non-number. Equality tests work on all types of numbers, automatically performing any required coercions (as opposed to Maclisp in which generally only the spelled-out names work for all kinds of numbers). Ordering comparisons allow only real numbers, since they are meaningless on complex numbers. 3=* &rest 1numbers* Returns 2t* if all the arguments are numerically equal. They need not be of the same type; 1 and 1.0 are considered equal. Character objects are also allowed, and in effect coerced to integers for comparison. See also 2eql*, 4(FLOWCTL-1)Comparison Predicates*, which insists that both the type and the value match when its arguments are numbers. 3>* &rest 1numbers* 3greaterp* &rest 1numbers* 2>* compares each pair of successive arguments. If any argument is not greater than the next, 2>* returns 2nil*. But if the arguments are monotonically strictly decreasing, the result is 2t*. Zero arguments are always monotonically decreasing, and so is a single argument. Examples: 3(>) => t* 3(> 3) => t* 3(> 4 3) => t* 3(> 4 3 2 1 0) => t* 3(> 4 3 1 2 0) => nil* 2greaterp* is the Maclisp name for this function. 3>=* &rest 1numbers* 1* &rest 1numbers* 2* compares each pair of successive arguments. If any argument is less than the next, 2* returns 2nil*. But if the arguments are monotonically decreasing or equal, the result is 2t*. 2>=* is the Common Lisp name for this function. 3<* &rest 1numbers* 3lessp* &rest 1numbers* 2<* compares each pair of successive arguments. If any argument is not less than the next, 2<* returns 2nil*. But if the arguments are monotonically strictly increasing, the result is 2t*. Examples: 3(<) => t* 3(< 3) => t* 3(< 3 4) => t* 3(< 1 1) => nil* 3(< 0 1 2 3 4) => t* 3(< 0 1 3 2 4) => nil* 2lessp* is the Maclisp name for this function. 3<=* &rest 1numbers* 1* &rest 1numbers* 2* compares its arguments from left to right. If any argument is greater than the next, 2* returns 2nil*. But if the arguments are monotonically increasing or equal, the result is 2t*. 2<=* is the Common Lisp name for this function. 1* &rest 1numbers* 3//=* &rest 1numbers* 2t* if no two arguments are numerically equal. This is the same as 2(not (= ...))* when there are two arguments, but not when there are more than two. With zero or one argument, the value is always 2t*, since there is no pair of arguments that fail to be equal. 2//=* is the Common Lisp name for this function. In Common Lisp syntax, it would be written 2/=*. 3max* &rest 1one-or-more-args* Returns the largest of its arguments, which must not be complex. Example: 3(max 1 3 2) => 3* 2max* requires at least one argument. 3min* &rest 1one-or-more-args* Returns the smallest of its arguments, which must not be complex. Example: 3(min 1 3 2) => 1* 2min* requires at least one argument. =Node: Arithmetic =Text: 3ARITHMETIC* All of these functions require that their arguments be numbers, and signal an error if given a non-number. They work on all types of numbers, automatically performing any required coercions (as opposed to Maclisp, in which generally only the spelled-out versions work for all kinds of numbers, and the `2$*' versions are needed for floats). 3+* &rest 1args* 3plus* &rest 1args* 3+$* &rest 1args* Returns the sum of its arguments. If there are no arguments, it returns 20*, which is the identity for this operation. 2plus* and 2$+* are Maclisp names, supported for compatibility. 3-* 1arg* &rest 1args* 3-$* 1arg* &rest 1args* With only one argument, 2-* returns the negative of its argument. With more than one argument, 2-* returns its first argument minus all of the rest of its arguments. Examples: 3(- 1) => -1* 3(- -3.0) => 3.0* 3(- 3 1) => 2* 3(- 9 2 1) => 6* 2-$* is a Maclisp name, supported for compatibility. 3minus* 1x* Returns the negative of 1x*, just like 2-* with one argument. 3difference* 1arg* &rest 1args* Returns its first argument minus all of the rest of its arguments. If there are at least two arguments, 2difference* is equivalent to 2-*. 3abs* 1x* Returns 2|1x*|*, the absolute value of the number 1x*. 2abs* for real numbers could have been defined as 3(defun abs (x)* 3 (cond ((minusp x) (minus x))* 3 (t x)))* 2abs* of a complex number could be computed, though imprecisely, as 3(sqrt (^ (realpart x) 2) (^ (imagpart x) 2)) ** &rest 1args* 3times* &rest 1args* 3*$* &rest 1args* Returns the product of its arguments. If there are no arguments, it returns 21*, which is the identity for this operation. 2times* and 2*$* are Maclisp names, supported for compatibility. 3//* 1arg* &rest 1args* 3//$* 1arg* &rest 1args* With more than one argument, 2//* it returns the first argument divided by all of the rest of its arguments. With only one argument, 2(// 1x*)* is the same as 2(// 1 1x*)*. The name of this function is written 2//* rather than 2/* because 2/* is the escape character in traditional Lisp syntax and must be escaped in order to suppress that significance. 2//$* is a Maclisp name, supported for compatibility. 2//* of two integers returns an integer even if the mathematically correct value is not an integer. More precisely, the value is the same as the first value returned by 2truncate* (see below). This will eventually be changed, and then the value will be a ratio if necessary so that the it is mathematically correct. All code that relies on 2//* to return an integer value rather than a ratio should be converted to use 2truncate* (or 2floor* or 2ceiling*, which may simplify the code further). In the mean time, use the function 2cli://* if you want a rational result. Examples: 3(// 3 2) => 1 *;Fixnum division truncates. 3(// 3 -2) => -1* 3(// -3 2) => -1* 3(// -3 -2) => 1* 3(// 3 2.0) => 1.5* 3(// 3 2.0s0) => 1.5s0* 3(// 4 2) => 2* 3(// 12. 2. 3.) => 2* 3(// 4.0) => .25 quotient* 1arg* &rest 1args* Returns the first argument divided by all of the rest of its arguments. When there are two or more arguments, 2quotient* is equivalent to 2//*. 3cli://* 1number* &rest 1numbers* This is the Common Lisp division function. It is like 2//* except that it uses exact rational division when the arguments are integers. 2//* will someday be changed to divide integers exactly. Then there will no longer be a distinct function 2cli://*; that name will become equivalent to 2//*. Note that in Common Lisp syntax you would write just 2/* rather than 2cli://*. There are four functions for ``integer division'', the sort which produces a quotient and a remainder. They differ in how they round the quotient to an integer, and therefore also in the sign of the remainder. The arguments must be real, since ordering is needed to compute the value. The quotient is always an integer, but the arguments and remainder need not be. 3floor* 1x* &optional 1(y* 11)* 2floor*'s first value is the largest integer less than or equal to the quotient of 1x* divided by 1y*. The second value is the remainder, 1x* minus 1y* times the first value. This has the same sign as 1y* (or may be zero), regardless of the sign of 1x*. With one argument, 2floor*'s first value is the largest integer less than or equal to the argument. 3ceiling* 1x* &optional 1(y* 11)* 2ceiling*'s first value is the smallest integer greater than or equal to the quotient of 1x* divided by 1y*. The second value is the remainder, 1x* minus 1y* times the first value. This has the opposite sign from 1y* (or may be zero), regardless of the sign of 1x*. With one argument, 2ceiling*'s first value is the smallest integer greater than or equal to the argument. 3truncate* 1x* &optional 1(y* 11)* 2truncate* is the same as 2floor* if the arguments have the same sign, 2ceiling* if they have opposite signs. 2truncate* is the function that the divide instruction on most computers implements. 2truncate*'s first value is the nearest integer, in the direction of zero, to the quotient of 1x* divided by 1y*. The second value is the remainder, 1x* minus 1y* times the first value. This has the same sign as 1x* (or may be zero). 3round* 1x* &optional 1(y* 11)* 2round*'s first value is the nearest integer to the quotient of 1x* divided by 1y*. If the quotient is midway between two integers, the even integer of the two is used. The second value is the remainder, 1x* minus 1y* times the first value. The sign of this remainder cannot be predicted from the signs of the arguments alone. With one argument, 2round*'s first value is the integer nearest to the argument. Here is a table which clarifies the meaning of 2floor*, 2ceiling*, 2truncate* and 2round* with one argument: 3 floor ceiling truncate round* 3 2.6 2 3 2 3* 3 2.5 2 3 2 2* 3 2.4 2 3 2 2* 3 0.7 0 1 0 1* 3 0.3 0 1 0 0* 3 -0.3 -1 0 0 0* 3 -0.7 -1 0 0 -1* 3 -2.4 -3 -2 -2 -2* 3 -2.5 -3 -2 -2 -2* 3 -2.5 -3 -2 -2 -2* 3 -2.6 -3 -2 -2 -3* There are two kinds of remainder function, which differ in the treatment of negative numbers. The remainder can also be obtained as the second value of one of the integer division functions above, but if only the remaineder is desired it is simpler to use these functions. 3\* 1x* 1y* 3remainder* 1x* 1y* 3cli:rem* 1x* 1y* Returns the remainder of 1x* divided by 1y*. 1x* and 1y* must be integers (fixnums or bignums). This is the same as the second value of 2(truncate 1x* 1y*)*. Only the absolute value of the divisor is relevant. 3(\ 3 2) => 1* 3(\ -3 2) => -1* 3(\ 3 -2) => 1* 3(\ -3 -2) => -1* Common Lisp gives this function the name 2rem*, but since 2rem* in traditional Zetalisp is a function to remove elements from lists (see 4(MANLISTSTR-2)Lists as Tables*), the name 2rem* is defined to mean remainder only in Common Lisp programs. Note that the name 2\* would have to be written as 2\\* in Common Lisp syntax; but the function 2\* is not standard Common Lisp. 3mod* 1number* 1divisor* Returns the root of 1number* modulo 1divisor*. This is a number between 0 and 1divisor*, or possibly 0, whose difference from 1number* is a multiple of 1divisor*. It is the same as the second value of 2(floor 1number* 1divisor*)*. Examples: 3(mod 2 5) => 2* 3(mod -2 5) => 3* 3(mod -2 -5) => -2* 3(mod 2 -5) => -3* There are four ``floating point integer division'' functions. These produce a result which is a floating point number whose value is exactly integral. 3ffloor* 1x* &optional 1(y* 11)* 3fceiling* 1x* &optional 1(y* 11)* 3ftruncate* 1x* &optional 1(y* 11)* 3fround* 1x* &optional 1(y* 11)* Like 2floor*, 2ceiling*, 2truncate* and 2round* except that the first value is converted from an integer to a float. If 1x* is a float, then the result is the same type of float as 1x*. 3sys:divide-by-zero* (3sys:arithmetic-error* 3error*) 1Condition* Dividing by zero, using any of the above division functions, signals this condition. The 2:function* operation on the condition instance returns the name of the division function. The 2:dividend* operation may be available to return the number that was divided. 31+* 1x* 3add1* 1x* 31+$* 1x* 2(1+ x)* is the same as 2(+ x 1)*. The other two names are for Maclisp compatibility. 31-* 1x* 3sub1* 1x* 31-$* 1x* 2(1- x)* is the same as 2(- x 1)*. Note that the short name may be confusing: 2(1- 1x*)* does 1not* mean 1-1x*; rather, it means 1x*-1. The names 2sub1* and 21-$* are for Maclisp compatibility. 3gcd* &rest 1integers* 3\\* &rest 1integers* Returns the greatest common divisor of all its arguments, which must be integers. With one argument, the value is that argument. With no arguments, the value is zero. In Common Lisp syntax 2\\* would be written as 2\\\\*, but only the name 2gcd* is valid in strict Common Lisp. 3lcm* 1integer* &rest 1more-integers* Returns the least common multiple of the specified integers. 3expt* 1x* 1y* 3^* 1x* 1y* 3^$* 1x* 1y* Returns 1x* raised to the 1y*'th power. The result is rational (and possibly an integer) if 1x* is rational and 1y* an integer. If the exponent is an integer a repeated-squaring algorithm is used; otherwise the result is 2(exp (* 1y* (log 1x*)))*. If 1y* is zero, the result is 2(+ 1 (* 1x* 1y*))*; this is equal to one, but its type depends on those of 1x* and 1y*. 3sys:zero-to-negative-power* (3sys:arithmetic-error* 3error*) 1Condition* This condition is signaled when 2expt*'s first argument is zero and the second argument is negative. 3sqrt* 1x* Returns the square root of 1x*. A mathematically unavoidable discontinuity occurs for negative real arguments, for which the value returned is a positive real times 2i*. 3(sqrt 4) => 2* 3(sqrt -4) => 0+2i* 3(sqrt -4+.0001i) => .00005+2i *(approximately) 3(sqrt -4-.0001i) => .00005-2i *(approximately) 3isqrt* 1x* Integer square-root. 1x* must be an integer; the result is the greatest integer less than or equal to the exact square root of 1x*. 3*dif* 1x* 1y* 3*plus* 1x* 1y* 3*quo* 1x* 1y* 3*times* 1x* 1y* These are the internal microcoded arithmetic functions. There is no reason why anyone should need to write code with these explicitly, since the compiler knows how to generate the appropriate code for 2plus*, 2+*, etc. These names are only here for Maclisp compatibility. 3%div* 1dividend* 1divisor* The internal division function used by 2cli://*, it was available before 2cli://* was and may therefore be used in some programs. It takes exactly two arguments. Uses of 2%div* should be changed to use 2cli://*.