Skip to main content

Full text of "symbolics :: software :: open genera :: Symbolics Common Lisp Dictionary"

See other formats


Job ID: printopdf-22 
Title: Symbolics Common Lisp Dictio) 
Requesting User: genera 

Billing Info: {job-billing} 



iry 




£asy 
Coftware 
products 



Symbolics Common Lisp Dictionary 



^ number &rest numbers Function 

In your new programs, we recommend that you use function =, which is the Com- 
mon Lisp equivalent of ^. 

Returns t if number is not numerically equal to any of numbers, and nil otherwise. 
Either argument can be of any numeric type. 



< number &rest more-numbers Function 

In your new programs, we recommend that you use function <=, which is the Com- 
mon Lisp equivalent of <. 

< compares its arguments from left to right. If any argument is greater than the 
next, < returns nil. But if the arguments are monotonically increasing or equal, 
the result is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 
Examples: 

(< 5) => T 

(< 1 2 3) => T 

(< 3 6 2 8) => NIL 

(< 5 6.3) => T 



> number &rest more-numbers Function 

In your new programs, we recommend that you use function >= which is the Com- 
mon Lisp equivalent of >. 

> compares its arguments from left to right. If any argument is less than the next, 

> returns nil. But if the arguments are monotonically decreasing or equal, the re- 
sult is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 
Examples: 

(> 8) => T 

(> 3 2 2 1) => T 

(> 5 4 6 2) => NIL 

(> 6.02s23 6.02d23) => T 



+ &rest numbers Function 

Returns the sum of its arguments. If there are no arguments, it returns 0, which 

is the identity for this operation. An error signals if any argument is a non- 
number. 



Page 836 



If the arguments are of different numeric types, they are converted to a common 
type, which is also the type of the result. See the section "Coercion Rules for 
Numbers". 

Examples: 

(+) => 

(+ -8) => -8 

(+ 1 2 3 4) => 10 

(+ 2 5.9) => 7.9 

(+ 5/2 2 2/3) => 31/6 

When using Genera, the following functions are synonyms of + : 

zhplus 
zl:+$ 

For a table of related items, see the section "Arithmetic Functions". 



+ Variable 

While a form is being evaluated by a read-eval-print loop, + is bound to the previ- 
ous form that was read by the loop. Variable ++ is likewise bound to the penulti- 
mate evaluated form, and +++ to the form whose evaluation is removed from the 
form currently undergoing evaluation. 

(floor 5 2) => 2 1 
(eval +) => 2 1 



++ Variable 

Holds the previous value of +, that is, the form evaluated two interactions ago. 

+++ Variable 

Holds the previous value of ++, that is, the form evaluated three interactions ago. 

zl:+$ &rest args Function 

Returns the sum of its arguments. If there are no arguments, it returns 0, which 
is the identity for this operation. 

The following functions are synonyms of zl:+$ : 
zhplus 



number &rest more-numbers Function 



Page 837 



With only one argument, returns the negative of its argument. With more than 
one argument, - returns its first argument minus all of the rest of its arguments. 
In this way, - serves the dual function of a unary minus and polyadic minus. 
However, this can cause confusion, particularly when used with apply or given an 
unexpected number of arguments. 

If the arguments are of different numeric types they are converted to a common 
type, which is also the type of the result. See the section "Coercion Rules for 
Numbers". 

Examples: 

8) => -8 

9 3) => 6 

9 4 2 1) => 2 

#C(3 4) 4) => #C(-1 4) 

9 5/6) => 49/6 

1 2 3 4) => -8 

When using Genera, the following function is a synonym of - : 

zl:-$ 

For a table of related items, see the section "Arithmetic Functions". 



Variable 

While a form is being evaluated by a read-eval-print loop, - is bound to the form 
itself. 



(print -) prints: (print -) 



zl:-$ arg &rest args Function 

With only one argument, returns the negative of its argument. With more than 
one argument, zl:-$ returns its first argument minus all the rest of its arguments. 

The following function is a synonym of zl:-$ : 



zl:/ number &rest more-numbers Function 

In your new programs, we recommend that you use the function /, which is the 
Common Lisp equivalent of the function /. 

With more than one argument, / is the same as zhquotient; it returns the first ar- 
gument divided by all of the rest of its arguments. With only one argument, (/ x) 
is the same as (/ 1 x). 

With integer arguments, / acts like truncate, except that it returns only a single 
value, the quotient. 



Page 838 



Note that in Zetalisp syntax / is the quoting character and must therefore be dou- 
bled. 



; Integer division truncates. 



Examples: 

(zl :/ 3 2) => 1 

(zl :/ 3 -2) => -1 

(zl :/ -3 2) => -1 

(zl :/ -3 -2) => 1 

(zl :/ 3 2.0) => 1 .5 

(zl :/ 3 2.0d0) => 1 .5d0 

(zl :/ 4 2) => 2 

(zl :/ 12. 2. 3.) => 2 

(zl :/ 4.0) => .25 

The following function is a synonym of / : 

zl:/$ 

For a table of related items, see the section "Arithmetic Functions". 



/ number &rest more-numbers 



Function 



With more than one argument, / successively divides the first argument by all the 
others and returns the result. With one argument, / returns the reciprocal of the 
argument: (/ x) is the same as (/ 1 x). If the arguments are of different numeric 
types, they are converted to a common type, which is also the type of the result. 
See the section "Coercion Rules for Numbers". 

/ follows normal mathematical rules, so if the mathematical quotient of two inte- 
gers is not an exact integer, the function returns a ratio. To obtain an integer re- 
sult, use one of these functions: floor, ceiling, truncate, round. 

(/ 4) => 1/4 



(/ 4.0) => 0.25 

(/ 9 3) => 3 

(/ 18 4) => 9/2 

(/ 101 10.0) => 10.1 

(/ 101 10) => 101/10 

(/ 24 4 2) => 3 

(/ 36. 4. 3.) => 3 

(/ 36.0 4.0 3.0) => 3.0 

(/ tfc(1 1) tfc(1 -1)) => tfc(0 1) 

(/ #c(3 4) 5) => #c(3/5 4/5) 



; returns rational number in canonical form 
;applies coercion rules 



For a table of related items, see the section "Arithmetic Functions". 



zl:/$ arg &rest args 



Function 



With more than one argument, zl-user:$ is the same as zhquotient; it returns the 
first argument divided by all of the rest of its arguments. With only one argu- 
ment, (zl-user:$ x) is the same as (zl-user:$ 1 x). 



Page 839 



With integer arguments, zl-user:$ acts like truncate, except that it returns only a 
single value, the quotient. 

Note that in Zetalisp syntax zl:/ is the quoting character and must therefore be 
doubled. 

The following function is a synonym of zl-user:$: 
zl:/ 



/= number &rest numbers Function 

Returns t if all arguments are not equal, and nil otherwise. Arguments can be of 
any numeric type; the rules of coercion are applied for arguments of different nu- 
meric types. 

Two complex numbers are considered = if their real parts are = and their imagi- 
nary parts are =. 

Examples: 

(/= 4) => T 

(/= 4 4.0) => NIL 

(/= 4 #c(4.0 0)) => NIL 

(/= 4 5) => T 

(/= 4 5 6 7) => T 

(/= 4 5 6 7 4) => NIL 

(/= 4 5 4 7 4) => NIL 

(/= tfc(3 2) tfc(2 3) tfc(2 -3)) => T 

(/= tfc(3 2) tfc(2 3) tfc(2 -3) tfc(2 3.0)) => NIL 

When using Genera, the following function is a synonym of /= : 

For a table of related items, see the section "Numeric Comparison Functions". 

/ Variable 

While a form is being evaluated by a read-eval-print loop, / is bound to a list of 
the results printed the last time through the loop. 

If you are using CLOE, variable / is bound to the list of values returned by the 
last evaluated form. Variable // is bound to the list of values returned by the 
penultimate evaluated form, and variable /// is bound to the list of values re- 
turned by the form evaluated three before the current form. 

(floor 5 2) => 2, 1 
/ => (2 1) 



// Variable 



Page 840 



Holds the previous value of user::////////////////, that is, the list of results printed two 
times through the loop ago. 



/// Variable 

Holds the previous value of user::////////////////////////////////, that is, the list of results 
printed three times through the loop ago. 



< number &rest more-numbers Function 

Compares its arguments from left to right. If any argument is not less than the 
next, < returns nil. But if the arguments are monotonically strictly increasing, the 
result is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 
An error is returned if any of the arguments are complex or not numbers. 

Examples: 

(< 3 4) => T 

(< 1 1 .0) => NIL 

(< 1/2 2.0 3 4) => T 

(< 1 3 2 4) => NIL 

(< 5/2 5) => t 

(< 3 3.12) => t 

When using Genera, the following function is a synonym of < : 

zhlessp 

For a table of related items, see the section "Numeric Comparison Functions". 

<= number &rest more-numbers Function 

Compares its arguments from left to right. If any argument is greater than the 
next, <= returns nil. But if the arguments are monotonically increasing or equal, 
the result is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 
An error is returned if any of the arguments are complex or not numbers. 

Examples: 

(<= 8) => T 

(<= 3 4) => T 

(<= 1 1) => T 

(<= 1 1.0) => T 

(<= 1/2 2.0 3 4) => T 

(<= 1 3 2 4) => NIL 

(<= 1 3 3 4) => T 

(<= 5 5/2) => nil 

(<= 3 3.0 3.5 4) => t 



Page 841 



When using Genera, the following function is a synonym of <= : 

< 

For a table of related items, see the section "Numeric Comparison Functions". 



= number &rest more-numbers Function 

Tests for numeric equality of numbers, and works for any type of number. Differs 
from eq in that non-identical but numerically equal numbers will not be eq but 
will be =. Differs from eql in that numerically equal numbers need not be of the 
same type to be =. Returns t if all arguments are numerically equal. 

= takes arguments of any numeric type; the arguments can be of dissimilar numer- 
ic types. 

Examples: 

8) => T 

3 4) => NIL 

3 3.0 3.0d0) => T 

4 #C(4 0) #C(4.0 0.0) #C(4.0d0 0.0d0)) => T 
0.0) => t 
#c(1 2) #c(1 .0 2.0)) => t 

For a discussion of non-numeric equality predicates, see the section "Comparison- 
performing Predicates". 

For a table of related items, see the section "Numeric Comparison Functions". 



> number &rest more-numbers Function 

Compares its arguments from left to right. If any argument is not greater than 
the next, > returns nil. But if the arguments are monotonically strictly decreasing, 
the result is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 
An error is returned if any of the arguments are complex or not numbers. 

Examples: 

(> 4 3.0) => T 

(> 4 3 2 1/2 0) => T 

(> 4 3 1 2 0) => NIL 

(> 4 3) => t 

(> 3 3 2) => nil 

When using Genera, the following function is a synonym of > : 

zhgreaterp 

For a table of related items, see the section "Numeric Comparison Functions". 



>= number &rest more-numbers Function 



Page 842 



Compares its arguments from left to right. If any argument is less than the next, 
>= returns nil. But if the arguments are monotonically decreasing or equal, the re- 
sult is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 
An error is returned if any of the arguments are complex or not numbers. 

Examples: 

(>= 8) => T 

(>= 4 3.0) => T 

(>= 4 3 2 1 0) => T 

(>= 4 2 3 1 0) => NIL 

(>= 4 3 3 2 1/2 0) => T 

(>= 4 3) => t 

(>= 3 3 2) => t 

When using Genera, the following function is a synonym of >= : 

> 

For a table of related items, see the section "Numeric Comparison Functions". 

zl:\\ x y Function 

In your new programs, we recommend that you use either the function rem or 
remainder which are the Common Lisp equivalents of the function zl- 
user:\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 

\\\\\\\\\\\\\^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 

Returns the remainder of x divided by y. x and y must be integers. 

zl- 

user:\\\\\\\\\\\\M^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 

\\\\\\\\\\\\\^^^ 

\\\\\\\\\\\\\\\M^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 

\\\\\\\\\\\\\\\M^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 

\\\\\\\\\\\\\\\M^^ 

acts like truncate, except that it returns only a single value, the remainder. 



Page 843 



Examples: 

(zl :\\ 3 2) => 1 

(zl :\\ -3 2) => -1 

(zl :\\ 3 -2) => 1 

(zl :\\ -3 -2) => -1 

The following functions are synonyms for zl- 

user:\\\\\\\\\\\\\\\\\m 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\W^^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\M^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 

rem 
zhremainder 

Note: In programs using the Zetalisp syntax you would represent zl- 

user:\\\\\\\\\\\\\\\\\m 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\M^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 

as \. The function is represented here as zl- 

user:\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\W^^^^ 

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^^^ 
\\\\\\\\\\\\\\\\\\\\\\\\\\\\^^^ 
\\\\\\\\\\\\\\\M^^ 
\\\\\\\\\\\\\\\M^^ 
\\\\\\\\\\\\\\\M^^ 
\\\\\\\\\\\\\\\M^^ 

because all objects in this manual are represented as if printed by prinl with 

*package* bound to the Common Lisp readtable. In Common Lisp, the backslash 

character (\) is the escape character and must be doubled. 

zl:\\ x y &rest args Function 



Page 844 



Returns the remainder of x divided by y. The arguments must be integers. 

The following functions are synonyms of \\: 

zhremainder 
rem 

We recommend that you use rem in new programs. 

Note: In programs using the Zetalisp syntax you would represent W as \. The func- 
tion is represented here as \\ only because all objects in this manual are represent- 
ed as if printed by prinl with *package* bound to the Common Lisp readtable. In 
Common Lisp, the backslash character (\) is the escape character and must be 
doubled. 

zl: A x y Function 

Returns x raised to the yth power. The result is an integer if both arguments are 
integers (even if y is negative!) and floating-point if either x or y or both is float- 
ing-point. If the exponent is an integer a repeated-squaring algorithm is used, 
while if the exponent is floating the result is (exp (* y (log x))). 



The following functions are synonyms of zl: 

zhexpt 
zl:"$ 



zl:^$ x y Function 

Returns x raised to the yth power. The result is an integer if both arguments are 
integers (even if y is negative!) and floating-point if either x or y or both is float- 
ing-point. If the exponent is an integer a repeated-squaring algorithm is used, 
while if the exponent is floating the result is (exp (* y (log x))). 

The following functions are synonyms of zl:^$ : 

zhexpt 
zl: A 



* &rest numbers Function 

Returns the product of its arguments. If there are no arguments, it returns 1, 
which is the identity for this operation. 

If the arguments are of different numeric types they are converted to a common 
type, which is also the type of the result. See the section "Coercion Rules for 
Numbers". 

Examples: 



Page 845 



(*) => 1 

(* 4 6) => 24 

(* 1 2 3 4) => 24 

(* 2.5 4) => 10.0 

(* 3.0s4 10) => 300000.0 

(* 1.0 2.0 3/2 4/3) => 4.0 

(* #c(1.0 2.0) 3/2 #c(2 4/3)) => #c(-1.0 8.0) 

When using Genera, the following functions are synonyms of * : 

zktimes 
zl:*$ 

For a table of related items, see the section "Arithmetic Functions". 



* Variable 

While a form is being evaluated by a read-eval-print loop, * is bound to the result 
printed the last time through the loop. If several values were printed (because of a 
multiple-value return), * is bound to the first value. If no result was printed, * is 
not changed. Variable ** is bound to the value returned by the penultimate evalu- 
ated form, and *** is bound to the value returned by the form evaluated three be- 
fore the current form. The star forms always return only a single value. 

(floor 5 2) => 2, 1 
* => 2 



** Variable 

Holds the previous value of *, that is, the result of the form evaluated two interac- 
tions ago. 



*** Variable 

Holds the previous value of **, that is, the result of the form evaluated three in- 
teractions ago. 



zl:*$ &rest args Function 

Returns the product of its arguments. If there are no arguments, it returns 1, 
which is the identity for this operation. 

The following functions are synonyms of zl:*$ : 
zktimes 



1+ number Function 



Page 846 



(1+ number) is the same as (+ number 1). 
Examples: 

(1+ 5) => 6 

(1+ 3.0d0) => 4.0d0 

(1+ 3/2) => 5/2 

(1+ #C(4 5)) => #C(5 5) 

When using Genera, the following functions are synonyms of 1+ : 

zhaddl 
zl:l+$ 

For a table of related items: See the section "Arithmetic Functions". 

zl:l+$ x Function 

(zl:l+$ x) is the same as (+ x 1). 

The following functions are synonyms of zl:l+$ : 

zhaddl 
1+ 



1- number Function 

(1- number) is the same as (- number 1). Note that this name might be confusing: 

(1- number) does not mean 1 - number; rather, it means number - 1. 

Examples: 

(1- 9) => 8 
(1- 4.0) => 3.0 
(1- 4.0d0) => 3.0d0 
(1- #C(4 5)) => #C(3 5) 

When using Genera, the following functions are synonyms of 1- : 

zhsubl 
zl:l-$ 

For a table of related items: See the section "Arithmetic Functions". 



zl:l-$ x Function 

(zl:l-$ x) is the same as (- x 1). 
The following functions are synonyms of zl:l-$ : 
zhsubl 



sys:%ld-aloc array index Function 



Page 847 



Returns a locative pointer to the array element-cell selected by the index. sys:%ld- 
aloc is like zhaloc, except that it ignores the the number of dimensions of the ar- 
ray and acts as if it were a one-dimensional array by linearizing the multidimen- 
sional elements. 

Current style suggests that you should use (locf (sys:%ld-aref | ... | )) instead of 
sys:%ld-aloc. 

When using sys:%ld-aloc it is necessary to understand how arrays are stored in 
memory: See the section "Row-major Storage of Arrays". 

For an example of accessing elements of a multidimensional array as if it were a 
one-dimensional array: See the function sys:%ld-aref. 

For a table of related items: See the section "Accessing Multidimensional Arrays 
as One-dimensional". 



sys:%ld-aref array index Function 

Returns the element of array selected by the index. sys:%ld-aref is the same as 
aref, except that it ignores the number of dimensions of the array and acts as if it 
were a one-dimensional array by linearizing the multidimensional elements, copy- 
array-portion uses this function. 

For example: 

(setq *array* (make-array '(20 30 50))) => #<Art-Q-20-30-50 5023116> 
(setf (aref xarrayx 5 6 7) 'foo) => F00 

;;; The following three forms have the same effect, 
(aref xarrayx 5 6 7) => FOO 



(sys 
(sys 
(sys 



%1d-aref xarrayx (+ (* (+ (* 5 30) 6) 50) 7)) => FOO 
%1d-aref xarrayx (array-row-major-index xarrayx)) => FOO 
%1d-aref xarrayx (array-row-major-index xarrayx 5 6 7)) => FOO 



When using sys:%ld-aref it is necessary to understand how arrays are stored in 
memory: See the section "Row-major Storage of Arrays". 

For a table of related items: See the section "Accessing Multidimensional Arrays 
as One-dimensional". 



sys:%ld-aset value array index Function 

Stores a value into the specified array element, selected by the index. sys:%ld-aset 
is the same as zhaset, except that it ignores the number of dimensions of the ar- 
ray and acts as if it were a one-dimensional array. 

copy-array-portion uses this function. 

Current style suggests that you should use (setf (sys:%ld-aref | ... | )) instead of 
sys:%ld-aset. 



Page 848 



When using sys:%ld-aset it is necessary to understand how arrays are stored in 
memory: See the section "Row-major Storage of Arrays". 

For an example of accessing elements of a multidimensional array as if it were a 
one-dimensional array: See the function sys:%ld-aref. 

For a table of related items: See the section "Accessing Multidimensional Arrays 
as One-dimensional". 



2d-array-blt alu nrows ncolumns from-array from-row from-column to-array to-row 
to-column Function 

Copies a rectangular portion of from-array into a portion of to-array. 2d-array-blt 
is similar to bitblt but takes (row,column) style arguments on two-dimensional ar- 
rays, while bitblt takes (x,y) arguments on rasters. 

The number of columns in from-array times the number of bits per element must 
be a multiple of 32. The same is true for to-array. 

This can be used on sysrart-fixnum or sys:art-lb, sys:art-2b,... sys:art-16b arrays. 
It can also be used on sys:art-q arrays provided all the elements are fixnums. 

For a table of related items: See the section "Copying an Array". 



sys:%32-bit-difference fixnuml fixnum2 Function 

Returns the difference of fixnuml and fixnum2 in 32-bit two's complement arith- 
metic. Both arguments must be fixnums. The result is a fixnum. 

For a table of related items, see the section "Machine-Dependent Arithmetic Func- 
tions". 



sys:%32-bit-plus fixnuml fixnum2 Function 

Returns the sum of fixnuml and fixnum2 in 32-bit two's complement arithmetic. 
Both arguments must be fixnums. The result is a fixnum. 

For a table of related items, see the section "Machine-Dependent Arithmetic Func- 
tions". 



abs number Function 

Returns | number \ , the absolute value of number. For noncomplex numbers, abs 
could have been defined by: 

(defun abs (number) 

(cond ((minusp number) (minus number)) 
(t number))) 

Note that if number is equal to negative zero in IEEE floating-point format the 
above algorithm returns -0.0. 



Page 849 



For complex numbers, abs could have been defined by: 

(defun abs (number) 

(sqrt (+ (~ (real part number) 2) (~ (imagpart number) 2)))) 

(abs 81) => 81 

(abs -81 .0) => 81 .0 

(abs #c(3 4)) => 5.0 
See the function phase. 
For a table of related items, see the section "Arithmetic Functions". 

aeons key datum alist Function 

Constructs a new association list by adding the pair {key . datum) onto the front of 
alist. aeons returns a new association list which has the new key and datum pair 
added to it. See the section "Association Lists". This is equivalent to using the 
cons function on key and datum, and consing it onto the old list as follows: 

(aeons key datum alist) = (cons (cons key datum) alist) 

Example: 

(setq bird-alist '((wader . heron) (raptor . eagle))) => 
((WADER . HERON) (RAPTOR . EAGLE)) 

(aeons 'diver 'loon bird-alist) => 

((DIVER . LOON) (WADER . HERON) (RAPTOR . EAGLE)) 

bi rd-al ist => 

((WADER . HERON) (RAPTOR . EAGLE)) 

In the following example, aeons updates the association list of tenured professors 
and their classes. 

(setq professors-with-tenure 
'(("smith" . (CS202 CS231)) 

("parks" . (CS221)) ("hunter" . (CS216 CS232)))) 

(setq professors-with-tenure 

(aeons "Jones" (list CS101 CS242) 
professors-with-tenure)) 

(professors-with-tenure 

'(("Jones" . (CS101 CS242)) ("smith" . (CS202 CS231)) 
("parks" . (CS221)) ("hunter" . (CS216 CS232)))) 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 



Page 850 



acos number Function 

Computes and returns the arc cosine of the argument (that is, the angle whose co- 
sine is equal to number). The result is in radians. 

The argument can be any noncomplex or complex number. Note that if the abso- 
lute value of number is greater than one, the result is complex, even if the argu- 
ment is not complex. 

The arc cosine being a mathematically multiple-valued function, acos returns a 
principal value whose range is that strip of the complex plane containing numbers 
with real parts between and %. The range excludes any number with a real part 
equal to zero and a negative imaginary part, as well as any number with a real 
part equal to jt and a positive imaginary part. 

Examples: 

(acos 1) => 0.0 

(acos 0) => 1.5707964 ; 31/2 radians 

(acos -1) => 3.1415927 ; % 

(acos 2) => #C(0.0 1.3169578) 

(acos -2) => #C(3. 1415927 -1.316958) 

(acos (/ (sqrt 2) 2)) => 0.785398 

For a table of related items, see the section "Trigonometric and Related 
Functions". 



acosh number Function 

Computes and returns the hyperbolic arc cosine of the argument (that is, the angle 
whose cosh is equal to number). The result is in radians. 

The argument can be any noncomplex or complex number, except -1. Note that if 
the value of number is less than one, the result is complex, even if the argument 
is not complex. The hyperbolic arc cosine being mathematically multiple-valued in 
the complex domain, acosh returns a principal value whose range is that half-strip 
of the complex plane containing numbers with a non-negative real part and an 
imaginary part between -n and % (inclusive). A number with real part zero is in 
the range if its imaginary part is between zero (inclusive) and tc (inclusive). 

Example: 

(acosh 1) => 0.0 ; (cosh 0) => 1.0 
(acosh -2) => #c(1. 316958 3.1415927) 

For a table of related items, see the section "Hyperbolic Functions". 



closradd-method generic-function method Generic Function 

Adds method to generic-function and returns the modified generic- function. 
closradd-method is the underlying mechanism of the closrdefmethod macro. 

generic-function A generic function object. 



Page 851 



method A method object. 

If the generic function already has a method with the same parameter specializers 
and qualifiers as method, then the existing method is replaced with method. 

An error is signaled if: 

• The lambda-list of the method is not congruent with the lambda-list of the 
generic function. 

• The method object is already attached to a different generic function object. 



zhaddl x Function 

(zhaddl x) is the same as (+ x 1). 

The following functions are synonyms of zhaddl: 

1+ 

zl:l+$ 



adjoin item list &key (:test #'eql) :test-not (:key #'identityj (:area sys:default-cons- 
areaj .-localize .-replace 

Function 

Adds an element to a set, provided it is not already a member. If item is added, 
the noew cons is returned. Otherwise, list is returned. The keywords are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. This func- 
tion is applied to both item and members of list. 

rlocalize Can be nil, t, or a positive integer when using Genera: 

nil Does not localize the top level of the list 

before returning the list. 

t Localizes the top level of list structure, by 

calling sys:localize-list or sys:localize-tree 

on the list before returning it. 



Page 852 



integer Localizes integer levels of list structure, by 

calling sys:localize-list or sys:localize-tree 

on the list before returning it. 

rreplace Destructively modifies the specified element (or elements) and 

replaces it with the value provided, rreplace's value can be t 
or nil. Not available in CLOE. 

Note that, since adjoin adds an element only if it is not already a member, the 
sense of :test and :test-not have inverted effect: with :test, an item is added to 
the list only if there is no element of the list for which the predicate returns t. 
With :test-not, an item is added if there is no element for which the predicate re- 
turns nil. 

When :test is eql, the default, then: 

(adjoin item list) = (if (member item list) list (cons item list)) 

Here are some examples: 

(setq bird-list '((loon . diver) (heron . wader))) => 
((LOON . DIVER) (HERON . WADER)) 

(setq bird-list (adjoin '(eagle . raptor) bird-list :key #'car)) => 
((EAGLE . RAPTOR) (LOON . DIVER) (HERON . WADER)) 

(adjoin '(eagle . oops) bird-list :key #'car) => 
((EAGLE . RAPTOR) (LOON . DIVER) (HERON . WADER)) 

(setq add-to-list '(j-jones "John Jones" "acct rep")) 

(setq list (adjoin add-to-list list 

:test tt'string-equal :key tf'cadr)) 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 

Compatibility Note: The keywords :area, rlocalize, and rreplace are Symbolics ex- 
tension to Common Lisp, not available in CLOE. 



adjust-array array new-dimensions &key -.element-type -.initial-element -.initial- 
contents -.fill-pointer :displaced-to :displaced-index-offset :displaced-conformally 

Function 

Changes the dimensions of an array. It returns an array of the same type and 
rank as array, but with the new-dimensions. The number of new-dimensions must 
equal the rank of the array. All elements of array that are still in the bounds are 
carried over to the new array. 

:element-type specifies that elements of the new array are required to be of a cer- 
tain type. An error is signalled if array contains elements that are not of that 
type. :element-type thus provides an error check. 



Page 853 



rinitial-element allows you to specify an initial element for any elements of the 
new array that are not in the bounds of array. 

The rinitial-contents and : displaced- to options have the same effect as they do for 
make-array. If you use either of these options, none of the elements of array are 
carried over to the new array. 

You can use the :fill-pointer option to reset the fill pointer of array. If array had 
no fill pointer an error is signalled. 

If the size of the array is being increased, adjust-array might have to allocate a 
new array somewhere. In that case, it alters array so that references to it are 
made to the new array instead, by means of "invisible pointers" under Genera. See 
the function structure-forward, adjust-array returns this new array if it creates 
one, and otherwise it returns array. Be careful to be consistent about using the re- 
turned result of adjust-array, because you might end up holding two arrays that 
are not the same (that is, not eq), but that share the same contents. 

Compatibility Note: rdisplaced-conformally is a Symbolics extension to Common 
Lisp, and not available in CLOE. 

(setq xprint-arrayx t) 

(setq array-1 (make-array '(2 3 2) : initial -element 'a :adjustable t)) 
=> #3A(((A A) (A A) (A A)) ((A A) (A A) (A A))) 

(adjust-array array-1 '(3 2 2) : initial-element 'b) 
=> #3A(((A A) (A A)) ((A A) (A A)) ((B B) (B B))) 

(setq an-array (make-array 10 :element-type 'string-char :adjustable t 

: initial -element #\x)) 
=> "xxxxxxxxxx" 

(adjust-array an-array 15 : initial-element #\y) 
=> "xxxxxxxxxxyyyyy" 

(setq xprint-arrayx t) 

(setq an-array (make-array '(2 3) :adjustable t 

:initial-contents '((1 2 3) (4 5 6)))) 
#2A((1 2 3) (4 5 6)) 

(adjust-array an-array '(3 2) : initial-element #\y) 
#2A((1 2) (4 5)(tf\y tf\y)) 



zl:adjust-array-size array new-size Function 

If array is a one-dimensional array, its size is changed to be new-size. If array has 
more than one dimension, its size is changed to new-size by changing only the first 
dimension. 

If array is made smaller, the extra elements are lost. If array .is made bigger, the 
new elements are initialized in the same fashion as make-array would initialize 
them: either to nil, or (code-char 0), depending on the type of array. 



Page 854 



Example: 

(setq a (make-array 5)) 
(setf (aref a 4) 'foo) 
(aref a 4) => foo 
(zl : ad just-array-size a 2) 
(aref a 4) => an error occurs 

See the function adjust-array. 

The meaning of zl:adjust-array-size for conformal indirect arrays is undefined. 

adjustable-array-p array Function 

Returns t if array is adjustable, and nil if it is not. Lisp dialects supported by 
Genera make most arrays adjustable even if the radjustable option to make-array 
is not specified; but to guarantee that an array can be adjusted after created, it is 
necessary to use the radjustable option. Under CLOE, arrays are adjustable only if 
the radjustable option is specified non-nil. 

(setq foo (make-array (4 5))) 
(adjustable-array-p foo) => nil ; under CLOE 

=> T ; under Genera 
(setq bar (make-array (4 5) adjustable t)) 
(adjustable-array-p bar) => t ;CL0E and Genera 

For a table of related items: See the section "Getting Information About an Array". 

r advance-input-buffer &optional new-pointer Message 

If new-pointer is non-nil, it is the index in the buffer array of the next byte to be 
read. If new-pointer is nil, the entire buffer has been used up. 

sysr*all-flavor-names* Variable 

This is a list of the names of all the flavors that have ever been created by 
defflavor. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 

&allow-other-keys Lambda List Keyword 

In a lambda-list that accepts keyword arguments, specifies that keywords that are 
not specifically listed after &key are allowed. They and their corresponding values 
are ignored, as far as keywords arguments are concerned, but they do become part 
of the &rest argument, if there is one. 

zlraloc array &rest subscripts Function 



Page 855 



Returns a locative pointer to the element of array selected by the subscripts. The 
subscripts must be integers and their number must match the dimensionality of ar- 
ray. See the section "Cells and Locatives". 

Current style suggests using locf with aref instead of zhaloc. For example: 

(locf (aref array subscripts)) 



alpha-char-p char Function 

Returns t if char is a letter of the alphabet. 

(alpha-char-p #\A) => T 
(alpha-char-p #\1) => NIL 

For a table of related items, see the section "Character Predicates". 

alphalessp x y Function 

(alphalessp x y) is equivalent to (string-lessp x y). If the arguments are not 
strings, alphalessp compares numbers numerically, lists by element, and all other 
objects by printed representation, alphalessp is a Maclisp all-purpose alphabetic 
sorting function. 

Examples: 

(alphalessp "apple" "orange") => T 
(alphalessp 'torn 'tim) => NIL 
(alphalessp "same" "same") => NIL 
(alphalessp 'symbol "string") => NIL 
(alphalessp ' (a b c) '(a b d)) => T 

alphanumericp char Function 

Returns t if char is a letter of the alphabet or a base-10 digit. 

(alphanumericp #\7) => T 
(alphanumericp #\%) => NIL 

For a table of related items, see the section "Character Predicates". 

always keyword for loop 

always expr 

Causes the loop to return t if expr always evaluates non-null. 
If expr evaluates to nil, the loop immediately returns nil, with- 
out running the epilogue code (if any, as specified with the 
finally clause); otherwise, t is returned when the loop finishes, 
after the epilogue code has been run. If the loop terminates be- 
fore expr is ever evaluated, the epilogue code is run and the 
loop returns t. 



Page 856 



always expr is like (and exprl expr2 ...), except that if no expr 
evaluates to nil, always returns t and and returns the value 
of the last expr. If the loop terminates before expr is ever eval- 
uated, always is like (and). 

If you want a similar test, except that you want the epilogue 
code to run if expr evaluates to nil, use while. 



Examples: 



(defun loop-always (my-list) 
(loop for x in my-list 

finally (print "what you going to do next ?") 
do 
(princ x) (princ " ") 
do 
and always (equal x 'a))) => LOOP-ALWAYS 

(loop-always ' (b c a d)) => B NIL 

(loop-always '(a a)) => A A 
"what you going to do next ?" T 

See the section "Aggregated Boolean Tests for loop". 

and &rest types Type Specifier 

Allows the definition of data types that are the intersection of other data types 
specified by types. As a type specifier, and can only be used in list form. 

Examples: 

(typep 89 '(and integer number)) => T 

(subtypep 'bit-vector '(and vector array)) => T and T 

(sys:type-arglist 'and) => (&REST TYPES) and T 

See the section "Data Types and Type Specifiers". 

For a discussion of the function and: See the section "Flow of Control". 

and &rest forms Special Form 

Evaluates each form one at a time, from left to right. If any form evaluates to nil, 
and immediately returns nil without evaluating any other form. If every form eval- 
uates to non-nil values, and returns the value of the last form. 

and can be used in two different ways. You can use it as a logical and function, 
because it returns a true value only if all of its arguments are true. So you can 
use it as a predicate: 

Examples: 



Page 857 



(if (and 'this 'that) "reaches this point") => "reaches this point" 

(if (and (equal 1 1) (equal nil '())) "equal") => "equal" 

(if (and socrates-is-a-person al 1 -people-are-mortal ) 
(setq socrates-is-mortal t)) 

Because the order of evaluation is well-defined, you can do: 

(if (and (boundp 'x) 
(eq x 'foo)) 
(setq y 'bar)) => NIL 

knowing that the x in the eq form is not evaluated if x is found to be unbound. 

You can also use and as a simple conditional form: 

Examples: 

(and) => T 

(and t nil) => NIL 

(and t 'hi (numberp 3.14)) => T 

(when (and (setq temp (assq x y)) 
(rplacd temp z))) 

(when (and bright-day 

glorious-day 

(princ "It is a bright and glorious day."))) 

In the following example, very-expensive-function is not evaluated because a prior 
form is false: 

(setq foo 12 bar '(3 4 5)) 

(if (and (eql 12 foo) 
(eql foo bar) 

(very-expensive-function bar)) 
bar 
foo) 

Note: (and) => t , which is the identity for the and operation. 

For a table of related items: See the section "Conditional Functions". 

CLOE Note: This is a macro in CLOE. 



zl:ap-l array index Function 

This is an obsolete version of zhaloc that works only for one-dimensional arrays. 
There is no reason ever to use it. 



Page 858 



zl:ap-2 array indexl index2 Function 

This is an obsolete version of zhaloc that works only for two-dimensional arrays. 
There is no reason ever to use it. 



zl:ap-leader array index Function 

Returns a locative pointer to the indexed element of array's leader, array should be 
an array with a leader, and index should be an integer. See the section "Cells and 
Locatives". 

However, the preferred method is to use locf and array-leader as shown in the 
following example: 

(setq xarrayx 

(make-array '(2 3) : element-type 'character 
:leader-list ' (t nil))) 

(locf (array-leader xarrayx 1)) 



append &rest lists Function 

Concatenates lists, returning the resulting list. The arguments to append are lists. 
They are not changed (see nconc). Example: 

(append ' (a b c) ' (d e f) nil ' (g)) => (a b c d e f g) 

append makes copies of the top-level list structure of all the arguments it is 
given, except for the last one. So the new list shares the conses of the last argu- 
ment to append, but all the other conses are newly created. Only the lists are 
copied, not the elements of the lists. The function concatenate can perform a sim- 
ilar operation, but always copies all its arguments. See also nconc, which is like 
append but destroys all its arguments except the last. 

The last argument does not have to be a list, but can be any Lisp object, which 
becomes the tail of the constructed list. For example, 

(append ' (a b c) 'd) => (a b c . d) 

A version of append that only accepts two arguments could have been defined by: 

(defun append2 (x y) 
(cond ((atom x) y) 

((cons (car x) (append2 (cdr x) y)) ))) 

The generalization to any number of arguments could then be made (relying on 
car of nil being nil): 

(defun append (&rest args) 

(if (< (length args) 2) (car args) 
(append2 (car args) 

(apply (function append) (cdr args))))) 



Page 859 



These definitions do not express the full functionality of append; the real defini- 
tion under Genera minimizes storage utilization by cdr-coding the list it produces. 
See the section "Cdr-Coding". 

Example: 

(setq a '(1 2) b '(3 4) c '(5 6) d 7) => 7 
(setq x (append a b c)) => (1 2 3 4 5 6) 
(setf (car c) 'foo) (setf (car b) 'bar) x => 
(1 2 bar 4 foo 6) 

(append a b c d) => (1 2 bar 4 foo 6 . 7) 
a => (1 2) 

To copy a list, use copy-list; the old practice of using 

(append x ' ()) 
to copy lists is unclear and obsolete. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



append keyword for loop 
append expr {into var} 



Causes the values of expr on each iteration to be appended together. When the 
epilogue of the loop is reached, var has been set to the accumulated result and 
can be used by the epilogue code. 

It is safe to reference the values in var during the loop, but they should not be 
modified until the epilogue code for the loop is reached. 

The forms append and appending are synonymous. 

Examples: 

(defun splice-list (listl list2) 
(loop for iteml in listl 

for item2 in list2 

append (list iteml) into result 

append (list item2) into result 

finally (return (append result )))) => SPLICE-LIST 
(splice-list '(Let not the of minds) '(me to marriage true)) => 
(LET ME NOT TO THE MARRIAGE OF TRUE) 

Is equivalent to 



Page 860 



(defun splice-list (listl list2) 
(loop for iteml in listl 

for item2 in list2 

appending (list iteml) into result 

appending (list item2) into result 

finally (return (append result )))) => SPLICE-LIST 
(splice-list '(Let not the of minds) '(me to marriage true)) => 
(LET ME NOT TO THE MARRIAGE OF TRUE) 

Not only can there be multiple accumulations in a loop, but a single accumulation 
can come from multiple places within the same loop form, if the types of the col- 
lections are compatible, append, collect, and nconc are compatible. 

See the section "Accumulating Return Values for loop". 

apply function argument &rest arguments 

Function 

Applies the function function to arguments, function can be any function, but it 
cannot be a special form or a macro. The arguments for function consist of the 
last argument to apply appended to the end of the list of all other arguments to 
apply except for function itself. It is as if all the arguments to apply except func- 
tion were given to list* to create the argument list. 

Examples: 

(setq fred '+) 

(apply fred '(1 2)) => 3 

(apply fred 1 2 ' (3 4) => 10 

(apply 'cons '((+ 2 3) 4)) => ((+ 2 3) .4) not (5 . 4) 

Note that if the function takes keyword arguments, you must put the keywords as 
well as the corresponding values in the argument list. 

(apply #' (lambda (&key a b) (list a b)) '(:b 3) => (nil 3) 

Compatibility Note: In Symbolics Common Lisp, apply is extended to allow you to 
call an array as a function. 

See the section "Functions for Function Invocation". 



zhapply fn args Function 

Applies the function fn to the list of arguments args. args must be a list; fn can 
be any function, but it cannot be a special form or a macro. The arguments for fn 
consist of the elements of the list args. 

Examples: 



Page 861 



(setq fred '+) 

(zl :apply fred '(1 2)) => 3 

(setq fred '-) 

(zl :apply fred '(1 2)) => -1 

(zl: apply 'cons '((+ 2 3) 4)) => ((+ 2 3) .4) not (5 . 4) 

Of course, args can be nil. Note: Unlike Maclisp, zhapply never takes a third ar- 
gument; there are no "binding context pointers" in Symbolics Common Lisp. 

See the function funcall. 

See the section "Functions for Function Invocation". 



apropos string &optional package (do-inherited-symbols t) do-packages-used-by 

Function 

Searches for all symbols whose print-names contain string as a substring. When it 
finds a symbol, it prints out the symbol's name; if the symbol is defined as a func- 
tion and/or bound to a value, it tells you so, and prints the names of the argu- 
ments (if any) to the function or the dynamic value of the symbol. If package is 
specified, it only searches for symbols containing string in that package, otherwise 
all packages are searched, as if by do-all-symbols. Because symbols can be avail- 
able in more than one package by inheritance, apropos might print information 
about the same symbol more than once. 

Compatibility Note: Symbolics Common Lisp provides two additional optional ar- 
guments, do-inherited-symbols and do-packages-used-by. If do-inherited-symbols is t, 
the set of packages searched includes all packages that package uses. If do- 
packages-used-by is t, the set also includes all packages that use package. You can- 
not use these two optional arguments in CLOE runtime. 

apropos prints its information to *standard-output*. It returns nil. 



zhapropos apropos-substring &optional pkg (do-packages-used-by t) do-packages-used 

Function 

Searches for all symbols whose print-names contain apropos-substring as a sub- 
string. When it finds a symbol, it prints out the symbol's name; if the symbol is 
defined as a function and/or bound to a value, it tells you so, and prints the names 
of the arguments (if any) to the function. It checks all symbols in a certain set of 
packages. The set always includes pkg. If do-packages-used-by is t, the set also in- 
cludes all packages that use pkg. If do-packages-used is t, the set also includes all 
packages that pkg uses, pkg defaults to the global package, so normally all pack- 
ages are searched, apropos returns a list of all the symbols it finds. This is simi- 
lar to the Find Symbol command, except that Find Symbol only searches the cur- 
rent package unless you specify otherwise. 



apropos-list string &optional package do-packages-used-by Function 



Page 862 



Searches for all symbols whose print-names contain string as a substring. If the 
Symbolics Common Lisp optional argument package is specified, the function only 
searches for symbols containing string in that package, otherwise all packages are 
searched, as if by do-all-symbols. It returns a list of the symbols it finds. 

Compatibility Note: Symbolics Common Lisp provides the additional optional argu- 
ment do-packages-used-by . If do-packages-used-by is t, the set also includes all pack- 
ages that use package. Package and do-packages-used-by may not work in other im- 
plementations of Common Lisp and does not work in CLOE Runtime. 

For more information, see the function apropos. 



zl:ar-l array index Function 

This is an obsolete version of aref that works only for one-dimensional arrays. 
There is no reason ever to use it. 



zl:ar-2 array indexl index2 Function 

This is an obsolete version of aref that works only for two-dimensional arrays. 
There is no reason ever to use it. 



aref array &rest subscripts Function 

Returns the element of array selected by the subscripts. The subscripts must be in- 
tegers and their number must match the dimensionality of array. 

(setq this-array (make-array '(2 3) : initial-contents 

'((a be) (d e f)))) 

(aref this-array 0) => A 

(aref this-array 1) => B 

(aref this-array 2) => C 

(aref this-array 1 0) => D 

setf can be used with aref to set the value of an array element. 

(setf (aref this-array 1 0) 'x) => X 
(aref this-array 1 0) => X 

The subscripts can refer to an element beyond a fill pointer. 

(setq this-array 
(make-array '(3 2 2) :element-type 'integer : initial-contents 
'(((5 6) (12 8)) 
((7 8) (5 13)) 
((9 4) (22 6))))) 

(aref this-array 1 0) => 7 
For a table of related items: See the section "Basic Array Functions". 



Page 863 



zharg x Function 

(zharg nil), when evaluated during the application of a lexpr, gives the number of 
arguments supplied to that lexpr. This is primarily a debugging aid, since lexprs 
also receive their number of arguments as the value of their lambda-variable. 

(zharg i), when evaluated during the application of a lexpr, gives the value of the 
1'th argument to the lexpr. i must be an integer in this case. It is an error if i is 
less than 1 or greater than the number of arguments supplied to the lexpr. Exam- 
ple: 



(defun foo nargs 
(print (arg 2)) 
(+ (arg 1) 

(arg (- nargs 1)))) 



jdefine a lexpr foo. 
;print the second argument. 
; return the sum of the first 
;and next to last arguments. 

zharg exists only for compatibility with Maclisp lexprs. To write functions that 
can accept variable numbers of arguments, use the &optional and &rest keywords. 
See the section "Evaluating a Function Form". 

arglist function &optional real-flag Function 

Given an ordinary function, a generic function, or a function spec, returns a repre- 
sentation of the function's lambda-list. It can also return a second value that is a 
list of descriptive names for the values returned by the function. The third value 
is a symbol specifying the type of function: 

Returned Value Function Type 

nil ordinary or generic function 

subst substitutable function 

special special form 

macro macro 

shspecial-macro both a special form and a macro 

array array 

If function is a symbol, arglist of its function definition is used. 

Some functions' real argument lists are not what would be most descriptive to a 
user. A function can take an &rest argument for technical reasons even though 
there are standard meanings for the first element of that argument. For such cas- 
es, the definition of the function can specify, with a local declaration, a value to be 
returned when the user asks about the argument list. Example: 

(defun foo (&rest rest-arg) 

(declare (arglist x y &rest z)) 
) 

Note that since the declared argument list is supplied by the user, it does not nec- 
essarily correspond to the function's actual argument list. 

real-flag allows the caller of arglist to say that the real argument list should be 
used even if a declared argument list exists. 



Page 864 



If real-flag is t or a declared argument list does not exist, arglist computes its re- 
turn value using information associated with the function. Normally the computed 
argument list is the same as that supplied in the source definition, but occasional- 
ly some differences occur. However, arglist always returns a functionally correct 
answer in that the number and type of the arguments is correct. 

When a function returns multiple values, it is useful to give the values names so 
that the caller can be reminded which value is which. By means of a values decla- 
ration in the function's definition, entirely analogous to the arglist declaration 
above, you can specify a list of mnemonic names for the returned values. This list 
is returned by arglist as the second value. 

(arglist 'arglist) 
=> (function &optional real -flag) and (arglist values type) 



args-info fen Function 

Returns an integer called the "numeric argument descriptor" of fen, which de- 
scribes the way the function takes arguments. This descriptor is used internally by 
the microcode, the evaluator, and the compiler, fen can be a function or a function 
spec. 

The information is stored in various bits and byte fields in the integer, which are 
referenced by the symbolic names shown below. By the usual Symbolics convention, 
those starting with a single "%" are bit-masks (meant to be bit-tested with the 
number with logand or zl:bit-test), and those starting with "%%" are byte descrip- 
tors (meant to be used with ldb or ldb-test). 

Here are the fields: 

sys:%%arg-desc-min-args 

This is the minimum number of arguments that can be passed to this 
function, that is, the number of "required" parameters. 

sys:%%arg-desc-max-args 

This is the maximum number of arguments that can be passed to this 
function, that is, the sum of the number of "required" parameters and the 
number of "optional" parameters. If there is an &rest argument, this is not 
really the maximum number of arguments that can be passed; an arbitrari- 
ly large number of arguments is permitted, subject to limitations on the 
maximum size of a stack frame (about 200 words). 

sys:%%arg-desc-rest-arg 

If this is nonzero, the function takes an &rest argument or &key argu- 
ments. A greater number of arguments than sys:%%arg-desc-max-args can 
be passed. 

sys:%arg-desc-interpreted 

This function is not a compiled-code object. 

sys:%%arg-desc-interpreted 

This is the byte field corresponding to the sys:%arg-desc-interpreted bit. 



Page 865 



sys:%%arg-desc-quoted 

This is obsolete. 



sys:%args-info function Function 

An internal function; it is like args-info, but does not work for interpreted func- 
tions. Also, function must be a function, not a function spec. 



zhargument-typecase arg-name &body clauses Special Form 

A hybrid of zhtypecase and zl:check-arg-type. Its clauses look like clauses to 
zhtypecase. zhargument-typecase automatically generates an otherwise clause 
which signals an error. The proceed types to this error are similar to those from 
zhcheck-arg; that is, you can supply a new value that replaces the argument that 
caused the error. 

For example, this: 

(defun foo (x) 
(argument-typecase x 

(: symbol (print 'symbol)) 
(:number (print 'number)))) 

is the same as this: 

(defun foo (x) 
(check-arg x 
(typecase x 

(:symbol (print 'symbol) t) 
(:number (print 'number) t) 
(otherwise nil)) 
"a symbol or a number")) 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



array &optional ( element-type '* ) (dimensions '* ) Type Specifier 

array is the type specifier symbol for the Lisp data structure of that name. 

The types array, cons, symbol, number, and character are pairwise disjoint. 

The type array is a supertype of the types: 

simple-array 
vector 

This type specifier can be used in either symbol or list form. Used in list form, 
array allows the declaration and creation of specialized arrays whose members are 
all members of the type element-type and whose dimensions match dimensions. 



Page 866 



element-type must be a valid type specifier, or unspecified. For standard Symbolics 
Common Lisp type specifiers: See the section "Type Specifiers". 

dimensions can be a non-negative integer, which is the number of dimensions, or it 
can be a list of non-negative integers representing the length of each dimension 
(any of which can be an asterisk), dimensions can also be an asterisk. 

Note that (array t) is a proper subset of (array *). This is because (array t) is 
the set of arrays that can hold any Symbolics Common Lisp object (the elements 
are of type t, which includes all objects). On the other hand, (array *) is the set 
of all arrays whatsoever, including for example arrays that can hold only charac- 
ters, (array character) is not a subset of (array t); the two sets are in fact dis- 
joint because (array character) is not the set of all arrays that can hold charac- 
ters, but rather the set of arrays that are specialized to hold precisely characters 
and no other objects. To test whether an array foo can hold a character, you 
should not use 

(typep foo '(array character)) 
but rather 

(subtypep 'character (array-element-type foo)) 

Examples: 

(setq example-array (make-array '(3) : f il 1-pointer 2)) 
=> #<ART-Q-3 43063275> 

(typep example-array 'array) => T 

(typep example-array 'simple-array) => NIL 
; simple arrays do not have fill-pointers. 

(zl : typep #*101) => : ARRAY 

(subtypep 'array t) => T and T 

(array-has-f il 1-pointer-p example-array) => T 

(arrayp example-array) => T 

(sys: type-argl ist 'array) 
=> (&0PTI0NAL (ELEMENT-TYPE '*) (DIMENSIONS '*)) and T 

See the section "Data Types and Type Specifiers". 

See the section "Arrays". 

zharray x type &rest dimlist Macro 

Creates an sys:art-q type array in sys:default-cons-area with the given dimen- 
sions. (That is, dimlist is given to zhmake-array as its first argument.) type is ig- 
nored. If x is nil, the array is returned; otherwise, the array is put in the function 
cell of symbol, and symbol is returned. This exists for Maclisp compatibility. 

Use the Common Lisp function make-array in your new programs. 

zl:*array x type &rest dimlist Function 



Page 867 



Creates an sys:art-q type array in sys:default-cons-area with the given dimen- 
sions, and evaluates all of the arguments. It exists for Maclisp compatibility. 



zl:array-#-dims array Function 

We recommend that you use the function array-rank, which is the Common Lisp 
equivalent of zl:array-#-dims. 

Returns the dimensionality of array. For example: 

(zl :array-#-dims (make-array '(3 5))) => 2 

For a table of related items: See the section "Getting Information About an Array". 



zharray-active-length array Function 

Returns the number of active elements in array. If array does not have a fill 
pointer, this returns whatever (array-total-size array) would have. If array does 
have a fill pointer that is a non-negative fixnum, zharray-active-length returns it. 
See the section "Array Leaders". 

A general explanation of the use of fill pointers is in that section. 

Note that length provides the same functionality for lists and vectors. 



sys:array-bits-per-element Variable 

The value of sys:array-bits-per-element is an association list that associates each 
array type symbol with the number of bits of unsigned numbers (or fixnums) it 
can hold, or nil if it can hold Lisp objects. This can be used to tell whether an ar- 
ray can hold Lisp objects or not. See the section "Association Lists". 

For a table of related items: See the section "Array Representation Tools". 



sys:array-bits-per-element index Function 

Given the internal array-type code numbers, returns the number of bits per cell 
for unsigned numeric arrays, or nil for a type of array that can contain Lisp ob- 
jects. 



array-dimension array dimension-number Function 

Returns the length of the dimension numbered dimension-number of array, dimen- 
sion-number should be a non-negative integer less than the rank of array. 

(setq foo (make-array '(3 2 4 6))) 
(array-dimension foo 0) => 3 

(array-dimension foo 3) => 6 
For a table of related items: See the section "Getting Information About an Array". 



Page 868 



array-dimension-limit Constant 

Represents the upper exclusive bound on each individual dimension of an array. 
The value of this is 134217728 under Genera, and CLOE. 

(when (> max-number-in-categories array-dimension-limit) 
(setq xnumber-of-arrays-neededx 

(ceiling max-number-in-categories array-dimension-limit))) 

For a table of related items: See the section "Basic Array Functions". 



zl:array-dimension-n n array Function 

Returns the size for the specified dimension of the array, array can be any kind of 
array, and n should be an integer. If n is between 1 and the dimensionality of ar- 
ray, this returns the nth dimension of array. If n is 0, this returns the length of 
the leader of array; if array has no leader it returns nil. If n is any other value, 
this returns nil. Examples: 

(setq a (make-array '(3 5) : leader-length 7)) 

(zl :array-dimension-n 1 a) => 3 

(zl :array-dimension-n 2a) => 5 

(zl :array-dimension-n 3 a) => nil 

(zl :array-dimension-n a) => 7 

We recommend that you use the function array-dimension, which is the Common 
Lisp equivalent of zl:array-dimension-n. 

array-dimensions array Function 

Returns a list whose elements are the dimensions of array. Example: 

(setq a (make-array '(3 5))) 
(array-dimensions a) => (3 5) 

For a table of related items: See the section "Getting Information About an Array". 

sys:array-displaced-p array Function 

Tests whether the array is a displaced array, array can be any kind of array. This 
predicate returns t if array is any kind of displaced array (including an indirect 
array). Otherwise it returns nil. 

For a table of related items: See the section "Getting Information About an Array". 

sys:array-element-byte-size array Function 

Given an array, returns the number of bits that fit into an element of that array. 
For arrays that can hold general Lisp objects, the result is 32; this assumes that 
you are storing bits into the array with sys:%logdpb, rather than storing numbers 
into the array with dpb. 



Page 869 



For a table of related items: See the section "Array Representation Tools". 



sys:array-element-size array Function 

Given an array, returns the number of bits that fit into an element of that array. 
For arrays that can hold general Lisp objects, the result is 31; this assumes that 
you are storing fixnums in the array and manipulating their bits with dpb (rather 
than sys:%logdpb). You can store any number of bits per element in an array that 
holds general Lisp objects, by letting the elements expand into bignums. 

For a table of related items: See the section "Array Representation Tools". 



array-element-type array Function 

Returns the type specifier of the elements allowed in the array. In some cases this 
may be different thatn the element-type specified in the call to make-array. Ex- 
ample: 

(setq a (make-array '(3 5))) 

(array-element-type a) => T 

(array-element-type "foo") => STRING-CHAR 

(setq bar (make-array '(3 2 4) : element-type 'bit)) 

(array-element-type bar) => (integer (2)) 

For a table of related items: See the section "Getting Information About an Array". 

sys:array-elements-per-q index Function 

Given the internal array-type index, returns the number of array elements stored 
in one word, for an array of that type. 

For a table of related items: See the section "Array Representation Tools". 

sys:array-elements-per-q index Variable 

This is an association list that associates each array type symbol with the number 
of array elements stored in one word, for an array of that type. See the section 
"Association Lists". 

For a table of related items: See the section "Array Representation Tools". 

zl:array-grow array &rest dimensions Function 

Creates a new array of the same type as array, with the specified dimensions. 
Those elements of array that are still in bounds are copied into the new array. 
The elements of the new array that are not in the bounds of array are initialized 
to nil or as appropriate. If array has a leader, the new array has a copy of it. 
zl:array-grow returns the new array and also forwards array to it, like adjust- 
array. 



Page 870 



Unlike adjust-array, zl:array-grow usually creates a new array rather than grow- 
ing or shrinking the array in place. (If the array is one-dimensional and it is being 
shrunk, zl:array-grow does not create a new array.) zl:array-grow of a multidi- 
mensional array can change all the subscripts and move the elements around in 
memory to keep each element at the same logical place in the array. 



array-has-fill-pointer-p array Function 

Returns t if the array has a fill pointer; otherwise it returns nil. array can be any 
array. 

(setq foo (make-array 12 : element-type 'string-char : f il 1-pointer 0)) 
(array-has-fill-pointer-p foo) => t 

array-has-leader-p array Function 

Returns t if array has a leader; otherwise it returns nil. array can be any array. 

For a table of related items: See the section "Operations on Array Leaders". Also: 
See the section "Getting Information About an Array". 

array-in-bounds-p array &rest subscripts Function 

Checks whether subscripts is a valid set of subscripts for array, and returns t if 
they are; otherwise it returns nil. 

In the following example, the second set of indices returns an out-of-bounds result 
because Common Lisp arrays are zero based. Therefore, 2 is the highest allowable 
index for a dimension of 3. 

(setq foo (make-array '(3 2 4 6))) 
(array-in-bounds foo 2 1 3 5) => t 
(array-in-bounds foo 3 1 3 5) => nil 

For a table of related items: See the section "Getting Information About an Array". 

sys:array-indexed-p array Function 

Returns t if array is an indirect array with an index-offset. Otherwise it returns 
nil. array can be any kind of array. Note, however, that displaced arrays with an 
offset are not considered indexed. 

sys:array-indirect-p array Function 

Returns t if array is an indirect array. Otherwise it returns nil. array can be any 
kind of array. 



Page 871 



array-leader array index Function 

Returns the indexed element of array's leader, array should be an array with a 
leader, and index should be an integer. 

For a table of related items: See the section "Operations on Array Leaders". 



array-leader-length array Function 

Returns the length of array's leader if it has one, or nil if it does not. array can 
be any array. 

For a table of related items: See the section "Getting Information About an Array". 



array-leader-length-limit Variable 

This is the exclusive upper bound of the length of an array leader. It is 1024 on 
Symbolics 3600-family computers, 256 on Ivory-based machines. 

(condition-case (err) 

(make-array 4 : leader-length array-leader-length-limit) 
(error (princ err))) 
=> Leader length specified (1024) is too large. 
#<FERR0R 60065043> 



zharray-length array Function 

We recommend that you use the function array-total-size, which is the Common 
Lisp equivalent of zharray-length. 

Returns the total number of elements in array, array can be any array. The total 
size of a one-dimensional array is calculated without regard for any fill pointer. 
For a one-dimensional array, zharray-length returns one greater than the maxi- 
mum allowable subscript. For example: 

(zl : array-length (make-array 3)) => 3 

(zl : array-length (make-array '(3 5))) => 15 

Note that if fill pointers are being used and you want to know the active length of 
the array, you should use length or zharray-active-length instead of zharray- 
length. 

zharray-length does not return the same value as the product of the dimensions 
for conformal arrays. 

For a table of related items: See the section "Getting Information About an Array". 



zharray-pop array &optional (default nil) Function 

We recommend that you use the function vector-pop, which is the Common Lisp 
equivalent of the function zharray-pop. 



Page 872 



Decreases the fill pointer by one and returns the array element designated by the 
new value of the fill pointer, array must be a one-dimensional array that has a fill 
pointer. 

The second argument, if supplied, is the value to be returned if the array is emp- 
ty. If zl:array-pop is called with one argument and the array is empty, it signals 
an error. 

The two operations (decrementing and array referencing) happen uninterruptibly. 
If the array is of type sys:art-q-list, an operation similar to nbutlast has taken 
place. The cdr coding is updated to ensure this. 

See the function vector-pop. 



zl:array-push array x Function 

Attempts to store x in the element of the array designated by the fill pointer and 
increase the fill pointer by one. array must be a one-dimensional array that has a 
fill pointer, and x can be any object allowed to be stored in the array. If the fill 
pointer does not designate an element of the array (specifically, when it gets too 
big), it is unaffected and zl:array-push returns nil; otherwise, the two actions 
(storing and incrementing) happen uninterruptibly, and zl:array-push returns the 
former value of the fill pointer, that is, the array index in which it stored x. 

If the array is of type sys:art-q-list, an operation similar to nconc has taken 
place, in that the element has been added to the list by changing the cdr of the 
formerly last element. The cdr coding is updated to ensure this. 

See the function vector-push. 



zl:array-push-extend array x &optional extension Function 

Similar to zl:array-push except that if the fill pointer gets too large, the array is 
grown to fit the new element; that is, it never "fails" the way zl:array-push does, 
and so never returns nil. extension is the number of elements to be added to the 
array if it needs to be grown. It defaults to something reasonable, based on the 
size of the array. zl:array-push-extend returns the former value of the fill pointer, 
that is, the array index in which it stored x. 

See the function vector-push-extend. 

zl:array-push-portion-extend to-array from-array &optional (from-start 0) from-end 

Function 

We recommend that you use the function vector-push-portion-extend, which is 
the Symbolics Common Lisp equivalent of the function zl:array-push-portion- 
extend. 

Copies a portion of one array to the end of another, updating the fill pointer of the 
other to reflect the new contents. The destination array must have a fill pointer. 
The source array need not. This is equivalent to numerous zl:array-push-extend 



Page 873 



calls, but more efficient. zl:array-push-portion-extend returns the to-array and the 
index of the next location to be filled. 

Example: 

(setq to-string 

(zl : array-push-portion-extend to-string 

f rom-string 
(or from 0) 
to)) 

This is similar to zl:array-push-extend except that it copies more than one ele- 
ment and has different return values. The arguments default in the usual way, so 
that the default is to copy all of from-array to the end of to-array. 

zl:array-push-portion-extend adjusts the array size using adjust-array. It picks 
the new array size in the same way that zl:array-push-extend does, making it big- 
ger than needed for the information being added. In this way, successive additions 
do not each end up consing a new array. zl:array-push-portion-extend uses copy- 
array-portion internally. 

See the function vector-push-portion-extend. 



array-rank array Function 

Returns the number of dimensions of array. For example: 
(array-rank (make-array '(3 5))) => 2 

For a table of related items: See the section "Getting Information About an Array". 

array-rank-limit Constant 

Represents the exclusive upper bound on the rank of an array. The value of this is 
8 under Genera, and 256 under CLOE. 

(when (> number-of-categories array-rank-limit) 
(setq xnumber-of-arrays-neededx 

(ceiling number-of-categories array-rank-limit))) 

For a table of related items: See the section "Basic Array Functions". 

array-row-major-index array &rest subscripts Function 

Takes an array and valid subscripts for the array and returns a single positive in- 
teger, less than the total size of the array, that identifies the accessed element in 
the row-major ordering of the elements. The number of subscripts supplied must 
equal the rank of the array. Each subscript must be a nonnegative integer less 
than the corresponding array dimension. Like aref, array-row-major-index returns 
the position whether or not that position is within the active part of the array. 

For example: 



Page 874 



window is a conformal array whose 0,0 coordinate is at 256,256 of big-array. The 
following code creates a 1/4 size portal into the center of big-array. 

;;; -*- Syntax: Zetalisp; Package: USER; Base: 10; Mode: LISP -*- 
(setq big-array (make-array '(1024 1024) :type 'art-q 

: initial-value 0)) 
(setq window (make-array '(512 512) :type 'art-q 

:displaced-to big-array 
: di spl aced-i ndex-of f set 

(array-row-major-index big-array 256 256) 
:displaced-conformal ly t)) 

For a one-dimensional array, the result of array-row-major-index equals the sup- 
plied subscript. 

An error is signalled if some subscript is not valid. 

array-row-major-index can be used with the :displaced-index-offset option of 
make-array to construct the desired value for multidimensional arrays. 

(setq foo (make-array '(2 3 3) : initial-contents 
'(((0 1 2) (3 4 5) (6 7 8)) 

((9 10 11) (12 13 14) (15 16 17))))) 
(array-row-major-index foo 2 2) => 8 

For a table of related items: See the section "Getting Information About an Array". 



sys:array-row-span array Function 

Returns the number of array elements spanned by one of its rows, given a two- 
dimensional array. Normally, this is just equal to the length of a row (that is, the 
number of columns), but for conformally displaced arrays, the length and the span 
are not equal. 

(sys: array-row-span (make-array '(4 5))) => 5 

(sys: array-row-span (make-array '(4 5) 

:displaced-to (make-array '(8 9)) 
:displaced-conformal ly t)) 
=> 9 

Note: If the array is conceptually a raster, it is better to use decode-raster-array 
than sys:array-row-span. 

For a table of related items: See the section "Getting Information About an Array". 
See the section "Accessing Multidimensional Arrays as One-dimensional". 



array-total-size array Function 

Returns the total number of elements in array. The total size of a one-dimensional 
array is calculated without regard for any fill pointer. 

(array-total-size (make-array '(3 5 2))) => 30 



Page 875 



Note that if fill pointers are being used and you want to know the active length of 
the array, you should use length or under Genera, zharray-active-length. 

array-total-size does not return the same value as the product of the dimensions 
for Genera conformal arrays. 

For a table of related items: See the section "Getting Information About an Array". 



array-total-size-limit Constant 

Represents the exclusive upper bound on the number of elements of an array. The 
value of this is 134217728 under Genera and CLOE. 

(when (> number-of-data-elements array-total-size-limit) 
(setq xnumber-of-arrays-neededx 

(ceiling number-of-data-elements array-total-size-limit))) 

For a table of related items: See the section "Basic Array Functions". 



sys:array-type array Function 

Returns the symbolic type of array. Example: 

(sys: array-type (make-array '(3 5))) => SYS:ART-Q 

sys:*array-type-codes* Variable 

The value of sys:*array-type-codes* is a list of all of the array type symbols such 
as sys:art-q, sys:art-4b, sysrart-string and so on. The values of these symbols are 
internal array type code numbers for the corresponding type. 

For a table of related items: See the section "Array Representation Tools". 

sys:array-types index Function 

Returns the symbolic name of the array type. The index is the internal numeric 
code stored in sys:*array-type-codes*. 

For a table of related items: See the section "Array Representation Tools". 

zharraydims array Function 

Returns a list whose first element is the symbolic name of the type of array, and 
whose remaining elements are its dimensions, array can be any array; it also can 
be a symbol whose function cell contains an array (for Maclisp compatibility). 

Example: 

(setq a (make-array '(3 5))) 

(zl :arraydims a) => (sys:art-q 3 5) 

Note: the list returned by (array-dimensions x) is equal to the cdr of the list re- 
turned by (zharraydims x). 



Page 876 



See the function array-dimensions. 

arrayp object Function 

Returns t if its argument is an array, otherwise nil. Note that strings are arrays. 

(setq screen (make-array (640 350) : element-type 'bit)) 

(arrayp screen) => t 

(arrayp "foo") => t 

(arrayp '((a b) (c d))) => nil 

zl:as-l value array index Function 

This is an obsolete version of zhaset that works only for one-dimensional arrays. 
There is no reason ever to use it. 

zl:as-2 value array indexl index2 Function 

This is an obsolete version of zhaset that works only for two-dimensional arrays. 
There is no reason ever to use it. 

zhascii n Function 

Returns a symbol whose printname is the character n. 

n can be an integer (a character code), a character, a string, or a symbol. 

Examples: 

(zl :asci i 2) => a 

(zl :ascii #\y) => |y| 

(zl :ascii "Y") => Y 

(zl :asci i 'a) => A 

The symbol returned is interned in the current package. 
This function is provided for Maclisp compatibility only. 

ascii-code spec Function 

Returns an integer that is the ASCII code named by spec. If spec is a character, 
char-to-ascii is called. Otherwise, spec can be a string or keyword that names one 
of the ASCII special characters. 

ascii-code returns an integer, for example, (ascii-code #: | #\\RETURN | ) => #ol5. 

ascii-code also recognizes strings and looks up the names of the ASCII "control" 
characters. Thus (ascii-code "SOH") and (ascii-code #:|#\\l|) return 1. (ascii- 
code #\c-A) returns 65, not 1; there is no mapping between Symbolics character 
set control characters and ASCII control characters. 



Page 877 



Valid ASCII special character names are listed below. All numbers are in octal. 

NUL 000 HT Oil DC1 021 SUB 032 

SOH 001 LF 012 DC2 022 ESC 033 

STX 002 NL 012 DC3 023 ALT 033 

ETX 003 VT 013 DC4 024 FS 034 

EOT 004 FF 014 NAK 025 GS 035 

ENQ 005 CR 015 SYN 026 RS 036 

ACK 006 SO 016 ETB 027 US 037 

BEL 007 SI 017 CAN 030 SP 040 

BS 010 DLE 020 EM 031 DEL 177 
TAB 011 

For a table of related items, see the section "ASCII Characters". 



ascii-to-char code Function 

Converts code (an ASCII code) to the corresponding character. The caller must ig- 
nore LF after CR if desired. 

ascii-to-char performs an inverse mapping of the function char-to-ascii, and this 
mapping embeds the ASCII character character set in the Symbolics character set. 
There is no attempt to map more obscure ASCII control codes into the also ob- 
scure and unrelated Symbolics control codes. For example, Escape, is a character 
in the Symbolics character set corresponding to the key marked Escape. The ASCII 
code Escape is not the same as the Symbolics Escape. See the function char-to- 
ascii. See the function ascii-code. See the section "ASCII Conversion String Func- 
tions". 

The functions char-to-ascii and ascii-to-char provide the primitive conversions 
needed by ASCII-translating streams. They do not translate the Return character 
into a CR-LF pair; the caller must handle that. They just translate #\Return into 
CR and #\Line into LF. Except for CR-LF, char-to-ascii and ascii-to-char are 
wholly compatible with the ASCII-translating streams. 

They ignore Symbolics control characters; the translation of #\c-G is the ASCII 
code for G, not the ASCII code to ring the bell, also known as "control G." (ascii- 
to-char (ascii-code "BEL")) is #\k, not #\c-G. The translation from ASCII to char- 
acter never produces a Symbolics control character. 

For a table of related items, see the section "ASCII Characters". 



ascii-to-string ascii-array Function 

Converts ascii-array, an sys:art-8b array representing ASCII characters, into a 

Lisp string. Note that the length of the string can vary depending on whether 

ascii-array contained a Newline character or Carriage Return Line Feed charac- 
ters. See the section "ASCII Characters". 

Example: 



Page 878 



(setq a-string-array 

(zl : make-array 5 :type zl:art-8b : initial -value (asci i-code #\x))) 
=> #(120 120 120 120 120) 
(ascii-to-string a-string-array) => "xxxxx" 

For a table of related items: See the section "ASCII Conversion String Functions". 



zkaset element array &rest subscripts Function 

Stores element into the element of array selected by the subscripts. The subscripts 
must be integers and their number must match the dimensionality of array. The 
returned value is element. 

Current style suggests using setf and aref instead of zhaset. For example: 

(setf (aref array subscripts...) new-value) 



ash number count Function 

Shifts number arithmetically left count bits if count is positive, or right -count bits 
if count is negative. Unused positions are filled by zeroes from the right, and by 
copies of the sign bit from the left. Thus, unlike lsh, the sign of the result is al- 
ways the same as the sign of number. If number is an integer, this is a shifting 
operation. If number is a floating-point number in Genera, this does scaling (multi- 
plication by a power of two), rather than actually shifting any bits. If you are us- 
ing CLOE, it is an error for number to be a float. 
Examples: 

(ash 1 3) => 8 
(ash 10 3) => 80 
(ash 10 -3) => 1 
(ash 1 -3) => 
(ash 1 .5 3) => 12.0 
(ash -1 3) => -8 
(ash -1 -3) => -1 

See the section "Functions Returning Result of Bit-wise Logical Operations". 

For a table of related items: See the section "Functions Returning Result of Bit- 
wise Logical Operations". 



asin number Function 

Computes and returns the arc sine of number. The result is in radians. 

The argument can be any noncomplex or complex number. Note that if the abso- 
lute value of number is greater than one, the result is complex, even if the argu- 
ment is not complex. 

The arc sine being a mathematically multiple-valued function, asin returns a prin- 
cipal value whose range is that strip of the complex plane containing numbers 



Page 879 



with real parts between -n/2 and ji/2. Any number with a real part equal to -%/2 
and a negative imaginary part is excluded from the range. Also excluded from the 
range is any number with real part equal to ji/2 and a positive imaginary part. 

Examples: 

(asin 1) => 1.5707964 ;ji/2 radians 
(asin 0) => 0.0 

(asin -1) => -1.5707964 ;-7t/2 radians 
(asin 2) => #c(1. 5707964 -1.316958) 
(asin -2) => #c(-1 .5707964 1.3169578) 
(asin (/ (sqrt 2) 2)) => 0.785398 

For a table of related items, see the section "Trigonometric and Related 
Functions". 



asinh number Function 

Computes and returns the hyperbolic arc sine of number. The result is in radians. 
The argument can be any noncomplex or complex number. 

The hyperbolic arc sine being mathematically multiple-valued in the complex plane, 
asinh returns a principal value whose range is that strip of the complex plane 
containing numbers with imaginary parts between -7t/2 and n/2. Any number with 
an imaginary part equal to -7t/2 is not in the range if its real part is negative; any 
number with real part equal to 7t/2 is excluded from the range if its imaginary 
part is positive. 

Example: 

(asinh 0) => 0.0 ;(sinh 0) => 0.0 

For a table of related items, see the section "Hyperbolic Functions". 



zkass pred item list Function 

Looks up item in the association list list. Returns the first cons whose car matches 
item according to pred, or nil if none does, (zkass 'eq a b) is the same as (zkassq 
a b). As with zkniem, you can use noncommutative predicates; the first argument 
to the predicate is item and the second is the indicator of the element of list. See 
the function zkniem. 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 



assert test-form &optional references format-string &rest format-args Macro 

Signals an error if the value of test-form is nil. It is possible to proceed from this 
error; the function lets you change the values of some variables, and starts over, 
evaluating test-form again. 

assert returns nil. 



Page 880 



test-form is any form. 

references is a list, each item of which must be a generalized variable reference 
that is acceptable to the macro setf. These should be variables on which test-form 
depends, whose values can sensibly be changed by the user in attempting to cor- 
rect the error. Subforms of each of references are only evaluated if an error is sig- 
nalled, and can be re-evaluated if the error is re-signalled (after continuing with- 
out actually fixing the problem). 

format-string is an error message string. 

format-args are additional arguments; these are evaluated only if an error is sig- 
nalled, and reevaluated if the error is signalled again. 

The function format is applied in the usual way to format-string and and format- 
args to produce the actual error message. 

If format-string (and therefore also format-args) are omitted, a default error mes- 
sage is used. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



assoc item a-list &key {test #'eql) test-not {key #'identity) Function 

Searches the association list a-list. The value returned is the first pair in a-list 
whose car satisfies the predicate specified by :test, or nil if no such pair is found. 
If nil is one of the elements in the association list, assoc passes over it. The key- 
words are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

Example: 

(assoc 'loon '((eagle . raptor) (loon . diver))) => 
(LOON . DIVER) 

(assoc 'diver '((eagle . raptor) (loon . diver))) => NIL 

(assoc '2 '((1 a b c) (2 b c d) (-7 x y z))) => (2 B C D) 

It is possible to rplacd the result of assoc (provided that it is non-nil) in order to 
update a-list. 



Page 881 



(setq values '((x . 100) (y . 200) (z . 50))) => 
((X . 100) (Y . 200) (Z . 50)) 

(assoc 'y values) => (Y . 200) 

(rplacd (assoc 'y values) 201) => (Y . 201) 

(assoc 'y values) => (Y . 201) 

The two expressions: 

(assoc item alist :test pred) 
and 

(find item alist :test pred :key #'car) 

are almost equivalent in meaning. The difference occurs when nil appears in a-list 
in place of a pair, and the item being searched for is nil. In these cases, find com- 
putes the car of the nil in a-list, finds that it is equal to item, and returns nil, 
while assoc ignores the nil in a-list and continues to search for an actual cons 
whose car is nil. See also, find and position. 

It is often better to update an association list by adding new pairs to the front, 
rather than altering old pairs. The following example demonstrates an association 
list consisting of pairs of keys and association lists. 

(setq financial -statement) 

'((MONTHLY-CASH-ON-HAND ((11 . 52) (12 . 73))) 
(MONTHLY-EXPENSE ((10 . 20) (11 . 21))) 
(MONTHLY-REVENUE ((10 . 31) (11 . 42)))) 

In the following example, the first call to assoc extracts the monthly-cash-on-hand 
association list. The second assoc extracts the monthly-cash-on-hand for the month 
of November from monthly-cash-on-hand: 

(setq monthly-cash-on-hand 

(assoc 'monthly-cash-on-hand financial -statement)) 
=> (MONTHLY-CASH-ON-HAND ((11 . 52) (12 . 73))) 
(assoc '11 (cdr monthly-cash-on-hand)) 
=>(11 . 52) 

In the next example, rplacd alters a value stored in the association list, and assoc 
delivers the pointer for rplacd. 

(assoc 'monthly-revenue financial -statement) 
=> (MONTHLY-REVENUE . ((10 . 31) (11 . 42))) 

(setf (cdr (assoc '11 (assoc 'monthly-revenue financial -statement))) 
22) 

(assoc 'monthly-revenue financial -statement) 
=> (MONTHLY-REVENUE . ((10 . 31) (11 . 22))) 

Usually, association lists are updated by adding a new pair to the front of the list, 
as shown in the following example: 



Page 882 



(aeons '11 '22 (assoc 'monthly-revenue financial -statement)) 

(assoc 'monthly-revenue financial -statement) 

=> (MONTHLY-REVENUE . ((11 . 22) (10 . 31) (11 . 42))) 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 



zkassoc item in-list Function 

Looks up item in the association list in-list. Returns the first cons whose car is 
zkequal to item, or nil if none is found. Example: 

(zl: assoc '(a b) '((x . y) ((a b) . 7) ((c . d) .e))) 
=> ((a b) . 7) 

zkassoc could have been defined by: 

(defun assoc (item list) 
(cond ((null list) nil) 

((equal item (caar list)) (car list)) 
((assoc item (cdr list))) )) 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 



assoc-if predicate a-list &key :key Function 

Searches the association list a-list. Returns the first pair in a-list whose car satis- 
fies predicate, or nil if there is no such pair in a-list. The keyword is: 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. :key is a 
Symbolics extension to Common Lisp. 

Example: 

(assoc-if tf'integerp '((eagle . raptor) (1 . 2))) => 
(1 . 2) 

(assoc-if tf'symbolp '((eagle . raptor) (1 . 2))) => 
(EAGLE . RAPTOR) 

(assoc-if tf'floatp '((eagle . raptor) (1 . 2))) => 
NIL 

In the following example, the function finds the largest numeric key in an associa- 
tion list by repeating assoc-if with a test for a key greater than the greatest key 
found so far. 



Page 883 



(defun find-largest-key (a-list &optional (start 0)) 
(if (setq pair 

(assoc-if ft' (lambda(x) (> x start)) a-list)) 
(find-largest-key a-list (car pair)))) 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 

Compatibility Note: :key is a Symbolics extension to Common Lisp, not available 
in CLOE. 



assoc-if-not predicate a-list &key :key Function 

Searches the association list a-list. The value returned is the first pair in a-list 
whose car does not satisfy predicate, or nil if there is no such pair in a-list. The 
keyword is: 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. :key is a 
Symbolics extension to Common Lisp. 

Example: 

(assoc-if-not #'integerp '((eagle . raptor) (1 . 2))) => 
(EAGLE . RAPTOR) 

(assoc-if-not tf'symbolp '((eagle . raptor) (1 . 2))) => 
(1 . 2) 

(assoc-if-not tf'symbolp '((eagle . raptor) (loon . diver))) => 
NIL 

In the following example, the callto assoc-if-not finds the first pair in a-list such 
that its key is not string-equal to "salary". 

(assoc-if-not ft' (lambda(x) (string-equal "salary" x)) 
a-1 ist) 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 

Compatibility Note: :key is a Symbolics extension to Common Lisp, not available 
in CLOE. 



zhassq item in-list Function 

Looks up item in the association list in-list. The value is the first cons whose car 
is eq to item, or nil if none is found. Examples: 

(zl:assq 'r '((a . b) (c . d) (r . x) (s . y) (r . z))) 
=> (r . x) 



Page 884 



(zl:assq 'fooo '((foo . bar) (zoo . goo))) 
=> nil 

(zl:assq 'b '((a be) (be d) (x y z))) 
=> (b c d) 

You can rplacd the result of zkassq as long as it is not nil, if you want to update 
the "table" in-list. Example: 

(setq values '((x . 100) (y . 200) (z . 50))) 

(zl:assq 'y values) => (y . 200) 

(rplacd (zl:assq 'y values) 201) 

(zl:assq 'y values) => (y . 201) now 

A typical trick is to use (cdr (zkassq x y)). Since the cdr of nil is guaranteed to 
be nil, this yields nil if no pair is found (or if a pair is found whose cdr is nil.) 

zkassq could have been defined by: 

(defun zl:assq (item list) 
(cond ((null list) nil) 

((eq item (caar list)) (car list)) 
((zl:assq item (cdr list))) )) 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 



atan y &optional x Function 

With two arguments, y and x, computes and returns the arc tangent of the quanti- 
ty ylx. If either argument is a double-float, the result is also a double-float. In the 
two argument case neither argument can be complex. The returned value is in ra- 
dians and is always between -n (exclusive) and n (inclusive). The signs of y and x 
determine the quadrant of the result angle. 

Note that either y or x (but not both simultaneously) can be zero. The examples il- 
lustrate a few special cases. 

With only one argument y, atan computes and returns the arc tangent of y. The 
argument can be any noncomplex or complex number. The result is in radians and 
its range is as follows: for a noncomplex y the result is noncomplex and lies be- 
tween -n/2 and n/2 (both exclusive); for a complex y the range is that strip of the 
complex plane containing numbers with a real part between -n/2 and n/2. A num- 
ber with real part equal to -n/2 is not in the range if it has a non-positive imagi- 
nary part. Similarly, a number with real part equal to n/2 is not in the range if its 
imaginary part is non-negative. 

Examples: 



Page 885 



(atari 0) => 0.0 

(atari 673) => 0.0 ; (atari (/ y x)) 

(atari 1 1) => 0.7853982 ; first quadrant 

(atari 1 -1) => 2.3561945 ; second quadrant 

(atan -1 -1) => -2.3561945 ;third quadrant 

(atan -1 1) => -0.7853982 ; fourth quadrant 
(atan 10) => 1 .5707964 

(setq theta (/ pi 4)) -^ 0.785398 

(atan (cos theta) (sin theta)) = theta => 0.785398 
When given a single argument, atan accepts a complex argument. 
(atan (/ (cos theta) (sin theta))) = theta => 0.785398 

(atan y) is the same as 

(* -1 (log (* (+1 (* i y)) 

(sqrt (/ 1 (+1 (expt y 2))))))) 

For a table of related items, see the section "Trigonometric and Related 
Functions". 

zlratan y x Function 

Returns the angle, in radians, whose tangent is ylx. zlratan always returns a num- 
ber between zero and 2jt. 

Examples: 

(zl :atan 1 1) => 0.7853982 
(zl :atan -1 -1) => 3.926991 

For a table of related items: See the section "Trigonometric and Related 
Functions". 

zl:atan2 y x Function 

Returns the angle, in radians, whose tangent is ylx. zl:atan2 always returns a 
number between -n and n. 

Similar to zlratan, except that it accepts only noncomplex arguments. 

For a table of related items: See the section "Trigonometric and Related 
Functions". 

atanh number Function 

Computes and returns the hyperbolic arc tangent of number. The result is in radi- 
ans. The argument can be any noncomplex or complex number. Note that if the 
absolute value of the argument is greater than one, the result is complex even if 
the argument is not complex. 



Page 886 



The hyperbolic arc tangent being mathematically multiple-valued in the complex 
plane, atanh returns a principal value whose range is that strip of the complex 
plane containing numbers with imaginary parts between -jt/2 and n/2. Any number 
with an imaginary part equal to -%/2 is not in the range if its real part is non- 
negative; any number with imaginary part equal to n/2 is excluded from the range 
if its real part is non-positive. 

Example: 

(atanh 0) => 0.0 

For a table of related items, see the section "Hyperbolic Functions". 

atom object Function 

Returns t if object is not a cons, otherwise nil. 

Note that (atom ' ()) is true because () is equivalent to nil. 

(atom x) 
is equivalent to 

(type x 'atom) 
is equivalent to 

(not (typep x 'cons)) 

Note that arrays, strings, structures, vectors, numbers, and symbols are all atoms. 

(atom ' ()) => t 

(setq foo (make-array '(4 2)) bar "24" baz '(a foo bar)) 

(atom foo) => t 

(atom bar) => t 

(atom baz) => nil 

For a table of related items, see the section "Predicates that Operate on Lists". 

atom object Function 

Returns t if object is not a cons, otherwise nil. 

Note that (atom ' ()) is true because () is equivalent to nil. 

(atom x) 
is equivalent to 

(type x 'atom) 
is equivalent to 

(not (typep x 'cons)) 

Note that arrays, strings, structures, vectors, numbers, and symbols are all atoms. 



Page 887 



(atom ' ()) => t 

(setq foo (make-array '(4 2)) bar "24" baz '(a foo bar)) 

(atom foo) => t 

(atom bar) => t 

(atom baz) => nil 

For a table of related items, see the section "Predicates that Operate on Lists". 



atom Type Specifier 

atom is the type specifier symbol for the predefined Lisp object of that name. 

atom = (not cons). 
Examples: 

(typep 'a 'atom) => T 

(zl : typep 'a) => : SYMBOL 

(subtypep 'atom 'common) => NIL and NIL 

(atom 'a) => T 

(sys: type-argl ist 'atom) => NIL and T 

See the section "Data Types and Type Specifiers". 
See the section "Symbols, Keywords, and Variables". 

&aux Lambda List Keyword 

Separates the arguments of a function from the auxiliary variables. If it is present, 
all specifiers after it are entries of the form: 

(variable initial-value-form) 

zhbase Variable 

The value of zhbase is a number that is the radix in which integers and ratios 
are printed in, or a symbol with a shprinc-function property. The initial value of 
zhbase is 10. zhbase should not be greater than 36 or less than 2. 

The printing of trailing decimal points for integers in base 10 is controlled by the 
value of variable *print-radix*. See the section "Printed Representation of Rational 
Numbers". 

In your new programs use the Common Lisp variable *print-base*. 

beep &optional beep-type (stream zhterminal-io) Function 

Tries to attract the user's attention by causing an audible beep, or flashing the 
screen, or something similar. If the stream supports the :beep operation, this func- 
tion sends it a :beep message, passing type along as an argument. Otherwise it 



Page 888 



just causes an audible beep on the terminal, type is a keyword selecting among 
several different beeping noises. The allowed types have not yet been defined; type 
is currently ignored and should always be nil. See the message :beep. 



:beep &optional type Message 

This is supported by interactive streams. It attracts the attention of the user by 
making an audible beep and/or flashing the screen, type is a keyword selecting 
among several different beeping noises. The allowed types have not yet been de- 
fined; type is currently ignored and should always be nil. 



bignum Type Specifier 

bignum is the type specifier symbol for the predefined primitive Lisp object of 
that name. 

The types bignum and fixnum are an exhaustive partition of the type integer, 
since integer = (or bignum fixnum). These two types are internal representations 
of integers used by the system for efficiency depending on integer size; in general, 
bignums and fixnums are transparent to the programmer. 

Examples: 

(typep 1000000000000000000000000000000000 'bignum) => T 

(typep '1 'bignum) => NIL 

(zl: typep '10000000000000000000000000000000) => :BIGNUM 

(subtypep 'bignum 'integer) => T and T ; subtype and certain 

(typep 565682366398848747848463539404874 'common) => T 

(zl:bigp 444444444445555555555555555556666666666666) => T 

(sys: type-argl ist 'bignum) => NIL and T 

(type-of 09889374897338373689484949494373639484099876) => BIGNUM 
See the section "Data Types and Type Specifiers". 
See the section "Numbers". 

zhbigp object Function 

Returns t if object is a bignum, otherwise nil. 

For a table of related items, see the section "Numeric Type-checking Predicates". 

bit array &rest subscripts Function 

Returns the element of array selected by the subscripts. The subscripts must be in- 
tegers and their number must match the dimensionality of array. The array must 
be an array of bits. 



Page 889 



(setq foo (make-array (2 3) 
: adjustable t 
: element-type 'bit 
: initial-contents '((1 1 1) 

(1 1)))) 

(bit foo 1 1) => 

Note that the bit-array in the previous example is adjustable, and therfore not 
simple. Therfore, we can not use sbit for foo. We could have used aref, but bit is 
generally more efficient for bit-arrays. 

For a table of related items: See the section "Arrays of Bits". 

bit Type Specifier 

bit is equivalent to the type (integer 1) and (unsigned-byte 1). 

bit-and first second &optional third Function 

Performs logical and operations on bit arrays. The arguments must be bit arrays 
of the same rank and dimensions. A new array is created to contain the result if 
the third argument is nil or omitted. If the third argument is t, the first array is 
used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 

bit-andcl first second &optional third Function 

Performs logical and operations on the complement of first with second on bit ar- 
rays. The arguments must be bit arrays of the same rank and dimensions. A new 
array is created to contain the result if the third argument is nil or omitted. If 
the third argument is t, the first array is used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 

bit-andc2 first second &optional third Function 

Performs logical and operations on first with the complement of second on bit ar- 
rays. The arguments must be bit arrays of the same rank and dimensions. A new 
array is created to contain the result if the third argument is nil or omitted. If 
the third argument is t, the first array is used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 

bit-eqv first second &optional third Function 

Performs logical exclusive nor operations on bit arrays. The arguments must be bit 
arrays of the same rank and dimensions. A new array is created to contain the re- 



Page 890 



suit if the third argument is nil or omitted. If the third argument is t, the first 
array is used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 



bit-ior first second &optional third Function 

Performs logical inclusive or operations on bit arrays. The arguments must be bit 
arrays of the same rank and dimensions. A new array is created to contain the re- 
sult if the third argument is nil or omitted. If the third argument is t, the first 
array is used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 



bit-nand first second &optional third Function 

Performs logical not and operations on bit arrays. The arguments must be bit ar- 
rays of the same rank and dimensions. A new array is created to contain the re- 
sult if the third argument is nil or omitted. If the third argument is t, the first 
array is used to hold the result. 



bit-nor first second &optional third Function 

Performs logical not or operations on bit arrays. The arguments must be bit arrays 
of the same rank and dimensions. A new array is created to contain the result if 
the third argument is nil or omitted. If the third argument is t, the first array is 
used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 



bit-not source &optional destination Function 

Returns a bit-array of the same rank and dimensions that contains a copy of the 
argument with all the bits inverted, source must be a bit-array. If destination is nil 
or omitted, a new array is created to contain the result. If destination is t, the re- 
sult is destructively placed in the source array. 

(bit-not #*1001) => #*0110 

For a table of related items: 

See the section "Arrays of Bits". 



bit-orcl first second &optional third Function 

Performs logical or operations on the complement of first with second on bit ar- 
rays. The arguments must be bit arrays of the same rank and dimensions. A new 
array is created to contain the result if the third argument is nil or omitted. If 
the third argument is t, the first array is used to hold the result. 



Page 891 



For a table of related items: See the section "Arrays of Bits". 



bit-orc2 first second &optional third Function 

Performs logical or operations on first with the complement of second on bit ar- 
rays. The arguments must be bit arrays of the same rank and dimensions. A new 
array is created to contain the result if the third argument is nil or omitted. If 
the third argument is t, the first array is used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 



zl:bit-test x y Function 

In your new programs, we recommend that you use the function logtest, which is 
the Common Lisp equivalent of the function zl:bit-test. 

zl:bit-test is a predicate that returns t if any of the bits designated by the l's in x 

are l's in y. 

For a table of related items: See the section "Predicates for Testing Bits in Inte- 
gers". 



bit-vector &optional ( size '* ) Type Specifier 

bit-vector is the type specifier symbol for the Lisp data structure of that name. 

The type bit-vector is a subtype of the type vector; (bit-vector) means (vector 
bit). 

The type bit-vector is a supertype of the type simple-bit-vector. 

The types (vector t), string, and bit-vector are disjoint. 

This type specifier can be used in either symbol or list form. Used in list form, 
bit-vector allows the declaration and creation of specialized types of bit vectors 
whose size is restricted to the specified size, (bit-vector size) means the same as 
(array bit (size)): the set of bit-vectors of the indicated size. 

Examples: 

(setq array-bit-vector 

(make-array '(3) : element-type 'bit : f il 1-pointer 2)) 
=> #<ART-1B-3 43015121> 

(typep #*10110 'bit-vector) => T 

(typep #*101 '(bit-vector 3)) => T 

(typep array-bit-vector 'bit-vector) => T 

(subtypep 'bit-vector 'vector) => T and T 

(bit-vector-p #x) => T ; empty bit vector 

(sys:type-arglist 'bit-vector) => (&0PTI0NAL (SIZE '*)) and T 

See the section "Data Types and Type Specifiers". 



Page 892 



See the section "Arrays". 



bit-vector-cardinality bit-vector &key (.start 0) send Function 

Counts how many of the bits in the range are one's and returns the number 
found. 

bit-vector is a one-dimensional array whose elements are required to be bits. See 
the type specifier bit-vector. 

rstart and rend must be non-negative integer indices into the bit-vector, rstart 
must be less than or equal to rend, or else an error is signalled, rstart defaults to 
zero (the start of the bit vector). 

rstart indicates the start position for the operation within the bit-vector, rend is 
the position of the first element in the bit-vector beyond the end of the operation. 

For example: 

(bit-vector-cardinality #*11111) 
=> 5 

(bit-vector-cardinality #*11100) 
=> 3 

(bit-vector-cardinality #*1110011 :start :end 5) 
=> 3 

For a table of related items: See the section "Operations on Vectors". 

bit-vector-disjoint-p bit-vector-1 bit-vector-2 &key (sstartl 0) :endl (:start2 0) :end2 

Function 

Tests two bit vectors to see if they are disjoint (have no common positions contain- 
ing l's) in a range specified by rstartl, rendl, rstart2, and rend2. 

bit-vector-1 and bit-vector-2 are one-dimensional arrays whose elements are required 
to be bits. See the type specifier bit-vector. 

rstartl, rendl, rstart2, and rend2 must be non-negative integer indices into bit- 
vectorl and bit-vector-2. rstartl and rstart2 must be less than or equal to rendl and 
rend2, or else an error is signalled, rstartl and rstart2 default to zero (the start of 
the bit vector). If rend is unspecified or nil, the length bit-vector is used. 

rstartl and rstart2 indicate the start positions for the operation within the bit- 
vector, rendl and rend2 are the position of the first element in the bit-vector be- 
yond the end of the operation. 

For example: 



Page 893 



(bit-vector-disjoint-p #*001000001 #*001000001) 
=> NIL 

(bit-vector-disjoint-p #*1 110010000 #*1 11 001 0011) 
=> NIL 

(bit-vector-disjoint-p #*1 110010000 #*1110010011 :start1 1 :end1 6 :start2 6 :end2 8) 
=> T 

For a table of related items: See the section "Operations on Vectors". 

bit-vector-p object Function 

Tests whether the given object is a bit vector. A bit vector is a one-dimensional ar- 
ray whose elements are required to be bits. See the type specifier bit-vector. 

(bit-vector-p (make-array 3 : element-type 'bit : f il 1-pointer 2)) 
=> T 

(bit-vector-p (make-array 5 :element-type 'string-char)) 
=> NIL 

For a table of related items: See the section "Operations on Vectors". 

bit-vector-position bit bit-vector &key (.start 0) send Function 

If bit-vector contains an element matching bit, returns the index within the bit vec- 
tor of the leftmost such element as a non-negative integer; otherwise nil is re- 
turned. 

bit is either or 1. 

bit-vector is a one-dimensional array whose elements are required to be bits. See 
the type specifier bit-vector. 

rstart and rend must be non-negative integer indices into the bit-vector, rstart 
must be less than or equal to rend , or else an error is signalled, rstart defaults to 
zero (the start of the bit vector). If rend is unspecified or nil, the length bit- 
vector is used. 

rstart indicates the start position for the operation within the bit vector, rend is 
the position of the first element in the bit-vector beyond the end of the operation. 

For example: 

(bit-vector-position 1 #*11111) 



(bit-vector-position 1 #*0011111) 
=> 2 



Page 894 



(bit-vector-position 1 #*0011111 :start 3 :end 5) 
=> 3 

(bit-vector-position #*111) 
=> NIL 

For a table of related items: See the section "Operations on Vectors". 



bit-vector-subset-p bit-vector-1 bit-vector-2 &key Ostartl 0) :endl (:start2 0) :end2 

Function 

Tests if one bit vector is a subset of another bit vector (subset means that for 
each position of bit-vector-2 that contains a one, the same position in bit-vector-1 
also contains a 1) in a range specified by rstartl, :endl, :start2, and :end2. 

bit-vector-1 and bit-vector-2 are one-dimensional arrays whose elements are required 
to be bits. See the type specifier bit-vector. 

rstartl, rendl, :start2, and :end2 must be non-negative integer indices into bit- 
vectorl and bit-vector-2. rstartl and :start2 must be less than or equal to rendl and 
:end2, else an error is signalled, rstartl and rstart2 default to zero (the start of 
the bit vector). If rend is unspecified or nil, the length bit-vector is used. 

rstartl and rstart2 indicate the start position for the operation within the bit vec- 
tor, rendl and rend2 are the positions of the first element in the bit-vector beyond 
the end of the operation. 

For example: 

(bit-vector-subset-p #*00100100111 #*00100100111) 
=> T 

(bit-vector-subset-p #*1 11 001 0011 #*0010010011) 
=> NIL 

(bit-vector-subset-p #*11100000 #*11100011 :start1 :end1 6 :start2 :end2 6) 
=> T 

(bit-vector-subset-p #*11100000 #*11100011 :start1 :end1 8 :start2 :end2 8) 
=> NIL 

For a table of related items: See the section "Operations on Vectors". 



bit-vector-zero-p bit-vector &key (.start 0) send Function 

Tests if bit-vector is a bit vector of zeros in the range specified by rstart and rend. 

bit-vector is a one-dimensional array whose elements are required to be bits. 

rstart and rend must be non-negative integer indices into the bit-vector, rstart 
must be less than or equal to rend, or else an error is signalled, rstart defaults to 
zero (the start of the bit vector). 



Page 895 



rstart indicates the start position for the operation within the bit vector, rend is 
the position of the first element in the bit-vector beyond the end of the operation. 
See the type specifier bit-vector. 

For example: 

(bit-vector-zero-p #*00000 :start :end 5) 
=> T 

(bit-vector-zero-p #*00011) 
=> NIL 

(bit-vector-zero-p #*00011 : start :end 3) 
=> T 

For a table of related items: See the section "Operations on Vectors". 



bit-xor first second &optional third Function 

Performs logical exclusive or operations on bit arrays. The arguments must be bit 
arrays of the same rank and dimensions. A new array is created to contain the re- 
sult if the third argument is nil or omitted. If the third argument is t, the first 
array is used to hold the result. 

For a table of related items: See the section "Arrays of Bits". 



bitblt alu width height from-raster from-x from-y to-raster to-x to-y Function 

Copies a rectangular portion of from-raster into a rectangular portion of to-raster. 
from-raster and to-raster must be two-dimensional arrays of bits or bytes (sysrart- 
lb, sys:art-2b, sys:art-4b, sys:art-8b, sys:art-16b, or sysrart-fixnum). The value 
stored can be a Boolean function of the new value and the value already there, un- 
der the control of alu. This function is most commonly used in connection with 
raster images for TV displays. 

The top-left corner of the source rectangle is: 

(raster-aref from-raster from-x from-y) 
The top-left corner of the destination rectangle is: 

(raster-aref to-raster to-x to-y) 

width and height are the dimensions of both rectangles. If width or height is zero, 
bitblt does nothing. 

from-raster and to-raster are allowed to be the same array, bitblt normally travers- 
es the arrays in increasing order of x and y subscripts. If width is negative, 
(abs width) is used as the width, but the processing of the x direction is done 
backwards, starting with the highest value of x and working down. If height is 
negative it is treated analogously. When bitblting an array to itself, when the two 
rectangles overlap, it might be necessary to work backwards to achieve the desired 



Page 896 



effect, such as shifting the entire array upwards by a certain number of rows. 
Note that negativity of width or height does not affect the (x,y) coordinates speci- 
fied by the arguments, which are still the top-left corner even if bitblt starts at 
some other corner. 

If the two arrays are of different types, bitblt works bit-wise and not element-wise. 
That is, if you bitblt from an sys:art-2b raster into an sys:art-4b raster, then two 
elements of the from-raster correspond to one element of the to-raster. width is in 
units of elements of the to-raster. Note that the width and heigth arguments are 
relative to the to-raster array, not the from-raster array. 

If bitblt goes outside the bounds of the source array, it wraps around. This allows 
such operations as the replication of a small stipple pattern through a large array. 
If bitblt goes outside the bounds of the destination array, it signals an error. 

If src is an element of the source rectangle, and dst is the corresponding element 
of the destination rectangle, then bitblt changes the value of dst to (boole alu src 
dst). The following are the symbolic names for some of the most useful alu func- 
tions: 

tv:alu-seta plain copy 

tv:alu-setz set destination to 

tv:alu-ior inclusive or 

tv:alu-xor exclusive or 

tv:alu-andca and with complement of source 

For a chart of more alu possibilities: See the function boole. 

bitblt is written in highly optimized microcode and goes very much faster than the 
same thing written with ordinary raster operations would. Unfortunately this caus- 
es bitblt to have a couple of strange restrictions. Wraparound does not work cor- 
rectly if from-raster is an indirect array with an index offset. On black-and-white 
screens, bitblt signals an error if the widths of from-raster and to-raster are not 
both integral multiples of the machine word length. On color screens, the product 
of the number of bits per raster element and the width must be an integral multi- 
ple of 32. You can determine the number of bits per raster element by the number 
of bits which correspond to a single pixel on the screen. For sys:art-lb arrays, 
width must be a multiple of 32., for sys:art-2b arrays it must be a multiple of 16., 
and so on. Use :draw-l-bit-raster rather than bitblt in programs that run without 
modification on color screens. 

For a table of related items: See the section "Operations on Rasters". Also: See the 
section "Copying an Array". 



block name &body body 

Special Form 

Provides an exit context for the evaluation of its body argument. Evaluates each 
form in sequence and normally returns the (possibly multiple) values of the last 
form. However, (return-from name value) or (return or (return (values-list list)) 



Page 897 



form) might be evaluated during the evaluation of some form. In that case, the 
(possibly multiple) values that result from evaluating value are immediately re- 
turned from the innermost block that has the same name and that lexically con- 
tains the return-from form. Any remaining forms in that block are not evaluated. 

name is not evaluated. It must be a symbol. 

The scope of name is lexical. That is, the return-from form must be inside the 
block itself (or inside a block that that block lexically contains), not inside a func- 
tion called from the block. 

do, prog, and their variants establish implicit blocks around their bodies; you can 
use return-from to exit from them. These blocks are named nil unless you specify 
a name explicitly. 

Examples: 

(block nil 

(print "clear") 

(return) 

(print "open")) => "clear" NIL 

(let ((x 2400)) 
(block time-x 
(when (= x 2400) 

(return-from time-x "time to go")) 
("time time time"))) => "time to go" 

(defun bar () 
(princ "zero ") 
(block a 

(princ "one ") (return-from a "two ") 
(princ "three ")) 
(princ "four ") 
t) => BAR 
(bar) => zero one four T 

(block negative 

(mapcar (function (lambda (x) 

(cond ((minusp x) 

(return-from negative x)) 



(t (f x))) )) 



y)) 



(block foo 

(let ((num xa-numberx) 
(result 0)) 
(dotimes (i num result) 

(if (= i 20) (return-from foo result)) 
(setq result (+ result (expt i 2)))))) 

defun establishes an implicit block whose name is the same as that of the defined 



Page 898 



function. 

(defun matrix-find (elt matrix) 

(dotimes (i (array-dimension matrix 0)) 
(dotimes (j (array-dimension matrix 1)) 
(if (eql elt (aref matrix i j)) 

(return-from matrix-find (values i j)))))) 

The following two forms are equivalent: 

(cond ((predicate x) 

(do-one-thing)) 
(t 
(format t "The value of X is ~S~%" x) 
(do- the-other- thing) 
(do-somethi ng-el se-too) ) ) 

(block deal-with-x 
(when (predicate x) 

(return-from deal-with-x (do-one-thing))) 
(format t "The value of X is ~S~%" x) 
(do- the-other- thing) 
(do-somethi ng-el se-too) ) 

The interpreter and compiler generate implicit blocks for functions whose name is 
a list (such as methods) just as they do for functions whose name is a symbol. You 
can use return-from for methods. The name of a method's implicit block is the 
name of the generic function it implements. If the name of the generic function is 
a list, the block name is the second symbol in that list. 

For a table of related items: See the section "Blocks and Exits Functions and Vari- 
ables". 



&body Lambda List Keyword 

This keyword is used with macros only. It is identical in function to &rest, but it 
informs output-formatting and editing functions that the remainder of the form is 
treated as a body, and should be indented accordingly. 

Note that either &body or &rest, but not both, should be used in any definition. 



boole op integerl &rest more-integers Function 

This function is the generalization of logical functions such as zhlogand, zhlogior 
and zhlogxor. It performs bit-wise logical operations on integer arguments return- 
ing an integer which is the result of the operation. 

The argument op specifies the logical operation to be performed; sixteen operations 
are possible. These are listed and described in the table below which also shows 
the truth tables for each value of op. 



Page 899 



op can be specified by writing the name of one of the constants listed below which 
represents the desired operation, or by using an integer between and 15 inclusive 
which controls the function that is computed. If the binary representation of op is 
abed (a is the most significant bit, d the least) then the truth table for the 
Boolean operation is as follows: 

integer2 
I 1 



integerl 



HI a c 
1 I b d 



Examples: 

(boole 6 0) => 
(boole 11 1 0) => -2 
(boole 2 6 9) => 9 



; a=0 

; a=1 and b=0 

; a=b=d=0 c=1 therefore 1's appear only 

; when integerl is and integer2 is 1 



With two arguments, the result of boole is simply its second argument. At least 
two arguments are required. 

If boole has more than three arguments, it is associated left to right; thus, 

(boole op x y z) = (boole op (boole op x y) z) 
(boole boole-and 1 1) => 

For the basic case of three arguments, the results of boole are shown in the table 
below. This table also shows the value of bits abed in the binary representation of 
op for each of the sixteen operations. (For example, boole-clr corresponds to 
#b0000, boole-and to #b0001, and so on.) As the table shows, 



op = (boole op 


#b0101 #b0011) 


= (boole op 5 3) 




a 


b 


c 


d 




Integerl 





1 





1 




op Integer2 








1 


1 


Operation Name 


boole-clr 














clear, always 


boole-and 











1 


and 


boole-andcl 








1 





and complement of integerl 
with integer2 


boole-2 








1 


1 


last of more-integers 


boole-andc2 





1 








and integerl with complement 
of integer2 


boole-1 





1 





1 


integerl 


boole-xor 





1 


1 





exclusive or 


boole-ior 





1 


1 


1 


inclusive or 


boole-nor 


1 











nor (complement of 
inclusive or) 


boole-eqv 


1 








1 


equivalence {exclusive nor) 



boole-cl 
boole-orcl 


1 
1 






1 
1 




1 


boole-c2 
boole-orc2 


1 
1 


1 
1 








1 


boole-nand 
boole-set 


1 
1 


1 
1 


1 
1 




1 



Page 900 



complement of integerl 
or complement of integerl 
with integer2 
complement of integer2 
or integerl with complement 
of integer2 

nand (complement of and) 
set, always 1 

Examples: 

(boole boole-cl r 3) => 3 ;with two arguments always returns 

; integerl 
(boole boole-set 7) => 7 

(boole boole-1 1 0) => 1 
(boole boole-2 1 0) => 

(boole boole-orc2 1 4) => -5 

(boole (if flag then boole-xor boole-ior) intl int2) 

As a matter of style the explicit logical functions such as logand, logior, and 
logxor are usually preferred over the equivalent forms of boole. boole is useful, 
however, when you want to generalize a procedure so that it can use one of sever- 
al logical operations. 

For a table of related items: See the section "Functions Returning Result of Bit- 
wise Logical Operations". 



boole-1 Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical operation that returns the first integer argument of boole. 



boole-2 Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical operation that returns the last integer argument of boole. 



boole-and Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical and operation to be performed on the integer arguments of boole. 



boole-andcl Constant 



Page 901 



Can be used as the first argument to the function boole; it specifies a logical op- 
eration to be performed on the integer arguments of boole, namely, a bit-wise logi- 
cal and of the complement of the first integer argument with the next integer ar- 
gument. 



boole-andc2 Constant 

Can be used as the first argument to the function boole; it specifies a logical op- 
eration to be performed on the integer arguments of boole, namely, a bit-wise logi- 
cal and of the first integer argument with the complement of the next integer ar- 
gument. 



boole-cl Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical operation that returns the complement of the first integer argument of boole. 



boole-c2 Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical operation that returns the complement of the last integer argument of boole. 



boole-clr Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical clear operation to be performed on the integer arguments of boole. 



boole-eqv Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical equivalence operation to be performed on the integer arguments of boole. 



boole-ior Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical inclusive or operation to be performed on the integer arguments of boole. 



boole-nand Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical not-and operation to be performed on the integer arguments of boole. 



boole-nor Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical not-or operation to be performed on the integer arguments of boole. 



Page 902 



boole-orcl Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical operation to be performed on the integer arguments of boole, namely, the logi- 
cal or of the complement of the first integer argument with the next integer ar- 
gument. 



boole-orc2 Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical operation to be performed on the integer arguments of boole, namely, the logi- 
cal or of the first integer argument with the complement of the next integer ar- 
gument. 



boole-set Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical set operation to be performed on the integer arguments of boole. 



boole-xor Constant 

Can be used as the first argument to the function boole; it specifies a bit-wise log- 
ical exclusive or operation to be performed on the integer arguments of boole. 



both-case-p char Function 

Returns t if char is a letter that exists in another case. 

(both-case-p #\M) => T 
(both-case-p #\m) => T 

Returns T if char is an uppercase character and a lowercase character analog can 
be obtained by using char-downcase, or if char is a lowercase character and an up- 
percase character analog can be obtained by using char-upcase. 

(both-case-p #\$) => nil 
(both-case-p #\a) => t 

For a table of related items, see the section "Character Predicates". 

boundp symbol Function 

Returns t if the dynamic (special) variable symbol is bound; otherwise, it returns 
nil. 

(defvar xalarmsx) 
(boundp 'xalarmsx) => nil 



Page 903 



(setq xalarmsx 20) 

(boundp 'xalarmsx) => t 
See the section "Functions Relating to the Value of a Symbol". 

boundp-in-closure closure symbol Function 

Returns t if symbol is bound in the environment of closure; that is, it does what 
boundp would do if you restored the value cells known about by closure. If symbol 
is not closed over by closure, this is just like boundp. See the section "Dynamic 
Closure-Manipulating Functions". 

boundp-in-instance instance symbol Function 

Returns t if the instance variable symbol is bound in the given instance. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 

break &optional format-string &rest format-args Function 

Like zhdbg, when evaluated, causes entry to the Debugger (a Debugger Break). 
However, break takes a format-string and format-args instead of a process. 

The format-string is a user-written error message that is printed in the Debugger's 
Break message whenever break is encountered and you enter the Debugger, for- 
mat-args are the zhformat-style arguments to zhformat directives in format-string. 

break is a temporary way to insert Debugger breakpoints into your program while 
you are debugging it. It is not designed for permanent use in your program as a 
way of signalling errors. Therefore, you would use this function only for the dura- 
tion of your debugging session. Continuing from break will not trigger any unusu- 
al recovery action. 

zhbreak &optional tag (conditional t) Special Form 

Enters a breakpoint loop, which is similar to a Lisp top-level loop, (zhbreak tag) 
always enters the loop; (zhbreak tag conditional) evaluates conditional and only 
enter the break loop if it returns non-nil. If the break loop is entered, zhbreak 
prints out: 

; Breakpoint tag; Resume to continue, Abort to quit. 

The standard values for any variables are checked. If zhbreak rebinds any of 
these standard variables, it warns you that it has done so. zhbreak then enters a 
loop reading, evaluating, and printing forms. A difference between a break loop 
and the top-level loop is that when reading a form, zhbreak checks for the follow- 
ing special cases: If the RBORT key is pressed, control is returned to the previous 



Page 904 



break or Debugger, or to top level if there is none. If the RESUME key is pressed, 
zhbreak returns nil. If the list (return form) is typed, zhbreak evaluates form 
and returns the result. 

Inside the zhbreak loop, the streams zhstandard-output, zhstandard-input, and 
zl:query-io are bound to be synonymous to zl:terminal-io; zl:terminal-io itself is 
not rebound. Several other internal system variables are bound, and you can add 
your own symbols to be bound by pushing elements onto the value of the variable 
sys:*break-bindings*. (See the variable sys:*break-bindings*.) 

If tag is omitted, it defaults to nil. 

There are two easy ways to write a breakpoint into your program: (zhbreak) gets 
a read-eval-print loop, and (zhdbg) gets the Debugger. (These are the programmat- 
ic equivalents of the SUSPEND and n-SUSPEND keys on the keyboard.) 



sys:*break-bindings* Variable 

When zhbreak is called, it binds some special variables under control of the list 
that is the value of sys:*break-bindings*. Each element of the list is a list of two 
elements: a variable and a form that is evaluated to produce the value to bind it 
to. The bindings happen sequentially. You can push things on this list (adding to 
the front of it), but should not replace the list wholesale since several of the vari- 
able bindings on this list are essential to the operation of zhbreak. 



*break-on-warnings* Variable 

This variable controls the action of the function warn. If *break-on-warnings* is 
nil, warn prints a warning message without signalling. 

If *break-on-warnings* is not nil, warn enters the Debugger and prints the warn- 
ing message. The default value is nil. 

This flag is intended primarily for use when you are debugging programs that is- 
sue warnings. 

Note that this flag is still supported but is considered obsolete. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



breakon &optional function (condition t) 

Function 

With no arguments, returns a list of all functions with breakpoints set by 
breakon. 

breakon sets a trace-style breakpoint for the function. Whenever the function 
named by function is called, the condition dbg:breakon-trap is signalled, and the 
Debugger assumes control. At this point, you can inspect the state of the Lisp en- 
vironment and the stack. Proceeding from the condition then causes the program 
to continue to run. 



Page 905 



The first argument can be any function, so that you can trace methods and other 
functions not named by symbols. See the section "Function Specs". 

condition can be used for making a conditional breakpoint, condition should be a 
Lisp form. It is evaluated when the function is called. If it returns nil, the func- 
tion call proceeds without signalling anything, condition arguments from multiple 
calls to breakon accumulate and are treated as an or condition. Thus, when any 
of the forms becomes true, the breakpoint "goes off", condition is evaluated in the 
dynamic environment of the function call. You can inspect the arguments of func- 
tion by looking at the variable arglist. 

For a table of related items: See the section "Breakpoint Functions". 



dbgrbug-report-description condition stream nframes Generic Function 

Called by the :Mail Bug Report (c-M) command in the Debugger to print out the 
text that is the initial contents of the mail-sending buffer. The handler should sim- 
ply print whatever information it considers appropriate onto stream, nframes is the 
numeric argument given to c-M. The Debugger interprets nframes as the number 
of frames from the backtrace to include in the initial mail buffer. A nframes of nil 
means all frames. 

The compatible message for dbgrbug-report-description is: 

:bug-report-description 

For a table of related items: See the section "Debugger Bug Report Functions". 

dbgrbug-report-recipient-system condition Generic Function 

Called by the :Mail Bug Report (c-M) command in the Debugger to find the mail- 
ing list to which to send the bug report mail. The mailing list is returned as a 
string. 

The default method (the one in the condition flavor) returns "lispm", and this is 
passed as the first argument to the zhbug function. 

The compatible message for dbgrbug-report-recipient-system is: 
:bug-report-recipient-system 

For a table of related items: See the section "Debugger Bug Report Functions". 

clos:built-in-class Class 

The class of many of the predefined classes corresponding to Common Lisp types, 
such as list and t. 

These classes (objects whose class is clos:built-in-class) are provided so users can 
define methods that specialize on them. They do not support the full behavior of 
user-defined classes (whose class is clos:standard-class). For example, you cannot 
use closrmake-instance to create instances of these classes. 



Page 906 



butlast x &optional (n 1) Function 

Creates and returns a list with the same elements as x, excepting the last element. 
Examples: 

(butlast '(abed)) => (a b c) 
(butlast '((a b) (c d))) => ((a b)) 
(butlast ' (a)) => nil 
(butlast nil) => nil 
(setq a '(1 2 3 4 5 6 7)) 
(butlast a) => (1 2 3 4 5 6) 
(butlast a 4) => (1 2 3) 
a => (1 2 3 4 5 6 7) 

The name is from the phrase "all elements but the last". 

For a table of related items: See the section "Functions for Modifying Lists". 

byte size position Function 

Creates a byte specifier for a byte size bits wide, position bits from the right-hand 
(least-significant) end of the word. The arguments size and position must be inte- 
gers greater than or equal to zero. 

The byte specifier so created serves as an argument to various byte manipulation 
functions. 

Examples: 

(ldb (byte 2 1) 9) => 
(ldb (byte 3 4) #o12345) => 6 
(setq byte-spec (byte 5 2)) 
(byte-size byte-spec) => 5 
(byte-position byte-spec) => 2 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 

byte-position bytespec Function 

Extracts the position field of bytespec. 

bytespec is built using function byte with bit size and position arguments. 

Example: 

(byte-position (byte 3 4)) => 4 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 

byte-size bytespec Function 

Extracts the size field of bytespec. 



Page 907 



bytespec is built using function byte with bit size and position arguments. 

Example: 

(byte-size (byte 3 4)) => 3 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



caaaar x 

(caaaar x) is the same as (car (car (car (car x)))) 



Function 



caaadr x 

(caaadr x) is the same as (car (car (car (cdr x)))) 



Function 



caaar x 

(caaar x) is the same as (car (car (car x))) 



Function 



caadar x 

(caadar x) is the same as (car (car (cdr (car x)))) 



Function 



caaddr x 

(caaddr x) is the same as (car (car (cdr (cdr x)))) 



Function 



caadr x 

(caadr x) is the same as (car (car (cdr x))) 



Function 



caar x 



(caar x) is the same as (car (car x)) 



Function 



cadaar x 

(cadaar x) is the same as (car (cdr (car (car x)))) 



Function 



cadadr x 



Function 



(cadadr x) is the same as (car (cdr (car (cdr x)))) 



Page 908 



cadar x 

(cadar x) is the same as (car (cdr (car x))) 



Function 



caddar x 

(caddar x) is the same as (car (cdr (cdr (car x)))) 



Function 



cadddr x 

(cadddr x) is the same as (car (cdr (cdr (cdr x)))) 



Function 



caddr x 

(caddr x) is the same as (car (cdr (cdr x))) 



Function 



cadr x 



Function 



(cadr x) is the same as (car (cdr x)) 



call-arguments-limit 



Constant 



A positive integer that is the upper exclusive bound on the number of arguments 
that can be passed to a function. The current value is 128 for 3600-series ma- 
chines, 50 for Ivory-based machines, and 256 for CLOE. 

For example, let's assume that we have two functions, process-elements-pairwise 
and process-elements-atonce. The first takes the elements of an array and oper- 
ates on them by repeatedly calling a subordinate function of two variables. The 
second function atonce calls a subordinate function that takes each element of the 
array as arguments. Then we might use the following code to call the appropriate 
function: 

(if (> (array-total-size array) call-arguments-limit) 
(process-el ements-pai rwi se array) 
(process-elements-atonce array)) 



flavorrcall-component-method function-spec &key apply arglist 



Function 



Produces a form that calls function-spec, which must be the function-spec for a 
component method. If no keyword arguments are given to flavorrcall-component- 



Page 909 



method, the method receives the same arguments that the generic function re- 
ceived. That is, the first argument to the generic function is bound to self inside 
the method, and succeeding arguments are bound to the argument list specified 
with defmethod. Additional internal arguments are passed to the method, but the 
user never needs to be concerned about these. 

arglist is a list of forms to be evaluated to supply the arguments to the method, 
instead of simply passing through the arguments to the generic function. 

When arglist and apply are both supplied, :apply should be followed by t or nil. If 
rapply t is supplied, the method is called with apply instead of funcall. :apply nil 
causes the method to be called with funcall. 

When arglist is not supplied, the value following rapply is the argument that 
should be given to apply when the method is called. (Certain internal arguments 
are also included in the apply form.) For example: 

(flavor :cal 1 -component-method function-spec : apply list) 
Results in: 

(apply ft' function-spec internal arguments list) 

In other words, the following two forms have the same effect: 

(flavor :cal 1 -component-method function-spec : apply list) 
(flavor :cal 1 -component-method function-spec : arglist (list list) 

: apply t) 

If function-spec is nil, flavorrcall-component-method produces a form that returns 
nil when evaluated. 

For examples, see the section "Examples of define-method-combination". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



flavorrcall-component-methods function-spec-list &key (operator 'progn) Function 

Produces a form that invokes the function or special form named operator. Each 
argument or subform is a call to one of the methods in function-spec-list, operator 
defaults to progn. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



closrcall-method method &optional next-method-list Macro 

Used within effective method forms (forms returned by the body of closrdefine- 
method-combination) to call a method. The macro closrcall-method calls the 
method and supplies it with the arguments that were supplied to generic function. 

The next-method-list argument to closrcall-method defines the "next method" for 
closrcall-next-method and closmext-method-p. That is, if closrcall-next-method is 



Page 910 



called within the method, the first method in next-method-list will be called; if 
clos:call-next-method is called within that method, the second method in next- 
method-list will be called, and so on. 

method A method object, or a list such as (closrmake-method form). 

Such a list specifies a method object whose method function 
has a body that is the given Lisp form. 

next-method-list A list of method objects. Each element is either a method ob- 
ject or a list such as (closrmake-method form), as described 
above. 

closrcall-method returns the value or values returned by the method. 

When closrcall-method is called and the next-method-list argument is unsupplied, 
it means that semantically there is no such thing as a "next method"; for example, 
this is true for before-methods and after-methods in closrstandard method combi- 
nation. Thus, when the next-method-list is unsupplied, closrcall-next-method is not 
allowed inside the method, and the behavior of closmext-method-p is undefined. If 
the next-method-list argument is supplied as nil, and the method uses closrcall- 
next-method, then closmo-next-method is called. 



closrcall-next-method &rest args Function 

Used within a method body to call the "next method", closrcall-next-method re- 
turns the value or values returned by the method it calls. 

args Arguments to be passed to the next method. If any args are 

provided, the following condition must hold: the ordered set of 
methods applicable for args must be the same as the ordered 
set of methods applicable for the arguments that were passed 
to the generic function. If this requirement is not satisfied, an 
error is signaled. 

If no args are provided, closrcall-next-method passes the 
method's original arguments on to the next method. 

The method-combination type in use determines which kinds of methods can use 
closrcall-next-method, and defines the meaning of "next method". The 
closrstandard method-combination type supports closrcall-next-method in around- 
methods and primary methods, but not in before-methods or after-methods. It de- 
fines the next method as follows: 

• If closrcall-next-method is called in an around-method, the next method is the 
next most specific around-method, if one is applicable. 

• If closrcall-next-method is called in the least specific applicable around-method, 
the next method consists of the following: 

° All the before-methods in most-specific-first order. 



Page 911 



° The most specific primary method. If clos:call-next-method is called in the 
primary method, then the next method is the next most specific primary 
method. 

° All the after-methods in most-specific-last order. 

If clos:call-next-method is called and there is no next method, then clos:no-next- 
method is called. The default method for clos:no-next-method signals an error. 

If clos:call-next-method is called with arguments but omits optional arguments, 
the next method called defaults those arguments. 

clos:call-next-method has lexical scope and indefinite extent. 

You can use clos:next-method-p to test whether the next method exists. 

If clos:call-next-method is called in a method that does not support it, an error is 
signaled. The method-combination type in use controls which kinds of methods sup- 
port clos:call-next-method. 



car x Function 

Returns the head (car) of list or cons x. Example: 
(car ' (a b c)) => a 

(setq a '(first second third))=> 

(FIRST SECOND THIRD) 

(car a)=> 

FIRST 

(car (cdr a))=> 

SECOND 

Officially car is applicable only to conses and locatives. However, as a matter of 
convenience, car of nil returns nil. 

For a table of related items: See the section "Functions for Extracting from Lists". 

zhcar-location cons Function 

Returns a locative pointer to the cell containing the car of cons. 

Note: there is no cdr-location function; since the cons itself can be used as a loca- 
tive to its cdr. 

For a table of related items: See the section "Functions for Finding Information 
About Lists and Conses". 



case test-object &body clauses Special Form 

This is a conditional that chooses one of its clauses to execute by comparing a val- 
ue to various constants. The constants can be any object. 



Page 912 



Its form is as follows: 

(case test-object 

(keylist consequent consequent ...) 

(keylist consequent consequent ...) 

(keylist consequent consequent ...) 

Structurally case is much like cond, and it behaves like cond in selecting one 
clause and then executing all consequents of that clause. However, case differs in 
the mechanism of clause selection. 

The first thing case does is to evaluate test-object, to produce an object called the 
key object. Then case considers each of the clauses in turn. If key is eql to any 
item in the test list of a clause, case evaluates the consequents of that clause as 
an implicit progn. 

If no clause is satisfied, case returns nil. 

case returns the value of the last consequent of the clause evaluated, or nil if 
there are no consequents to that clause. 

The keys in the clauses are not evaluated; they must be literal key values. It is an 
error for the same key to appear in more than one clause. The order of the claus- 
es does not affect the behavior of the case construct. 

Instead of a test, one can write one of the symbols t and otherwise. A clause with 
such a symbol always succeeds and must be the last clause; this is an exception to 
the order-independence of clauses. 

If there is only one key value for a clause, that key value can be written in place 
of a list of that key, provided that no ambiguity results. Such a "singleton key" can 
not be nil (which is confusable with (), a list of no keys), t, otherwise, or a cons. 

Examples: 

(let ((num 69)) 
(case num 

((1 2) "math. . .ack") 

((3 4) "great now we can count"))) => NIL 

(let ((num 3)) 
(case num 

((1 2) "one two") 

((3 4 5 6) (princ "numbers") (princ " three") (fresh-line) ) 

(t "not today"))) => numbers three 
T 

(let ((object-one 'candy)) 
(case object-one 

(apple (setq class 'health) "weekdays") 

(candy (setq class 'junk) "weekends") 

(otherwise (setq class 'unknown) "all week long"))) => "weekends" 
class => JUNK 



Page 913 



For a table of related items: See the section "Conditional Functions". 

(defun print-field (object) 
(when (consp object) 

(case (list-length object) 
(1 (print (car object))) 
((2 3 4 5) (print (cadr object))) 
(otherwise (print "too large to print"))))) 



zhcaseq test-object &body clauses Special Form 

Provided for Maclisp compatibility; it is exactly the same as zhselectq. This is not 
perfectly compatible with Maclisp, because zhselectq accepts otherwise as well as 
t where zhcaseq would not accept otherwise, and because Maclisp accepts a more 
limited set of keys then zhselectq does. Maclisp programs that use zhcaseq work 
correctly as long as they do not use the symbol otherwise as the key. 

Examples: 





(let (( a 'big-b, 


ang)) 












(caseq a 














(light 


"day") 












(dark 


"night' 


"))) 


=> NIL 








(setq a 3) => 3 














(caseq a 














(1 "one") 














(2 "two") 














(t "not one or ■ 


two" 


)) => "not one or two" 






(let (( a 'big-b; 


ang)) 












(caseq a 














(light 


"day") 












(dark 


"night' 


") 










(otherwise "n 


ight 


and day"))) 


=> "night 


and day" 


For 


a table of related items: 


See the section ' 


'Conditional Functions". 



catch tag &body body Special Form 

Provides an environment for evaluating its argument forms as an implicit progn 
with dynamic exit capability throw. Although throw need not be in the lexical 
scope of catch, it must be in the dynamic scope. 

Used with throw for nonlocal exits, catch first evaluates tag to obtain an object 
that is the "tag" of the catch. Then the body forms are evaluated in sequence, and 
catch returns the (possibly multiple) values of the last form in the body. 

However, a throw (or in Genera, a *throw) form might be evaluated during the 
evaluation of one of the forms in body. In that case, if the throw "tag" is eq to the 
catch "tag" and if this catch is the innermost catch with that tag, the evaluation 



Page 914 



of the body is immediately aborted, and catch returns values specified by the 
throw or zl:*throw form. 

If the catch exits abnormally because of a throw form, it returns the (possibly 
multiple) values that result from evaluating throw's second subform. If the catch 
exits abnormally because of a zl:*throw form, it returns two values: the first is 
the result of evaluating zl:*throw's second subform, and the second is the result 
of evaluating zl:*throw's first subform (the tag thrown to). 

(catch 'foo form) catches a (throw 'foo form) but not a (throw 'har form). It is 
an error if throw is done when no suitable catch exists. 

The scope of the tags is dynamic. That is, the throw does not have to be lexically 
within the catch form; it is possible to throw out of a function that is called from 
inside a catch form. 

For example: 

(catch 'done 

(ask-database <pattern> 

#' (lambda (x) (when (nice-p x) 

(throw 'done x))))) 

The throw to 'done returns x, the pattern searched for in the database. The sec- 
ond example that follows acts as a somewhat extended example of a tiny parser. 

(catch 'foo (list 'a (catch 'bar (throw 'foo 'b)))) -> B 

(defvar xinput-bufferx nil) 

(defun parse (xinput-bufferx) 
(catch 'parse-error 

(list 's (parse-np) (parse-vp)))) 

(defun parse-np (&aux (item (pop xinput-bufferx))) 
(if (member item '(a an the)) 

1 (np (det item) (n , (pop xinput-bufferx))) 
(throw 'parse-error 

(format t "Problem with ~A in noun phrase. ~%" item)))) 

(defun parse-vp (&aux (item (pop xinput-bufferx))) 
(if (member item '(eats sleeps runs)) 
' (vp (v item)) 
(throw 'parse-error 

(format t "Problem with ~A in verb phrase. ~%" item)))) 

(parse '(a man eats)) => (S (NP (DET A) (N MAN)) (UP (U EATS))) 

(parse '(a man walks)) => NIL 
prints: Problem with WALKS in verb phrase. 

For a table of related items, see the section "Nonlocal Exit Functions". 



Page 915 



zl:*catch tag &body body Special Form 

An obsolete version of catch that is supported for compatibility with Maclisp. It is 
equivalent to catch except that if zl:*catch exits normally, it returns only two 
values: the first is the result of evaluating the last form in the body, and the sec- 
ond is nil. If zl:*catch exits abnormally, it returns the same values as catch when 
catch exits abnormally: that is, the returned values depend on whether the exit re- 
sults from a throw or a zl:*throw. See the special form catch. 

For a table of related items, see the section "Nonlocal Exit Functions". 



catch-error form &optional (printflag t) 

Macro 

Evaluates form, trapping all errors. 

form can be any Lisp expression. 

printflag controls the printing or suppression of an error message by catch-error. 

If an error occurs during the evaluation of form, catch-error prints an error mes- 
sage if the value of printflag is not nil. The default value of printflag is t. 

catch-error returns two values: if form evaluated without error, the value of form 
and nil are returned. If an error did occur during the evaluation of form, t is re- 
turned. 

Only the first value of form is returned if it was successfully evaluated. 

catch-error-restart (flavors description &rest args) &body body 

Special Form 

Establishes a restart handler for flavors and then evaluates the body. If the han- 
dler is not invoked, catch-error-restart returns the values produced by the last 
form in the body, and the restart handler disappears. If a condition is signalled 
during the execution of the body and the restart handler is invoked, control is 
thrown back to the dynamic environment of the catch-error-restart form. In this 
case, catch-error-restart also returns nil as its first value and something other 
than nil as its second value. Its format is: 

(catch-error-restart (flavors description) 
form-1 
form-2 

flavors is either a condition or a list of conditions that can be handled, description 
is a list of arguments to be passed to format to construct a meaningful description 
of what would happen if the user were to invoke the handler. The Debugger uses 
these values to create a message explaining the intent of the restart handler. 

The conditional variant of catch-error-restart is the form: 



Page 916 



catch-error-restart-if 

For a table of related items: See the section "Restart Functions". 



catch-error-restart-if cond (flavors description &rest args) &body body 

Special Form 

Establishes its restart handler conditionally. In all other respects, it is the same as 
catch-error-restart. Its format is: 

(catch-error-restart-if cond 
(flavors description) 
form-1 
form-2 

catch-error-restart-if first evaluates cond. If the result is nil, it evaluates body as 
if it were a progn but does not establish any handlers. If the result is not nil, it 
continues just like catch-error-restart, establishing the handlers and executing 
body. 

For a table of related items: See the section "Restart Functions". 



cease object &body body Special Form 

The name of this function stands for "continuable exhaustive case". 

Structurally cease is much like case, and it behaves like case in selecting one 
clause and then executing all consequents of that clause. However, cease does not 
permit an explicit otherwise or t clause. The form of cease is as follows: 

(cease key-form 

(test consequent consequent ...) 

(test consequent consequent ...) 

(test consequent consequent ...) 

object (which serves as the key-form) must be a generalized variable reference ac- 
ceptable to setf. 

The first thing cease does is to evaluate key-form, to produce an object called the 
key object. 

Then cease considers each of the clauses in turn. If key is eql to any item in the 
test list of a clause, cease evaluates the consequents of that clause as an implicit 
progn. 

cease returns the value of the last consequent of the clause evaluated, or nil if 
there are no consequents to that clause. 

The test lists in the clauses are not evaluated; literal key values must appear in 
test. It is an error for the same key value to appear in more than one clause. The 
order of the clauses does not affect the behavior of the cease construct. 



Page 917 



If there is only one key value for a clause, that key value can be written in place 
of a list of that key, provided that no ambiguity results. Such a "singleton key" can 
not be nil (which is confusable with (), a list of no keys), t, otherwise, or a cons. 

If no clause is satisfied, cease uses an implicit otherwise clause to signal an error 
with a message constructed from the clauses. To continue from this error supply a 
new value for object argument, causing cease to store that value and restart the 
clause tests. Subforms of object can be evaluated multiple times. 

Examples: 

(let ((num 24)) 
(cease num 

((1 2 3) "integer less then 4") 
((4 5 6) "integer greater than 3"))) => 
Error: The value of NUM is SI:*E\/AL, 24, was of the wrong type. 
The function expected one of 1, 2, 3, 4, 5, or 6. 

SI:*EVAL: 

Arg (SYS:F0RM): (DBG : CHECK-TYPE-1 'NUM NUM '#) 

Arg 1 (SI:ENV): ((tt tt) NIL (it) (tt) . ..) 

— defaulted args: — 

Arg 2 (SI:H00K) : NIL 
s-A, <RESUME>: Supply a replacement value to be stored into NUM 
s-B, <AB0RT>: Return to Lisp Top Level in dynamic Lisp Listener 1 
— > Supply a replacement value to be stored into NUM: 
4 
"integer greater than 3" 

(let ((num 3)) 
(cease num 

((1 2) "one two") 

((3 4 5 6) (princ "numbers") (princ " three") (terpri) ) 

(t "not today"))) => numbers three 
T 

(let ((Dwarf 'Sleepy)) 
(cease Dwarf 

((Grumpy Dopey) (setq class "confused")) 

((Bilbo Frodo) (setq class "Hobbits not Dwarfs")) 

(otherwise (setq class 'unknown) "talk to Snow White"))) 

=> "talk to Snow White" 

class => UNKNOWN 

For a table of related items: See the section "Conditional Functions". 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



cdaaar x Function 



(cdaaar x) is the same as (cdr (car (car (car x)))) 



Page 918 



cdaadr x 

(cdaadr x) is the same as (cdr (car (car (cdr x)))) 



Function 



cdaar x 

(cdaar x) is the same as (cdr (car (car x))) 



Function 



cdadar x 

(cdadar x) is the same as (cdr (car (cdr (car x)))) 



Function 



cdaddr x 

(cdaddr x) is the same as (cdr (car (cdr (cdr x)))) 



Function 



cdadr x 

(cdadr x) is the same as (cdr (car (cdr x))) 



Function 



cdar x 



(cdar x) is the same as (cdr (car x)) 



Function 



cddaar x 

(cddaar x) is the same as (cdr (cdr (car (car x)))) 



Function 



cddadr x 

(cddadr x) is the same as (cdr (cdr (car (cdr x)))) 



Function 



cddar x 

(cddar x) is the same as (cdr (cdr (car x))) 



Function 



cdddar x 



Function 



Page 919 



(cdddar x) is the same as (cdr (cdr (cdr (car x)))) 

cddddr x Function 

(cddddr x) is the same as (cdr (cdr (cdr (cdr x)))) 

cdddr x Function 

(cdddr x) is the same as (cdr (cdr (cdr x))) 

cddr x Function 

(cddr x) is the same as (cdr (cdr x)) 

cdr x Function 

Returns the tail (cdr) of list or cons x. Example: 

(cdr '(a b c)) => (b c) 

(setq a '(1 (first second third) c d)=> 

=> (1 (FIRST SECOND THIRD) C D)) 

(setq b (cdr a)) 

=> ((FIRST SECOND THIRD) C D) 

(cdr (car b)) 

=> (SECOND THIRD) 

Officially cdr is applicable only to conses and locatives. However, as a matter of 
convenience, cdr of nil returns nil. 

For a table of related items: See the section "Functions for Extracting from Lists". 

ceiling number &optional (divisor I) Function 

Divides number by divisor, and truncates the result toward positive infinity. The 
truncated result and the remainder are the returned values. 

number and divisor must each be a noncomplex number. Not specifying a divisor is 
exactly the same as specifying a divisor of 1. 

If the two returned values are Q and R, (+ (* Q divisor) R) equals number. If divi- 
sor is 1, then Q and R add up to number. If divisor is 1 and number is an integer, 
then the returned values are number and 0. 

The first returned value is always an integer. The second returned value is inte- 
gral if both arguments are integers, is rational if both arguments are rational, and 
is floating-point if either argument is floating-point. If only one argument is speci- 
fied, then the second returned value is always a number of the same type as the 
argument. 



Page 920 



Examples: 

(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 
(cei 

For a tab 



ing 5) => 5 and 

ing -5) => -5 and 

5.2) => 6 and -0.8000002 
-5.2) => -5 and -0.19999981 
5.8) => 6 and -0.19999981 
-5.8) => -5 and -0.8000002 
5 3) => 2 and -1 
-5 3) => -1 and -2 
5 4) => 2 and -3 
-5 4) => -1 and -1 
5.2 3) => 2 and -0.8000002 
-5.2 3) => -1 and -2.1999998 
5.2 4) => 2 and -2.8000002 
-5.2 4) => -1 and -1 .1999998 
5.8 3) => 2 and -0.19999981 
-5.8 3) => -1 and -2.8000002 
5.8 4) => 2 and -2.1999998 
-5.8 4) => -1 and -1 .8000002 



ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 
ing 

e of related items 



See the section "Functions that Divide and Convert 



Quotient to Integer". 



cerror optional-condition-name continue-format-string error-format-string &rest args 

Function 

Signals proceedable (continuable) errors. Like error, it signals an error and enters 
the Debugger. However, cerror allows the user to continue program execution 
from the debugger after resolving the error. 

If the program is continued after encountering the error, cerror returns nil. The 
code following the call to cerror is then executed. This code should correct the 
problem, perhaps by accepting a new value from the user if a variable was invalid. 

If the code that corrects the problem interacts with the program's use and might 
possibly be misleading, it should make sure the error has really been corrected be- 
fore continuing. One way to do this is to put the call to cerror and the correction 
code in a loop, checking each time to see if the error has been corrected before 
terminating the loop. 

Compatibility Note: Optional-condition-name is a Symbolics Common Lisp exten- 
sion, which allows you to specify a particular flavor error. 

The continue-format-string argument, like the error-format-string argument, is given 
as a control string to format along with args to construct a message string. The 
error message string is used in the same way that error uses it. The continue 
message string should describe the effect of continuing. The message is displayed 
as an aid to the user in deciding whether and how to continue. For example, it 
might be used by an interactive debugger as part of the documentation of its 
"continue" command. 



Page 921 



The content of the continue message should adhere to the rules of style for error 
messages. 

In complex cases where the error-format-string uses some of the args and the con- 

tinue-format-string uses others, it may be necessary to use the format directives "* 

and 

to skip over unwanted arguments in one or both of the format control strings. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



clos:change-class instance new-class Generic Function 

Changes the class of the existing instance to new-class, and returns the modified 
instance. The modified instance is eq to the original instance. 

instance The instance whose class is to be changed. 

new-class The desired class of the instance. This can be the name of a 

class or a class object. 

clos:change-class modifies the structure of the instance to be correct for the new 
class. It does the following: 

• Adds local slots: For any local slot defined by the new class that is not defined 
by the previous class, that slot is added to the instance. 

• Deletes local slots: For any local slot defined by the previous class that is not 
defined by the new class, that slot is deleted from the instance. 

• Retains the values of local slots: For any local slot defined by both the previous 
and the new class, the instance retains the value of that slot. If the slot was 
unbound, it remains unbound. 

• Retains the values of slots defined as shared in the previous class and local in 
the new class. 

• Replaces the values of slots defined as local in the previous class and shared in 
the new class; the instance now "sees" the value of the shared slot. 

Next, clos:change-class initializes newly added slots according to their initforms 
by calling clos:update-instance-for-different-class with two arguments: a copy of 
the instance before its class was changed (which enables methods to access the 
slot values), and the modified instance. clos:change-class does not provide any ini- 
tialization arguments in its call to clos:update-instance-for-different-class. 

You can customize the behavior of this step by defining an after-method for 
clos:update-instance-for-different-class. 

See the section "Changing the Class of a CLOS Instance". 



Page 922 



change-instance-flavor instance new-flavor Function 

Changes the flavor of an instance to another flavor. The result is a modified in- 
stance, which is eq to the original. 

For those instance variables in common (contained in the definition of the old fla- 
vor and the new flavor), the values of the instance variables remain the same 
when the instance is changed to the new format. New instance variables (defined 
by the new flavor but not the old flavor) are initialized according to any defaults 
contained in the definition of the new flavor. 

Instance variables contained by the old flavor but not the new flavor are no longer 
part of the instance, and cannot be accessed once the instance is changed to the 
new format. 

Instance variables are compared with eq of their names; if they have the same 
name and are defined by both the old flavor (or any of its component flavors) and 
the new flavor (or any of its component flavors), they are considered to be "in 
common". 

If you need to specify a different treatment of instance variables when the in- 
stance is changed to the new flavor, you can write code to be executed at the time 
that the instance is changed. See the generic function flavorrtransform-instance. 

Note: There are two possible problems that might occur if you use change- 
instance-flavor while a process (either the current process or some other process) 
is executing inside of a method. The first problem is that the method continues to 
execute until completion even if it is now the "wrong" method. That is, the new 
flavor of the instance might require a different method to be executed to handle 
the generic function. The Flavors system cannot undo the effects of executing the 
wrong method and cause the right method to be executed instead. 

The second problem is due to the fact that change-instance-flavor might change 
the order of storage of the instance variables. A method usually commits itself to a 
particular order at the time the generic function is called. If the order is changed 
after the generic function is called, the method might access the wrong memory 
location when trying to access an instance variable. The usual symptom is an ac- 
cess to a different instance variable of the same instance or an error "Trap: The 
word #<DTP-HEADER-I nnnn> was read from location nnnn" . If the garbage collector 
has moved objects around in memory, it is possible to access an arbitrary location 
outside of the instance. 

When a flavor is redefined, the implicit change-instance-flavor that happens nev- 
er causes accesses to the wrong instance variable or to arbitrary locations outside 
the instance. But redefining a flavor while methods are executing might leave 
those methods as no longer valid for the flavor. 

We recommend that you do not use change-instance-flavor of self inside a 
method. If you cannot avoid it, then make sure that the old and new flavors have 
the same instance variables and inherit them from the same components. You can 
do this by using mixins that do not define any instance variables of their own, and 
using change-instance-flavor only to change which of these mixins are included. 
This prevents the problem of accessing the wrong location for an instance variable, 



Page 923 



but it cannot prevent a running method from continuing to execute even if it is 
now the wrong method. 

A more complex solution is to make sure that all instance variables accessed after 
the change-instance-flavor by methods that were called before the change- 
instance-flavor are ordered (by using the rordered-instance-variables option to 
defflavor), or are inherited from common components by both the old and new 
flavors. The old and new flavors should differ only in components more specific 
than the flavors providing the variables. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



rchange-properties error-p &rest properties Message 

Changes the file properties of the file open on this stream. You should not use 
rchange-properties. Instead, use fs:change-file-properties. 

If the error-p argument is t, a Lisp error is signalled. If error-p is nil and an error 
occurs, the error object is returned. 



char string index Function 

Returns the character at position index of string. The count is from zero. The 
character is returned as a character object; it will necessarily satisfy the predicate 
string-char-p. 

string must be a string. 

index must be a non-negative integer less than the length of string. 

Note that the array-specific function aref, and the general sequence function elt 
also work on strings. 

To destructively replace a character within a string, use char in conjunction with 
the function setf. 

Examples: 

(char "a string" 1) => #\Space 
(string-char-p (char "a string" 3)) => T 

(char (make-array 4 : element-type 'character 

: initial -element #\y) 3) => #\y 
(string-char-p (char (make-array 4 :element-type 'character 

: initial-element #\.) 2)) => T 



(char (make-array 4 



element-type 'character 
initial-element #\. 
fill-pointer 2) 1) => #\. 



Page 924 



(defvar a-string 

(make-array 10 

: element-type 'string-char 
: f il 1-pointer t 
: initial -element #\a)) 
=> "aaaaaaaaaa" 

(char a-string 0) => #\a 

(setf (char a-string 1) #\b) => #\b 

a-string => "abaaaaaaaa" 

(char a-string 1) => #\b 

Because a-string is not a simple string, char rather than schar is used to access 
elements of the string. 

For a table of related items: See the section "String Access and Information". 

char^ char &rest chars Function 

This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If all of the arguments are 
equal, nil is returned, otherwise t. 

(char/= #\A #\A #\A) => NIL 
(char/= #\A #\B #\C) => T 

char^ can be used in place of user::char////=. 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 

char< char &rest chars Function 

This predicate compares characters exactly, depending on all fields including code, 
bits, character style, and alphabetic case. If each of the arguments is equal to or 
less than the next, t is returned, otherwise nil. 

(char<= #\A #\B #\C) => T 
(char<= #\C #\B #\A) => NIL 
(char<= #\A #\A) => T 

char< can be used instead of char<=. 

char> char &rest chars Function 

This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If each of the arguments is 
equal to or greater than the next, t is returned, otherwise nil. 



Page 925 



(char>= #\C #\B #\A) => T 
(char>= #\A #\A) => T 
(char>= #\A #\B #\C) => NIL 

char> can be used instead of char>=. 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 



char/= char &rest chars Function 

This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If all of the arguments are 
equal, nil is returned, otherwise t. 

(char/= #\A #\A #\A) => NIL 
(char/= #\A #\B #\C) => T 

char^ can be used in place of user::char////=. 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 



char< char &rest chars Function 

This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If all of the arguments are 
ordered from smallest to largest, t is returned, otherwise nil. 

(charx #\A #\B #\C) => T 
(charx #\A #\A) => NIL 
(charx #\A #\C #\B) => NIL 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 



char<= char &rest chars Function 

This predicate compares characters exactly, depending on all fields including code, 
bits, character style, and alphabetic case. If each of the arguments is equal to or 
less than the next, t is returned, otherwise nil. 

(charx= #\A #\B #\C) => T 
(char<= #\C #\B tf\A) => NIL 
(char<= #\A tf\A) => T 

char< can be used instead of char<=. 



char= char &rest chars Function 



Page 926 



This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If all of the arguments are 
equal, t is returned, otherwise nil. 

(char= #\A #\A #\A) => T 
(char= #\A #\B #\C) => NIL 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 



char> char &rest chars Function 

This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If all of the arguments are 
ordered from largest to smallest, t is returned, otherwise nil. 

(char> #\C #\B #\A) => T 
(char> #\A #\A) => NIL 
(char> #\A #\B #\C) => NIL 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 



char>= char &rest chars Function 

This comparison predicate compares characters exactly, depending on all fields in- 
cluding code, bits, character style, and alphabetic case. If each of the arguments is 
equal to or greater than the next, t is returned, otherwise nil. 

(char>= #\C #\B #\A) => T 
(char>= #\A #\A) => T 
(char>= #\A #\B #\C) => NIL 

char> can be used instead of char>=. 

For a table of related items, see the section "Character Comparisons Affected by 
Case and Style". 



character Type Specifier 

character is the type specifier symbol for the the predefined Lisp character data 
type. 

The types character, cons, symbol, and array are pairwise disjoint. 

The type character is a supertype of the type string-char. 

Examples: 



Page 927 



(typep #\0 'character) => T 

(zl:typep #\~) => : CHARACTER 

(characterp #\A) => T 

(characterp (character "1")) => T 

(sys: type-argl ist 'character) => NIL and T 

See the section "Data Types and Type Specifiers". See the section "Characters". 

character x 

Function 

Coerces x to a single character. If x is a character, it is returned. If x is a string, 
an array, or a symbol, an error is returned. If x is a number, the number is con- 
verted to a character using int-char. See the section "The Character Set". 

For a table of related items, see the section "Character Conversions". 



characterp object Function 

Returns t if object is a character object. See the section "Type Specifiers and Type 
Hierarchy for Characters". 

(setq foo '(#\c 44 "h")) 
(characterp foo) => nil 
(characterp (car foo)) => t 
(characterp (cadr foo)) => nil 
(characterp (caddr foo)) => nil 

Note in the previous example that "h" is not a character, but a string. 

(characterp (aref "h" 0)) => t 

For a table of related items: See the section "Character Predicates". 



rcharacters Message 

Returns t if the stream is a character stream, nil if it is a binary stream. 

dbg:*character-style-for-bug-mail-prologue* Variable 

Creates the bug-report banner inserted into the text of bug messages, enabling you 
to choose the font. The default is NIL.NIL.TINY, specifying a small font for the 
bug-report banner. 

To display a bug-report banner in a small font you can type the following: 

(setq dbg : xcharacter-styl e-f or-bug-mai 1 -prol ogue* 

(si :character-style-for-device-font 'fonts: quantum si :*b&w-screenx)) 

To display a bug-report banner in a large font you can type the following: 

(setq dbg : xcharacter-styl e-f or-bug-mai 1 -prol ogue* 
(si : parse-character-style '(nil nil :huge))) 



Page 928 



You can also type the following to specify a particular font: 

(setq dbg :*character-style-for-bug-mail -prologue* '(nil nil :huge)) 

char-bit char name Function 

Returns t if the bit specified by name is set in char; otherwise it returns nil. name 
can be rcontrol, :meta, rsuper, or rhyper. You can use setf on char-bit access- 
form name. 

(char-bit #\c-A :control) => T 

(char-bit #\h-c-A :hyper) => T 

(char-bit #\h-c-A :meta) => NIL 

(setq char #\D) 

(char-bit (set-char-bit char :control t) :control) => t 

(char-bit char :control) => nil 

For a table of related items, see the section "Character Fields". 

char-bits char Function 

Returns the bits field of char. You can use setf on (char-bits access- form) . 

(char-bits #\c-A) => 1 
(char-bits #\h-c-A) => 9 
(char-bits #\m-c-A) => 3 
(char-bits #\Control-D) => 1 
(char-bits #\D) => 

For a table of related items, see the section "Character Fields". 

char-bits-limit Constant 

The value of char-bits-limit is a non-negative integer that is the upper limit for 
the value in the bits field. Its value is 16. 

(if (= char-bits-limit 1) 
(setq xno-bitsx t) 
(setq xno-bitsx nil)) 

For a table of related items: See the section "Character Attribute Constants". 

char-code char Function 

Returns the code field of char. 

(char-code #\A) => 65 
(char-code #\&) => 38 

For a table of related items, see the section "Character Fields". 



Page 929 



char-code-limit Constant 

The value of char-code-limit is a non-negative integer that is the upper limit for 
the number of character codes that can be used. Its value is 65536. 

(let ((intnum (read stream)) 
(bits (read stream))) 
(if (> intnum char-code-limit) 

(error "Cannot make ~A a character code" intnum) 
(code-char intnum bits))) 

For a table of related items: See the section "Character Attribute Constants". 



char-control-bit Constant 

The value of char-control-bit is the weight of the control bit, which is 1. 
For a table of related items: See the section "Character Bit Constants". 

char-downcase char Function 

If char is an uppercase alphabetic character in the standard character set, char- 
downcase returns its lowercase form; otherwise, it returns char. If character style 
information is present it is preserved. In no case will the font or bits attribute val- 
ues differ from those of char. 

(char-downcase #\A) => #\a 
(char-downcase #\A) => #\a 
(char-downcase #\3) => #\3 
(char-downcase #\a) => #\a 

For a table of related items, see the section "Character Conversions". 

char-equal char &rest chars Function 

This is the primitive for comparing characters for equality; many of the string 
functions call it. char and chars must be characters; they cannot be integers, char- 
equal compares code and bits, ignores case and character style, and returns t if 
the characters are equal. Otherwise it returns nil. 

(char-equal #\A #\A) => T 
(char-equal #\A #\Control-A) => NIL 
(char-equal #\A #\B #\A) => NIL 

Compatibility Note: Common Lisp specifies that char-equal should ignore bits. 
This difference is incompatible. Under CLOE, lisp:char-equal ignores the bits at- 
tribute of the character arguments. 

For a table of related items, see the section "Character Comparisons Ignoring Case 
and Style". 



Page 930 



char-fat-p char Function 

Returns t if char is a fat character, otherwise nil. char must be a character object. 
A character that contains non-zero bits or style information is called a fat charac- 
ter. See the section "Type Specifiers and Type Hierarchy for Characters". 

(char-fat-p #\A) => NIL 
(char-fat-p #\c-A) => T 
(char-fat-p (make-character #\A :style '(nil :bold nil))) => T 

For a table of related items: See the section "Character Predicates". 



char-flipcase char Function 

If char is a lowercase alphabetic character in the standard character set, char- 
flipcase returns its uppercase form. If char is an uppercase alphabetic character in 
the standard character set, char-flipcase returns its lowercase form. Otherwise, it 
returns char. If character style information is present it is preserved. 

(char-flipcase #\X) => #\x 
(char-flipcase #\b) => #\B 

For a table of related items, see the section "Character Conversions". 



char-font char Function 

Returns the font field of the character object specified by char. Genera characters 
do not have a font field so char-font always returns zero for character objects. 

Genera does not support the Common Lisp concept of fonts, but supports the char- 
acter style system instead. See the section "Character Styles". To find out the 
character style of a character, use si:char-style: See the function si:char-style. 

The only reason to use char-font would be when writing a program intended to be 
portable to other Common Lisp systems. 

(char-font #\A) => 

For a table of related items: See the section "Character Fields". 



char-font-limit Constant 

The value of char-font-limit is the upper exclusive limit for the value of values of 
the font bit. Genera characters do not have a font field so the value of char-font- 
limit is 1. Genera does not support the Common Lisp concept of fonts, but sup- 
ports the y character style system instead. See the section "Character Styles". 

(if (= char-font-limit 1) 
(setq xno-fontsx t) 
(setq xno-fontsx nil)) 

For a table of related items: See the section "Character Attribute Constants". 



Page 931 



char-greaterp char &rest chars Function 

Compares characters for order; many of the string functions call it. char and chars 
must be characters; they cannot be integers. The result is t if char comes after 
chars ignoring case and style, otherwise nil. See the section "The Character Set". 
Details of the ordering of characters are in that section. 

This function compares the code and bits fields and ignores character style and 
distinctions of alphabetic case. 

(char-greaterp #\A #\B #\C) => NIL 
(char-greaterp #\A #\B #\B) => T 

Compatibility Note: Common Lisp specifies that char-greaterp should ignore bits. 
This difference is incompatible. 

For a table of related items, see the section "Character Comparisons Ignoring Case 
and Style". 



char-hyper-bit Constant 

The name for the hyper bit attribute. The value of char-hyper-bit is 8. 
For a table of related items: See the section "Character Bit Constants". 

char-int char Function 

Returns the character as an integer, including the fields that contain the charac- 
ter's code (which itself contains the character's set and subindex into that charac- 
ter set), bits, and style. 

(char-int #\a) => 97 

(char-int #\8) => 56 

(char-int #\c-m-A) => 50331713 ;under Genera 

(char-int 

(make-character #\a :style '(nil :bold nil))) => 65633 ;under Genera 

(char-int #\A) => 65 

(eq (< (char-int charl) (char-int char2)) 
(char< charl char2)) 

=> T 

(defvar char-arr (make-array 512)) 

(setf (elt char-arr (char-int #\a)) 'first) 

For a table of related items, see the section "Character Conversions". 

char-lessp char &rest chars Function 



Page 932 



This primitive compares characters for order; many of the string functions call it. 
char and chars must be characters; they cannot be integers. The result is t if char 
comes before chars ignoring case and style, otherwise nil. See the section "The 
Character Set". Details of the ordering of characters are in that section. 

This comparison predicate compares the code and bits fields and ignores character 
style and distinctions of alphabetic case. 

(char-lessp #\A #\B #\C) => T 
(char-lessp #\A #\B #\B) => NIL 

Compatibility Note: Common Lisp specifies that char-lessp should ignore bits. 
This difference is incompatible. 

For a table of related items, see the section "Character Comparisons Ignoring Case 
and Style". 



char-meta-bit Constant 

The name for the meta bit attribute. The value of char-meta-bit is 2. 
For a table of related items: See the section "Character Bit Constants". 

char-mouse-button char Function 

Returns the number corresponding to the mouse button that would have to be 
pushed to generate char. 0, 1, and 2 correspond to the Left, Middle, and Right 
mouse buttons, respectively. 

Example: 

(char-mouse-button #\m-mouse-m) ==> 
1 

The complementary function is make-mouse-char. 

char-mouse-equal charl char2 Function 

Returns t if the mouse characters charl and char2 are equal, nil otherwise, char- 
mouse-equal checks that its arguments are really mouse characters and signals an 
error otherwise. You can also use eql, which is slightly faster, to compare mouse 
characters, when you do not require the argument checking. 

char-name char Function 

char must be a character object, char-name returns the name of the object (a 
string) if it has one. If the character has no name, or if it has non-zero bits or a 
character style other than NIL.NIL.NIL, nil is returned. 

(char-name #\Tab) => "Tab" 
(char-name #\Space) => "Space" 
(char-name #\A) => NIL 



Page 933 



For a table of related items, see the section "Character Names". 



char-not-equal char &rest chars Function 

This primitive compares characters for non-equality; many of the string functions 
call it. char and chars must be characters; they cannot be integers, char-equal 
compares code and bits, ignores case and character style, and returns t if the 
characters are not equal. Otherwise it returns nil. 

(char-not-equal #\A #\B) => T 

(char-not-equal #\A #\c-A) => T 

(char-not-equal #\A #\A) => NIL 

(char-not-equal #\a #\A) => NIL 

Compatibility Note: Common Lisp specifies that char-not-equal should ignore 
bits. This difference is incompatible. 

For a table of related items, see the section "Character Comparisons Ignoring Case 
and Style". 



char-not-greaterp char &rest chars Function 

This primitive compares characters for order; many of the string functions call it. 
char and chars must be characters; they cannot be integers. The result is t if char 
does not come after chars ignoring case and style, otherwise nil. See the section 
"The Character Set". Details of the ordering of characters are in that section. 

This comparison predicate compares the code and bits fields and ignores character 
style and distinctions of alphabetic case. 

(char-not-greaterp #\A #\B) => T 
(char-not-greaterp #\a #\A) => T 
(char-not-greaterp #\A #\a) => T 
(char-not-greaterp #\A #\A) => T 

For a table of related items, see the section "Character Comparisons Ignoring Case 
and Style". 



char-not-lessp char &rest chars Function 

This primitive compares characters for order; many of the string functions call it. 
char and chars must be characters; they cannot be integers. The result is t if char 
does not come before chars ignoring case and style, otherwise nil. See the section 
"The Character Set". Details of the ordering of characters are in that section. 

This comparison predicate compares the code and bits fields and ignores character 
style and distinctions of alphabetic case. 

(char-not-lessp #\A #\B) => NIL 
(char-not-lessp #\B #\b) => T 
(char-not-lessp #\A #\A) => T 



Page 934 



For a table of related items, see the section "Character Comparisons Ignoring Case 
and Style". 

si:char-style char Function 

Returns the character style of the character object specified by char. The returned 
value is a character style object. 

(si : char-style #\a) 

=> #<CHARACTER-STYLE NIL. NIL. NIL 204004146> 

(si : char-style (make-character #\a :style '(:swiss :bold nil))) 
=> #<CHARACTER-STYLE SWISS . BOLD. NIL 116035602> 

For a table of related items: See the section "Character Fields". 

sysrchar-subindex char Function 

Returns the subindex field of char as an integer. 

For a table of related items, see the section "Character Fields". 

char-super-bit Constant 

The name for the super bit attribute. The value of char-super-bit is 4. 
For a table of related items: See the section "Character Bit Constants". 

char-to-ascii ch Function 

Converts the character object ch to the corresponding ASCII code. This function 
works only for characters with neither bits nor style. 

char-to-ascii performs an inverse mapping of the function ascii-to-char, and this 
mapping embeds the ASCII character character set in the Symbolics character set 
in an invertible way. There is no attempt to map more obscure ASCII control 
codes into the also obscure and unrelated Symbolics control codes. For example, 
Escape, is a character in the Symbolics character set corresponding to the key 
marked Escape. The ASCII code Escape is not the same as the Symbolics Escape. 
See the function ascii-to-char. See the function ascii-code. See the section "ASCII 
Conversion String Functions". 

It is an error to give char-to-ascii anything other than one of the 95 standard 
ASCII printing characters. To get the ASCII code of one of the other characters, 
use ascii-code, and give it the correct ASCII name. 

The functions char-to-ascii and ascii-to-char provide the primitive conversions 
needed by ASCII-translating streams. They do not translate the Return character 
into a CR-LF pair; the caller must handle that. They just translate #\Return into 
CR and #\Line into LF. Except for CR-LF, char-to-ascii and ascii-to-char are 
wholly compatible with the ASCII-translating streams. 



Page 935 



They ignore Symbolics control characters; the translation of #\c-G is the ASCII 
code for G, not the ASCII code to ring the bell, also known as "control G." (ascii- 
to-char (ascii-code "BEL")) is #\k, not #\c-G. The translation from ASCII to char- 
acter never produces a Symbolics control character. 

For a table of related items, see the section "ASCII Characters". 



char-upcase char Function 

If char, which must be a character, is a lowercase alphabetic character in the 
standard character set, char-upcase returns its uppercase form; otherwise, it re- 
turns char. In Genera, if character style information is present, it is preserved. In 
no case will the font or bits attribute values differ from those of char. 

(char-upcase #\a) => #\A 

(char-upcase #\a) => #\A 

(char-upcase #\3) => #\3 

(char-upcase #\A) => #\A 

For a table of related items, see the section "Character Conversions". 



zl:check-arg arg-name predicate-or-form type-string 

Macro 

Checks arguments to make sure that they are valid. A simple example is: 

(zl :check-arg foo stringp "a string") 

foo is the name of an argument whose value should be a string, stringp is a pred- 
icate of one argument, which returns t if the argument is a string. "A string" is 
an English description of the correct type for the variable. 

The general form of zl:check-arg is 

(zl :check-arg var-name 
predicate 
description) 

var-name is the name of the variable whose value is of the wrong type. If the er- 
ror is proceeded this variable is setq'ed to a replacement value, predicate is a test 
for whether the variable is of the correct type. It can be either a symbol whose 
function definition takes one argument and returns non-nil if the type is correct, 
or it can be a nonatomic form which is evaluated to check the type, and presum- 
ably contains a reference to the variable var-name. description is a string which 
expresses predicate in English, to be used in error messages. 

The predicate is usually a symbol such as zhfixp, stringp, zhlistp, or zhclosurep, 

but when there isn't any convenient predefined predicate, or when the condition is 
complex, it can be a form. For example: 



Page 936 



(defun testl (a) 
(zl :check-arg a 

(and (numberp a) (< a 10.) (> a 0.)) 

"a number from one to ten") 
...) 

If testl is called with an argument of 17, the following message is printed: 

The argument A to TEST1 , 17, was of the wrong type. 
The function expected a number from one to ten. 

In general, what constitutes a valid argument is specified in two ways in a 
zl:check-arg. description is human-understandable and predicate is executable. It is 
up to the user to ensure that these two specifications agree. 

zl:check-arg uses predicate to determine whether the value of the variable is of 
the correct type. If it is not, zl:check-arg signals the sys:wrong-type-argument 
condition. See the flavor sys:wrong-type-argument. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



zl:check-arg-type arg-name type &optional type-string Macro 

A useful variant of the zl:check-arg form. A simple example is: 

(zl :check-arg-type foo : number) 

foo is the name of an argument whose value should be a number, rnumber is a 
value which is passed as a second argument to zhtypep; that is, it is a symbol 
that specifies a data type. The English form of the type name, which gets put into 
the error message, is found automatically. 

The general form of zl:check-arg-type is: 

(zl :check-arg-type var-name 
type-name 
description) 

var-name is the name of the variable whose value is of the wrong type. If the er- 
ror is proceeded this variable is setq'ed to a replacement value, type-name de- 
scribes the type which the variable's value ought to have. It can be exactly those 
things acceptable as the second argument to zhtypep. description is a string which 
expresses predicate in English, to be used in error messages. It is optional. If it is 
omitted, and type-name is one of the keywords accepted by zhtypep, which de- 
scribes a basic Lisp data type, then the right description is provided correctly. If it 
is omitted and type-name describes some other data type, then the description is 
the word "a" followed by the printed representation of type-name in lowercase. 

The Common Lisp equivalent of zhcheck-arg-type is the macro: 

check-type 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



Page 937 



check-type place type &optional (type-string 'nil) Macro 

Signals an error if the contents of place are not of the desired type. If you contin- 
ue from this error, you will be asked for a new value; check-type stores the new 
value in place and starts over, checking the type of the new value and signalling 
another error if it is still not of the desired type. Subforms of place can be evalu- 
ated multiple times because of the implicit loop generated, check-type returns nil. 

place must be a generalized variable reference acceptable to the macro setf. 

type must be a type specifier; it is not evaluated. For standard Symbolics Common 
Lisp type specifiers, see the section "Type Specifiers". 

type-string should be an English description of the type, starting with an indefinite 
article ("a" or "an"); it is evaluated. If type-string is not supplied, it is computed 
automatically from type. This optional argument is allowed because some applica- 
tions of check-type may require a more specific description of what is wanted 
than can be generated automatically from the type specifier. 

The error message mentions place, its contents, and the desired type. 

Examples: 

(setq bees '(bumble wasp jacket)) => (BUMBLE WASP JACKET) 
(check-type bees (vector integer )) 

=> Error : The value of BEES in SI:*EVAL, (BUMBLE WASP JACKET), 
was of the wrong type. 
The function expected a vector whose typical element 
is an integer, 
(setq naards 'foo) => F00 

(check-type naards (integer x) "a positive integer") 
=> Error : The value of NAARDS in SI:*E\/AL, FOO, was of the wrong 
type. 
The function expected a positive integer. 

In CLOE, if a condition is signalled, handlers of this condition can use the func- 
tions type-error-object and type-error-expected-type to access the contents of 
place and the typespec, respectively. 

Compatibility Note: In Zetalisp, the equivalent facility is called user::check-arg- 
type. 

See the section "Data Types and Type Specifiers". 



Using check-type in CLOE 

In CLOE, if store-value is called, check-type will store the new value which is 
the argument to store-value (or which is prompted for interactively by the debug- 
ger) in place and start over, checking the type of the new value and signalling an- 
other error if it is still not the desired type. Subforms of place may be evaluated 
multiple times because of the implicit loop generated, check-type returns nil. 
Here's an example of using check- type in CLOE: 



Page 938 



Lisp> (SETQ AARDVARKS '(SAM HARRY FRED)) 
-» (SAM HARRY FRED) 

Lisp> (CHECK-TYPE AARDVARKS (ARRAY * (3))) 
Error: The value of AARDVARKS, (SAM HARRY FRED), 
is not a 3-long array. 

1: Specify a value to use instead. 

2: Return to Lisp Toplevel. 
Debug> :1 

Use Value: #(SAM FRED HARRY) 
-» NIL 

Lisp> AARDVARKS 
-» #<ARRAY-T-3 13571> 
Lisp> (MAP 'LIST ft' IDENTITY AARDVARKS) 
-» (SAM FRED HARRY) 
Lisp> (SETQ AARDVARK-COUNT 'F00) 
-> F00 

Lisp> (CHECK-TYPE AARDVARK-COUNT (INTEGER *) "a positive integer") 
Error: The value of AARDVARK-COUNT, FOO, is not a positive integer. 

1: Specify a value to use instead. 

2: Return to Lisp Toplevel. 
Debug> :2 
Lisp> 



circular-list &rest args Function 

Constructs a circular list whose elements are args, repeated infinitely, circular-list 
is the same as list except that the list itself is used as the last cdr, instead of nil. 
circular-list returns a circular list, repeating its elements infinitely, circular-list 
is especially useful with mapcar, as in the expression: 

(mapcar (function +) foo (circular-list 5)) 

which adds each element of foo to 5. circular-list could have been defined by: 

(defun circular-list (&rest elements) 
(setq elements (copylistx elements)) 
(rplacd (last elements) elements) 
elements) 

circular-list is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 

cis radians Function 

This function can be defined by: 



(defun cis (radians) 

(complex (cos radians) (sin radians))) 



Page 939 



radians must be a noncomplex number. 

(signum #c(x y)) — > (cis (phase #c(x y))) 

Mathematically, this is equivalent to e 1 radians . 

For a table of related items: See the section "Trigonometric and Related 
Functions". 



clos:class-name class-object Generic Function 

Returns the name of the class object. You can use setf with clos:class-name to set 
the name of the class object. 

class-object A class object. 

If the class object has no name, nil is returned. 

clos:class-of object Function 

Returns the class of the given object. The returned value is a class object. 

object Any Lisp object. 



(flavorrmethod rclear sirheap) Method 

Remove all of the entries from the heap. 

For a table of related items: See the section "Heap Functions and Methods". 

:clear-hash Message 

Removes all of the entries from the hash table. This message is obsolete; use 
clrhash instead. 

clear-input &optional input-stream Function 

Clears any buffered input associated with input-stream. It is primarily useful for 
removing type-ahead from keyboards when some kind of asynchronous error has 
occurred. If this operation doesn't make sense for the stream involved, then clear- 
input does nothing, clear-input returns nil. 

(let ((c (read-char))) 
(list (peek-char) 

(progn (clear-input) (read-char-no-hang) )))xy 
=> (#\x NIL) 

:clear-input Message 



Page 940 



The stream clears any buffered input. If the stream does not handle this, the de- 
fault handler ignores it. 



clear-output &optional output-stream Function 

Some streams are implemented in an asynchronous, or buffered, manner, clear- 
output attempts to abort any outstanding output operation in progress in order to 
allow as little output as possible to continue to the destination. This is useful, for 
example, to abort a lengthy output to the terminal when an asynchronous error 
occurs, clear-output returns nil. 

output-stream, if unspecified or nil, defaults to *standard-output*, and if t, is 
*terminal-io*. 



rclear-output Message 

The stream clears any buffered output. If the stream does not handle this, the de- 
fault handler ignores it. 



:clear-rest-of-line Message 

Erases from the current position to the end of the current line. This message is 
supported by all terminal streams and windows. 

:clear-rest-of-line replaces the obsolete message :clear-eol. 



:clear-rest-of-window Message 

Erases from the current position to the end of the current window. This message 
is supported by all windows. Non-window streams do not support this operation. 



rclear-window Message 

Erases the window on which this stream displays. Non-window streams do not sup- 
port this operation. 

rclear-window replaces the obsolete message rclear-screen. 



rclose &optional mode Message 

The stream is "closed", and no further operations should be performed on it; you 
can, however, rclose a closed stream. If the stream does not handle rclose, the de- 
fault handler ignores it. 

The mode argument is normally not supplied. If it is rabort, we are abnormally ex- 
iting from the use of this stream. If the stream is outputting to a file, and has not 
been closed already, the stream's newly created file is deleted, as if it were never 
opened in the first place. Any previously existing file with the same name remains, 
undisturbed. 



Page 941 



zhclosure symbol-list function Function 

Use the Symbolics Common Lisp function make-dynamic-closure, which is equiva- 
lent to the function zhclosure. 

zhclosure creates and returns a dynamic closure of function over the variables in 
symbol-list. Note that all variables on symbol-list must be declared special. 

To test whether an object is a dynamic closure, use the zhclosurep predicate. See 
the section "Predicates". The typep function returns the symbol zhclosure if given 
a dynamic closure, (typep x rclosure) is equivalent to (zhclosurep x). 

See the section "Dynamic Closure-Manipulating Functions". 



zhclosure-alist closure Function 

Use the Symbolics Common Lisp function dynamic-closure-alist, which is equiva- 
lent to the function zhclosure-alist. 

Returns an alist of (symbol . value) pairs describing the bindings which the dy- 
namic closure performs when it is called. This list is not the same one that is ac- 
tually stored in the closure; that one contains pointers to value cells rather than 
symbols, and zhclosure-alist translates them back to symbols so you can under- 
stand them. As a result, clobbering part of this list does not change the closure. 

If any variable in the closure is unbound, this function signals an error. 

See the section "Dynamic Closure-Manipulating Functions". 



closure-function closure Function 

Returns the closed function from the dynamic closure closure. This is the function 
that was the second argument to zhclosure when the dynamic closure was created. 
See the section "Dynamic Closure-Manipulating Functions". 



zhclosure-variables closure Function 

Use the Symbolics Common Lisp function function dynamic-closure-variables, 
which is equivalent to the function zhclosure-variables. 

Creates and returns a list of all of the variables in the dynamic closure closure. It 
returns a copy of the list that was passed as the first argument to zhclosure when 
closure was created. 

See the section "Dynamic Closure-Manipulating Functions". 



zhclosurep x Function 

Returns t if its argument is a closure, otherwise nil. 

clrhash table Function 



Page 942 



Removes all of the entries from table and returns the hash table itself, 
(hash-table-count (cl rhash old-hash-table)) => 

For a table of related items: See the section "Table Functions". 

zhclrhash-equal hash-table Function 

Removes all of the entries from hash-table. This function is obsolete; use clrhash 
instead. 

sysrcl-structure-printer structure-name object stream depth Macro 

Expands into an efficient function that prints a given structure object of type struc- 
ture-name to the specified stream in #S format. It depends on the information cal- 
culated by defstruct, and so is only useful after the defstruct form has been com- 
piled. This macro enables a structure print function to respect the variable *print- 
escape*. 

(defstruct (foo 

( : print-function foo-printer)) 
a b c) 

(defun foo-printer (object stream depth) 
(if xprint-escapex 

(sys:cl-structure-printer foo object stream depth) 
other-printing-strategy)) 

For a table of related items: See the section "Functions Related to defstruct Struc- 
tures". 

code-char code &optional (bits 0) (font 0) Function 

Constructs a character given its code field, code, bits, and font must be non- 
negative integers. If code-char cannot construct a character given its arguments, 
it returns nil. 

To set the bits of a character, supply one of the character bits constants as the 
bits argument. See the section "Character Bit Constants". 

For example: 

(code-char 65 char-control-bit) => #\c-A 
(char-code 65) => #\A 
(char-code 65 4) => #\Super-A 

Since the value of char-font-limit is 1, the only valid value of font is 0. The only 
reason to use the font option would be when writing a program intended to be 
portable to other Common Lisp systems. 

In Genera, to construct a new character that has character style other than 
NIL.NIL.NIL, use make-character. See the function make-character. 



Page 943 



For a table of related items, see the section "Making a Character". 

coerce object result-type Function 

Converts an object to an equivalent object of another type. 

object is a Lisp object. 

result-type must be a type-specifier; object is converted to an equivalent object of 
the specified type. If object is already of the specified type, as determined by 
typep, it is returned. 

If the coercion cannot be performed, an error is signalled. In particular, (coerce x 
nil) always signals an error. 

Example: 

(coerce 'x nil) 
=> Error: I don't know how to coerce an object to nothing 

It is not generally possible to convert any object to be of any type whatsoever; only 
certain conversions are allowed: 

Any sequence type can be converted to any other sequence type, provided the new 
sequence can contain all actual elements of the old sequence (it is an error if it 
cannot). If the result-type is specified as simply array, for example, then array t is 
assumed. A specialized type such as string or (vector (complex short-float)) can 
be specified; 

Examples: 

(coerce ' (a b c) 'vector) => #(A B C) 
(coerce ' (a b c) 'array) => #(A B C) 

(coerce #*101 '(vector (complex short-float))) => #(1 1) 
(coerce #(4 4) 'number) 
=> Error: I don't know how to coerce an object to a number 

Elements of the new sequence will be eql to corresponding elements of the old se- 
quence. Note that elements are not coerced recursively. If you specify sequence as 
the result-type, the argument can simply be returned without copying it, if it al- 
ready is a sequence. 

Examples: 

(coerce #(8 9) 'sequence) => #(8 9) 

(eql (coerce #(1 2) 'sequence) #(1 2)) => NIL 

(equalp (coerce #(1 2) 'sequence) #(1 2)) => T 

In this respect, (coerce sequence type) differs from (concatenate type sequence), 
since the latter is required to copy the argument sequence. 

Some strings, symbols, and integers can be converted to characters. If object is a 
string of length 1, the sole element of the string is returned. If object is a symbol 
whose print name is of length 1, the sole element of the print name is returned. If 
object is an integer n, (int-char n) is returned. 



Page 944 



Examples: 

(coerce "b" 'character) => #\b 
(coerce "ab" 'character) 
=> Error: "AB" is not one character long, 
(coerce 'a 'character) => #\A 
(coerce 'ab 'character) 
=> Error: "AB" is not one character long, 
(coerce 65 'character) => #\A 
(coerce 150 'character) => #\Circle 

Any non-complex number can be converted to a short-float, single-float double- 
float, or long-float. If simply float is specified as the result-type and if object is 
not already a floating-point number of some kind, object is converted to a single- 
float. 

Examples: 

(coerce 'short-float) => 0.0 
(coerce 3.5L0 'float) => 3.5d0 
(coerce 7/2 'float) => 3.5 

Any number can be converted to a complex number. If the number is not already 
complex, a zero imaginary part is provided by coercing the integer zero to the type 
of the given real part. If the given real part is rational, however, the rule of 
canonicalization for complex rational numbers results in the immediate reconver- 
sion of the the result type from type complex back to type rational. 

Examples: 

(coerce 4.5s0 'complex) => #C(4.5 0.0) 
(coerce 7/2 'complex) => 7/2 
(coerce #C(7/2 0) '(complex double-float)) 
=> #C(3.5d0 0.0d0) 

Any object can be coerced to type t. 

Example: 

(coerce 'house 't) => HOUSE 

is equivalent to 

(identity 'house) => HOUSE 

Coercions from floating-point numbers to rational numbers, and of ratios to inte- 
gers are not supported because of rounding problems. Use one of the specialized 
functions such as rational, rationalize, floor, and ceiling instead. See the section 
"Numeric Type Conversions". 

Similarly, coerce does not convert characters to integers; use the specialized func- 
tions char-code or char-int instead. 

See the section "Data Types and Type Specifiers". 
collect keyword for loop 



Page 945 



collect expr {into var} 

Causes the values of expr on each iteration to be collected into a list. When the 
epilogue of the loop is reached, var has been set to the accumulated result and 
can be used by the epilogue code. 

It is safe to reference the values in var during the loop, but they should not be 
modified until the epilogue code for the loop is reached. 

The forms collect and collecting are synonymous. 

Examples: 

(defun loopl (start end) 

(loop for x from start to end 
collect x)) => L00P1 
(loopl 4) => (0 1 2 3 4) 

(defun loop2 (small-list) 
(loop for x from 

for item in small -list 
collect (list x item))) => L00P2 
(loop2 '("one" "two" "three" "four")) 
=> ((0 "one") (1 "two") (2 "three") (3 "four")) 

The following examples are equivalent. 

(defun loop3 (small-list) 
(loop for x from 

for item in small -list 

collect x into result-1 

collect item into result-2 

finally (print (list result-1 result-2)))) => L00P3 
(loop3 ' (a b c d e f)) => 
((012345) (A B C D E F)) NIL 

(defun loop3 (small-list) 
(loop for x from 

for item in small -list 

collecting x into result-1 

collecting item into result-2 

finally (print (list result-1 result-2)))) => L00P3 
(loop3 ' (a b c d e f)) => 
((012345) (A B C D E F)) NIL 

Not only can there be multiple accumulations in a loop, but a single accumulation 
can come from multiple places within the same loop form, if the types of the col- 
lections are compatible, collect, nconc, and append are compatible. 

See the section "Accumulating Return Values for loop". 



Page 946 



zhcomment Special Form 

Ignores its form and returns the symbol zhcomment. Example: 

(defun foo (x) 

(cond ((null x) 0) 

(t (comment x has something in it) 
(1+ (foo (cdr x)))))) 

Usually it is preferable to comment code using the semicolon-macro feature of the 
standard input syntax. This allows you to add comments to your code that are ig- 
nored by the Lisp reader. Example: 

(defun foo (x) 

(cond ((null x) 0) 

(t (1+ (foo (cdr x)))) ;x has something in it 

)) 

A problem with such comments is that they are discarded when the form is read 
into Lisp. If the function is read into Lisp, modified, and printed out again, the 
comment is lost. However, this style of operation is hardly ever used; usually the 
source of a function is kept in an editor buffer and any changes are made to the 
buffer, rather than the actual list structure of the function. Thus, this is not a 
real problem. 

See the section "Functions and Special Forms for Constant Values". 

common Type Specifier 

This is the type specifier symbol denoting an exhaustive union of the following 
Common Lisp data types: 

cons, symbol 

(array x), where x is either t or a subtype of common 

string, fixnum, bignum, ratio, short-float, 

single-float, double-float long-float 

(complex x) where x is a subtype of common 

standard-char, hash-table, readtable, package, 

pathname, stream, random-state 

and all types created by the user with defstruct, or defflavor. 

The type common is a subtype of type t. 

Examples: 

(typep '#c(3 4) 'common) => T 

(subtypep 'common t) => T and T 

(commonp 'cons) => T 

(sys: type-argl ist 'common) => NIL and T 



Page 947 



(setq four 

(let ((x 4)) 

(closure ' (x) 'zerop))) => #<DTP-CLOSURE 1510647> 

(typep four 'sys: dynamic-closure) => T 

(subtypep 'sys: dynamic-closure 'common) => NIL and NIL 

See the section "Data Types and Type Specifiers". 
commonp object 



Function 



Returns true if object is a standard Common Lisp data object; otherwise, returns 
false. However, some standard Common Lisp data objects (such as characters with 
one or more bits attributes set) and function objects are not included in type 
common. All structure objects are of type common, even though their types are 
defined by the user with defstruct. 

(commonp x) = (typep x 'common) 

Examples: 

(commonp 1 .5d9) => T 

(commonp 1.0) => T 

(commonp -12.) => T 

(commonp '3kd) => T 

(commonp 'symbol) => T 

(commonp #c(3 4)) => T 

(commonp 4) => T is equivalent to (typep 4 'common) => T 

See the section "Data Types and Type Specifiers". 

See the section "Predicates". 



commonp object 

Function 

Returns true if object is a standard Common Lisp data object; otherwise, returns 
false. However, some standard Common Lisp data objects (such as characters with 
one or more bits attributes set) and function objects are not included in type 
common. All structure objects are of type common, even though their types are 
defined by the user with defstruct. 



(commonp x) = (typep x 'common) 
Examples: 



Page 948 



(commonp 1 .5d9) => T 

(commonp 1.0) => T 

(commonp -12.) => T 

(commonp '3kd) => T 

(commonp 'symbol) => T 

(commonp #c(3 4)) => T 

(commonp 4) => T is equivalent to (typep 4 'common) => T 

See the section "Data Types and Type Specifiers". 

See the section "Predicates". 



compile-flavor-methods flavor 1 flavor2... Macro 

Causes the combined methods of a program to be compiled at compile-time, and 
the data structures to be generated at load-time, rather than both happening at 
run-time, compile-flavor-methods is thus a very good thing to use, since the need 
to invoke the compiler at run-time slows down a program using flavors the first 
time it is run. (The compiler is still called if incompatible changes have been 
made, such as addition or deletion of methods that must be called by a combined 
method.) 

It is necessary to use compile-flavor-methods when you use the rconstructor op- 
tion for defflavor, to ensure that the constructor function is defined. 

Generally, you use compile-flavor-methods by including the forms in a file to be 
compiled. (The compile-flavor-methods forms can also be interpreted.) This causes 
the compiler to include the automatically generated combined methods for the 
named flavors in the resulting binary file, provided that all of the necessary flavor 
definitions have been made. Furthermore, when the binary file is loaded, internal 
data structures (such as the list of all methods of a flavor) are generated. 

You should use compile-flavor-methods only for flavors that will be instantiated. 
For a flavor that will never be instantiated (that is, one that only serves to be a 
component of other flavors that actually do get instantiated), it is almost always 
useless. The one exception is the unusual case where the other flavors can all in- 
herit the combined methods of this flavor instead of each having its own copy of a 
combined method that happens to be identical to the others. 

The compile-flavor-methods forms should be compiled after all of the information 
needed to create the combined methods is available. You should put these forms af- 
ter all of the definitions of all relevant flavors, wrappers, and methods of all com- 
ponents of the flavors mentioned. 

In general, Flavors cannot guarantee that defmethod macro-expands correctly un- 
less the flavor (and all of its component flavors) have been compiled. Therefore, 
the compiler gives a warning when you try to compile a method before the flavor 
and its components have been compiled. 

If you see this warning and no other warnings, it is usually the case that the fla- 
vor system did compile the method correctly. 



Page 949 



In complicated cases, such as a regular function and an internal flavor function 
(defined by defun-in-flavor or the related functions) having the same name, the 
flavor system cannot compile the method correctly. In those cases it is advisable to 
compile all the flavors first, and then compile the method. 

See the function flavor:print-flavor-compile-trace. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



compiled-function Type Specifier 

This is the type specifier symbol for the predefined Lisp data type compiled- 
function. 

Examples: 

(typep (compile nil '(lambda (a b) (+ a b))) 'compiled-function) 
=> T 

(zl: typep (compile nil '(lambda (a b) (+ a b)))) 
=> : COMPILED-FUNCTION 

(sys: type-argl ist 'compiled-function) => NIL and T 

(compiled-function-p (compile nil '(lambda (a) (+ a a)))) => T 

See the section "Data Types and Type Specifiers". 

See the section "Functions". 



compiled-function-p x Function 

Returns t if its argument is any compiled code object. 

compiler-let bindlist &body body 

Special Form 

When interpreted, a compiler-let form is equivalent to let with all variable bind- 
ings declared special. When the compiler encounters a compiler-let, however, it 
performs the bindings specified by the form (no compiled code is generated for the 
bindings) and then compiles the body of the compiler-let with all those bindings in 
effect. In particular, macros within the body of the compiler-let form are expanded 
in an environment with the indicated bindings. See the section "Nesting Macros". 

compiler-let allows compiler switches to be bound locally at compile time, during 
the processing of the body forms. Value forms are evaluated at compile time. See 
the section "Compiler Switches". In the following example the use of compiler-let 
prevents the compiler from open-coding the map. 

(compiler-let ((compiler :open-code-map-switch nil)) 
(map (function (lambda (x) ...)) foo)) 



Page 950 



The body of the compiler-let form is an implicit progn; thus, the forms are evalu- 
ated sequentially, and the value of the last evaluated form is returned. The differ- 
ence between compiler-let and let is that the former use the bindings at the time 
of semantic analysis, rather than use the bindings at execution time. For example, 
causing the compiler to use the bindings while generating code for the body, 
rather than generate code for the bindings. Of course, another difference is the 
implicit special declaration of the bindings. In general, only embedded macrolet 
and compiler-let forms can reliably recognize the bindings (though in some di- 
alects these bindings may coincidentally be visible in interpreted code). 

In the following example, compiler-let enables two macros which are used together 
for effective communication. First, the macro with-end-push establishes a context 
that points to the end of a list. Second macro push-onto-end uses the pointer to 
add items to the end of the list, much as push adds to the beginning of a list. The 
special variable *end-ptr* is bound to the pointer. Therefore, when push-onto-end 
is expanded in the context of that binding, the appropriate pointer is employed. 

(defvar xend-ptrx nil) 

(def macro with-end-push (list &body body) 
(let ((lastptr (gensym))) 

'(let ((, lastptr (last ,list))) 

(compiler-let ((xend-ptrx ', lastptr)) 
.body)))) 

(defmacro push-onto-end (val ) 

1 (setf , xend-ptrx (setq , xend-ptrx (cons , val nil)))) 

(let ((mylist (list 1 2 3)) 

(a-list (list 'a 'b 'c 'd))) 
(with-end-push mylist 

(dolist (1 a-list mylist) 
(push-onto-end 1)))) 

=> (1 2 3 A B C D) 

The difference between compiler-let and let is only relevant when the actual code 
that contains the macro with compiler-let is compiled. 

See the section "Special Forms for Binding Variables". 



rcomplete-connection &key (timeout (* 60. 6.)) Message 

This message is sent to a new stream created by :start-open-auxiliary-stream, in 
order to wait for the connection to be fully established, rcomplete-connection is 
used whether or not this side is active. 

Timeout is interpreted as the number of sixtieths of a second to wait before timing 
out. 



Page 951 



When rcomplete-connection returns, the stream is fully connected to an active 
network connection. At this point, :connected-p to that stream returns t. 

rcomplete-connection signals an error if the connection times out or does not 
complete for another reason. 



complex &optional ( type '* ) Type Specifier 

complex is the type specifier symbol for the predefined Lisp complex number type. 

The types complex, rational, and float are pairwise disjoint subtypes of the type 
number. 

This type specifier can be used in either symbol or list form. Used in list form, 
complex allows the declaration and creation of complex numbers, whose real part 
and imaginary part are each of type type. 

Examples: 

(typep #c(3 4) 'complex) => T 

(subtypep 'complex 'number) => T and T ; subtype and certain 

(typep '(complex 3 4) 'common) => T 
The expression 

(complexp #c(4/5 7.0)) => T 
Is equivalent to 

(typep #c(4/5 7.0) 'complex) => T 
Here is an example of using the type argument for complex: 

(typep #c(3.0 4.0) 'complex) => T 

(typep #c(3.0 4.0) '(complex integer)) => NIL 

(typep #c(3.0 4.0) '(complex float)) => T 

(typep #c(3 4) '(complex integer)) => T 
See the section "Data Types and Type Specifiers". 
See the section "Numbers". 

complex realpart &optional imagpart Function 

Constructs a complex number from real and imaginary noncomplex parts, applying 
complex canonicalization. 

If the types of the real and imaginary parts are different, the coercion rules are 
applied to make them the same. If imagpart is not specified, a zero of the same 
type as realpart is used. If realpart is an integer or a ratio, and imagpart is 0, the 
result is realpart. 
Examples: 



Page 952 



(complex 7) => 7 

(complex 4.3 0) => #C(4.3 0.0) 

(complex 2 0) => 2 

(complex 3 4) => #C(3 4) 

(complex 3 4.0) => #C(3.0 4.0) 

(complex 3.0d0 4) => #C(3.0d0 4.0d0) 

(complex 5/2 4.0d0) => #C(2.5d0 4.0d0) 

Related Functions: 

realpart 
imagpart 

For a table of related items: See the section "Functions that Decompose and Con- 
struct Complex Numbers". 



complexp object Function 

Returns t if object is a complex number, otherwise nil. The following code tests 
whether a and b are numbers. If numbers, they are added. Otherwise, we attempt 
to extract complex numbers that are then tested by complexp. 

(if (and (numberp a) (numberp b)) 
(+ a b) 
(if (and (consp a) 

(complexp (cadr a)) 
(consp b) 

(complexp (cadr b))) 
(+ (cadr a) (cadr b)) 
(error "couldn't extract complexs from ~a and ~a" a b))) 

For a table of related items, see the section "Numeric Type-checking Predicates". 

complexp object Function 

Returns t if object is a complex number, otherwise nil. The following code tests 
whether a and b are numbers. If numbers, they are added. Otherwise, we attempt 
to extract complex numbers that are then tested by complexp. 

(if (and (numberp a) (numberp b)) 
(+ a b) 
(if (and (consp a) 

(complexp (cadr a)) 
(consp b) 

(complexp (cadr b))) 
(+ (cadr a) (cadr b)) 
(error "couldn't extract complexs from ~a and ~a" a b))) 

For a table of related items, see the section "Numeric Type-checking Predicates". 
flavorrcompose-handler generic flavor-name &key env Function 



Page 953 



Finds the methods that handle the specified generic operation on instances of the 
specified flavor. Four values are returned: 

handler-function-spec 

The name of the handler, which can be a combined method, a 
single method, or an instance-variable accessor. 

combined-method-list 

A list of function specs of all the methods called, in order of 
execution; the order is approximate because of wrappers. 

method-combination A list of the method combination type and parameters to it. 

error nil normally, otherwise a string describing an error that oc- 

curred. 

For example, to use flavorrcompose-handler on the generic function change- 
status for the flavor box-with-cell: 

(flavor :compose-handler 'change-status 'box-with-cell) 
— >(FUW0R:C0MBINED CHANGE-STATUS BOX-WITH-CELL) 

((FLAVOR: METHOD CHANGE-STATUS CELL) 
(FLAVOR: METHOD CHANGE-STATUS BOX-WITH-CELL)) 

(:AND :MOST-SPECIFIC-LAST) 

NIL 

The generic function change-status and the methods for the flavors box-with-cell 
and cell are defined elsewhere. See the section "Example of Programming with 
Flavors: Life". 

In the second return value of sample output here, we put each method on one line, 
for readability. This is not done by flavorrcompose-handler. 

For documentation of the env parameter, see the function flavorrcompose-handler- 
source. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



flavorrcompose-handler-source generic flavor-name &key env Function 

Finds the methods that handle the specified generic operation on instances of the 
flavor specified by flavor-name, and finds the source code of the combined method 
(if any). Seven values are returned: 

form A Lisp form which is the body of the combined method. If 

there isn't actually a combined method, this is nil. 

handler-function-spec 

The name of the handler, which can be a combined method, a 
single method, or an instance-variable accessor. 



Page 954 



combined-method-list 

A list of function specs of all the methods called, in order of 
execution; the order is approximate because of wrappers. 

wrapper-sources Information that the combined method requires so that Flavors 
knows when it needs to be recompiled. 

lambda-list A list describing what the arguments of the combined method 

should be (not including the three interal arguments automati- 
cally given to all methods). 

method-combination A list of the method combination type and parameters to it. 

error nil normally, otherwise a string describing an error that oc- 

curred. 

flavorrcompose-handler-source is generally slower than flavorrcompose-handler, 

since the latter function can usually take advantage of pre-computed information 
present in virtual memory. 

The env parameter to flavorrcompose-handler and flavorrcompose-handler-source 

can be used to insert hypotheses into their computations. If env is nil, the gener- 
ics, flavors, and methods in the running world are used, env can be an alist of 
modifications to the running world; each element takes the form: 

(name flavor-structure generic-structure (method definition)...) 

Everything except name can be nil. name is the name of a generic, or a flavor, or 
both, flavor-structure is nil or the internal structure that describes the flavor. 
generic-structure is nil or the internal structure that describes the generic function. 
The remaining elements of an alist element refer to methods of the flavor named 
name; method is a function spec and definition is nil if that method is to be ig- 
nored, t if the method is to be assumed to exist, or the actual definition (expander 
function) in the case of a wrapper. 

env can also be the symbol compile, which is used internally to access the com- 
pile-time environment. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



sircompress-who-calls-database Function 

Makes the who-calls database more compact and efficient. Call this function after 
sirenable-who-calls. With the function (sirenable-who-calls 'rail), the function 
sircompress-who-calls-database takes a long time to complete its job. However, it 
is faster than using sirfull-gc, and you can perform an Incremental Disk Save 
(IDS) afterwards. See the section "Using the Incremental Disk Save (IDS) Facility". 

closrcompute-applicable-methods generic-function function-arguments Function 



Page 955 



Returns the set of methods that are applicable for function-arguments; the methods 
are sorted according to precedence order. 

generic-function A generic function object. 

function-arguments A list of the arguments to the generic function. 



concatenate result-type &rest sequences Function 

Combines the elements of the sequences in the order the sequences were given as 
arguments. Returns the new, combined sequence. 

The result does not share any structure with any of the argument sequences. The 
type of the result is specified by result-type, which must be a subtype of type se- 
quence. It must be possible for every element of the argument sequences to be an 
element of a sequence of type result-type. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(concatenate 'vector "abc" tf(ab) "gh") => #(#\a #\b #\c AB #\g #\h) 

(setq vector (vector 'a 'b '1 '2)) => #(A B 1 2) 

(setq list (make-list 3 : initial -element 'blah)) 
=> (BLAH BLAH BLAH) 

(concatenate 'list vector list) 
=> (A B 1 2 BLAH BLAH BLAH) 

(concatenate 'vector list vector) => #(BLAH BLAH BLAH A B 1 2) 

(concatenate 'string ' (#\a #\b #\c)) => "abc" 

If only one sequence argument is provided and it has the type specified by result- 
type, concatenate is required to to copy the argument rather than simply return- 
ing it. If a copy is not required, but only possible type-conversion, then the func- 
tion coerce can be appropriate. 

For a table of related items: See the section "Sequence Construction and Access". 

cond &rest clauses Special Form 

Consists of the symbol cond followed by several clauses. Each clause consists of a 
predicate form, called the antecedent, followed by zero or more consequent forms. 



Page 956 



(cond (antecedent consequent consequent...) 
(antecedent) 

(antecedent consequent ...) 
... ) 

Each clause represents a case that is selected if its antecedent is satisfied and the 
antecedents of all preceding clauses were not satisfied. When a clause is selected, 
its consequent forms are evaluated. 

cond processes its clauses in order from left to right. First, the antecedent of the 
current clause is evaluated. If the result is nil, cond advances to the next clause. 
Otherwise, the cdr of the clause is treated as a list of consequent forms that are 
evaluated in order from left to right. After evaluating the consequents, cond re- 
turns without inspecting any remaining clauses. The value of the cond special 
form is the value of the last consequent evaluated, or the value of the antecedent 
if there were no consequents in the clause. If cond runs out of clauses, that is, if 
every antecedent evaluates to nil, and thus no case is selected, the value of the 
cond is nil. 

Examples: 

(cond) => NIL 

(cond ((= 2 3) (print "2 equals 3, new math")) 

((< 3 3) (print "3 < 3, not yet !"))) => NIL 



(cond ((equal 'Becky 'Becky) "Girl") 
((equal 'Tom 'Tom) "Boy")) 



=> "Girl' 



(cond ((equal 'Rover 'Red) "dog") 
((equal 'Pumpkin 'Pickles) 
(t "rat")) => "rat" 



'cat") 



(cond ((zerop x) 
(+ Y 3)) 

((null y) 

(setq y 4) 

(cons x z)) 

(z) 

(t 

105) 
) 



;First clause: 

; (zerop x) is the antecedent. 

; (+ y 3) is the consequent. 

;A clause with 2 consequents: 

; this 

;and this. 

;A clause with no consequents: 

;is just z. If z is non-nil, 

;An antecedent of t 

;is always satisfied. 

;This is the end of the cond. 



the antecedent 
it is returned. 



For a table of related items: See the section "Conditional Functions". The following 
is an approximate possible implementation of zl-user:constantp using cond: 



Page 957 



(defun constantp (object) 

(cond ((consp object) (eq (car object) (quote quote))) 
((not (symbol p object)) t) 
((def ined-constant-p object) t) 
((or (null object) (eq object t) t) 
((keywordp object) t) 
(t nil))) 



cond-every &body clauses Special Form 

Has the same syntax as cond, but executes every clause whose predicate is satis- 
fied, not just the first. If a predicate is the symbol otherwise, it is satisfied if and 
only if no preceding predicate is satisfied. The value returned is the value of the 
last consequent form in the last clause whose predicate is satisfied. Multiple val- 
ues are not returned. 

Examples: 

(cond-every) => NIL 

(cond-every ((> 2 3) (print "sister")) 

((= 2 3) (print "brother"))) => NIL 

(cond-every ((equal 'mom 'mom) (princ "mother ")) 

((equal 'dog 'cat) (princ "pet dog")) 

((equal 'dad 'dad) (princ "father"))) 
=> mother father" father" 

(cond-every ((= 1 1) t) ((= 2 2) "yes!") 
(otherwise "no")) => "yes!" 

For a table of related items: See the section "Conditional Functions". 

condition-bind list &body body 

Special Form 

Binds handlers for conditions and then evaluates its body with those handlers 
bound. One of the handlers might be invoked if a condition is signalled while the 
body is being evaluated. The handlers bound have dynamic scope. 

The following simple example sets up application-specific handlers for two standard 
error conditions, fs:file-not-found and fsrdelete-failure. 

(condition-bind ((fs: file-not-found 'my-fnf-handler) 

(f s : del ete-f ai 1 ure ' my-del ete-handl er) ) 
(deletef pathname)) 

The format for condition-bind is: 



Page 958 



(condition-bind ( (condition- flav or- 1 handler-!) 
(condition-flavor-2 handler-2) 



form-1 
form-2 

form-n) 
condition-flavor 

handler 



(condition-flavor-m handler-m) ) 



form 



The name of a condition flavor or a list of names of condition 
flavors, condition-flavor need not be unique or mutually exclu- 
sive. (See the section "Finding a Handler". Search order is ex- 
plained in that section.) 

A form that is evaluated to produce a handler function. One 
handler is bound for each condition flavor clause in the list. 
The forms for binding handlers are evaluated in order from 
handler-1 to handler. All the handler-j forms are evaluated and 
then all handlers are bound. 

When handler is a lambda-expression, it is compiled. The han- 
dler function is a lexical closure, capable of referring to the 
lexical variables of the containing block. 

Note: handler must have one argument, which is the condition 
object. Otherwise, an error is signalled. 

A body, constituting an implicit progn. The forms are evaluat- 
ed sequentially. The condition-bind form returns whatever val- 
ues form returns (nil when the body contains no forms). The 
handlers that are bound disappear when the condition-bind 
form is exited. 



If a condition signal occurs for one of the condition-flavors during evaluation of 
the body, the signalling mechanism examines the bound handlers in the order in 
which they appear in the condition-bind form, invoking the first appropriate han- 
dler. You can think of the mechanism as being analogous to typecase or case. It 
invokes the handler function with one argument, the condition object. The handler 
runs in the dynamic environment in which the error occurred; no throw is per- 
formed. 

Any handler function can take one of three actions: 

• It can return nil to indicate that it does not want to handle the condition after 
all. The handler is free to decide not to handle the condition, even though the 
condition-flavors matched. (In this case the signalling mechanism continues to 
search for a condition handler.) 

• It can throw to some outer catch-form, using throw. 



Page 959 



• If the condition has any proceed types, it can proceed from the condition by call- 
ing the sysrproceed generic function on the condition object and returning the 
resulting values. In this case, signal returns all of the values returned by the 
handler function. (Proceed types are not available for conditions signalled with 
error. See the section "Proceeding".) 

The conditional variant of condition-bind is the form: 
condition-bind-if 

For a table of related items, see the section "Basic Forms for Bound Handlers". 

condition-bind-default list &body body Special Form 

Binds its handlers on the default handler list instead of the bound handler list. 
See the section "Finding a Handler". In other respects condition-bind-default is 
just like condition-bind. The default handlers are examined by the signalling 
mechanism only after all of the bound handlers have been examined. Thus, a 
condition-bind-default can be overridden by a condition-bind outside of it. This 
advanced feature is described in more detail in another section. See the section 
"Default Handlers and Complex Modularity". 

The conditional variant of condition-bind-default is the form: 

condition-bind-default-if 

For a table of related items, see the section "Basic Forms for Default Handlers". 

condition-bind-default-if cond list &body body Special Form 

Binds its handlers on the default handler list instead of the bound handler list. 
See the section "Finding a Handler". In other respects condition-bind-default-if is 
just like condition-bind-if. The default handlers are examined by the signalling 
mechanism only after all of the bound handlers have been examined. Thus, a 
condition-bind-default-if can be overridden by a condition-bind outside of it. This 
advanced feature is described in more detail in another section. See the section 
"Default Handlers and Complex Modularity". 

For a table of related items, see the section "Basic Forms for Default Handlers". 

condition-bind-if cond list &body body 

Special Form 

Binds its handlers conditionally. In all other respects, it is just like 
condition-bind. It has an extra subform called cond, for the conditional. Its format 
is: 



Page 960 



(condition-bind-if cond 

{{condition-flavor-1 handler-!) 
(condition-flavor-2 handler-2) 



(condition-flavor-m handler-m) ) 



form-1 
form-2 



form-n) 

condition-bind-if first evaluates cond. If the result is nil, it evaluates the handler 
forms but does not bind any handlers. It then executes the body as if it were a 
progn. If the result is not nil, it continues just like condition-bind binding the 
handlers and executing the body. 

For a table of related items: See the section "Basic Forms for Bound Handlers". 

condition-call f&rest varlist) form &body clauses Special Form 

Binds handlers for conditions, expressing the handlers as clauses of a case-like 
construct instead of as functions. These handlers have dynamic scope. 

condition-call and condition-case have similar applications. The major distinction 
is that condition-call provides the mechanism for using a complex conditional cri- 
terion to determine whether or not to use a handler, condition-call clauses have 
the ability to decline to handle a condition because the clause is selected on the 
basis of the predicate, rather than on the basis of the type of a condition. 

The format is: 

(condition-call (var) 
form 
(predicate-1 form-1-1 form-1-2 ... form-l-n) 
(predicate-2 form-2-1 form-2-2 ... form-2-n) 

(predicate-m form-m-1 form-m-2 ... form-m-n) ) 

Each predicate must be a function of one argument. The predicates are called, 
rather than evaluated. The form-m-n are a body, a list of forms constituting an im- 
plicit progn. The handler clauses are bound simultaneously. 

When a condition is signalled, each predicate in turn (in the order in which they 
appear in the definition) is applied to the condition object. The corresponding han- 
dler clause is executed for the first predicate that returns a value other than nil. 
The predicates are called in the dynamic environment of the signaller. 

condition-call takes the following actions when it finds the right predicate: 

1. It automatically performs a throw to unwind the dynamic environment back 
to the point of the condition-call. This discards the handlers bound by the 
condition-call. 



Page 961 



2. It executes the body of the corresponding clause. 

3. It makes condition-call return the values produced by the last form in the 
clause. 

During the execution of the clause, the variable var is bound to the condition ob- 
ject that was signalled. If none of the clauses needs to examine the condition ob- 
ject, you can omit var: 

(condition-cal 1 () . . . ) 

condition-call and :no-error 

As a special case, predicate-m (the last one) can be the special symbol :no-error. If 
form is evaluated and no error is signalled during the evaluation, condition-case 
executes the :no-error clause instead of returning the values returned by form. 
The variables vars are bound to the values produced by form, in the style of 
multiple-value-bind, so that they can be accessed by the body of the :no-error 
case. Any extra variables are bound to nil. 

Some limitations on predicates: 

• Predicates must not have side effects. The number of times that the signalling 
mechanism chooses to invoke the predicates and the order in which it invokes 
them are not defined. For side effects in the dynamic environment of the signal, 
use condition-bind. 

• The predicates are not lexical closures and therefore cannot access variables of 
the lexically containing form, unless those variables are declared special. 

• Lambda-expression predicates are not compiled. 

The conditional variant of condition-call is the form: 
condition-call-if 

For a table of related items: See the section "Basic Forms for Bound Handlers". 

condition-call-if cond f&rest varlist) form &body clauses Special Form 

Binds its handlers conditionally. In all other respects, it is just like condition-call. 
Its format includes cond, the subform that controls binding handlers: 

(condition-cal 1 -if cond (var) 
form 

(predicate-1 form-1-1 form-1-2 ... form-l-n) 
(predicate-2 form-2-1 form-2-2 ... form-2-n) 

{predicate-m form-m-1 form-m-2 ... form-m-n) ) 



Page 962 



condition-call-if first evaluates cond. If the result is nil, it does not set up any 
handlers; it just evaluates the form. If the result is not nil, it continues just like 
condition-call, binding the handlers and evaluating the form. 

The :no-error clause applies whether or not cond is nil. 

For a table of related items: See the section "Basic Forms for Bound Handlers". 

condition-case f&rest varlist) form &rest clauses 

Special Form 

Binds handlers for conditions, expressing the handlers as clauses of a case-like 
construct instead of as functions. The handlers bound have dynamic scope. 

Examples: 

(condition-case () 

(time:parse string) 
(time: parse-error xdefaul t-timex)) 

(condition-case (e) 

(time:parse string) 
(time:parse-error 
(format xerror-outputx "~A, using default time instead." e) 
xdefaul t-timex)) 

(do () (nil) 

(condition-case (e) 

(return (time:parse string)) 
(time:parse-error 
(setq string 

(prompt-and-read 
:string 
"~A~%Use what time instead? " e))))) 

The format is: 

(condition-case (varl var2 ...) 
form 
(condition-flavor-1 form-1-1 form-1-2 ... form-l-n) 
(condition-flavor-2 form-2-1 form-2-2 ... form-2-n) 

(condition-flavor-m form-m-1 form-m-2 ... form-m-n) ) 

Each condition-flavor-j is either a condition flavor, a list of condition flavors, or 
:no-error. If :no-error is used, it must be the last of the handler clauses. The re- 
mainder of each clause is a body, a list of forms constituting an implicit progn. 

condition-case binds one handler for each clause. The handlers are bound simul- 
taneously. 



Page 963 



If a condition is signalled during the evaluation of form, the signalling mechanism 
examines the bound handlers in the order in which they appear in the definition, 
invoking the first appropriate handler. 

condition-case normally returns the values returned by form. If a condition is sig- 
nalled during the evaluation of form, the signalling mechanism determines whether 
the condition is one of the condition-flavor-j . If so, the following actions occur: 

1. It automatically performs a throw to unwind the dynamic environment back 
to the point of the condition-case. This discards the handlers bound by the 
condition-case. 

2. It executes the body of the corresponding clause. 

3. It makes condition-case return the values produced by the last form in the 
handler clause. 

While the clause is executing, varl is bound to the condition object that was sig- 
nalled and the rest of the variables (var2, ...) are bound to nil. If none of the 
clauses needs to examine the condition object, you can omit varl. 

(condition-case () ...) 

As a special case, condition-flavor-m (the last one) can be the special symbol mo- 
error. If form is evaluated and no error is signalled during the evaluation, 
condition-case executes the :no-error clause instead of returning the values re- 
turned by form. The variables varl, var2, and so on are bound to the values pro- 
duced by form, in the style of multiple-value-bind, so that they can be accessed by 
the body of the :no-error case. Any extra variables are bound to nil. 

When an event occurs that none of the cases handles, the signalling mechanism 
continues to search the dynamic environment for a handler. You can provide a case 
that handles any error condition by using error as one condition-flavor-j. 

The conditional variant of condition-case is the form: 
condition-case-if 

For a table of related items: See the section "Basic Forms for Bound Handlers". 



condition-case-if cond f&rest varlist) form &rest clauses Special Form 

Binds its handlers conditionally. In all other respects, it is just like 
condition-case. Its syntax includes cond, a subform that controls binding handlers: 

(condition-case-if cond (var) 
form 
(condition-flavor-1 form-1-1 form-1-2 ... form-l-n) 
(condition-flavor-2 form-2-1 form-2-2 ... form-2-n) 

{condition-flavor-m form-m-1 form-m-2 ... form-m-n) ) 



Page 964 



condition-case-if first evaluates cond. If the result is nil, it does not set up any 
handlers; it just evaluates the form. If the result is not nil, it continues just like 
condition-case, binding the handlers and evaluating the form. 

The :no-error clause applies whether or not cond is nil. 

For a table of related items: See the section "Basic Forms for Bound Handlers". 



dbg:condition-handled-p condition Function 

Searches the bound handler list and the default handler list to see whether a han- 
dler exists for the condition object, condition. This function should be called only 
from a condition-bind handler function. It starts looking from the point in the 
lists from which the current handler was invoked and proceeds to look outwards 
through the bound handler list and the default handler list. It returns a value to 
indicate what it found: 

Value Meaning 

rmaybe condition-bind handlers for the flavor exist. These handlers 

are permitted to decline to handle the condition. You cannot 
determine what would happen without actually running the 
handler. 

nil No handler exists. 

t A handler exists. 



conjugate number Function 

Returns the complex conjugate of number. If number is complex, then conjugate re- 
turns a complex with the same real part as number, and with imaginary part the 
negation of number's imaginary part. A non-complex argument number is returned. 
The conjugate of a noncomplex number is itself, conjugate could have been de- 
fined by: 

(defun conjugate (number) 

(complex (real part number) (- (imagpart number)))) 

For a table of related items, see the section "Arithmetic Functions". 



:connected-p Message 

Returns t if the stream is fully connected to an active network connection, nil 
otherwise. If the stream is in a transitory state that is not completely connected, 
:connected-p returns nil. 

:connected-p must be callable in a scheduler context. That is, it cannot call 
:process-wait. 



cons x y Function 



Page 965 



Creates a new cons whose car is x and whose cdr is y. 

cons can be thought of as creating a cons or a list, or as adding a new element to 
the front of a list. 

Examples: 

(cons 'a 'b) => (a . b) 

(cons 'a (cons 'b (cons 'c nil))) => (a b c) 

(cons 'a '(be d)) => (a b c d) 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



cons Type Specifier 

This is the type specifier symbol for the predefined Lisp object cons . 

The types cons and null form an exhaustive partition of the type list. 

The types cons, symbol, array, number, and character are pairwise disjoint. 

Examples: 

(typep '(a.b) 'cons) => T 

(typep ' (a b c) 'cons) => T 

(zl :listp '(a b c)) => T 

(subtypep 'cons 'list) => T and T 

(subtypep 'list 'cons) => NIL and T 

(sys: type-argl ist 'cons) => NIL and T 

(consp ' (a b c)) => T 

(type-of ' (signed-byte 3)) => CONS 

See the section "Data Types and Type Specifiers". See the section "Type Specifiers 
and Type Hierarchy for Lists". 

cons-in-area x y area Function 

Creates a cons, whose car is x and whose cdr is y, in the specified area. (Areas are 
an advanced feature of storage management. See the section "Areas".) 

Example: 

(cons-in-area 'a 'b my-area) => (a . b) 

cons-in-area is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 

consp object Function 



Page 966 



Returns t if its argument is a cons and nil otherwise. Thus, consp is the direct 
inverse of atom , that is, (consp X) if and only if (not (atom X)). fconsp nil) 
returns nil since nil is the empty list but not a cons. For this reason, listp should 
be used to determine whether or not an object is a list. If consp returns true for 
object, the use of various functions that require a cons object, such as car and 
cdr, is legitimate. 

For a table of related items: See the section "Predicates that Operate on Lists". 



constantp object Function 

This predicate is t if object, when considered as a form to be evaluated, always 
evaluates to the same thing. This includes self-evaluating objects such as numbers, 
characters, strings, bit-vectors and keywords, as well as all constant symbols de- 
clared by defconstant, such as nil, t, and pi. In addition, a list whose car is 
quote, such as (quote rhumba) also returns t when it is given as object to 
constantp. 

This predicate is nil if object, considered as a form, may or may not always evalu- 
ate to the same thing. 

If you are using CLOE, consider the following example: 

(constantp '(quote foo)) => t 

(constantp 'foo) => nil 

(constantp (make-array foo '(2 3))) => t 



continue- whopper &rest args Special Form 

Calls the combined method for the generic function that was intercepted by the 
whopper. Returns the values returned by the combined method. 

args is the list of arguments passed to those methods. This function must be 
called from inside the body of a whopper. Normally the whopper passes down the 
same arguments that it was given. However, some whoppers might want to change 
the values of the arguments and pass new values; this is valid. 

For more information on whoppers, including examples: See the section "Wrappers 
and Whoppers". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



copy-alist al &optional area Function 

Returns an association list that is equal to al, but is not eq. See the section "As- 
sociation Lists". Only the top level of list structure is copied; that is, copy-alist 
copies in the cdr direction, but not in the car direction. Each cons of al is replaced 
in the copy by a new cons with the same car and cdr. See the function copy-seq. 
See the function copy-tree. 



Page 967 



Here is an example of copy-alist: 

(copy-alist ' ((canoe. paddle) (rowboat.oar))) 

returns the following association list, which is equal to the original association 
list: 

((canoe. paddle) (rowboat.oar)) 

The optional area argument is the number of the area in which to create the new 
list. (Areas are an advanced feature of storage management. See the section 
"Areas".) 

Compatibility Note: area is a Symbolics extension to Common Lisp. It is not sup- 
ported under CLOE. 

Example: 

(setq alist-1 (pairlis '(abed) '(1 2 3 4))) 
=> ((A . 1)(B . 2)(C . 3)(D . 4)) 

(setq alist-2 (copy-alist alist)) 
=> ((A . 1)(B . 2)(C . 3)(D . 4)) 

(setf (cdr (assoc 'a alist-1)) 42) 
=> 42 

(assoc 'a al ist-1) 
=> (A . 42) 

(assoc 'a al ist-2) 
=> (A . 1) 

This function is specifically intended for copying association lists, that is, a-lists 
consisting of a list of conses. 

For a table of related items: See the section "Functions for Copying Lists". 



copy-array-contents from-array to-array Function 

Copies the contents of from-array into the contents of to-array, element by element. 
from-array and to-array must be arrays. If to-array is shorter than from-array, the 
rest of from-array is ignored. If from-array is shorter than to-array, the rest of to- 
array is filled with nil if it is a general array, or if it is a numeric array or 
(code-char 0) for strings. This function always returns t. 

Note that even if from-array or to-array has a leader, the whole array is used; the 
convention that leader element is the "active" length of the array is not used by 
this function. The leader itself is not copied. 

copy-array-contents works on multidimensional arrays, from-array and to-array 
are "linearized" and row-major order is used. See the section "Row-major Storage 
of Arrays". 

copy-array-contents does not work on conformally displaced arrays. 



Page 968 



copy-array-contents-and-leader from-array to-array Function 

Copies the contents and leader of from-array into the contents of to-array, element 
by element, copy-array-contents copies only the main part of the array. 

copy-array-contents-and-leader does not work on conformally displaced arrays. 

For a table of related items: See the section "Copying an Array". 



copy-array-portion from-array from-start from-end to-array to-start to-end Function 

Copies the portion of the array from-array with indices greater than or equal to 
from-start and less than from-end into the portion of the array to-array with in- 
dices greater than or equal to to-start and less than to-end, element by element. If 
there are more elements in the selected portion of to-array than in the selected 
portion of from-array, the extra elements are filled with the default value as by 
copy-array-contents. If there are more elements in the selected portion of from- 
array, the extra ones are ignored. Multidimensional arrays are treated the same 
way as copy-array-contents treats them. This function always returns t. 

copy-array-portion does not work on conformally displaced arrays. 

This function copies one element at a time in increasing order of subscripts. This 
means that when copying from and to the same array, the results might be unex- 
pected if from-start is less than to-start. You can safely copy from and to the same 
array as long as from-start >= to-start. 

For a table of related items: See the section "Copying an Array". 



zhcopy-closure closure Function 

Use the Symbolics Common Lisp function copy-dynamic-closure, which is equiva- 
lent to the function zhcopy-closure. 

Creates and returns a new closure by copying the dynamic closure closure, zhcopy- 
closure generates new external value cells for each variable in the closure and ini- 
tializes their contents from the external value cells of closure. 

See the section "Dynamic Closure-Manipulating Functions". 



copy-dynamic-closure closure Function 

Creates and returns a new closure by copying the dynamic closure closure, copy- 
dynamic-closure generates new external value cells for each variable in the clo- 
sure and initializes their contents from the external value cells of closure. 

See the section "Dynamic Closure-Manipulating Functions". 



sys:copy-if-necessary thing &optional (default-cons-area sys:working-storage-area) 

Function 



Page 969 



Moves thing from a temporary storage area, or stack list, to a permanent area. 
Thing can be a string, symbol, list, tree, or &rest argument. sys:copy-if-necessary 
checks whether thing is in a temporary area of some kind, and moves it if it is. If 
thing is not in a temporary area, it is simply returned. The copy has the same 
type and dimensionality as the source. 

This function is used especially for &rest arguments, which are not guaranteed to 
be in permanent storage. Sometimes the rest-argument list is stored in the func- 
tion-calling stack, and loses its validity when the function returns. If you wish to 
return a rest-argument or make it part of a permanent list structure, you must 
copy it first, as you must always assume that it is one of these special lists. 

Use sys:copy-if-necesary to copy a list if your only purposes are: 

• To preserve a (possibly) stack-consed list outside of its stack extent. 

• To copy an object in storage with dynamic extent, thus it is not suitable for 
guaranteeing that a given list does not share structure with any other list. 

In all other cases, you should use copy-list, which copies unconditionally, thus it is 
suitable for making a private copy of a list, copy-list copies only lists, while 
sys:copy-if-necessary copies trees of conses as well as copying several other object 
types. 

See the section "Lambda-List Keywords". 

sys:copy-if-necessary is a Symbolics extension to Common Lisp. 

For more information on stack lists: See the section "Consing Lists on the Control 
Stack". See the function with-stack-list. 

For more information on temporary storage areas, see the :gc keyword of make- 
area. See the function make-area. 

For a table of related items: See the section "Functions for Copying Lists". 



copy-list list &optional area force-dotted Function 

Returns a list that is equal to list, but not eq. Under Genera, the returned list is 
fully cdr-coded, to minimize storage. (See the section "Cdr-Coding".) 

Only the top level of the list structure is copied; that is, copy-list copies in the 
cdr direction, but not in the car direction. Each element of list that is a cons is 
replaced in the copy by a new cons with the same car and cdr. See also: 

copy-alist 
copy-seq 
copy-tree 
copy-tree-share 

Compatibility Note: The optional arguments area and forced-dotted are Symbolics 
extensions to Common Lisp. Area is the number of the area in which to create the 



Page 970 



new list. (Areas are an advanced feature of storage management. See the section 
"Areas".) Note that these options are not supported under CLOE. 

Example: 

(copy-list '(heron loon sandpiper)) 
Returns the following list, which is equal to list, but not eq: 

(heron loon sandpiper) 

Example: 

(setq a '(one (two-a two-b))) 

(setq b (list 1 a 'three)) 

=> (1 (ONE (TWO-A TWO-B)) THREE) 

(setq c (copy-list b)) 

=> (1 (ONE (TWO-A TWO-B)) THREE) 

(eq (last b) (last c)) => nil 

(eq (cdr b) (cdr c)) => nil 

(eq (cadr b) (cadr c)) => t 

For a table of related items: See the section "Functions for Copying Lists". 

copy-list* list &optional area Function 

Returns a list that is equal to list, but not eq, and whose last cons is never cdr- 
coded. 

See the function copy-list. See the section "Cdr-Coding". This increases efficiency 
if you add something onto the list later with nconc. 

The optional area argument is the number of the area in which to create the new 
list. (Areas are an advanced feature of storage management. See the section 
"Areas".) 

copy-list* is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Copying Lists". 

copy-readtable &optional (from-readtable *readtable*) to-readtable Function 

A copy is made of from-readtable, which defaults to the current readtable (the val- 
ue of the global variable *readtable*). If from-readtable is nil, then a copy of a 
standard Common Lisp readtable is made. For example, 

(setq xreadtablex (copy-readtable nil)) 

will restore the input syntax to standard Common Lisp syntax, even if the original 
readtable has been clobbered. 

If to-readtable is unsupplied or nil, a fresh copy is made. Otherwise, to-readtable 
must be a readtable, which is destructively copied into. 



Page 971 



(let* ((foo "zzzY'zzz") 

(newrt (copy-readtable)) 

(xreadtablex newrt) 

(result (read-f rom-string foo))) 
(set-syntax-f rom-char #\" #\%) 
(setq result (cons result (read-f rom-string foo)))) 

=> (ZZZ . | ZZZ"ZZZ | ) 



zhcopy-readtable &optional from-readtable to-readtable Function 

from-readtable, which defaults to the current readtable, is copied. If to-readtable is 
unsupplied or nil, a fresh copy is made. Otherwise to-readtable is clobbered with 
the copy. Use zhcopy-readtable to get a private readtable before using the other 
readtable functions to change the syntax of characters in it. The value of 
zhreadtable at the start of a session is the initial standard readtable, which usual- 
ly should not be modified. 



copy-seq sequence &optional area 

Function 

Non-destructively copies the argument sequence. Returns a new sequence which is 
equalp to the argument, but not eq. The function copy-seq returns the same re- 
sult as the function subseq, when the value of the start argument of subseq is 0. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(setq name "Bill") => "Bill" 

(setq a-copy (copy-seq name)) => "Bill" 

a-copy => "Bil 1 " 

name => "Bil 1 " 

(equalp a-copy name) => T 

(eq a-copy name) => NIL 

Compatibility Note: The optional area argument is the number of the area in 
which to create the new alist. (Areas are an advanced feature of storage manage- 
ment.) area is a Symbolics extension to Common Lisp and is not supported by 
CLOE. See the section "Areas". 

In the following example, copy-seq makes a copy of a sequence before destructive- 
ly operating with repl ace. 



Page 972 



(setq dated-copy (vector (get-name) (get-date) 123 456 987)) 

=> (SALLY 1-AUG-89 123 456 987) 

(replace (copy-seq dated-copy) #( (get-date) 321 654 789) 
:start1 1) 

=> (SALLY 2-AUG-89 321 654 789) 

dated-copy => (SALLY 1-AUG-89 123 456 987) 
For a table of related items: See the section "Sequence Construction and Access". 

copy-symbol symbol &optional copyprops Function 

Returns a new uninterned symbol with the same print-name as symbol. If copy- 
props is non-nil, then the value and function-definition of the new symbol are the 
same as those of sym, and the property list of the new symbol is a copy of 
symbol's. If copyprops is nil (the default), then the new symbol is unbound and un- 
defined, and its property list is empty. 

(copy-symbol symbol nil) = (make-symbol (symbol -name symbol)) 
See the section "Functions for Creating Symbols". 

copy-tree tree &optional area Function 

Copies a tree of conses. The argument tree can be any Lisp object. If it is not a 
cons, it is returned; otherwise the result is a new cons made from the results of 
calling copy-tree on the car and cdr of the argument. In other words, all conses in 
the tree are copied recursively, stopping only when non-conses are encountered. 
Circularities and the sharing of substructure are not preserved. The optional area 
argument is the number of the area in which to create the new tree. (Areas are 
an advanced feature of storage management. See the section "Areas".) 

area is a Symbolics extension to Common Lisp, and is not available in CLOE. 

Example: 

(copy-tree '((freesia) (carnation) (rose))) 
returns the following tree: 

((freesia) (carnation) (rose)) 

In the following example, we have an association list whose components are pairs 
of keys and association lists. A call to copy-alist only provides a true copy of the 
top level association list and not of the lower level a-list. 



Page 973 



(setq keys '(monthly-cash-on-hand monthly-expense monthly-revenue)) 
(setq data '((pairlis '(11 12) '(52 73)) 

(pairlis '(10 11) '(20 21)) 

(pairlis '(10 11) '(31 42)))) 
(setq financial -statement (pairlis keys data)) 

The function what-if, defined in the following example, executes coordinated 
changes in the low-level association lists. These changes are made on a trial basis, 
and copy-tree allows the changes to occur in a copy of the data-base rather than 
the data base itself. 

(defun what-if (a-list, revenue) 
(let ((november-cash-on-hand 

(assoc '11 (assoc 'monthly-cash-on-hand a-list))) 
(november-expense 

(assoc '11 (assoc 'monthly-expense a-list))) 
(november-revenue revenue) 
(december-cash-on-hand 0)) 
(setf (cdr (assoc '11 (assoc 'monthly-revenue a-list))) 

november-revenue) 
(setq december-cash-on-hand 

(+ november-cash-on-hand (- november-revenue november-expense))) 
(setf (cdr (assoc '12 (assoc 'monthly-cash-on-hand a-list))) 

december-cash-on-hand) 
december-cash-on-hand) ) 

(what-if (copy-tree financial -statement) 40) => 71 

(assoc '12 (assoc 'monthly-cash-on-hand financial -statement)) 
=> (12 . 73) 

For a definition and diagram of a tree: See the section "Overview of Lists". 

For a table of related items: See the section "Functions for Copying Lists". 



copy-tree-share tree &optional area (hash (make-hash-table :test #'zl:equal)) cdr- 
code Function 

Similar to copy-tree, it makes a copy of an arbitrary structure of conses, copying 
at all levels, and optimally cdr-coding. However, it also assures that all lists, or 
tails of lists, are optimally shared when equal. 

The arguments for copy- tree-share are: the tree to be copied, and an optional 
storage area, an externally created hash table to be used for the equality testing 
and a cdr-code, which is the storage location of the conses that compose a tree or 
list. The default storage area for the new list is the area occupied by the old list. 
If cdr-code is t, lists will never be "forked" to enable sharing a tail. This wastes 
space, but improves locality. 

Note: copy-tree-share might be very slow, in the general case, for long lists. How- 
ever, applying it at the appropriate level of a specific structure-copying routine 



Page 974 



(furnishing a common, externally created hash table) is likely to yield all the shar- 
ing possible, at a much lower computational cost. For example, copy-tree-share 
could be applied only to the branches of a long association list. 

Example: 

(copy-tree-share '((1 2 3) (12 3) (0 12 3) (0 2 3))) 
If x = ' (1 2 3), the above returns (roughly): 

<(,x ,x (0 . ,x) (0 . ,(cdr x))) 
copy-tree-share is a Symbolics extension to Common Lisp. 

zhcopyalist al &optional area Function 

In your new programs, we recommend that you use the function copy-alist which 
is the Common Lisp equivalent of the function zhcopyalist. 

Copies an association list. Returns a list that is zhequal to al, but not eq. Each 

element of al that is a cons is replaced in the copy by a new cons with the same 

car and cdr. You can optionally specify the area in which to create the new copy. 
The default is to copy the new list into the area occupied by the old list. 

For a table of related items: See the section "Functions for Copying Lists". 

zhcopylist list &optional area force-dotted Function 

In your new programs we recommend that you use the function copy-list which is 
the Common Lisp equivalent of the function zhcopylist. 

Returns a list that is zhequal to list, but not eq. zhcopylist does not copy any ele- 
ments of the list: only the conses of the list itself. The returned list is fully cdr- 
coded, to minimize storage. See the section "Cdr-Coding". If the list is "dotted", 
that is, (cdr (last list)) is a non-nil atom, this is true of the returned list also. You 
can specify the area in which to create the new copy. The default is to copy the 
new list into the area occupied by the old list. 

For a table of related items: See the section "Functions for Copying Lists". 

zhcopylist* list &optional area Function 

Use the Common Lisp function copy-list*, which is equivalent to zhcopylist*. 

Returns a list that is zhequal to list, but not eq. zhcopylist* does not copy any el- 
ements of the list: only the conses of the list. The last cons of the resulting list is 
never cdr-coded. See the function zhcopylist. See the section "Cdr-Coding". This 
increases efficiency, if you add something onto the list later using nconc. 

For a table of related items: See the section "Functions for Copying Lists". 
zhcopysymbol symbol &optional copyprops 



Page 975 



Function 

Use the Common Lisp function copy-symbol, which is equivalent to 
zhcopysymbol. 

Returns a new uninterned symbol with the same print-name as symbol. If copy- 
props is non-nil, then the value and function-definition of the new symbol are the 
same as those of sym, and the property list of the new symbol is a copy of 
symbol's. If copyprops is nil (the default), then the new symbol is unbound and un- 
defined, and its property list is empty. 

(copy-symbol symbol nil) = (make-symbol (symbol -name symbol)) 
See the section "Functions for Creating Symbols". 



zhcopytree tree &optional area Function 

In your new programs, we recommend that you use the function copy-tree, which 
is the Common Lisp equivalent of the function zhcopytree. 

Copies all the conses of a tree and makes a new tree with the same fringe. You 
can specify the area in which to create the new copy. The default is to copy the 
new list into the area occupied by the old list. 

For a table of related items: See the section "Functions for Copying Lists". 



zhcopytree-share tree &optional area (hash (cl:make-hash-table :test #'equal 
rlocking nil :number-of-values 0)) cdr-code Function 

Use the Symbolics Comon Lisp function copy-tree-share, which is equivalent to 
zhcopytree-share. 

zhcopytree-share is similar to zhcopytree; it makes a copy of an arbitrary struc- 
ture of conses, copying at all levels, and optimally cdr-coding. However, it also as- 
sures that all lists or tails of lists are optimally shared when zhequal. 

zhcopytree-share takes as arguments the tree to be copied, and optionally a stor- 
age area, an externally created hash table to be used for the equality testing and a 
cdr-code, which is the storage location of the conses that compose a tree or list. 
The default storage area for the new list is the area occupied by the old list. If 
cdr-code is t, lists will never be "forked" to enable sharing a tail. This wastes 
space, but improves locality. 

Note: zhcopytree-share might be very slow, in the general case, for long lists. 
However, applying it at the appropriate level of a specific structure-copying routine 
(furnishing a common, externally created hash table) is likely to yield all the shar- 
ing possible, at a much lower computational cost. For example, zhcopytree-share 
could be applied only to the branches of a long alist. 

Example: 

(zl :copytree-share '((1 2 3) (12 3) (0 12 3) (0 2 3))) 



Page 976 



If x = ' (1 2 3), the above returns (roughly): 

<(,x ,x (0 . ,x) (0 . ,(cdr x))) 
For a table of related items: See the section "Functions for Copying Lists". 

sircoroutine-bidirectional-stream Flavor 

A flavor implementing bidirectional coroutine streams. Defines :next-input-buffer, 
:new-output-buffer, and :send-output-buffer methods. Use this to construct a 
bidirectional stream to a function written in terms of input and output operations. 

si:coroutine-input-stream Flavor 

A flavor implementing input coroutine streams. Defines a :next-input-buffer 
method. Use this to construct an input stream from a function written in terms of 
output operations. 

sircoroutine-output-stream Flavor 

A flavor implementing output coroutine streams. Defines :new-output-buffer and 
:send-output-buffer methods. Use this to construct an output stream to a function 
written in terms of input operations. 

cos radians Function 

Returns the cosine of radians, radians can be of any numeric type. 

Examples: 

(cos 0) => 1 .0 

(cos (/ pi 2)) => -0.0d0 

(cos (/ pi 4)) => 0.70710677 

For a table of related items: See the section "Trigonometric and Related 
Functions". 

cosd degrees Function 

Returns the cosine of degrees, degrees can be of any numeric type. 

Examples: 

(cosd 90) => -0.0 
(cosd 45) => 0.7071068 
(cosd 36.2) => 0.80696034 

For a table of related items: See the section "Trigonometric and Related 
Functions". 

cosh radians Function 



Page 977 



Returns the hyperbolic cosine of radians. 

Example: 

(cosh 0) => 1 .0 

For a table of related items: See the section "Hyperbolic Functions". 



count item sequence &key (:test #'eql) :test-not (:key #'identity) :from-end (.start 0) 
send 

Function 

Counts the number of elements in a subsequence of sequence satisfying the predi- 
cate specified by the :test keyword, count returns a non-negative integer, which 
represents the number of elements in the specified subsequence of sequence. 

item is matched against the elements specified by the test keyword, item can be 
any Symbolics Common Lisp object. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

:test specifies the test to be performed. An element of sequence satisfies the test if 
(funcall testfun item (keyfn x)) is true, where testfun is the test function specified 
by :test, keyfn is the function specified by :key and x is an element of the se- 
quence. The default test is eql. 

For example: 

(count 'a '(abed) :test-not #'eql) => 3 

:test-not is similar to :test, except that the sense of the test is inverted. An ele- 
ment of sequence satisfies the test if (funcall testfun item (keyfn x)) is false. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. For example: 

(count 'a '((a b) (a b) (b c)) :key tf'car) => 2 

(count 1 #(1 2 3 1 4 1) :key ft' (lambda (x) (- x 1))) => 1 

The :from-end argument does not affect the result returned; it is accepted purely 
for compatibility with other sequence functions. For example: 

(count 'a ' (a a a b c d) :from-end t :start 3) => 

(count 'a ' (a a a b c d) :from-end nil :start 3) => 

For the sake of efficiency, you can delimit the portion of the sequence to be oper- 
ated on by the keyword arguments rstart and rend. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 



Page 978 



rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

b a)) => 2 

'(heron loon heron pelican heron stork)) => 3 

a b b a a) : start 1 :end 5) => 2 

a b b a a) : start 1 :end 6) => 3 

b b b a) ) => 2 

For a table of related items: See the section "Searching for Sequence Items". 



(count 


'a '(a 


(count 


'heron 


(count 


'a '(a 


(count 


'a '(a 


(count 


'a tf(a 



count keyword for loop 
count expr {into var} {data-type} 



If expr evaluates non-nil, a counter is incremented. The data-type defaults to 
fixnum. When the epilogue of the loop is reached, var has been set to the accu- 
mulated result and can be used by the epilogue code. 

It is safe to reference the values in var during the loop, but they should not be 
modified until the epilogue code for the loop is reached. 

The forms count and counting are synonymous. 

Examples: 

(defun num-entry (small-list) 
(loop for x in small-list 

count t into num 

finally (return num))) => NUM-ENTRY 
(num-entry '(a be d)) => 4 

is equivalent to 

(defun num-entry (small-list) 
(loop for x in small-list 

counting t into num 

finally (return num))) => NUM-ENTRY 
(num-entry '(a be d)) => 4 

Not only can there be multiple accumulations in a loop, but a single accumulation 
can come from multiple places within the same loop form, if the types of the col- 
lections are compatible, count and sum are compatible. 

See the section "Accumulating Return Values for loop". 



Page 979 



count-if predicate sequence &key :key :from-end (.start 0) send 

Function 

Returns a non-negative integer, which represents the number of elements in the 
specified subsequence of sequence satisfying the predicate. 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(count-if tf'atom '((a b) ((a) b) (nil nil)) :key tf'car) => 2 

(count-if tf'zerop #(1 2 1) :key ft' (lambda (x) (- x 1))) => 2 

The :from-end argument does not affect the result returned; it is accepted purely 
for compatibility with other sequence functions. 

For example: 

(count-if tf'oddp '(1 1 2 2) : start 2 :from-end t) => 

(count-if tf'oddp '(1 1 2 2) : start 2 :from-end nil) => 

For the sake of efficiency, you can delimit the portion of the sequence to be oper- 
ated on by the keyword arguments rstart and rend. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(count-if tf'oddp '(121 2)) => 2 

(count-if tf'oddp '(111222) : start 2 :end 4) => 1 

(count-if tf'numberp '(heron 1.0 a 2 #\Space)) => 2 

(setq pressure-readings '(1230 1400 :over-limit 1687)) 

(count-if ft' (lambda(x) (eq x :over-l imit)) pressure-readings) => 1 

For a table of related items: See the section "Searching for Sequence Items". 
count-if-not predicate sequence &key :key :from-end (.start 0) send 



Page 980 



Function 

Returns a non-negative integer, which represents the number of elements in the 
specified subsequence of sequence that do not satisfy the predicate. 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(count-if-not tf'atom '((a b) ((a) b) (nil nil)) :key tf'car) => 1 

(count-if-not tf'zerop #(1 2 1) :key ft' (lambda (x) (- x 1))) => 1 

The :from-end argument does not affect the result returned; it is accepted purely 
for compatibility with other sequence functions. 

For example: 

(count-if-not tf'oddp '(1 1 2 2) : start 2 :from-end t) => 2 

(count-if-not #'oddp '(1 1 2 2) : start 2 :from-end nil) => 2 

For the sake of efficiency, you can delimit the portion of the sequence to be oper- 
ated on by the keyword arguments rstart and rend. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(count-if-not #'numberp '(heron 1.0 a 2 #\Space)) => 3 
(count-if-not tf'oddp '(343 4)) => 2 

(setq pressure-readings '(1230 1400 :over-limit 1687)) 
(count-if-not ft' (lambda(x) (numberp x)) pressure-readings) 

=> 1 
For a table of related items: See the section "Searching for Sequence Items". 



rcreation-date Message 



Page 981 



Returns the creation date of the file, as a number which is a universal time. See 
the section "Dates and Times". See the function fs:directory-list. 

ctypecase object &body body Special Form 

ctypecase is similar to typecase, except that it does not allow an explicit 
otherwise or t clause, and if no clause is satisfied it signals a proceedable error 
instead of returning nil. 

ctypecase is a conditional that chooses one of its clauses by examining the type of 
an object. Its form is as follows: 

(ctypecase form 

(types consequent consequent ...) 
(types consequent consequent ...) 

) 

First ctypecase evaluates form, producing an object, ctypecase then examines 
each clause in sequence, types in each clause is a type specifier in either symbol or 
list form, or a list of type specifiers. The type specifier is not evaluated. If the ob- 
ject is of that type, or of one of those types, then the consequents are evaluated 
and the result of the last one is returned (or nil if there are no consequents in 
that clause). Otherwise, ctypecase moves on to the next clause. 

If no clause is satisfied, ctypecase signals an error with a message constructed 
from the clauses. To continue from this error, supply a new value for object, caus- 
ing ctypecase to store that value and restart the type tests. Subforms of object can 
be evaluated multiple times. 

For an object to be of a given type means that if typep is applied to the object 
and the type, it returns t. That is, a type is something meaningful as a second ar- 
gument to typep. See the section "Data Types and Type Specifiers". 

It is permissible for more than one clause to specify a given type, particularly if 
one is a subtype of another; the earliest applicable clause is chosen. Thus, for 
ctypecase, the order of the clauses can affect the behavior of the construct. 

Examples: 

(defun tel 1-about-car (x) 
(ctypecase (car x) 

(string "string") ))=> TELL-ABOUT-CAR 
(tel 1-about-car '("word" "more")) => "string" 
(tel 1-about-car '(a 1)) => proceedable error is signalled 



Page 982 



(defun tel 1-about-car (x) ; see typecase 

(ctypecase (car x) 

(fixnum "number.") 

((or string symbol) "string or symbol.") 

(otherwise "I don't know."))) => TELL-ABOUT-CAR 
(tel 1-about-car '(1 a)) => "number." 
(tel 1-about-car '(a 1)) => "string or symbol." 
(tel 1-about-car '("word" "more")) => "string or symbol." 
(tel 1-about-car '(1.0)) => " I don't know." 

For a table of related items: See the section "Conditional Functions". 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



zhcursorpos &rest args Function 

This function exists primarily for Maclisp compatibility. It performs operations re- 
lated to the cursor position, such as returning the position, moving the position, or 
performing another cursor operation. 

zhcursorpos normally operates on the zh standard-output stream; however, if the 
last argument is a stream or t (meaning zl:terminal-io), zhcursorpos uses that 
stream and ignores it when doing the operations described below. Note that 
zhcursorpos works only on streams that are capable of these operations, such as 
windows. A stream is taken to be any argument that is not a number and not a 
symbol, or a symbol other than nil with a name more than one character long. 

(zhcursorpos) => (line . column), the current cursor position. 

(cursorpos line column) moves the cursor to that position. It returns t if it suc- 
ceeds and nil if it does not. 

(cursorpos op) performs a special operation coded by op and returns t if it suc- 
ceeds and nil if it does not. op is tested by string comparison, is not a keyword 
symbol, and can be in any package. 

F Moves one space to the right. 

B Moves one space to the left. 

D Moves one line down. 

U Moves one line up. 

T Homes up (moves to the top left corner). Note that t as the last argument 

to zhcursorpos is interpreted as a stream, so a stream must be specified if 
the t operation is used. 

Z Homes down (moves to the bottom left corner). 

A Advances to a fresh line. See the :fresh-line stream operation. 



Page 983 



C Clears the window. 

E Clears from the cursor to the end of the window. 

L Clears from the cursor to the end of the line. 

K Clears the character position at the cursor. 

X B then K. 



sysrdebug-instance instance Function 

Enters the Debugger in the lexical environment of instance. This is useful in de- 
bugging. You can examine and alter instance variables, and run functions that use 
the instance variables. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



*debug-io* Variable 

The value of *debug-io* is a stream to be used for interactive debugging purposes. 
In CLOE-Runtime, *debug-io* is initially a synonym stream of *terminal-io*. 

(format xdebug-iox "Return to top level?") 
(if (positive-response (read xdebug-iox))) 



zl:debug-io Variable 

In your new programs, we recommend that you use the variable *debug-io*, which 
is the Common Lisp equivalent of zl:debug-io. 

If not nil, this is the stream that the Debugger should use. The default value is a 
synonym stream that is synonymous with zl:terminal-io. If the value of 
dbg:*debug-io-override* is not nil, the Debugger uses the value of that variable 
as the stream instead of the value of zl:debug-io. 

The value of zl:debug-io can also be a string. This causes the Debugger to use 
the cold-load stream; the string is the reason why the cold-load stream should be 
used. 

No program other than the Debugger should do stream operations on the value of 
zl:debug-io, since the value cannot be a stream. Other programs should use 
zl:query-io, zherror-output, or zhtrace-output. zl:debug-io is equivalent to 
*debug-io*. 



dbg:*debugger-bindings* Variable 



Page 984 



When the Debugger is entered, it binds some special variables under control of the 
list that is the value of dbg:*debugger-bindings*. Each element of the list is a 
list of two elements: a variable and a form that is evaluated to produce the value 
to bind it to. The bindings happen sequentially. You can push things on this list 
(adding to the front of it), but should not replace the list wholesale since several 
of the variable bindings on this list are essential to the operation of the Debugger. 



debugging-info function Function 

Returns the debugging info alist of function. Most of the elements of this alist are 
an internal interface between the compiler and the Debugger. 



decf access-form &optional amount Macro 

Decrements the value of a generalized variable, (decf ref) decrements the value of 
ref by 1. (decf ref amount) subtracts amount from ref and stores the difference 
back into ref. It returns the new value of ref. 

access-form can be any form acceptable to setf. 

(decf (car (mumble))) 
is almost equivalent to 

(setf (car (mumble)) (1- (car (mumble)))) 

except that while the latter would evaluate mumble twice, decf actually expands 
into a let and mumble is evaluated only once. 

(setq arr (make-array (4) : element-type 'integer 

: initial-element 5)) 

(decf (aref arr 3) 4) => #(5 5 5 1) 
See the section "Generalized Variables". 



declaration namel name2 ... Declaration 

Tells the compiler that the names given are valid but non-standard declarations so 
the compiler does not issue warnings about them. This allows you to put declara- 
tions meant for another compiler or another program processor into your program. 
declaration can only be used with proclaim. 

See the section "Declaration Specifiers". 



declare &rest forms Special Form 

Provides additional information to the Lisp system (interpreter and compiler). 

The declare special form can be used in two ways: at top level or within function 
bodies. For information on top-level declare forms: See the section "How the 
Stream Compiler Handles Top-level Forms". 



Page 985 



declare forms that appear within function bodies provide information to the Lisp 
system (for example, the interpreter and the compiler) about this particular func- 
tion. Expressions appearing within the function-body declare are declarations; they 
are not evaluated, declare forms must appear at the front of the body of certain 
special forms, such as let and defun. Some declarations apply to function defini- 
tions and must appear as the first forms in the body of that function; otherwise 
they are ignored. 

See the section "Function-body Declarations". 

The compiler also recognizes any number of declare forms as the first forms in 
the bodies of the following macros and special forms. This means that you can 
have special declarations that are local to any of these blocks. In addition, declara- 
tions can appear at the front of the body of a function definition, like defun, 
defmacro, defsubst, and so on. 

destructuring-bind multiple-value-bind 

let let* 

do do* 

zl:do-named (not in CLOE) zl:do*-named (not in CLOE) 

prog prog* 

lambda 

See the section "Operators for Making Declarations". 



decode-float float Function 

Determines and returns the significand, the exponent, and the sign corresponding 
to the floating-point argument float. The argument float is equal to: 

(* sign significand (expt (float-radix sign) exponent)) 

The significand is returned as a floating-point number of the same format as float. 
It is obtained by dividing the argument by an integral power of 2, the radix of the 
floating-point representation, so as to bring its value between 1/2 (inclusive) and 1 
(exclusive). The quotient is then returned as the significand. 

The second result of decode-float is the integer exponent e to which 2 must be 
raised to produce the appropriate power for the division. 

The third result is a floating-point number, of the same format as the argument, 
whose absolute value is one and whose sign matches that of the argument. 

Examples: 



Page 986 



(decode-float 2.0) => 0.5 and 2 and 1.0 
(decode-float -2.0) => 0.5 and 2 and -1.0 
(decode-float 4.0) => 0.5 and 3 and 1.0 
(decode-float 8.0) => 0.5 and 4 and 1.0 
(decode-float 3.0) => 0.75 and 2 and 1.0 
(decode-float 0.0) => 0.0 and and 1.0 
(decode-float -0.0) => 0.0 and and -1.0 
(decode-float 5.06) -^ .06325 3 1.0 
;;;; a possible use of decode-float 
;;;; (log-abs float) = (log (abs float)) 

(defun log-abs (float) 

(multiple-value-bind (significand exponent) 
(decode-float float) 
(+ (log significand) ;log ab= log a + log b 

(x exponent (log 2))))) ;log (expt x y)= ylogx 

(log-abs 2.0) => 0.6931472 ;(log 2) => 0.6931472 

For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 



decode-raster-array raster Function 

Returns the following attributes of the raster as values: width, height, and span- 
ning width. In a row-major implementation, width and height are the second and 
first dimensions, respectively. The spanning width is the number of linear array el- 
ements needed to go from (x,y) to (x,y+l). For nonconformal arrays, this is the 
same as the width. For conformal arrays, this is the width of the underlying array 
that provides the storage adjusted for possibly differing numbers of bits per ele- 
ment. 

decode-raster-array should be used rather than array-dimensions, zharray- 
dimension-n, or sys:array-row-span for the following reasons. 

• decode-raster-array does error checking by ensuring that the array is two- 
dimensional. 

• A single call to decode-raster-array is faster than any non-null combination of 
the alternatives. 

• decode-raster-array always returns the width and height, which are not the 
first and second dimensions as returned by array-dimensions or zharray- 
dimension-n. 

For a table of related items: See the section "Operations on Rasters". 
mathrdecompose a &optional lu ps ignore Function 



Page 987 



Computes the LU decomposition of matrix a. If lu is non-nil, stores the result into 
it and returns it; otherwise it creates an array to hold the result, and returns that. 
The lower triangle of lu, with ones added along the diagonal, is L, and the upper 
triangle of lu is U, such that the product of L and U is a. Gaussian elimination 
with partial pivoting is used. The lu array is permuted by rows according to the 
permutation array ps, which is also produced by this function. If the argument ps 
is supplied, the permutation array is stored into it; otherwise, an array is created 
to hold it. This function returns two values: the LU decomposition and the permu- 
tation array. 



def function &rest defining-forms Special Form 

If a function is created in some strange way, wrapping a def special form around 
the code that creates it informs the editor of the connection. The form: 

(def function-spec 
forml form2 . . .) 

simply evaluates the forms forml, form2, and so on. It is assumed that these forms 
create or obtain a function somehow, and make it the definition of function-spec. 

Alternatively, you could put (def function-spec) in front of or anywhere near the 
forms that define the function. The editor only uses it to tell which line to put the 
cursor on. 



closrdefclass class-name superclasses slot-specifiers &rest class-options Macro 

Defines a class named class-name, and returns the class object. 

If a class already exists with that name, then the existing class is redefined. A re- 
defined class is eq to the original class. See the section "Redefining a CLOS 
Class". 

class-name A symbol naming the class. 

superclasses A list of class names. The new class inherits slots and other 

characteristics from each of its superclasses. See the section 
"CLOS Inheritance". 

slot-specifiers Each slot-specifier is one of the following: 

slot-name 

{slot-name slot-options . . .) 

The slot-options are: 

rreader reader-name 

Defines a method for a reader generic function named 
reader-name. The reader takes a single argument (an ob- 
ject that is a member of this class), and returns the val- 
ue of this slot. 



Page 988 



rwriter writer-name 

Defines a method for a writer generic function named 
writer-name. The writer takes two arguments (the new 
value, and an object that is a member of this class), and 
sets the value of this slot, writer-name can be a symbol 
or a list of the form (future-common-lisprsetf symbol). 
The following examples show the calling syntax in the 
two cases: 

;;; if the CLOS writer's name is a symbol 
(writer-name new-value instance) 

; ; ; if the CLOS writer's name is (clos:setf symbol) 
(setf (symbol instance) new-value) 

Note that when defining a writer method in CLOS to 
use the setf syntax, the function spec must be (future- 
common-lisprsetf symbol). However, when calling the 
writer generic function, you can use either setf or 
future-common-lisp : setf. 

: accessor reader-name 

Defines a method for a reader generic function named 
reader-name, and a method for a writer named (future- 
common-lisprsetf reader-name). 

rlocator locator-name 

This is a Symbolics CLOS extension, which is supported 
on 3600-family and Ivory-based machines only. This op- 
tion defines a method for a locator generic function 
which enables you to get a locative pointer to the cell in- 
side an instance that contains the value of a slot, locator- 
name can be a symbol or a list of the form (locf 
symbol). In the latter case, the locator is called with locf 
syntax: 

(locf (symbol object)) 

rallocation allocation-type 

Defines the allocation type of the slot. If allocation-type 
is rinstance, then a local slot is defined. If allocation-type 
is :class, then a shared slot is defined. If the rallocation 
option is not provided, the slot will be a local slot. 

A local slot means that each instance of the class stores 
its own value for the slot. In other words, the storage 
for the slot is allocated on a per-instance basis. 

A shared slot means that all members of the class share 
the value of the slot. The storage for the slot is allocat- 
ed only once. 



Page 989 



Both local and shared slots are inherited: See the section 
"Inheritance of Slots and closrdefclass Options". 

rinitform form 

Provides a default initial value for the slot. When a new 
instance is created, the initform is used if the slot is not 
initialized in some other way, such as by providing an 
initialization argument in the call to closrmake-instance 
that initializes the slot. The form is evaluated each time 
it is used, in the same lexical environment in which the 
closrdefclass form was evaluated. For local slots, the 
form is evaluated in the dynamic environment in which 
closrmake-instance was called; for shared slots, it is 
evaluated in the dynamic environment in which the 
closrdefclass form was evaluated. 

rinitarg initarg-name 

Provides a means to initialize the slot in a call to 
closrmake-instance. This slot option declares the initarg- 
name as a valid initialization argument to closrmake- 
instance. If you provide the initarg-name and a value in 
a call to closrmake-instance, the slot is initialized with 
that value. This overrides the slot's initform. 

rtype type-specifer 

Declares that the value of the slot is of the type type- 
specifier. Symbolics CLOS ignores this option. 

r documentation string 

Provides a documentation string describing the slot. 

The following slot options may be given more than once for a 
single slot: rreader, rwriter, raccessor, rlocator, and rinitarg. 

If any other slot option is given more than once for a single 
slot, an error is signaled. 

class-options Options that pertain to the class as a whole. The class-options 

are: 

(rdefault-initargs initarg-list) 

The initarg-list is a list of alternating initialization argu- 
ment names and default initial value forms. If an initial- 
ization argument name is not provided in a call to 
closrmake-instance, and it does appear in the rdefault- 
initargs initarg-list, the default value form is evaluated 
and used. The form is evaluated in the same lexical en- 
vironment as that in which the closrdefclass was evalu- 
ated, and in the same dynamic environment in which 
closrmake-instance was called. An error is signaled if 
an initialization argument name appears more than once 
in the initarg-list. 



Page 990 



(: documentation string) 

Provides a documentation string describing the class. 
You can get the documentation string of a class as fol- 
lows: 

(documentation class-name 'type) 

(rmetaclass class-name) 

Specifies the class of the class being defined. The default 
is clos:standard-class. In Symbolics CLOS, the effects 
are undefined if any other value is given to this option. 

The rdefault-initargs, : documentation, and rmetaclass class 
options may not be given more than once. 

See the section "Inheritance of Slots and closrdefclass Options". 
See the section "CLOS Class Precedence List". 



zhdefconst variable initial-value &optional documentation Special Form 

The same as defvar, except that variable is always set to initial-value regardless of 
whether variable is already bound. The rationale for this is that defvar declares a 
global variable, whose value is initialized to something but is then changed by the 
functions that use it to maintain some state. On the other hand, zhdefconst de- 
clares a constant, whose value is never changed by the normal operation of the 
program, only by changes to the program, zhdefconst always sets the variable to 
the specified value so that if, while developing or debugging the program, you 
change your mind about what the constant value should be, and you then evaluate 
the zhdefconst form again, the variable gets the new value. It is not the intent of 
zhdefconst to declare that the value of variable never changes; for example, 
zhdefconst is not license to the compiler to build assumptions about the value of 
variable into programs being compiled. See defconstant for that. 

See the section "Special Forms for Defining Special Variables". 



defconstant variable initial-value &optional documentation Special Form 

Declares the use of a named constant in a program. Additionally, defconstant indi- 
cates that the value of the constant remains the same, initial-value is evaluated 
and variable set to the result. The value of variable is then fixed. It is an error if 
variable has any special bindings at the time the defconstant form is executed. 
Once a special variable has been declared constant by defconstant, any further as- 
signment to or binding of that variable is an error. 

The compiler is free to build assumptions about the value of the variable into pro- 
grams being compiled. If the compiler does replace references to the name of the 
constant by the value of the constant in code to be compiled, the compiler takes 
care that such "copies" appear to be eql to the object that is the actual value of 
the constant. For example, the compiler can freely make copies of numbers, but it 
exercises care when the value is a list. 



Page 991 



In Symbolics Common Lisp, defconstant and zhdefconst are essentially the same 
if the value is other than a number, a character, or an interned symbol. However, 
if the variable being declared already has a value, zhdefconst freely changes the 
value, whereas defconstant queries before changing the value, defconstant's 
query offers three choices: Y, N, and P. 

• The Y option changes the value. 

• The N option does not change the value. 

• The P option changes the value and when you change any future value, prints a 
warning rather than a query. 

The P option sets sysrinhibit-fdefine-warnings to :just-warn. defconstant obeys 
that variable, just as query-about-redefinition does. Use (setq sysrinhibit-fdefine- 
warnings nil) to revert to the querying mode. 

When the value of a constant is changed by a patch file, a warning is printed. 

defconstant assumes that changing the value is dangerous because the old value 
might have been incorporated into compiled code, which is out of date if the value 
changed. 

In general, you should use defconstant to declare constants whose value is a 
number, character, or interned symbol and is guaranteed not to change. An exam- 
ple is 7t. The compiler can optimize expressions that contain references to these 
constants. If the value is another type of Lisp object or if it might change, you 
should use zhdefconst instead. 

documentation, if provided, should be a string. It is accessible to the 
documentation function. 

For example: 

(defvar xmax-alarmsx 1000 

"The maximum number of times alarms can be sounded.") 

For more information see the section "Special Forms for Defining Special 
Variables". 



deff function definition Special Form 

This is a simplified version of def. It evaluates the form definition, which should 
produce a function, and makes that function the definition of function, which is not 
evaluated, deff is used for giving a function spec a definition that is not obtain- 
able with the specific defining forms such as defun and macro. For example: 

(deff foo 'bar) 

makes foo equivalent to bar, with an indirection so that if bar changes, foo like- 
wise changes; 

(deff foo (function bar)) 



Page 992 



copies the definition of bar into foo with no indirection, so that further changes to 
bar have no effect on foo. 



defflavor name instance-variables component-flavors &rest options Special Form 

name is a symbol that is the name of this flavor. 

defflavor defines the name of the flavor as a type name in both the Common Lisp 
and Zetalisp type systems; for further information, see the section "Flavor In- 
stances and Types", defflavor also defines the name of the flavor as a presentation 
type name; for further information, see the section "User-defined Data Types as 
Presentation Types". 

instance-variables is a list of the names of the instance variables containing the lo- 
cal state of this flavor. Each element of this list can be written in two ways: ei- 
ther the name of the instance variable by itself, or a list containing the name of 
the instance variable and a default initial value for it. Any default initial values 
given here are forms that are evaluated by make-instance if they are not overrid- 
den by explicit arguments to make-instance. 

If you do not supply an initial value for an instance variable as an argument to 
make-instance, and there is no default initial value provided in the defflavor 
form, the value of an instance variable remains unbound. (Another way to provide 
a default is by using the :default-init-plist option to defflavor.) 

component-flavors is a list of names of the component flavors from which this fla- 
vor is built. 

Each option can be either a keyword symbol or a list of a keyword symbol and its 
arguments. The syntax of the defflavor options is given below, and the semantics 
of the options are described in detail elsewhere: See the section "Summary of 
defflavor Options". See the section "Complete Options for defflavor". 

Several options affect instance variables, including: 

rinitable-instance-variables 

rgettable-instance-variables 

rlocatable-instance-variables (not available in CLOE) 

rreadable-instance-variables 

: settable-instance- variables 

: special-instance- variables (not available in CLOE) 

rwritable-instance-variables 

The options listed above can be given in two ways: 

keyword The keyword appearing by itself indicates that the option ap- 

plies to all instance variables listed at the top of this defflavor 
form. 

(keyword varl var2 ...) 

A list containing the keyword and one or more instance vari- 
ables indicates that this option refers only to the instance vari- 
ables listed here. 



Page 993 



Briefly, the syntax of the other options is as follows: 

rabstract-flavor 

: area-keyword symbol) (not available in CLOE) 
:component-order args...) 
:conc-name symbol) 
rconstructor args...) 
: default-handler function-name) 
:default-init-plist plist) 
: documentation string) 
rfunctions internal-function-names) 
:init-keywords symbols...) 
rmethod-combination symbol) 
:method-order generic-function-names) 
rmixture specs...) 

no-vanilla-flavor (not available in CLOE) 
rordered-instance-variables symbols) 
rrequired-flavors flavor-names) 
:required-init-keywords init-keywords) 
rrequired-instance-variables symbols) 
rrequired-methods generic-function-names) 

rspecial-instance-variables-binding-methods generic-function-names) 
(not available in CLOE) 

The following form defines a flavor wink to represent tiddly-winks. The instance 
variables x and y store the location of the wink. The default initial value of both x 
and y is 0. The instance variable color has no default initial value. The options 
specify that all instance variables are rinitable-instance-variables; x and y are 
: writable-instance- variables; and color is a rreadable-instance-variable. 

(defflavor wink ((x 0) (y 0) color) ;x and y represent location 

() ;no component flavors 

: ini table- instance- variables 

( :writable-instance-variables x y) ;this implies readable 

( : readabl e-i nstance-vari abl es col or) ) 

You can specify that an option should alter the behavior of instance variables in- 
herited from a component flavor. To do so, include those instance variables explic- 
itly in the list of instance variables at the top of the defflavor form. In the follow- 
ing example, the variables x and y are explicitly included in this defflavor form, 
even though they are inherited from the component flavor, wink. These variables 
are made initable in the defflavor form for big-wink; they are made writable in 
the defflavor form for wink. 

(defflavor big-wink (x y size) 

(wink) ;wink is a component 

( : initable-instance-variables x y)) 

If you specify a defflavor option for an instance variable that is not included in 
this defflavor form, an error is signalled. Flavors assumes you misspelled the 
name of the instance variable. 



Page 994 



For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



formatrdefformat directive (arg-type) arglist body 
Defines a new format directive. 



Function 



directive is a symbol that names the directive. If directive is longer than one char- 
acter, the user must enclose it in backslashes in calls to format. For example: 



(format t " WfooW" 



) 



directive is usually in the format package; if it is in another package, the user 
must specify the package in calls to format. For example, we've defined a format 
directive called sirkeystroke that prints out the short names for all characters. 

(defun gtest () 

(loop for (name char) in '(("Space" #\space) 

'c-Space" #\c-space) 

'Tab" #\tab) 

'Page" #\page) 

'Left" #\mouse-L) 

'c-Left" #\c-mouse-L) 

'A" tf\A) 

'c-A" #\c-A)) 
do 

(format t "~%~A: ~C, ~\\si :keystroke\\" name char char))) => 
Space: , Space 
c-Space: c- , c-Space 
Tab: , Tab 
Page: , Page 
Left: Mouse-L, Mouse-L 
c-Left: c-Mouse-L, c-Mouse-L 
A: A, A 
c-A: c-A, c-A 
NIL 

formatrdefformat defines a function to be called when format is called using di- 
rective, body is the body of the function definition, arg-type is a keyword that deter- 
mines the arguments to be passed to the function as arglist: 



:no-arg 



:one-arg 



The directive uses no arguments. The function is passed one 
argument, a list of parameters to the directive. The value re- 
turned by the function is ignored. 

The directive uses one argument. The function is passed two 
arguments: the argument associated with the directive and a 
list of parameters to the directive. The value returned by the 
function is ignored. 



Page 995 



:multi-arg The directive uses a variable number of arguments. The func- 

tion is passed two arguments. The first is a list of the first ar- 
gument associated with the directive and all the remaining ar- 
guments to format. The second is a list of parameters to the 
directive. The function should cdr down the list of arguments, 
using as many as it wants, and return the tail of the list so 
that the remaining arguments can be given to other directives. 

The function can examine the values of format:colon-flag and format:atsign-flag. 
If format:colon-flag is not nil, the directive was given a : modifier. If 
format:atsign-flag is not nil, the directive was given an @ modifier. 

The function should send its output to the stream that is the value of 
format : *f ormat-output* . 

Here is an example of a format directive that takes one argument and prints a 
number in base 7: 

(format :def format format :base-7 (:one-arg) (argument parameters) 
parameters ; ignored 

(let ((xprint-basex 7)) 

(princ argument format :*f ormat-output*))) 

Now: 

(format nil "> ~\\base-7\\ <" 8) => "> 11 <" 



deffunction fspec lambda-type lambda-list &body rest Special Form 

Defines a function using an arbitrary lambda macro in place of lambda. A 
deffunction form is like a defun form, except that the function spec is immediate- 
ly followed by the name of the lambda macro to be used, deffunction expands the 
lambda macro immediately, so the lambda macro must already be defined before 
deffunction is used. For example, suppose the ilisp lambda macro were defined as 
follows: 

(lambda-macro ilisp (x) 

'(lambda (&optional ,@(second x) &rest ignore) . , (cddr x))) 

Then the following example would define a function called new-list that would use 
the lambda macro called ilisp: 

(deffunction new-list ilisp (x y z) 
(list x y z)) 

new-list's arguments are optional, and any extra arguments are ignored. Examples: 

(new-list 1 2) => (1 2 nil) 
(new-list 1 2 3 4) -> (1 2 3) 



defgeneric name arglist &body options Special Form 



Page 996 



Defines a generic function named name that accepts arguments defined by arglist, 
a lambda-list, arglist is required unless the rfunction option is used to indicate 
otherwise, arglist represents the object that is supplied as the first argument to 
the generic function. The flavor of the first element of arglist determines which 
method is appropriate to perform this generic function on the object. 

The semantics of the options for defgeneric are described elsewhere: See the sec- 
tion "Options for defgeneric". The syntax of the options is summarized here: 

(rcompatible-message symbol) 
(declare declaration) 
(rdispatch flavor-name) 
(: documentation string) 
(rfunction body...) 
rinline-methods 
(rinline-methods rrecursive) 
(rmethod (flavor options...) body...) 
(rmethod-arglist args...) 
(rmethod-combination name args...) 
(roptimize speed) 

For example, to define a generic function total-fuel-supply that works on in- 
stances of army and navy, and takes one argument (fuel-type) in addition to the 
object itself, we might supply military-group as argl: 

(defgeneric total-fuel-supply (military-group fuel-type) 
"Returns today's total supply 
of the given type of fuel 
available to the given military group." 
( : method-combination :sum)) 

The generic function is called as follows: 

(total -fuel -supply blue-army ':gas) 

The argument blue-army is known to be of flavor army. Therefore, Flavors choos- 
es the method that implements the total-fuel-supply generic function on instances 
of the army flavor. That method takes only one argument, fuel-type: 

(defmethod (total-fuel-supply army) (fuel-type) 
body of method) 

The arguments to defgeneric are displayed when you give the Arglist (m-K) com- 
mand or press c-sh-R while this generic function is current. 

It is not necessary to use defgeneric to set up a generic function. For further dis- 
cussion: See the section "Use of defgeneric". 

The function spec of a generic function is described elsewhere: See the section 
"Function Specs for Flavor Functions". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



closrdefgeneric function-specifier lambda-list &rest options 



Page 997 



Macro 



Defines a generic function and returns the generic function object. It is not always 
necessary to use closrdefgeneric, because using closrdefmethod will automatically 
create a generic function, if it does not already exist. However, closrdefgeneric is 
useful for defining the interface of the generic function, and for specifying options 
that pertain to the generic function as a whole, such as the method-combination 
type. 

The arguments to closrdefgeneric are: 



function-specifier 



lambda-list 



options 



The name of the generic function, which is either a symbol or 
a list of the form (future-common-lisp rsetf symbol). An error 
is signaled if the function-specifier indicates an ordinary Lisp 
function, a macro, or a special form. In other words, you can- 
not use closrdefgeneric to redefine an ordinary function, 
macro, or special form to be a generic function. 

Specifies the lambda-list of the generic function. This is an or- 
dinary lambda-list with some exceptions. Default values for op- 
tional and keyword parameters may not be provided, and &aux 
parameters may not be specified. 

One or more of the following options: 

( r argument-precedence-order {parameter-name } +) 

Specifies the precedence order of the required parame- 
ters, which is used when ordering methods from most 
specific to least specific. The default argument prece- 
dence order is left to right, such that the leftmost pa- 
rameter is considered first, followed by the parameters 
to its right. The name of each required parameter must 
be given. 

(declare {declaration} +) 

Specifies one or more declarations that pertain to the 
generic function. CLOS recognizes the optimize declara- 
tion, which declares whether method selection should be 
optimized for speed or space. Symbolics CLOS recognizes 
the following declarations as well: arglist, values, 
sysrdownward-funarg, and sysrfunction-parent. 

(r documentation string) 

Provides a documentation string describing the generic 
function. You can get the documentation string of a class 
as follows: 

(documentation class-name 'type) 

(rmethod-combination symbol {arg}*) 

Specifies the method-combination type to be used by the 
generic function, and any arguments to the method- 



Page 998 



combination type. The args are not evaluated. The de- 
fault method-combination type is closrstandard. 

(rmethod {method-qualifier}* specialized-lambda-list &body 
body) 

Enables you to define one or more methods for this 
generic function in the closrdefgeneric form, rather than 
having separate closrdefmethod forms. Sometimes it is 
convenient to define default methods within the 
closrdefgeneric form. For information on the arguments 
to the rmethod option, see the macro closrdefmethod. 

(rgeneric-function-class class-name) 

Specifies the class of the generic function. The default is 
closrstandard-generic-function. In Symbolics CLOS, the 
effects are undefined if any other value is given to this 
option. 

(rmethod-class class-name) 

Specifies the class of the methods for this generic func- 
tion. The default is closrstandard-method. In Symbolics 
CLOS, the effects are undefined if any other value is 
given to this option. 



zlr@ define &rest ignore Macro 

This macro turns into nil, doing nothing. It exists for the sake of the @ listing 
generation program, which uses it to declare names of special forms that define 
objects (such as functions) that @ should cross-reference. 



sirdefine-character-style-families device character-set &rest plists Function 

The mechanism for defining new character styles, and for defining which font 
should be used for displaying characters from character-set on the specified device, 
plists contain the actual mapping between character styles and fonts. 

It is necessary that a character style be defined in the world before you access a 
file that uses the character style. You should be careful not to put any characters 
from a style you define into a file that is shared by other users, such as 
sys.translations. 

It is possible for plists to map from a character style into another character style; 
this usage is called logical character styles. It is expected that the logical style 
used has its own mapping, in this sirdefine-character-style-families form or an- 
other such form, that eventually is resolved into an actual font. 

plists is a nested structure whose elements are of the form: 



Page 999 



( : family family 

( :size size 

( : face face target-font 
-. face face target-font 
-. face face target-font) 
:size size 

( : face face target-font 
-. face face target-font) ) ) 

Each target-font is one of: 

• A symbol such as fontsrcptfont, which represents a font for a black and white 
Symbolics console. 

• A string such as "furrier7", which represents a font for an LGP2 or LGP3 
printer. 

• A list whose car is :font and whose cadr is an expression representing a font, 
such as (:font ("Furrier" "B" 9 1.17)). This is also a font for an LGP2/LGP3 
printer. 

• A list whose car is rstyle and whose cdr is a character style, such as: ( : styl e 
family face size). This is an example of using a logical character style (see 
ahead for more details). 

Each size is either a symbol representing a size, such as rnormal, or an asterisk * 
used as a wildcard to match any size. The wildcard syntax is supported for the 
:size element only. When you use a wildcard for size the target-font must be a 
character style. The size element of target-font can be :same to match whatever 
the size of the character style is, or : smaller or rlarger. 

If you define a new size, that size cannot participate in the merging of relative 
sizes against absolute sizes. The ordered hierarchy of sizes is predefined. See the 
section "Merging Character Styles". 

The elements can be nested in a different order, if desired. For example: 

( :size size 

( : face face 

( : f am i 1 y target-font) ) ) 

The first example simply maps the character style BOX.ROMAN.NORMAL into the 
font fontsrboxfont for the character set si:*standard-character-set* and the de- 
vice si:*b&w-screen*. The face ROMAN and the size NORMAL are already valid 
faces and sizes, but BOX is a new family; this form makes BOX one of the valid 
families. 

;;; -*- Package : SYSTEM-INTERNALS; Mode:LISP; Base: 10 -*- 

(def i ne-character-styl e-f ami 1 i es xb&w-screenx xstandard-character-setx 
' ( : family :box 

(:size : normal ( : f ace : roman fonts :boxfont)))) 



Page 1000 



Once you have compiled this form, you can use the Zmacs command Change Style 
Region (invoked by c-K c-J) and enter BOX.ROMAN.NORMAL. This form does not 
make any other faces or sizes valid for the BOX family. 

The following example uses the wildcard syntax for the :size, and associates the 
faces ritalic, :bold, and :bold-italic all to the same character style of 
BOX.ROMAN.NORMAL. This is an example of using logical character styles. This 
form has the effect of making several more character styles valid; however, all 
styles that use the BOX family are associated with the same logical character 
style, which uses the same font. 

;;; -*- Package : SYSTEM-INTERNALS; Mode:LISP; Base: 10 -*- 

(def i ne-character-styl e-f ami 1 i es xb&w-screenx xstandard-character-setx 
' ( : family :box 

(:size * ( : f ace : italic (: style :box : roman : normal) 
:bold (: style :box : roman : normal) 
: bold-italic (: style :box : roman :normal))))) 

For lengthier examples: See the section "Examples of si:define-character-style- 
families". 

For related information: See the section "Mapping a Character Style to a Font". 



define-global-handler name conditions arglist &body body Function 

name is a symbol, and a handler function by that name is defined. 

conditions is a condition name, or a list of condition names. 

arglist is a list of one element, the name of the argument (a symbol) which is 
bound to the condition object. 

A global handler is like a bound handler with an important exception: unlike a 
bound handler which is of dynamic extent, a global handler is of indefinite extent. 
Once defined, a global handler must therefore be specifically removed with 
undefine-global-handler. 

Similarly, since a global handler could be called in any process by any program, it 
cannot use a throw the way a bound handler can. Instead it should return nil 
(keep searching for another handler), or return multiple values where the first one 
is the name of a proceed-type, as with bound handlers. 

A note of caution: The global handler functions do not maintain the order of the 
global handler list in any way. If there are two handlers whose conditions overlap 
each other in such a way that some instantiable condition could be handled by ei- 
ther, then either handler might run, depending on the order in which they were 
defined. When there is more experience with use of global handlers we will try to 
develop a good approach to this problem. 

Example: 



Page 1001 



(def ine-global -handler inf inity-is-three sys: divide-by-zero 
(error) 
(values : return-values '(3))) 

(/ 1 0) ==> 3 
For a table of related items, see the section "Basic Forms for Global Handlers". 

define-loop-macro keyword Macro 

Can be used to make keyword, a loop keyword (such as for), into a Lisp macro 
that can introduce a loop form. For example, after evaluating: 

(define-loop-macro for) => T 

you can now write an iteration as: 

(for i from 1 below n do ...) 

(for i from 1 to 5 

do 

(print i)) => 
1 
2 
3 
4 
5 NIL 

This facility exists primarily for diehard users of a predecessor of loop. Its uncon- 
strained use is not recommended, as it tends to decrease the transportability of the 
code and needlessly uses up a function name. 

See the macro loop. 

define-loop-path Macro 

Allows a function to generate code for a path to be declared to loop: 

(define-loop-path path-name-or-names path-function 
list-of-allowable-prepositions 
datum-1 datum-2 . . .) 

This defines path-function to be the handler for the path(s) path-name-or-names, 
which can be either a symbol or a list of symbols. Such a handler should follow 
the conventions described below. The datum-i are optional; they are passed in to 
path-function as a list. 

path-name The name of the path that caused the path function to be in- 

voked. 



Page 1002 



variable The "iteration variable". 

data-type The data type supplied with the iteration variable, or nil if 

none was supplied. 

prepositional-phrases 

A list with entries of the form (preposition expression), in the 
order in which they were collected. This can also include some 
supplied implicitly (for example, an of phrase when the itera- 
tion is inclusive, and an in phrase for the default-loop-path 
path); the ordering shows the order of evaluation that should 
be followed for the expressions. 

inclusive? t if variable should have the starting point of the path as its 

value on the first iteration (by virtue of being specified with 
syntax like for var being expr and its path-name, nil other- 
wise. When t, expr appears in prepositional-phrases with the of 
preposition; for example, for x being foo and its cdrs gets 
prepositional-phrases of ((of foo)). 

allowed-prepositions The list of allowable prepositions declared for the path-name 
that caused the path function to be invoked. It and data can be 
used by the path function such that a single function can han- 
dle similar paths. 

data The list of "data" declared for the path-name that caused the 

path function to be invoked. It might, for instance, contain a 
canonicalized path-name, or a set of functions or flags to aid 
the path function in determining what to do. In this way, the 
same path function might be able to handle different paths. 

The handler should return a list of either six or ten elements: 

variable-bindings 

A list of variables that need to be bound. The entries in it can be of the 
form variable, {variable expression), or {variable expression data-type). Note 
that it is the responsibility of the handler to make sure the iteration vari- 
able gets bound. All of these variables are bound in parallel; if initialization 
of one depends on others, it should be done with a setq in the prologue- 
forms. Returning only the variable without any initialization expression is 
not allowed if the variable is a destructuring pattern. 

prologue-forms 

A list of forms that should be included in the loop prologue. 

the four items of the iteration specification 

The four items: pre-step-endtest, steps, post-step-endtest, and pseudo-steps. See 
the section "The Iteration Framework". 

another four items of iteration specification 

If these four items are given, they apply to the first iteration, and the pre- 
vious four apply to all succeeding iterations; otherwise, the previous four 
apply to all iterations. 



Page 1003 



See the section "Iteration Paths for loop". 



define-loop-sequence-path path-name-or-names fetchfun sizefun &optional sequence- 
type element-type Macro 

One very common form of iteration is that over the elements of some object that 
is accessible by means of an integer index, loop defines an iteration path function 
for doing this in a general way, and provides a simple interface to allow users to 
define iteration paths for various kinds of "indexable" data. 

path-name-or-names is either an atomic path name or list of path names. 

fetchfun is a function of two arguments: the sequence, and the index of the item to 
be fetched. (Indexing is assumed to be zero-origined.) 

sizefun is a function of one argument, the sequence; it should return the number 
of elements in the sequence, sequence-type is the name of the data-type of the se- 
quence, and element-type the name of the data-type of the elements of the se- 
quence. These last two items are optional. 

Examples: 

(define-loop-sequence-path asci i-char 

(lambda (string i) 

(ascii-code (aref string i))) 
length) => NIL 

(loop for x being the ascii-char of "ABC" 
doing 
(print x)) => 
65 
66 
67 NIL ; 65 is the ascii equivalent of "A" 

The Symbolics Common Lisp implementation of loop utilizes the Symbolics Com- 
mon Lisp array manipulation primitives to define both array-element and array- 
elements as iteration paths: 

(define-loop-sequence-path (array-element array-elements) 
aref array-active-length) 

Then, the loop clause: 

for var being the array-elements of array 

steps var over the elements of array, starting from 0. The sequence path function 
also accepts in as a synonym for of. 

The range and stepping of the iteration can be specified with the use of all the 
same keywords that are accepted by the loop arithmetic stepper (for var from ...); 
they are by, to, downto, from, downfrom, below, and above, and are interpreted 
in the same manner. Thus: 



Page 1004 



(loop for var being the array-elements of array 
from 1 by 2 

steps var over all of the odd elements of array, and: 

(loop for var being the array-elements of array 
downto 

steps in "reverse" order. 

All such sequence iteration paths allow you to specify the variable to be used as 
the index variable, by use of the index keyword with the using prepositional 
phrase. You can also use the sequence keyword with the using prepositional 
phrase to specify the variable to be bound to the sequence. 



See the section "Iteration Paths for loop". 



define-method-combination name parameters method-patterns &body body Function 

Provides a rich declarative syntax for defining new types of method combination. 
This is more flexible and powerful than define-simple-method-combination. 

name is a symbol that is the name of the new method combination type, parame- 
ters resembles the parameter list of a defmacro; it is matched against the parame- 
ters specified in the rmethod-combination option to defgeneric or defflavor. 

method-patterns is a list of method pattern specifications. Each method pattern se- 
lects some subset of the available methods and binds a variable to a list of the 
function specs for these methods. Two of the method patterns select only a single 
method and bind the variable to the chosen method's function spec if a method is 
found and otherwise to nil. The variables bound by method patterns are lexically 
available while executing the body forms. See the section "Method-Patterns Option 
to define-method-combination". Each option is a list whose car is a keyword. 
These can be inserted in front of the body forms to select special options. See the 
section "Options Available in define-method-combination". The body forms are 
evaluated to produce the body of a combined method. Thus the body forms of 
define-method-combination resemble the body forms of defmacro. Backquote is 
used in the same way. The body forms of define-method-combination usually pro- 
duce a form that includes invocations of flavorrcall-component-method and/or 
flavorrcall-component-methods. These functions hide the implementation- 
dependent details of the calling of component methods by the combined method. 

Flavors performs some optimizations on the combined method body. This makes it 
possible to write the body forms in a simple and easy-to-understand style, without 
being concerned about the efficiency of the generated code. For example, if a com- 
bined method chooses a single method and calls it and does nothing else, Flavors 
implements the called method as the handler rather than constructing a combined 
method. Flavors removes redundant invocations of progn and multiple-value-progl 
and performs similar optimizations. 



Page 1005 



The variables flavorrgeneric and flavorrflavor are lexically available to the body 
forms. The values of both variables are symbols: 

flavorrgeneric value is the name of the generic operation whose handler is 

being computed. 

flavorrflavor value is the name of the flavor. 

The body forms are permitted to setq the variables defined by the method-patterns, 
if further filtering of the available methods is required, beyond the filtering pro- 
vided by the built-in filters of the method-patterns mechanism. It is rarely neces- 
sary to resort to this. Flavors assumes that the values of the variables defined by 
the method patterns (after evaluating the body forms) reflect the actual methods 
that will be called by the combined method body. 

body forms must not signal errors. Signalling an error (such as a complaint about 
one of the available methods) would interfere with the use of flavor examining 
tools, which call the user-supplied method combination routine to study the struc- 
ture of the erroneous flavor. If it is absolutely necessary to signal an error, the 
variable flavorrerror-p is lexically available to the body forms; its value must be 
obeyed. If nil, errors should be ignored. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



closrdefine-method-combination name &rest rest Macro 

Defines a new method-combination type. There are two forms of closrdefine- 
method-combination: a short form, for defining simple method-combination types; 
and a long form, for defining more complex method-combination types. 

closrdefine-method-combination returns the new method-combination object. 

Short-form Syntax 

closrdefine-method-combination name short-form-option* 

None of the subforms are evaluated. The arguments are: 

name The name of the method-combination type, a symbol. If the 

roperator option is not provided, the name of the method- 
combination type must also name a Lisp operator, such as a 
function, macro, or special form. The new method-combination 
type combines applicable primary methods in a call to this op- 
erator: 

(operator {primary-method- 1 args) 
(primary-method-2 args) 

■■■) 



short-form-option These options are: 



Page 1006 



(: documentation string) 

Provides a documentation string for the method- 
combination type. 

(:identity-with-one-argument boolean) 

If true, then an optimization is enabled for the case 
where there is only one applicable method, and it is a 
primary method. In that case, the operator is not called, 
and the value of the method is returned as the value of 
the generic function. This optimization makes sense for 
operators such as progn, +, and, max, and others. 

(roperator operator) 

This option is used when you want the name of the 
method-combination type to be different than the name 
of the operator. 

None of these options may be given more than once. 

A simple method-combination type defined by the short form of closrdefine- 
method-combination has the same semantics as the simple built-in method- 
combination types. For more information, see the section "CLOS Built-in Method- 
Combination Types". 

Long-form Syntax 

closrdefine-method-combination name lambda-list 

( { method-group-specifier } * ) 
[(: arguments . lamba-list)~\ 
[(:generic-function generic-function-symbol) ] 
{declaration \ doc-string}* 
{form}* 

Each method-group-specifier is of the form: 

{variable {{qualifier-pattern} + \ predicate} {option}*) 

The options are: 

description format-string 
order order 
requi red boolean 

name is the name of the method-combination type, a symbol. 

The lambda-list argument is an ordinary lambda-list. It receives any arguments 
provided after the name of the method-combination type in the rmethod- 
combination option to closrdefgeneric. 

The next argument is a list of method-group-specifiers. Each method group specifi- 
er selects a subset of the applicable methods to play a particular role, either by 



Page 1007 



matching their qualifiers against some patterns or by testing their qualifiers with 
a predicate. These method group specifiers define all the method qualifiers that 
can be used with this type of method combination. If an applicable method does 
not fall into any method group, the system signals the error that the method is in- 
valid for the kind of method combination in use. 

Each method group specifier names a variable. During the execution of the forms 
in the body of closrdefine-method-combination, this variable is bound to a list of 
the methods in the method group. The order of the methods in this list is most- 
specific-first, unless this is changed by rorder. 

A qualifier pattern is a list or the symbol *. A method matches a qualifier pattern 
if the method's list of qualifiers is equal to the qualifier pattern (except that the 
symbol * in a qualifier pattern matches anything). Thus a qualifier pattern can be 
one of the following: 

• The empty list (), which matches unqualified methods. 

• The symbol *, which matches all methods. 

• A true list, which matches methods with the same number of qualifiers as the 
length of the list when each qualifier matches the corresponding list element. 

• A dotted list that ends in the symbol *. The * matches any number of additional 
qualifiers. 

Each applicable method is tested against the qualifier patterns and predicates in 
left-to-right order. As soon as a qualifier pattern matches or a predicate returns 
true, the method becomes a member of the corresponding method group and no 
further tests are made. Thus if a method could be a member of more than one 
method group, it joins only the first such group. If a method group has more than 
one qualifier pattern, a method need only satisfy one of the qualifier patterns to be 
a member of the group. 

The name of a predicate function can appear instead of qualifier patterns in a 
method group specifier. The predicate is called for each method that has not been 
assigned to an earlier method group; it is called with one argument, the method's 
qualifier list. The predicate should return true if the method is to be a member of 
the method group. A predicate can be distinguished from a qualifier pattern be- 
cause it is a symbol other than nil or *. 

If there is an applicable method whose qualifiers are not valid for the method- 
combination type (that is, the qualifiers do not match any qualifier patterns, nor 
do they satisfy any predicate, nor do they fit any method group), the function 
clos:invalid-method-error is called. 

Method group specifiers can have keyword options following the qualifier patterns 
or predicate. Keyword options can be distinguished from additional qualifier pat- 
terns because they are neither lists nor the symbol *. Note that none of these op- 
tions may appear more than once in a method group specifier. The keyword op- 
tions are as follows: 



Page 1008 



: description format-string 

Provides a description of the role of methods in the method 
group. Programming environment tools use 

(apply ft' format stream format- string (method-qualifiers method)) 

to print this description, which is expected to be concise. This 
keyword option allows the description of a method qualifier to 
be defined in the same module that defines the meaning of the 
method qualifier. In most cases, format-string will not contain 
any format directives, but they are available for generality. If 
rdescription is not specified, a default description is generated 
based on the variable name and the qualifier patterns and on 
whether this method group includes the unqualified methods. 
The argument format-string is not evaluated. 

rorder order Specifies the order of methods. The order argument is a form 

that evaluates to :most-specific-first or :most-specific-last. If 
it evaluates to any other value, an error is signaled. This key- 
word option is a convenience and does not add any expressive 
power. If rorder is not specified, it defaults to rmost-specific- 
first. 

rrequired boolean Specifies whether at least one method in this method group is 
required. If the boolean argument is non-nil and the method 
group is empty (that is, no applicable methods match the quali- 
fier patterns or satisfy the predicate), an error is signaled. 
This keyword option is a convenience and does not add any ex- 
pressive power. If rrequired is not specified, it defaults to nil. 
The boolean argument is not evaluated. 

The use of method group specifiers provides a convenient syntax to select methods, 
to divide them among the possible roles, and to perform the necessary error 
checking. It is possible to perform further filtering of methods in the body forms 
by using normal list-processing operations and the functions closrmethod- 
qualifiers and closrinvalid-method-error. It is permissible to use setq on the vari- 
ables named in the method group specifiers and to bind additional variables. It is 
also possible to bypass the method group specifier mechanism and do everything in 
the body forms. This is accomplished by writing a single method group with * as 
its only qualifier pattern; the variable is then bound to a list of all of the applica- 
ble methods, in most-specific-first order. 

The body forms compute and return the Lisp form that specifies how the methods 
are combined, that is, the effective method. The effective method uses the macro 
closrcall-method. This macro has lexical scope and is available only in an effective 
method form. Given a method object in one of the lists produced by the method 
group specifiers and a list of next methods, the macro closrcall-method will invoke 
the method such that closrcall-next-method has available the next methods. 

When closrcall-method is called and the next-method-list argument is unsupplied, 
it means that semantically there is no such thing as a "next method"; for example, 



Page 1009 



this is true for before-methods and after-methods in closrstandard method combi- 
nation. Thus, when the next-method-list is unsupplied, clos:call-next-method is not 
allowed inside the method, and the behavior of clos:next-method-p is undefined. If 
the next-method-list argument is supplied as nil, and the method uses closrcall- 
next-method, then clos:no-next-method is called. 

When an effective method has no effect other than to call a single method, CLOS 
can employ an optimization that uses the single method directly as the effective 
method, thus avoiding the need to create a new effective method. This optimization 
is active when the effective method form consists entirely of an invocation of the 
closrcall-method macro whose first subform is a method object and whose second 
subform is nil. Each closrdefine-method-combination body is responsible for strip- 
ping off redundant invocations of progn, and, multiple-value-progl, and the like, 
if this optimization is desired. 

The list (rarguments . lambda-list) can appear before any declarations or documen- 
tation string. This form is useful when the method-combination type performs 
some specific behavior as part of the combined method and that behavior needs ac- 
cess to the arguments to the generic function. Each parameter variable defined by 
lambda-list is bound to a form that can be inserted into the effective method. 
When this form is evaluated during execution of the effective method, its value is 
the corresponding argument to the generic function. 

The arguments to the generic function might not match the lambda-list. If there 
are too few arguments, nil is assumed for missing arguments. If there are too 
many arguments, the extra arguments are ignored. If there are unhandled keyword 
arguments, they are ignored. Supplied-p parameters work in the normal fashion. 
Default value forms are evaluated in the null lexical environment (except for bind- 
ings of rarguments parameters to their left). 

If the effective method form returned by the body forms includes (setq ,variable 
...), or (setf ^variable ...), or (future-common-lisp rsetf ^variable ...), and variable is 
one of the rarguments parameters, the consequences are undefined. 

Erroneous conditions detected by the body should be reported with closrmethod- 
combination-error or closrinvalid-method-error; these functions add any neces- 
sary contextual information to the error message and will signal the appropriate 
error. 

The body forms are evaluated inside of the bindings created by the lambda-list and 
method group specifiers. Declarations at the head of the body are positioned direct- 
ly inside of bindings created by the lambda-list and outside of the bindings of the 
method group variables. Thus method group variables cannot be declared. 

If the list (rgeneric-function generic-function-symbol) is provided, then within the 
body forms, generic-function-symbol is bound to the generic function object. 

If a doc-string argument is present, it provides the documentation for the method- 
combination type. 

The functions closrmethod-combination-error and closrinvalid-method-error can 

be called from the body forms or from functions called by the body forms. 



Page 1010 



Examples 

;;; Examples of the short form of def ine-method-combi nation 

(def ine-method-combi nation and : identity-with-one-argument t) 

(def method func and ((x classl) y) ...) 

;;; The equivalent of this example in the long form is: 

(def ine-method-combi nation and 

(&optional (order ' :most-specif ic-f i rst)) 
((around (: around)) 
(primary (and) : order order : required t)) 
(let ((form (if (rest primary) 

'(and ,@(mapcar #' (lambda (method) 

'(call-method , method ()) 
primary)) 
'(call-method , (first primary) ())))) 
(if around 

1 (cal 1 -method , (first around) 
(,@(rest around) 
(make-method , form))) 
form))) 

;;; Examples of the long form of def ine-method-combi nation 



Page 1011 



;The default method-combination technique 
(def ine-method-combi nation standard () 
((around (: around)) 
(before (: before)) 
(primary () : required t) 
(after (: after))) 
(flet ((cal 1 -methods (methods) 

(mapcar #' (lambda (method) 

1 (cal 1 -method , method))) 
methods))) 
(let ((form (if (or before after (rest primary)) 
1 (mul tiple-value-progl 

(progn ,@(cal 1 -methods before) 

(call-method , (first primary) 
, (rest primary))) 
,@(cal 1 -methods (reverse after))) 
1 (cal 1 -method , (first primary))))) 
(if around 

1 (cal 1 -method , (first around) 
(,@(rest around) 
(make-method , form))) 
form)))) 

;A simple way to try several methods until one returns non-nil 
(def ine-method-combi nation or () 
((methods (or))) 
1 (or ,@(mapcar #' (lambda (method) 

1 (cal 1 -method , method)) 
methods))) 



Page 1012 



;A more complete version of the preceding 
(def ine-method-combi nation or 

(&optional (order ' :most-specif ic-f i rst)) 
((around (: around)) 
(primary (or))) 
; ; Process the order argument 
(case order 

( : most-spec if ic-f i rst) 

( :most-specif ic-last (setq primary (reverse primary))) 
(otherwise (method-combination-error "~S is an invalid order. ~@ 
:most-specif ic-f i rst and :most-specif ic-last are the possible values. 

order))) 
;; Must have a primary method 
(unless primary 

(method-combination-error "A primary method is required.")) 
;; Construct the form that calls the primary methods 
(let ((form (if (rest primary) 

1 (or ,@(mapcar #' (lambda (method) 

1 (cal 1 -method , method)) 
primary)) 
1 (cal 1 -method , (first primary))))) 
; ; Wrap the around methods around that form 
(if around 

1 (cal 1 -method , (first around) 
(,@(rest around) 
(make-method , form))) 
form))) 

;The same thing, using the :order and :required keyword options 
(def ine-method-combi nation or 

(&optional (order ': most-specific-first)) 
((around (: around)) 
(primary (or) :order order :required t)) 
(let ((form (if (rest primary) 

1 (or ,@(mapcar #' (lambda (method) 

1 (cal 1 -method , method)) 
primary)) 
1 (cal 1 -method , (first primary))))) 
(if around 

1 (cal 1 -method , (first around) 
(,@(rest around) 
(make-method , form))) 
form))) 



Page 1013 



;This short-form call is behavioral ly identical to the preceding 
(def ine-method-combi nation or : identity-with-one-argument t) 

;0rder methods by positive integer qualifiers 
;: around methods are disallowed to keep the example small 
(def ine-method-combi nation example-method-combination () 
((methods positive-integer-qual if ier-p)) 
1 (progn ,@(mapcar #' (lambda (method) 

1 (cal 1 -method , method)) 
(stable-sort methods #'< 
:key ft' (lambda (method) 

(first (method-qualifiers method))))))) 

(defun positive-integer-qual if ier-p (method-qualifiers) 
(and (= (length method-qualifiers) 1) 

(typep (first method-qualifiers) '(integer *)))) 

;;; Example of the use of : arguments 
(def ine-method-combi nation progn-with-lock () 
((methods ())) 
(: arguments object) 
1 (unwind-protect 

(progn (lock (object-lock , object)) 
,@(mapcar ft' (lambda (method) 

1 (cal 1 -method , method)) 
methods)) 
(unlock (object-lock , object)))) 



define-modify-macro name args function &rest documentation-and-declarations 

Macro 

Defines a read-modify-write macro named name. An example of such a macro is 
incf. The first subform of the macro will be a generalized-variable reference. The 
function is literally the function to apply to the old contents of the generalized- 
variable to get the new contents; it is not evaluated, args describes the remaining 
arguments for the name; these arguments come from the remaining subforms of 
the macro after the generalized-variable reference, args may contain &optional and 
&rest markers. (The &key marker is not permitted here; &rest suffices for the pur- 
poses of define-modify-macro.) documentation-and-declarations is documentation 
for the macro name being defined. 

The expansion of a define-modify-macro is equivalent to the following, except that 
it generates code that follows the semantic rules outlined above. 



Page 1014 



(defmacro name (reference . lambda-list) 
documentation-and-declarations 
1 (setf reference 

(function reference ,argl ,arg2 ...))) 

where argl, arg2, ..., are the parameters appearing in args; appropriate provision is 
made for a &rest parameter. 

As an example, incf could have been defined by: 

(def ine-modify-macro incf (&optional (delta 1)) +) 

A similar read-modify- write macro for the logior operation of taking the logical 
and of a number can be created by 

(def ine-modify-macro logiorf (arg2) logior) 
(setq first 5 second 6) 
(logiorf first second) => 7 

first => 7 

In the previous example, the lambda list only refers to the second argument to 
logior because these macros are presumed to take at least one argument, and only 
additional arguments require specification. The unspecified first argument is up- 
dated by the macro. 

define-setf-method access-function subforms &body body Macro 

In this context, the word "method" has nothing to do with flavors. 

This macro defines how to setf a generalized-variable reference that is of the form 
(access-function . . .). The value of the generalized-variable reference can always be 
obtained by evaluating it, so access-function should be the name of a function or a 
macro. 

subforms is a lambda list that describes the subforms of the generalized-variable 
reference, as with defmacro. The result of evaluating body must be five values 
representing the setf method. (The five values are described in detail at the end of 
this discussion.) Note that define-setf-method differs from the complex form of 
defsetf in that while the body is being executed the variables in subforms are 
bound to parts of the generalized-variable reference, not to temporary variables 
that will be bound to the values of such parts. In addition, define-setf-method 
does not have the defsetf restriction that access-function must be a function or a 
function-like macro. An arbitrary defmacro destructuring pattern is permitted in 
subforms. 

By definition, there are no good small examples of define-setf-method because the 
easy cases can all be handled by defsetf. A typical use is to define the setf method 
for ldb. 



Page 1015 



;;; SETF method for the form (LDB bytespec int). 

;;; Recall that the int form must itself be suitable for SETF. 

(def ine-setf-method ldb (bytespec int) 
(multiple-value-bind (temps vals stores 

store-form accessform) 
(get-setf-method int) ;Get SETF method for int. 

(let ((btemp (gensym)) ;Temp var for byte specifier, 

(store (gensym)) ;Temp var for byte to store, 

(stemp (first stores))) ;Temp var for int to store. 
;; Return the SETF method for LDB as five values, 
(values (cons btemp temps) ; Temporary variables, 
(cons bytespec vals) ; Value forms, 
(list store) ;Store variables, 

'(let ((, stemp (dpb , store , btemp , access-form))) 
, store-form 

, store) ;Storing form, 

'(ldb , btemp , access-form) ; Accessing form. 
)))) 

Here are the five values that express a setf method for a given access form. 
• A list of temporary variables. 



• 



A list of value forms (subforms of the given form) to whose values the tempo- 
rary variables are to be bound. 

• A second list of temporary variable, called store variables. 

• A storing form. 

• An accessing form. 

The temporary variables are bound to the value forms as if by let*; that is, the 
value forms are evaluated in the order given and may refer to the values of earlier 
value forms by using the corresponding variable. 

The store variables are to be bound to the values of the newvalue form, that is, 
the values to be stored into the generalized variable. In almost all cases, only a 
single value is stored, and there is only one store variable. 

The storing form and the accessing form may contain references to the temporary 
variables (and also, in the case of the storing form, to the store variables). The ac- 
cessing form returns the value of the generalized variable. The storing form modi- 
fies the value of the generalized variable and guarantees to return the values of 
the store variables as its values. These are the correct values for setf to return. 
(Again, in most cases there is a single store variable and thus a single value to be 
returned.) The value returned by the accessing form is, of course, affected by exe- 
cution of the storing form, but either of these forms may be evaluated any number 



Page 1016 



of times, and therefore should be free of side effects (other than the storing action 
of the storing form). 

The temporary variables and the store variables are generated names, as if by 
gensym or gentemp, so that there is never any problem of name clashes among 
them, or between them and other variables in the program. This is necessary to 
make the special forms that do more than one setf in parallel work properly. 
These are psetf, shiftf and rotatef. 

Here are some examples of setf methods for particular forms: 

• For a variable x: 





(g0001) 

(setq x g0001) 

x 

• For (car exp): 

(g0002) 

(exp) 

(g0003) 

(progn (rplaca g0002 g0003) g0003) 

(car g0002) 

• For (subseq seq s e): 

(g0004 g0005 g0006) 

(seq s e) 

(g0007) 

(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) 

g0007) 
(subseq g0004 g0005 g0006) 



define-simple-method-combination name operator &optional single-arg-is-value 
pretty-name Special Form 

Defines a new type of method combination that simply calls all the methods, pass- 
ing the values they return to the function named operator. 

It is also legal for operator to be the name of a special form. In this case, each 
subform is a call to a method. It is legal to use a lambda expression as operator. 

name is the name of the method-combination type to be defined. It takes one op- 
tional parameter, the order of methods. The order can be either :most-specific- 
first (the default) or :most-specific-last. 

When you use a new type of method combination defined by define-simple- 
method-combination, you can give the argument :most-specific-first or :most- 



Page 1017 



specific-last to override the order that this type of method combination uses by 
default. 

If single-arg-is-value is specified and not nil, and if there is exactly one method, it 
is called directly and operator is not called. For example, single-arg-is-value makes 
sense when operator is +. 

pretty-name is a string that describes how to print method names concisely. It de- 
faults to (string-downcase name). 

Most of the simple types of built-in method combination are defined with define- 
simple-method-combination. For example: 



(def i ne-si mpl e-method-combi nati on 
(def i ne-si mpl e-method-combi nati on 
(def i ne-si mpl e-method-combi nati on 
(def i ne-si mpl e-method-combi nati on 
(def i ne-si mpl e-method-combi nati on 



and and t) 
or or t) 
1 ist 1 ist) 
progn progn t) 
append append t) 



For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



define-symbol-macro name form 



Special Form 



Defines a symbol macro, name is a symbol to be defined as a symbol macro, form 
is a Lisp form to be substituted for the symbol when the symbol is evaluated. A 
symbol macro is more like an inline function than a macro: form is the form to be 
substituted for the symbol, not a form whose evaluation results in the substitute 
form. 

Example: 

(define-symbol-macro foo (+ 3 bar)) 
(setq bar 2) 
foo => 5 

A symbol defined as a symbol macro cannot be used in the context of a variable. 
You cannot use setq on it, and you cannot bind it. You can use setf on it: setf 
substitutes the replacement form, which should access something, and expands into 
the appropriate update function. 

For example, suppose you want to define some new instance variables and methods 
for a flavor. Then, you want to test the methods using existing instances of the 
flavor. For testing purposes, you might use hash tables to simulate the instance 
variables, using one hash table per instance variable with the instance as the key. 
You could then implement an instance variable x as a symbol macro: 

(defvar x-hash-table (make-hash-table)) 
(define-symbol-macro x (gethash self x-hash-table) 

To simulate setting a new value for x, you could use (setf x value), which would 
expand into (setf (gethash self x-hash-table) value) . 



Page 1018 



deflambda-macro name pattern &body body Function 

Like defmacro, but defines a lambda macro instead of a normal macro. 

name is the name of the lambda macro to be defined; it can be any function spec. 
See the section "Function Specs". The pattern can be anything made up out of sym- 
bols and conses. It is matched against the body of the lambda macro form; both 
pattern and the form are car'ed and cdr'ed identically, and whenever a non-nil 
symbol occurs in pattern, the symbol is bound to the corresponding part of the 
form. If the corresponding part of the form is nil, it goes off the end of the form. 
&optional, &rest, &key, and &body can be used to indicate where optional pat- 
tern elements are allowed. 

All of the symbols in pattern can be used as variables within body. 

body is evaluated with these bindings in effect, and its result is returned to the 
evaluator as the expansion of the macro. 

Here is an example of deflambda-macro used to define a lambda macro: 

(deflambda-macro ilisp (arglist &rest body) 
'(lambda (&optional , Sarglist) ,@body)) 

This defines a lambda macro called ilisp. After it has been defined, the following 
list is a valid Lisp function: 

(ilisp (x y z) (list x y z)) 



zhdeflambda-macro-displace name pattern &body body Special Form 

Like zhdefmacro-displace, but defines a displacing lambda macro instead of a dis- 
placing normal macro. 



deflocf access-function locate-function-or-subforms &body body Function 

Defines how locf creates a locative pointer to a cell referred to by access- function, 
similar to the way defsetf defines how setf sets a generalized-variable. See the 
macro defsetf. 

Subforms of the access-function are evaluated exactly once and in the proper left- 
to-right order. A locf of a call on access-function will also evaluate all of access- 
function's arguments; it cannot treat any of them specially. 

A deflocf function has two forms: a simple case and a slightly more complicated 
one. In the simplest case, locate-function-or-subforms is the name of a function or 
macro. In the more complicated case, locate-function-or-subforms is a lambda list of 
arguments. 

The simple form of deflocf is 

(deflocf array-leader ap-leader) 

This says that the form to create a locative pointer to array-leader is the function 
ap-leader. 



Page 1019 



If the access-function and the locate-function-or-subforms take their arguments in a 
different order or do anything special with their arguments, the more complicated 
form must be used, for example: 

(deflocf fs:pathname-property-l ist (pathname) 
'(send , pathname :property-l ist-location)) 



defmacro name pattern &body body Macro 

A general-purpose macro-defining macro. A defmacro form looks like: 

(defmacro name pattern . body) 

name is the name of the macro to be defined; it can be any function spec. See the 
section "Function Specs". Specifies the expansion of forms characterized by calling 
name with arguments as indicated in pattern. The expansion function is stored as 
the macro definition associated with name. The macro definition is evaluated in the 
context of the global environment. (To establish macros in the current lexical en- 
vironment, macrolet may be used instead of defmacro). The pattern argument 
specifies an extension to Common Lisp syntax by characterizing a structured form 
whose car is name. The chief distinction between macro lambda-lists and those 
used in function definitions is that macro lambda-lists recursively specify list-forms 
(also lambda-lists) that represent list forms actually appearing in the call. Consider 
the macro do in the following example: 

(do ((i (+ i 1)) 
(J 10 (- J 2))) 
((<= J 0) J) 
(setf (aref xglobx i) j)) 

The outer parentheses in the variable initialization and step form 

(i (+ i 1)) 

are explicitly represented in the lambda-list of the do definition. The inner set sur- 
rounding the + form is simply an argument form for the step parameter. This is 
similar to a form argument paired to a defun parameter. However, in the latter 
case the form is evaluated to produce a value for the parameter, while in the 
macro case the form represents a textual replacement for the step parameter. 

The pattern can be anything made up out of symbols and conses. It is matched 
against the body of the macro form; both pattern and the form are car'ed and 
cdr'ed identically, and whenever a non-nil symbol occurs in pattern, the symbol is 
bound to the corresponding part of the form. If the corresponding part of the form 
is nil, it goes off the end of the form. &optional, &rest, &key, and &body can be 
used to indicate where optional pattern elements are allowed. 

Of the existing limitations on this extension to the lambda-list function called de- 
structuring, most notable is that a lambda-list-form may not be used where a list- 
form appears in a defun-style lambda-list. For example, following the &optional 
lambda-list keyword. All of the symbols in pattern can be used as variables within 
body. 



Page 1020 



body is evaluated with these bindings in effect, and its result is returned to the 
evaluator as the expansion of the macro. Macro lambda-lists may also contain 
three additional lambda-list keywords: &body, &environment , and &whole. 

defmacro could have been defined in terms of destructuring-bind as follows, ex- 
cept that the following is a simplified example of defmacro showing no error- 
checking and omitting the &environment and &whole features. 

(defmacro defmacro (name pattern &body body) 
'(macro , name (form env) 

(destructuring-bind , pattern (cdr form) 
,§body))) 

The pattern in a defmacro is like the lambda-list of a normal function, defmacro 
is allowed to contain certain &-keywords. 

defmacro destructures all levels of patterns in a consistent way. The inside pat- 
terns can also contain &-keywords and there is checking of the matching of 
lengths of the pattern and the subform. See the special form destructuring-bind. 
This behavior exists for all of defmacro's parameters, except for &environment, 
&whole, and &aux. 

You must use &optional in the parameter list if you want to call the macro with 
less than its full complement of subforms. There must be an exact one-to-one cor- 
respondence between the pattern and the data unless you use &optional in the pa- 
rameter destructuring pattern. 

(defmacro nand (&rest args) '(not (and , &args))) 

(defmacro with-output-to-string 

((var &optional string &key index) &body body) 
1 (let ((with-output-to-string-internal-string 

, (or string ' (make-array 100 :type 'art-string))) 
...) 

,@body)) 
defmacro accepts these keywords: 

&optional &optional is followed by variable, (variable), (variable default), 

or (variable default present-p), exactly the same as in a func- 
tion. Note that default is still a form to be evaluated, even 
though variable is not being bound to the value of a form, vari- 
able does not have to be a symbol; it can be a pattern. In this 
case the first form is disallowed because it is syntactically am- 
biguous. The pattern must be enclosed in a singleton list. 

&rest The same as using a dotted list as the pattern, except that it 

might be easier to read and leaves a place to put &aux. 

&key Separates the positional parameters and rest parameter from 

the keyword parameters. See the section "Evaluating a Func- 
tion Form". 



Page 1021 



&body 



&whole 



&allow-other-keys In a lambda-list that accepts keyword arguments, says that 
keywords that are not specifically listed after &key are al- 
lowed. They and the corresponding values are ignored, as far 
as keyword arguments are concerned, but they do become part 
of the rest argument, if there is one. 

&aux The same in a macro as in a function, and has nothing to do 

with pattern matching. It separates the destructuring pattern 
of a macro from the auxiliary variables. Following &aux you 
can put entries of the form: 

(variable initial-value-form) 

or just variable if you want it initialized to nil or do not care 
what the initial value is. 

Identical to &rest except that it informs the editor and the 
grinder that the remaining subforms constitute a "body" rather 
than "arguments" and should be indented accordingly. The 
&body keyword should be used when the body is an implicit 
progn to signal printing routines to indent the body of macro 
calls as in an implicit progn. 

For macros defined by defmacro or macrolet only. &whole is 
followed by variable, which is bound to the entire macro-call 
form or subform. variable is the value that the macro-expander 
function receives as its first argument. &whole is allowed only 
in the top-level pattern, not in inside patterns. 

(defmacro abc (&whole form argl arg2) 
(if (and arg2 (not argl)) 
1 (cde , (cdr form) , arg2) 
1 (efg ,arg1 ,arg2))) 

For macros defined by defmacro or macrolet only. 
&environment is followed by variable, which is bound to an 
object representing the lexical environment where the macro 
call is to be interpreted. This environment might not be the 
complete lexical environment. It should be used only with the 
macroexpand function for any local macro definitions that the 
macrolet construct might have established within that lexical 
environment. &environment is allowed only in the top-level 
pattern, not in inside patterns. See the section "Lexical Envi- 
ronment Objects and Arguments". See the macro defmacro. 

&list-of is not supported as a result of making defmacro Common-Lisp compatible. 
Use zhloop or mapcar instead of &list-of. 

See the special form destructuring-bind. 



&environment 



zhdefmacro-displace name pattern &body body 



Macro 



Page 1022 



Like defmacro, except that it defines a displacing macro, using the zhdisplace 
function. 



defmacro-in-flavor (function-name flavor-name) arglist body...) Function 

Defines a macro inside a flavor. Functions inside the flavor can use this macro, 
but the macro is not accessible in the global environment. 

See the section "Defining Functions Internal to Flavors". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 

defmethod Special Form 

A method is the code that performs a generic function on an instance of a particu- 
lar flavor. It is defined by a form such as: 

(defmethod (generic-function flavor options...) (argl arg2...) 
body...) 

The method defined by such a form performs the generic function named by gener- 
ic-function, when that generic function is applied to an instance of the given 
flavor. (The name of the generic function should not be a keyword, unless you 
want to define a message to be used with the old send syntax.) You can include a 
documentation string and declare forms after the argument list and before the 
body. 

A generic function is called as follows: 

(generic-function g-f-argl g-f-arg2...) 

Usually the flavor of g-f-argl determines which method is called to perform the 
function. When the appropriate method is called, self is bound to the object itself 
(which was the first argument to the generic function). The arguments of the 
method are bound to any additional arguments given to the generic function. A 
method's argument list has the same syntax as in defun. 

The body of a defmethod form behaves like the body of a defun, except that the 
lexical environment enables you to access instance variables by their names, and 
the instance by self. 

For example, we can define a method for the generic function list-position that 
works on the flavor wink, list-position prints the representation of the object and 
returns a list of its x and y position. 

(defmethod (list-position wink) () ; no args other than object 
"Returns a list of x and y position." 

(print self) ; self is bound to the instance 

(list x y)) ; instance vars are accessible 

The generic function list-position is now defined, with a method that implements 
it on instances of wink. We can use it as follows: 



Page 1023 



(list-position my-wink) 
— > #<WINK 61311676> 
=> (4 0) 

If no options are supplied, you are defining a primary method. Any options given 
are interpreted by the type of method combination declared with the rmethod- 
combination argument to either defgeneric or defflavor. See the section "Defin- 
ing Special-Purpose Methods". For example, rbefore or rafter can be supplied to 
indicate that this is a before-daemon or an after-daemon. For more information: 
See the section "Defining Before- and After-Daemons". 

If the generic function has not already been defined by defgeneric, defmethod 
sets up a generic function with no special options. If you call defgeneric for the 
name generic-function later, the generic function is updated to include any new op- 
tions specified in the defgeneric form. 

Several other sections of the documentation contain information related to 
defmethod: See the section "defmethod Declarations". See the section "Writing 
Methods for make-instance". See the section "Function Specs for Flavor 
Functions". See the section "Setter and Locator Function Specs". See the section 
"Implicit Blocks for Methods". See the section "Variant Syntax of defmethod". See 
the section "Defining Methods to Be Called by Message-Passing". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



closrdefmethod function-specifier (method-qualifier}* specialized-lambda-list &body 
body Macro 

Defines a method for a generic function and returns the method object. 

If the generic function has not been defined, then closrdefmethod defines the 
generic function with the default argument precedence order, method-combination 
type, method class, and generic function class. The lambda-list of the generic func- 
tion is congruent with that of the method. If the method's lambda-list has keyword 
parameters, then the generic function's lambda-list will specify &key, but not name 
any keyword parameters. 

If the generic function has a method with the same parameter specializers and 
qualifiers, then that method is redefined. 

CLOS requires that the lambda-lists of a generic function and all its methods must 
be congruent. If a method violates the congruency pattern of its generic function, 
an error is signaled. 

The arguments to closrdefmethod are: 

function-specifier The name of the generic function, which is either a symbol or 
a list of the form (future-common-lisp rsetf symbol). An error 
is signaled if the function-specifier indicates an ordinary Lisp 
function, a macro, or a special form. In other words, you can- 
not use closrdefmethod to redefine an ordinary function, 
macro, or special form to be a generic function. 



Page 1024 



method-qualifier The method's qualifier or qualifiers state the role of this 
method in performing the work of the generic function. They 
are non-nil atoms that are used by the method-combination 
type. The closrstandard method-combination type supports the 
qualifiers raround, rbefore, and rafter, as well as unqualified 
methods. 

specialized-lambda-list 

A specialized lambda-list is an extension of an ordinary lamb- 
da-list that can specialize any of its required parameters. The 
specialized lambda-list states the set of arguments for which 
this method will be applicable, as described below. 

A specialized parameter is a list in one of the following for- 
mats: 

{variable-name (eql form)) 
{variable-name class-name) 

An unspecialized parameter appears as a variable name; this is 
the same as if the parameter were specialized on the class 
named t. 

When a generic function is called with a set of arguments, 
CLOS determines which methods are applicable, based on the 
required arguments and the lambda-lists of the methods for 
the generic function. For a method to be applicable, each re- 
quired argument must satisfy the corresponding parameter in 
the method's lambda-list. 

When a parameter is specialized with (eql form), the form is 

evaluated once, at the time that the closrdefmethod form is 

evaluated. The form is not evaluated each time the generic 
function is called. 

If the value of form is object, then the argument satisfies the 
specialized parameter if the following form returns true: 

(eql argument 'object) 

When a parameter is specialized with a class name, the argu- 
ment satisfies the specialized parameter if the following form 
returns true: 

(typep argument 'class-name) 

When a parameter is unspecialized (the variable-name appears 
as a lone symbol which is not enclosed within a list), any argu- 
ment satisfies the parameter. 

Note that if you are defining a future-common-lisp rsetf 
method, then the order of parameters in the specialized lamb- 
da-list is as shown: 

{new-value args...) 



Page 1025 



As in other methods, in future-common-lisp :setf methods, any 
of the required parameters may be specialized. 

declarations, documentation 

The closrdefmethod syntax allows for declarations and/or docu- 
mentation strings to appear after the specialized-lambda-list 
and before the body. 

body The body contains forms that do the work of the generic func- 

tion. When methods are defined to work together (via different 
roles), each method implements some portion of the work of 
the generic function. Often the body needs to access slots of 
instances that are given as arguments to the generic function. 
There are several ways to access slots: using reader or writer 
generic functions, using closrwith-accessors, or using 
clos:with-slots. 

The body has an implicit block around it. If the generic 
function's name is a symbol, the block has the same name as 
the generic function. If the generic function's name is (future- 
common-lisp :setf symbol), the block has the name symbol. 

Examples 

The following examples show the applicability of methods: 

;;; Applicable when first arg is a ship, second arg is a plane 
(cl os :def method collide ((s ship) (p plane) location) 
body) 

;;; Applicable when first arg is a plane, second arg is a plane 
(cl os :def method collide :after ((p plane) (p plane) location) 
body) 

;;; Applicable when second arg is a plane 
(clos:defmethod collide (vehicle (p plane) location) 
body) 

;;; Applicable when first arg is eql to the value of xEnterprisex 
(clos:defmethod collide ((ent (eql xEnterprisex)) vehicle location) 
body) 

The raccessor and rwriter options to closrdefclass enable you to define future- 
common-lisp :setf methods for slots automatically, but you can also do it by using 
closrdefmethod, as shown in this example: 

(clos:defclass boat () (speed location)) 

(clos:defmethod (future-common-1 isp:setf 'speed) (new-value (b boat)) 
(setf (slot-value b) new-value)) 



Page 1026 



defpackage name options... Special Form 

Defines a package named name; the name must be a symbol so that the source file 
name of the package can be recorded and the editor can correctly sectionize the 
definition. If no package by that name already exists, a new package is created ac- 
cording to the specified options. If a package by that name already exists, its char- 
acteristics are altered according to the options specified. If any characteristic can- 
not be altered, an error is signalled. If the existing package was defined by a dif- 
ferent file, you are queried before it is changed, as with any other type of defini- 
tion. 

Each option is a keyword or a list of a keyword and arguments. A keyword by it- 
self is equivalent to a list of that keyword and one argument, t; this syntax really 
only makes sense for the :external-only and :hash-inherited-symbols keywords. 

Wherever an argument is said to be a name or a package, it can be either a sym- 
bol or a string. Usually symbols are preferred, because the reader standardizes 
their alphabetic case and because readability is increased by not cluttering up the 
defpackage form with string quote (") characters. 

None of the arguments are evaluated. The keywords arguments, most of which are 
identical to make-package's, are: 

(rnicknames name name...) for defpackage 
rnicknames '(name name...) for make-package 

The package is given these nicknames, in addition to its primary name. 

(:prefix-name name) for defpackage 
:prefix-name name for make-package 

This name is used when printing a qualified name for a symbol in this 
package. You should make the specified name one of the nicknames of the 
package or its primary name. If you do not specify :prefix-name, it defaults 
to the shortest of the package's names (the primary name plus the nick- 
names). 

(ruse package package...) 

External symbols and relative name mappings of the specified packages are 
inherited. If this option is not specified, it defaults to (ruse CL) ((ruse 
global) in Zetalisp). To inherit nothing, specify (ruse). 

(rshadow name name...) for defpackage 
rshadow '(name name...) for make-package 

Symbols with the specified names are created in this package and declared 
to be shadowing. 

(rexport name name...) for defpackage 
rexport '(name name...) for make-package 

Symbols with the specified names are created in this package, or inherited 
from the packages it uses, and declared to be external. 

(rimport symbol symbol...) for defpackage 



Page 1027 



rimport '(name name...) for make-package 

The specified symbols are imported into the package. Note that unlike 
rexport, rimport requires symbols, not names; it matters in which package 
this argument is read. 

(rshadowing-import symbol symbol...) for defpackage 
rshadowing-import '(symbol symbol...) for make-package 

The same as rimport but no name conflicts are possible; the symbols are 
declared to be shadowing. 

(rimport-from package name name...) for defpackage 
rimport-from '(package name name...) for make-package 

The specified symbols are imported into the package. The symbols to be im- 
ported are obtained by looking up each name in package. 
(defpackage only) This option exists primarily for system bootstrapping, 
since the same thing can normally be done by rimport. The difference be- 
tween rimport and rimport-from can be visible if the file containing a 
defpackage is compiled; when rimport is used the symbols are looked up at 
compile time, but when rimport-from is used the symbols are looked up at 
load time. If the package structure has been changed between the time the 
file was compiled and the time it is loaded, there might be a difference. 

(rrelative-names (name package) (name package)...) - defpackage 

rrelative-names '((name package) ...) - make-package 

Declares relative names by which this package can refer to other packages. 
The package being created cannot be one of the packages, since it has not 
been created yet. For example, to be able to refer to symbols in the 
common-lisp package print with the prefix lispr instead of clr when they 
need a package prefix (for instance, when they are shadowed), you would 
use rrelative-names like this: 



(defpackage my-package ( 

( 
( 



use cl) 

shadow error) 

relative-names (lisp common-lisp))) 



(let ((xpackagex (find-package 'my-package))) 
(print (list 'my-package: :error 'cl:error))) 

(rrelative-names-for-me (package name) ...) for defpackage 
rrelative-names-for-me '((package name) ...) for make-package 

Declares relative names by which other packages can refer to this package. 
(defpackage only) It is valid to use the name of the package being created 
as a package here; this is useful when a package has a relative name for 
itself. 

(rsize number) for defpackage 
rsize number for make-package 

The number of symbols expected in the package. This controls the initial 
size of the package's hash table. You can make the rsize specification an 
underestimate; the hash table is expanded as necessary. 



Page 1028 



(:hash-inherited-symbols boolean) for defpackage 
:hash-inherited-symbols boolean for make-package 

If true, inherited symbols are entered into the package's hash table to 
speed up symbol lookup. If false (the default), looking up a symbol in this 
package searches the hash table of each package it uses. 

(:external-only boolean) for defpackage 
:external-only boolean for make-package 

If true, all symbols in this package are external and the package is locked. 
This feature is only used to simulate the old package system that was used 
before Release 5.0. See the section "External-only Packages and Locking". 

(rinclude package package...) for defpackage 
rinclude '(package package...) for make-package 

Any package that uses this package also uses the specified packages. Note 
that if the rinclude list is changed, the change is not propagated to users 
of this package. This feature is used only to simulate the old package sys- 
tem that was used before Release 5.0. 

(:new-symbol-function function) for defpackage 
:new-symbol-function function for make-package 

function is called when a new symbol is to be made present in the package. 
The default is si:pkg-new-symbol unless :external-only is specified. Do not 
specify this option unless you understand the internal details of the package 
system. 

(:colon-mode mode) for defpackage 
:colon-mode mode for make-package 

If mode is rexternal, qualified names mentioning this package behave dif- 
ferently depending on whether ":" or "::" is used, as in Common Lisp. ":" 
names access only external symbols. If mode is rinternal, ":" names access 
all symbols, rexternal is the default. See the section "Specifying Internal 
and External Symbols in Packages". 

(:prefix-intern-f unction function) for defpackage 
rprefix-intern-function function for make-package 

The function to call to convert a qualified name referencing this package 
with ":" (rather than "::") to a symbol. The default is intern unless (rcolon- 
mode rexternal) is specified. Do not specify this option unless you under- 
stand the internal details of the package system. 



defparameter variable initial-value &optional documentation Special Form 

The same as defvar, except that variable is always set to initial-value regardless of 
whether variable is already bound. The rationale for this is that defvar declares a 
global variable, whose value is initialized to something but is then changed by the 
functions that use it to maintain some state. On the other hand, defparameter de- 



Page 1029 



clares a constant, whose value is never changed by the normal operation of the 
program, only by changes to the program, defparameter always sets the variable 
to the specified value so that if, while developing or debugging the program, you 
change your mind about what the constant value should be, and you then evaluate 
the defparameter form again, the variable gets the new value. It is not the intent 
of defparameter to declare that the value of variable never changes; for example, 
defparameter is not a license to the compiler to build assumptions about the val- 
ue of variable into programs being compiled. See defconstant for that. 

For example: 

(defparameter xalarms-1 imitx 10 

"The number of alarms allowed to sound before 
a special message is printed.") 

See the section "Special Forms for Defining Special Variables". 



defprop sym value indicator Special Form 

Gives sym's property list an indicator-property corresponding to value. After this is 
done, (get sym indicator) returns value. See the section "Property Lists". 

defprop is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions That Operate on Property 
Lists". 



defselect fspec &body methods Special Form 

Defines a function that is a select-method. This function contains a table of sub- 
functions; when it is called, the first argument, a symbol on the keyword package 
called the message name, is looked up in the table to determine which subfunction 
to call. Each subfunction can take a different number of arguments, and have a 
different pattern of &optional and &rest arguments, defselect is useful for a vari- 
ety of "dispatching" jobs. By analogy with the more general message passing facili- 
ties in flavors, the subfunctions are sometimes called methods and the first argu- 
ment is sometimes called a message. 

The special form looks like: 

(def sel ect (function-spec default-handler no-which-operations) 
(message-name (args. . . ) 

body...) 
(message-name (args. . . ) 

body...) 

function-spec is the name of the function to be defined, default-handler is optional; 
it must be a symbol and is a function that gets called if the select-method is 
called with an unknown message. If default-handler is unsupplied or nil, then an 
error occurs if an unknown message is sent. If no-which-operations is non-nil, the 
rwhich-operations method that would normally be supplied automatically is sup- 



Page 1030 



pressed. The rwhich-operations method takes no arguments and returns a list of 
all the message names in the defselect. 

The :operation-handled-p and :send-if -handles methods are automatically sup- 
plied. See the message :operation-handled-p. See the message :send-if-handles. 

If function-spec is a symbol, and default-handler and no-which-operations are not 
supplied, then the first subform of the defselect can be just function-spec by itself, 
not enclosed in a list. 

The remaining subforms in a defselect define methods, message-name is the mes- 
sage name, or a list of several message names if several messages are to be han- 
dled by the same subfunction. args is a lambda-list; it should not include the first 
argument, which is the message name, body is the body of the function. 

A method subform can instead look like: 

(message-name . symbol) 

In this case, symbol is the name of a function that is called when the message- 
name message is received. It is called with the same arguments as the select- 
method, including the message symbol itself. 



defsetf access-function storing-function-or-args &optional store-variables &body body 

Macro 

Defines how to setf a generalized-variable reference of the form (access-function . . 
.). The value of a generalized-variable reference can always be obtained by evaluat- 
ing it, so access-function should be the name of a function or macro that evaluates 
its arguments, behaving like a function. 

The user of defsetf provides a description of how to store into the generalized- 
variable reference and return the value that was stored (because setf is defined to 
return this value). Subforms of the reference are evaluated exactly once and in the 
proper left-to-right order. A setf of a call on access-function will also evaluate all 
of access- function' s arguments; it cannot treat any of them specially. This means 
that defsetf cannot be used to describe how to store into a generalized variable 
that is a byte, such as (ldb field reference). To handle situations that do not fit 
the restrictions of defsetf, use define-setf-method, which gives the user additional 
control at the cost of additional complexity. 

A defsetf function can take two forms, simple and complex. In the simple case, 
storing-function-or-args is the name of a function or macro. In the complex case, 
storing-function-or-args is a lambda list of arguments. 

The simple form of defsetf is 

(defsetf access-function storing-function-or-args) 

storing-function-or-args names a function or macro that takes one more argument 
than access-function takes. When setf is given a place that is a call on access- 
function, it expands into a call on storing-function-or-args that is given all the ar- 



Page 1031 



guments to access-function and also, as its last argument, the new value (which 
must be returned by storing-function-or-args as its value). 

For example, the effect of 

(defsetf symbol -value set) 

is built into the Common Lisp system. This causes the form (setf (symbol -value 
foo) fu) to expand into (set foo fu). Note that 

(defsetf car rplaca) 

would be incorrect because rplaca does not return its last argument. 
The complex form of defsetf looks like 

(defsetf access-function storing-function-or-args 
(store-variables) . body) 

and resembles defmacro. The body must compute the expansion of a setf of a call 
on access-function, storing-function-or-args is a lambda list that describes the argu- 
ments of access-function and may include &optional, &rest, and &key markers. 
Optional arguments can have defaults and "supplied-p" flags, store-variables de- 
scribes the value to be stored into the generalized-variable reference. 

The body forms can be written as if the variables in storing-function-or-args were 
bound to subforms of the call on access-function and the store-variables were bound 
to the second subform of setf. However, this is not actually the case. During the 
evaluation of the body forms, these variables are bound to names of temporary 
variables, generated as if by gensym or gentemp, that will be bound by the expan- 
sion of setf to the values of those subforms. This binding permits the body forms 
to be written without regard for order of evaluation, defsetf arranges for the tem- 
porary variables to be optimized out of the final results in cases where that is 
possible. In other words, an attempt is made by defsetf to generate the best code 
possible. 

Note that the code generated by the body forms must include provision for return- 
ing the correct value (the value of store-variables). This is handled by the body 
forms rather than by defsetf because in many cases this value can be returned at 
no extra cost, by calling a function that simultaneously stores into the generalized 
variable and returns the correct value. 

Here is an example of the complex form of defsetf. 



Page 1032 



(defsetf subseq (sequence start &optional end) (new-sequence) 
1 (progn (replace , sequence , new-sequence 

:start1 , start :end1 , end) 
, new-sequence)) 

For even more complex operations on setf: See the macro define-setf-method. 

defstruct options &body items Macro 

Defines a record-structure data type. A call to defstruct looks like: 

(defstruct (name option-1 option-2 ...) 
si ot-descri pti on-1 
si ot-descri pti on-2 
...) 

name must be a symbol; it is the name of the structure. It is given a sirdefstruct- 
description property that describes the attributes and elements of the structure; 
this is intended to be used by programs that examine other Lisp programs and 
that want to display the contents of structures in a helpful way. name is used for 
other things; for more information, see the section "Named Structures". 

Because evaluation of a defstruct form causes many functions and macros to be 
defined, you must take care not to define the same name with two different 
defstruct forms. A name can only have one function definition at a time. If a 
name is redefined, the later definition is the one that takes effect, destroying the 
earlier definition. (This is the same as the requirement that each defun that is in- 
tended to define a distinct function must have a distinct name.) 

Each option can be either a symbol, which should be one of the recognized option 
names, or a list containing an option name followed by the arguments to the op- 
tion. Some options have arguments that default; others require that arguments be 
given explicitly. For more information about options, see the section "Options for 
defstruct". 

Each slot-description can be in any of three forms: 



slot-name 



(slot-name defaul t-init) 
((slot-name-1 byte-spec-1 defaul t-init-1) 
(slot-name-2 byte-spec-2 defaul t-init-2) 
...) 

Each slot-description allocates one element of the physical structure, even though 
several slots may be in one form, as in form 3 above. 

Each slot-name must always be a symbol; an accessor function is defined for each 
slot. 

In the example above, form 1 simply defines a slot with the given name slot-name. 
An accessor function is defined with the name slot-name. The :conc-name option 
allows you to specify a prefix and have it concatenated onto the front of all the 



Page 1033 



slot names to make the names of the accessor functions. Form 2 is similar, but al- 
lows a default initialization for the slot. Form 3 lets you pack several slots into a 
single element of the physical underlying structure, using the byte field feature of 
defstruct. 

For a table of related items: See the section "Functions Related to defstruct Struc- 
tures". 



future-common-lisp: defstruct name-and-options &body slot-descriptions Macro 

Defines a record-structure data type, and a corresponding class of the same name. 
You can define methods that specialize on structure classes. 

The syntax and semantics of future-common-lisp: defstruct adhere to the draft 
ANSI Common Lisp specification. 



zhdefstruct Macro 

Defines a record-structure data type. Use the Common lisp macro defstruct. 
defstruct accepts all standard Common Lisp options, and accepts several additional 
options, zhdefstruct is supported only for compatibility with pre-Genera 7.0 re- 
leases. See the section "Differences Between defstruct and zhdefstruct". 

The basic syntax of zhdefstruct is the same as defstruct: See the macro 
defstruct. 

For information on the options that can be given to zhdefstruct as well as 
defstruct: See the section "Options for defstruct". 

The :export option is accepted by zhdefstruct but not by defstruct. Stylistically, it 
is preferable to export any external interfaces in the package declarations instead 
of scattering :export options throughout a program's source files. 

:export 

Exports the specified symbols from the package in which the 
structure is defined. This option accepts as arguments slot 
names and the following options: :alterant, :accessors, 
constructor, :copier, :predicate, :size-macro, and :size- 
symbol. 

The following example shows the use of :export. 



Page 1034 



(zl :defstruct (2d-moving-object 
(:type : array) 
: cone-name 

;; export all accessors and the 
;; make-2d-moving-object constructor 
(: export : accessors : constructor)) 

mass 

x-pos 

y-pos 

x-velocity 

y-velocity) 

See the section "Importing and Exporting Symbols". 



defstruct-define-type type &body options Macro 

Teaches defstruct and zhdefstruct about new types that it can use to implement 
structures. 

The body of this function is shown in the following example: 

(defstruct-define-type type 
option-1 
option-2 

...) 

where each option is either the symbolic name of an option or a list of the form 
{option-name . rest). See the section "Options to defstruct-define-type". 

Different options interpret rest in different ways. The symbol type is given an 
si:defstruct-type-description property of a structure that describes the type com- 
pletely. 

For a table of related items: See the section "Functions Related to defstruct Struc- 
tures". 



defsubst function lambda-list &body body Special Form 

Defines inline functions. It is used just like defun and does almost the same thing. 

(defsubst name lambda-list . body) 

defsubst defines a function that executes identically to the one that a similar call 
to defun would define. The difference comes when a function that calls this one is 
compiled. Then, the call is open-coded by substituting the inline function's defini- 
tion into the code being compiled. Such a function is called an inline function. For 
example, if we define: 

(defsubst square (x) (x x x)) 

(defun foo (a b) (square (+ a b))) 

then if foo is used interpreted, square works just as if it had been defined by 
defun. If foo is compiled, however, the squaring is substituted into it and it com- 



Page 1035 



piles just like: 

(defun foo (a b) (* (+ a b) (+ a b))) 

square could have been defined as: 

(defun square (x) (* x x)) 
(proclaim '(inline square)) 
(defun foo . . . ) 

See the declaration inline. 

A similar square could be defined as a macro, with: 

(defmacro square (x) ' (* ,x ,x)) 

When the compiler open-codes an inline function, it binds the argument variables 
to the argument values with let, so they get evaluated only once and in the right 
order. Then, when possible, the compiler optimizes out the variables. In general, 
anything that is implemented as an inline function can be reimplemented as a 
macro, just by changing the defsubst to a defmacro and putting in the appropri- 
ate backquote and commas, except that this does not get the simultaneous guaran- 
tee of argument evaluation order and generation of optimal code with no unneces- 
sary temporary variables. The disadvantage of macros is that they are not func- 
tions, and so cannot be applied to arguments. Their advantage is that they can do 
much more powerful things than inline functions can. This is also a disadvantage 
since macros provide more ways to get into trouble. If something can be imple- 
mented either as a macro or as an inline function, it is generally better to make it 
an inline function. 

As with defun, name can be any function spec, but you get the "subst" effect only 
when name is a symbol. 

The difference between an inline function and one not declared inline is the way 
the calls to them are handled by the compiler. A call to a normal function is com- 
piled as a closed subroutine; the compiler generates code to compute the values of 
the arguments and then apply the function to those values. A call to an inline 
function is compiled as an open subroutine; the compiler incorporates the body 
forms of the inline function into the function being compiled, substituting the ar- 
gument forms for references to the variables in the function's lambda-list. 

defsubst-in-flavor (function-name flavor-name) arglist &body body Function 

Defines a function inside a flavor to be inline-coded in its callers. There is no 
analogous form for methods, since the caller cannot know at compile-time which 
method is going to be selected by the generic function mechanism. 

See the section "Defining Functions Internal to Flavors". 



Page 1036 



For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



defun Special Form 

Defines a function that is part of a program. A defun form looks like: 

(defun name lambda-list 
body . . . ) 

name is the function spec you wish to define as a function. The lambda-list is a 
list of the names to give to the arguments of the function. Actually, it is a little 
more general than that; it can contain lambda-list keywords such as &optional and 
&rest. (Keywords are explained elsewhere. See the section "Evaluating a Function 
Form". See the section "Lambda-List Keywords".) Additional syntactic features of 
defun are explained elsewhere. See the section "Function-Defining Special Forms". 

In Genera, defun creates a list which looks like: 

(si :digested-lambda. . .) 

and puts it in the function cell of name, name is now defined as a function and 
can be called by other forms. 

Examples: 

(defun addone (x) 
(1+ x)) 

(defun add-a-number (x &optional (inc 1)) 
(+ x inc)) 

(defun average (&rest numbers &aux (total 0)) 
(loop for n in numbers 

do (setq total (+ total n))) 
(// total (length numbers))) 

addone is a function that expects a number as an argument, and returns a num- 
ber one larger, add-a-number takes one required argument and one optional argu- 
ment, average takes any number of additional arguments that are given to the 
function as a list named numbers. 

If you are using Genera, a declaration (a list starting with declare) can appear as 
the first element of the body. It is equivalent to a zhlocal-declare surrounding the 
entire defun form. For example: 

(defun foo (x) 

(declare (special x)) 

(bar)) ;bar uses x free. 

is equivalent to and preferable to: 

(zl : local -declare ((special x)) 
(defun foo (x) 
(bar))) 



Page 1037 



(It is preferable because the editor expects the open parenthesis of a top-level 
function definition to be the first character on a line, which isn't possible in the 
second form without incorrect indentation.) 

A documentation string can also appear as the first element of the body (following 
the declaration, if there is one). (It shouldn't be the only thing in the body; other- 
wise it is the value returned by the function and so is not interpreted as docu- 
mentation. A string as an element of a body other than the last element is only 
evaluated for side effect, and since evaluation of strings has no side effects, they 
are not useful in this position to do any computation, so they are interpreted as 
documentation.) This documentation string becomes part of the function's debug- 
ging info and can be obtained with the function documentation. The first line of 
the string should be a complete sentence that makes sense read by itself, since 
there are two editor commands to get at the documentation, one of which is "brief" 
and prints only the first line. Example: 

(defun my-append (&rest lists) 

"Like append but copies all the lists. 
This is like the Lisp function append, except that 
append copies all lists except the last, whereas 
this function copies all of its arguments 
including the last one." 

...) 

If you are using CLOE, consider this example: 

(defun new-function (argl arg2 arg3) 

"returns substring of argl from position arg2+1 to position arg3-1 . " 

(declare (string argl)) 

(subseq argl (+ arg2 1) (- arg3 1))) 



defun-in-flavor (function-name flavor-name) arglist &body body Function 

Defines an internal function of a flavor. The syntax of defun-in-flavor is similar 
to the syntax of defmethod; the difference is the way the function is called and 
the scoping of function-name. 

See the section "Defining Functions Internal to Flavors". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



zhdefunp Macro 

Usually when a function uses prog, the prog form is the entire body of the func- 
tion; the definition of such a function looks like (defun name arglist (prog varlist 
...)). Although the use of prog is generally discouraged, prog fans might want to 
use this special form. For convenience, the zhdefunp macro can be used to pro- 
duce such definitions. A zhdefunp form such as: 



Page 1038 



(zl :defunp fctn (args) 
forml 
form2 

formn) 
expands into: 

(zl :defun fctn (args) 
(prog () 
forml 
form2 

(return formn))) 

You can think of zhdefunp as being like defun except that you can return out of 
the middle of the function's body. 



defvar name &optional initial-value documentation-or-first-key &key .-documentation 
.■localize Special Form 

Declares name special and records its location for the sake of the editor so that 
you can ask to see where the variable is defined. This is the recommended way to 
declare the use of a global variable in a program. If a second subform is supplied, 

(defvar name initial-value) 

name is initialized to the result of evaluating the form initial-value unless it al- 
ready has a value, in which case it keeps that value, initial-value is not evaluated 
unless it is used; this is useful if it does something expensive like creating a large 
data structure. See the special form sysrdefvar-resettable. See the special form 
sysrdefvar-standard. 

defvar should be used only at top level, never in function definitions, and only for 
global variables (those used by more than one function), (defvar foo 'bar) is 
roughly equivalent to: 

(declare (special foo)) 

(if (not (boundp 'foo)) 

(setq foo 'bar)) 

(defvar variable initial-value "documentation string") 

allows you to include a documentation string that describes what the variable is 
for or how it is to be used. Using such a documentation string is even better than 
commenting the use of the variable, because the documentation string is accessible 
to system programs that can show the documentation to you while you are using 
the machine. 

(defvar variable initial-value : documentation "string") 

is an alternate syntax for defvar. The rlocalize keyword is used for optimizing 
memory usage at the time of Symbolics distribution world building and is reserved 
for Symbolics use only. 



Page 1039 



If defvar is used in a patch file or is a single form (not a region) evaluated with 
the editor's compile/evaluate from buffer commands, if there is an initial-value the 
variable is always set to it regardless of whether it is already bound. See the sec- 
tion "Patch Facility". See the section "Special Forms for Defining Special 
Variables". 



sysrdefvar-resettable name initial-value &optional warm-boot-value documentation 

Special Form 

Like defvar, except that it also maintains a warm-boot value. During a warm-boot, 
the system sets the variable to its warm-boot value. You can use this function to 
assure that a variable is at a pre-determined state even after warm booting. See 
the section "Warm Booting". 



sysrdefvar-standard name initial-value &optional ignore standard-value validation- 
predicate documentation 

Special Form 

Like sysrdefvar-resettable, except that it also defines a standard value that the 
variable should be bound to in command and breakpoint loops. For example, the 
standard values of zhbase and zhibase are 10. The validation-predicate is used to 
ensure that the value of the variable is valid when it is bound in command loops. 

For example, zhbase is defined like this: 

(sys:defvar-standard zl:base 10. 10. 10. val i date-base) 
(defun val i date-base (b) 

(and (fixnump b) (< 1 b 37.))) 

See the section "Standard Variables". 



defwhopper Special Form 

The following form defines a whopper for a given generic-function when applied to 
the specified flavor: 

(defwhopper (generic-function flavor) (argl arg2..) 
body) 

The arguments should be the same as the arguments for any method performing 
the generic function. 

When a generic function is called on an object of some flavor, and a whopper is 
defined for that function, the arguments are passed to the whopper, and the code 
of the whopper is executed. 

Most whoppers run the methods for the generic function. To make this happen, 
the body of the whopper calls one of the following two functions: continue- 
whopper or lexpr-continue-whopper. At that point, the before daemons, primary 
methods, and after daemons are executed. Both continue-whopper and lexpr- 
continue-whopper return the values returned by the combined method, so the rest 
of the body of the whopper can use those values. 



Page 1040 



If the whopper does not use continue-whopper or lexpr-continue-whopper, the 
methods themselves are never executed, and the result of the whopper is returned 
as the result of calling the generic function. 

Whoppers return their own values. If a generic function is called for value rather 
than effect, the whopper itself takes responsibility for getting the value back to 
the caller. 

For more information on whoppers, including examples: See the section "Wrappers 
and Whoppers". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



defwhopper-subst (flavor generic-function) lambda-list &body body Macro 

Defines a wrapper for the generic-function when applied to the given flavor by com- 
bining the use of defwhopper with the efficiency of defwrapper. 

The following example shows the use of defwhopper-subst. 

(defwhopper-subst (xns add-checksum-to-packet) 
(checksum &optional (bias 0)) 
(when (= checksum #o1 77777) 

(setq checksum 0)) 
(continue-whopper checksum bias)) 

The body is expanded in-line in the combined method, providing improved time ef- 
ficiency but decreased space efficiency, unless the body is small. 

See the section "Wrappers and Whoppers". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



defwrapper Macro 

Offers an alternative to the daemon system of method combination, for cases in 
which rbefore and rafter daemons are not powerful enough. 

defwrapper defines a macro that expands into code that is wrapped around the in- 
vocation of the methods, defwrapper is used in forms such as: 

(defwrapper (generic-function flavor) ((argl arg2) form) 
body . . .) 

The wrapper created by this form is wrapped around the method that performs 
generic-function for the given flavor, body is the code of the wrapper; it is analo- 
gous to the body of a defmacro. During the evaluation of body, the variable form 
is bound to a form that invokes the enclosed method. The result returned by body 
should be a replacement form that contains form as a subform. During the evalua- 
tion of this replacement form, the variables argl, arg2, and so on are bound to the 
arguments given to the generic function when it is called. As with methods, self is 
implied as the first argument. 



Page 1041 



The symbol ignore can be used in place of the list (argl arg2) if the arguments to 
the generic function do not matter. This usage is common. 

For more information on wrappers, including examples: See the section "Wrappers 
and Whoppers". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



zlrdel pred item list &optional (ntimes -I) Function 

Returns the list with all occurrences of item removed, pred is used to match ele- 
ments of the list against item. The argument list is actually modified (rplacded) 
when instances of item are spliced out. zhdel should be used for value, not for ef- 
fect. 

For a table of related items: See the section "Functions for Modifying Lists". 



delete item sequence &key (:test #'eql) :test-not (:key #'identityj :from-end (.start 0) 
send :count Function 

Removes a sequence of those items in the subsequence of sequence delimited by 
rstart and rend which satisfy the predicate specified by the rtest keyword argu- 
ment. This is a destructive operation. The argument sequence can be destroyed and 
used to construct the result; however, the returned form may or may not be eq to 
sequence. The elements that are not deleted occur in the same order in the result 
that they did in the argument. 

For example: 

(setq nums '(1 2 3)) => (1 2 3) 
(delete 1 nums) => (2 3) 
nums => (1 2 3) 

However, 

nums => (1 2 3) 

(delete 2 nums) => (1 3) 

nums => (1 3) 

item is matched against the elements specified by the test keyword. The item can 
be any Symbolics Common Lisp object. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

rtest specifies the test to be performed. An element of sequence satisfies the test if 
(funcall testfun item (keyfn x)) is true. Where testfun is the test function specified 
by rtest, keyfn is the function specified by rkey and x is an element of the se- 
quence. The default test is eql. 

For example: 

(delete 4 ' (6 1 6 4) :test #'>) => (6 6 4) 



Page 1042 



:test-not is similar to :test, except that the sense of the test is inverted. An ele- 
ment of sequence satisfies the test if (funcall testfun item (keyfn x)) is false. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

Example: 

(delete '((0 1) (0 1) (1 0)) :key tf'second) => ((0 1) (0 1)) 
(delete #(1 2 1) :key ft' (lambda (x) (- x 1))) => #(2) 

If the value of the :from-end argument is non-nil, it only affects the result when 
the rcount argument is specified. In that case only the rightmost rcount elements 
that satisfy the predicate are deleted. 

For example: 

(delete 4 '(4 2 4 1) : count 1 ) => (2 4 1) 

(delete 4 #(4 2 4 1) : count 1 :from-end t) => #(4 2 1) 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(delete 'a #(a b c a)) => #(B C) 

(delete 4 ' (4 4 1)) => (1) 

(delete 4 ' (4 1 4) : start 1 :end 2) => (4 1 4) 

(delete 4 ' (4 1 4) : start :end 3) => (1) 

The rcount argument, if supplied, limits the number of elements deleted. If more 
than rcount elements of sequence satisfy the predicate, then only the leftmost 
rcount of those elements are deleted. A negative rcount argument is equivalent to 
a rcount of 0. 

For example: 

(delete 4 '(4 2 4 1) : count 1 ) => (2 4 1) 

delete is the destructive version of remove. 

For a table of related items: See the section "Functions for Modifying Lists". 

For a table of related items: See the section "Sequence Modification". 

r delete Message 



Page 1043 



Deletes the file open on this stream. The file does not really go away until the 
stream is closed. You should not use rdelete. Instead, use delete-file. 



zhdelete item list &optional (ntimes -I) Function 

Returns list with all occurrences of item removed, zhequal is used for the compar- 
ison. The argument list is actually modified (rplacd'ed) when instances of item are 
spliced out. zhdelete should be used for value, not effect. That is, use: 

(setq a (delete 'b a)) 

rather than: 

(delete 'b a) 

ntimes instances of item are deleted, ntimes is allowed to be zero. If ntimes is 
greater than or equal to the number of occurrences of item in the list, all oc- 
curences of item in the list are deleted. 

Use the Common Lisp function, delete. 

For a table of related items: See the section "Functions for Modifying Lists". 

For a table of related items: See the section "Sequence Modification". 



delete-duplicates sequence &key (:test #'eql) :test-not (.start 0) send :from-end :key 
.-replace Function 

Compares the elements of sequence pairwise, and if any two match, the one occur- 
ring earlier in the sequence is discarded. The returned form is sequence, with 
enough elements removed such that no two of the remaining elements match. 
delete-duplicates is a destructive function. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

:test specifies the test to be performed. An element of sequence satisfies the test if 
(funcall testfun item (keyfn x)) is true. Where testfun is the test function specified 
by :test, keyfn is the function specified by :key and x is an element of the se- 
quence. The default test is eql. 

For example: 

(delete-duplicates '(111222333) :test #'>) => (1 1 1 2 2 2 3 3 3) 
(delete-duplicates '(111222333) :test #'=) => (1 2 3) 

:test-not is similar to :test, except that the sense of the test is inverted. An ele- 
ment of sequence satisfies the test if (funcall testfun item (keyfn x)) is false. 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 



Page 1044 



rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(delete-dupl icates ' (a a b b c c)) => (A B C) 

(delete-duplicates #(11111 1)) => #(1) 

(delete-dupl icates #(111222) : start 3) => #(1 1 1 2) 

(delete-duplicates #(111222) : start 2 :end 4) => #(1 1 1 2 2 2) 

The function normally processes the sequence in the forward direction, but if a 
non-nil value is specified for rfrom-end, processing starts from the reverse direc- 
tion. If the rfrom-end argument is true, then the one later in the sequence is dis- 
carded. 

The value of the keyword argument rkey, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(delete-duplicates '((Smith S) (Jones J) (Taylor T) (Smith S)) :key tf'second) 
=> ((JONES J) (TAYLOR T) (SMITH S)) 

When the rreplace keyword is specified, elements that stay are moved up to the 
position of elements that are deleted, rreplace is not meaningful if the value of 
rfrom-end is t. 

Compatibility Note: rreplace is a Symbolics extension to Common Lisp, and is not 
available in CLOE. 

For example: 

(delete-duplicates '((1 a) (2 b) (3 c) (1 d) (4 e) (3 f)) 
:key tf'car : replace t) => 
((1 d) (2 b) (3 f) (4 e)) 

(delete-duplicates '((1 a) (2 b) (3 c) (1 d) (4 e) (3 f)) 

:key tf'car :replace nil) => 
((2 b) (1 d) (4 e) (3 f)) 

(delete-duplicates '((1 a) (2 b) (3 c) (1 d) (4 e) (3 f)) 

:key tf'car :replace nil :from-end t) => 
((1 a) (2 b) (3 c) (4 e)) 

delete-duplicates is the destructive version of remove-duplicates. 
For a table of related items: See the section "Sequence Modification". 



(flavorrmethod rdelete-by-item sirheap) item &optional (equal-predicate #'=) 

Method 



Page 1045 



Finds the first item that satisfies equal-predicate, and deletes it, returning the 
item and key if it was found, otherwise it signals si:heap-item-not-found. equal- 
predicate should be a function that takes two arguments. The first argument to 
equal-predicate is the current item from the heap and the second argument is item. 

For a table of related items: See the section "Heap Functions and Methods". 



(flavorrmethod : delete-by-key sirheap) key &optional (equal-predicate #'=) Method 

Finds the first item whose key satisfies equal-predicate and deletes it, returning 
the item and key if it was found; otherwise it signals si:heap-item-not-found. 
equal-predicate should be a function that takes two arguments. The first argument 
to equal-predicate is the current key from the heap and the second argument is 
key. 

For a table of related items: See the section "Heap Functions and Methods". 



delete-if predicate sequence &key :key :from-end (.start 0) send .-count Function 

Removes a sequence of those items in the subsequence of sequence delimited by 
rstart and rend which satisfy predicate. The elements that are not deleted occur in 
the same order in the result that they did in the argument. This is a destructive 
operation. The argument sequence can be destroyed and used to construct the re- 
sult; however, the returned form may or may not be eq to sequence. 

For example: 

(setq a-list ' (1 a b c)) => (1 A B C) 
(delete-if #'numberp a-list) => (A B C) 
a-list => (1 A B C) 

However, 

(setq my-list '(0 1 0)) => (0 1 0) 
(delete-if #'zerop my-list) => (1) 
my-list => (0 1) 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(delete-if #'atom '((book 1) (math (room c)) (text 3)) :key tf'second) 
=> ((MATH (ROOM C))) 

(delete-if tf'zerop #(1 2 1) :key ft' (lambda (x) (- x 1))) 
=> ft(2) 



Page 1046 



If the value of the :from-end argument is non-nil, it only affects the result when 
the rcount argument is specified. In that case only the rightmost rcount elements 
that satisfy the predicate are deleted. 

For example: 

(delete-if tf'numberp '(4241) :count 1 ) => (2 4 1) 

(delete-if tf'numberp '(4241) :count 1 :from-end t) => (4 2 4) 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(delete-if tf'atom '('a 1 "list")) => ('A) 

(delete-if tf'numberp '(4 1 4) : start 1 :end 2) => (4 4) 

(delete-if tf'evenp '(4 1 4) : start :end 3) => (1) 

The rcount argument, if supplied, limits the number of elements deleted. If more 
than rcount elements of sequence satisfy the predicate, then only the leftmost 
rcount of those elements are deleted. A negative rcount argument is equivalent to 
a rcount of 0. 

For example: 

(delete-if tf'oddp '(1122) :count 1 ) => (1 2 2) 

(setq text "Some, text; with too, much punctuation!.?") 
(delete-if ft' (lambda (x) (member x ' (#\, #\? #\! #\;))) text) 
a => "Some text with too much punctuation." 

delete-if is the destructive version of remove-if. 

For a table of related items: See the section "Sequence Modification". 



delete-if-not predicate sequence &key :key :from-end (.start 0) send .-count 

Function 

Removes a sequence of those items in the subsequence of sequence delimited by 
rstart and rend which satisfy predicate. The elements that are not deleted occur in 
the same order in the result that they did in the argument. This is a destructive 
operation. The argument sequence can be destroyed and used to construct the re- 
sult; however, the returned form may or may not be eq to sequence. 



Page 1047 



For example: 

(setq a-list '('s a b c)) => ('S ABC) 
(delete-if-not tf'atom a-list) => (A B C) 
a-list => ('S ABC) 

However, 

(setq my-list '(0 1 0)) => (0 1 0) 
(delete-if-not #'zerop my-list) => (0 0) 
my-list => (0 1) 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(delete-if-not #'atom '((book 1) (math (room c)) (text 3)) :key #'second) 
=> ((BOOK 1) (TEXT 3)) 

(delete-if-not tf'zerop #(1 2 1) :key ft' (lambda (x) (- x 1))) => #(1 1) 

If the value of the :from-end argument is non-nil, it only affects the result when 
the rcount argument is specified. In that case only the rightmost rcount elements 
that satisfy the predicate are deleted. 

For example: 

(delete-if-not tf'oddp '(4241) :count 1 ) => (2 4 1) 
(delete-if-not tf'oddp '(4241) :count 1 :from-end t) => (4 2 1) 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(delete-if-not tf'atom '('a 1 "list")) => (1 "list") 
(delete-if-not tf'numberp '(4 1 4) : start 1 :end 2) => (4 1 4) 
(delete-if-not tf'evenp '(4 1 4) : start :end 3) => (4 4) 



Page 1048 



The rcount argument, if supplied, limits the number of elements deleted. If more 
than rcount elements of sequence satisfy the predicate, then only the leftmost 
rcount of those elements are deleted. A negative rcount argument is equivalent to 
a rcount of 0. 

For example: 

(delete-if-not tf'oddp '(1122) :count 1 ) => (1 1 2) 

delete-if-not is the destructive version of remove-if-not. 

For a table of related items: See the section "Sequence Modification". 

zlrdel-if pred list Function 

Makes a modified list is made by applying pred (a function of one argument) to all 
the elements of list and removing the ones for which the predicate returns non-nil. 
zlrdel-if is the destructive version of zlrrem-if, without the extra-lists &rest argu- 
ment. 

For a table of related items: See the section "Functions for Modifying Lists". 

zlrdel-if-not pred list Function 

Applies pred to all elements of list and removes those for which the pred returns 
nil. Returns the modified list, zlrdel-if-not is the destructive version zlrrem-if-not, 
without the extra-lists &rest argument. 

For a table of related items: See the section "Functions for Modifying Lists". 

zlrdelq item list &optional (ntimes -I) Function 

Returns list with all occurrences of item removed, eq is used to match the ele- 
ments of list against item. The argument list is actually modified (rplacd'ed) when 
instances of item are spliced out. zlrdelq should be used for value, not for effect. 

For a table of related items: See the section "Functions for Modifying Lists". 

denominator rational Function 

If rational is a ratio, denominator returns the denominator of rational. If rational 

is an integer, denominator returns 1. 

Examples: 

(denominator 4/5) => 5 
(denominator 3) => 1 
(denominator 4/8) => 2 
(denominator (/ 12 -17)) => 17 
(denominator (rational 0.200)) => 67108864 

For a table of related items: See the section "Functions that Extract Components 
From a Rational Number". 



Page 1049 



deposit-byte into-value position size byte-value Function 

Like dpb, except that instead of using a byte specifier, the bit position and size 
are passed as separate arguments. The argument order is not analogous to that of 
dpb so that deposit-byte can be compatible with older versions of Lisp. 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



deposit-field newbyte bytespec integer Function 

Returns an integer that is the same as integer except for the bits specified by byte- 
spec which are taken from newbyte. 

This is like function dpb ("deposit byte"), except that newbyte is not taken to be 
right-justified; the bytespec bits of newbyte are used for the bytespec bits of the re- 
sult, with the rest of the bits taken from integer, integer must be an integer. 

bytespec is built using function byte with bit size and position arguments. 

deposit-field could have been defined as follows: 

(deposit-field newbyte bytespec integer) ==> 

(dpb (ldb bytespec newbyte) bytespec integer) 

(deposit-field 320 (byte 3 6) 1088) => (+ 1088 256) => 1344 

(setq place-numb #b100) => 4 

(deposit-field #b100111 (byte 8 3) place-numb) => 36 

place-numb => 4 

Example: 

(deposit-field #o230 (byte 6 3) #o4567) => #o4237 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



describe anything &optional no-complaints 

Function 

Provides all the interesting information about any object (except array contents). 
describe knows about arrays, symbols, all types of numbers, packages, stack 
groups, closures, instances, structures, compiled functions, and locatives, and prints 
out the attributes of each in human-readable form. For example, 

(describe 5) 5 is an odd fixnum 

Sometimes it describes something that it finds inside something else; such recur- 
sive descriptions are indented appropriately. For instance, describe of a symbol 
tells you about the symbol's value, its definition, and each of its properties. 
describe of a floating-point number shows you its internal representation in a way 
that is useful for tracking down roundoff errors and the like. 



Page 1050 



If anything is a named-structure, describe handles it specially. To understand this: 
See the section "Named Structures". First it gets the named-structure symbol, and 
sees whether its function knows about the rdescribe operation. If the operation is 
known, it applies the function to two arguments: the symbol rdescribe, and the 
named-structure itself. Otherwise, it looks on the named-structure symbol for infor- 
mation that might have been left by defstruct; this information would tell it the 
symbolic names for the entries in the structure, describe knows how to use the 
names to print out each field's name and contents. 

describe describes an instance by sending it the rdescribe message. The default 
method prints the names and values of the instance variables. 

This is the same as the Show Object command. 

describe always returns its argument, in case you want to do something else to it. 

Compatibility Note: The optional argument no-complaints is an extension to Com- 
mon Lisp, which might not work in other implementations of Common Lisp. 



rdescribe Message 

The object that receives this message should describe itself, printing a description 
onto the *standard-output* stream. The describe function sends this message 
when it encounters an instance. 

The rdescribe method of flavorrvanilla calls flavorrdescribe-instance, which 
prints the following information onto the *standard-output* stream: a description 
of the instance, the name of its flavor, and the names and values of its instance 
variables. It returns the instance. For example: 

(send cell-object :describe) 

— >#<CELL 1160762135>, an object of flavor CELL, 
has instance variable values: 

X: 24 

Y: 3 

STATUS: :ALIVE 

NEXT-STATUS: unbound 

NEIGHBORS: unbound 

=> #<CELL 1160762135> 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



(flavorrmethod rdescribe sirheap) &optional (stream zlrstandard-output) Method 

Describes the heap, giving the predicate, number of elements, and optionally the 
contents. If stream is given, the output of rdescribe is printed on stream. 

For a table of related items: See the section "Heap Functions and Methods". 
describe-defstruct instance &optional name Function 



Page 1051 



Takes an instance of a structure and prints out a description of the instance, in- 
cluding the contents of each of its slots, name should be the name of the struc- 
ture; you must provide this name so that describe-def struct can know of what 
structure instance is an instance, and thus figure out the names of instance's slots. 

If instance is a named structure, you do not have to provide name, since it is just 
the named structure symbol of instance. Normally the describe function calls 
describe-defstruct if it is asked to describe a named structure; however, some 
named structures have their own idea of how to describe themselves. See the sec- 
tion "Named Structures". 

For a table of related items: See the section "Functions Related to defstruct Struc- 
tures". 



describe-function fspec &key (stream *standard-output*) Function 

Shows the arglist, values and proclaims for the compiled function fspec. The 
rstream argument enables you to output the description to any stream. 

(describe-function 'locativep) => 
Debugging info: 

ARGLIST (OBJECT) 

SYS: FUNCTION-PARENT (LOCATIVEP DEFINE-TYPE-PREDICATE) 
Proclaimed properties: 

NOTINLINE 
NIL 

See the section "Operations the User Can Perform on Functions". 



dbgrdescribe-global-handlers Function 

Displays the list of conditions for which global handlers have been defined, as well 
as a list of these handlers. 



flavorrdescribe-instance instance Function 

Prints the following information onto the *standard-output* stream: a description 
of the instance, the name of its flavor, and the names and values of its instance 
variables. It returns the instance. For example: 

(flavor : describe- instance eel 1 -object) 

— >#<CELL 1160762135>, an object of flavor CELL, 
has instance variable values: 

X: 24 

Y: 3 

STATUS: :ALIVE 

NEXT-STATUS: unbound 

NEIGHBORS: unbound 
=> #<CELL 1160762135> 



Page 1052 



When you use describe on an instance, a default method (implemented for 
flavorrvanilla) performs the flavorrdescribe-instance function. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



closrdescribe-object object stream Generic Function 

Provides a mechanism for users to control what happens when describe is called 
for instances of a class, closrdescribe-object is called by describe and should not 
be called by users. 

object Any Lisp object. 

stream A stream (this cannot be t or nil). 

The default method lists the slot names and values. 

The stream argument passed to closrdescribe-object is not necessarily the same as 
the stream passed to describe (it might be an intermediate stream that imple- 
ments parts of describe). Therefore, methods for closrdescribe-object should not 
depend on the identity of the stream. 

describe-package package Function 

Print a description of package's attributes and the size of its hash table of symbols 
on *standard-output*. package can be a package object or the name of a package. 
The describe function calls describe-package when its argument is a package. 

zlrdesetq (variable-pattern value-pattern}... Special Form 

Lets you assign values to variables through destructuring patterns. In place of a 
variable to be assigned, you can provide a tree of variables. The value to be as- 
signed must be a tree of the same shape. The trees are destructured into their 
component parts, and each variable is assigned to the corresponding part of the 
value tree. 

The first value-pattern is evaluated. If variable-pattern is a symbol, it is set to the 
result of evaluating value-pattern. If variable-pattern is a tree, the result of evaluat- 
ing value-pattern should be a tree of the same shape. The trees are destructured, 
and each variable that is a component of variable-pattern is set to the value that is 
the corresponding element of the tree that results from evaluating value-pattern. 
This process is repeated for each pair of variable-pattern and value-pattern. 
zlrdesetq returns the last value. Example: 

(desetq (a b) ' ((x y) z) c b) 

=>z 

a is set to (x y), b is set to z, and c is set to z. The form returns the value of the 
last form, which is the symbol z. 



Page 1053 



destructuring-bind pattern datum &body body Special Form 

Binds variables to values, using defmacro's destructuring facilities, and evaluates 
the body forms in the context of those bindings. 

First datum is evaluated. If pattern is a symbol, it is bound to the result of evalu- 
ating datum. If pattern is a tree, the result of evaluating data should be a tree of 
the same shape. It signals an error if the trees do not match. The trees are disas- 
sembled, and each variable that is a component of pattern is bound to the value 
that is the corresponding element of the tree that results from evaluating datum. 
Finally, the body forms are evaluated sequentially, the old values of the variables 
are restored, and the result of the last body form is returned. 

As with the pattern in a defmacro form, pattern actually resembles the lambda- 
list of a function; it can have &-keywords. See the macro defmacro. 

Example: 

(destructuring-bind (a (b) &optional (c 'd)) 

'((x Y) (z)) 
(values a b c)) 

=> (x y) z d 

Under Genera, zl:destructuring-bind also exists. It is the same as destructuring- 
bind except that it does not signal an error if the trees datum and pattern do not 
match. If not enough values are supplied, the remaining variables are bound to nil. 
If too many values are supplied, the excess values are ignored. 



mathrdeterminant matrix Function 

Returns the determinant of matrix, matrix must be a two-dimensional square ma- 
trix. 



zhdfloat x Function 

Converts any noncomplex number to a double-precision floating-point number. 

For a table of related items: See the section "Functions that Convert Numbers to 
Floating-point Numbers". 

zhdifference arg &rest args Function 

Returns its first argument minus the sum of the rest of its arguments. Arguments 
of different numeric types are converted to a common type, which is also the type 
of the result. See the section "Coercion Rules for Numbers". 

zhdifference is similar to the function - used with more than one argument. 

For a table of related items, see the section "Arithmetic Functions". 



Page 1054 



digit-char weight &optional (radix 10) (style-index 0) Function 

Returns the character that represents a digit with a specified weight weight. Re- 
turns nil if weight is not between and (1- radix) or radix is not between 2 and 
36. 

See the function digit-char-p. 

For a table of related items, see the section "Character Conversions". 



digit-char-p char &optional (radix 10) Function 

char must be a character object, digit-char-p returns the weight of that digit char- 
acter (a number from zero to one less than the radix) if it is a valid digit in the 
specified radix. It returns nil if char is not a valid digit in the specified radix; it 
cannot return t. 

(digit-char-p #\Q) => nil 

(digit-char-p #\8) => 8 

(digit-char-p (character 'b) 16) => 11 

See the function digit-char. 

For a table of related items, see the section "Character Predicates". 



: direction Message 

Returns one of the keyword symbols rinput, routput, or rbidirectional. 

disassemble function &optional from-pc to-pc Function 

Prints out a human-readable version of the macroinstructions in function, function 
is either a compiled function, or a symbol or function spec whose definition is a 
compiled function. 

Compatibility Note: The optional arguments from-pc and to-pc, are Symbolics ex- 
tensions to Common Lisp, which might not work in other implementations of Com- 
mon Lisp. Note that they are not available if you are using CLOE on a 386 based 
machine. 

The CLOE primitive takes a name, a lambda expression, or a compiled function ob- 
ject as an argument. The function definition is retrieved and compiled if not al- 
ready compiled. The compiled function object is then disassembled, and pretty 
printed. 

zhdispatch ppss word &body clauses Special Form 

(zhdispatch byte-specifier number clauses...) is the same as select (not zhselectq), 

but the key is obtained by evaluating (ldb byte-specifier number), byte-specifier and 
number are both evaluated. See the section "Byte Manipulation Functions". Byte 
specifiers and ldb are explained in that section. Example: 



Page 1055 



(princ (dispatch 0202 cat-type 
(0 "Siamese.") 
(1 "Persian.") 
(2 "Alley.") 
(3 (ferror nil 

"~S is not a known cat type." 
cat-type)))) 

It is not necessary to include all possible values of the byte that is dispatched on. 

For a table of related items: See the section "Conditional Functions". 



zhdisplace form expansion Function 

Replaces the car and cdr of form so that it looks like: 

(si : displaced original-form expansion) 

form must be a list, original-form is equal to form but has a different top-level 
cons so that the replacing mentioned above does not affect it. sirdisplaced is a 
macro, which returns the caddr of its own macro form. So when the sirdisplaced 
form is given to the evaluator, it "expands" to expansion, zhdisplace returns ex- 
pansion. 

zhdlet ((variable-pattern value-pattern)...) body... Special Form 

Binds variables to values, using destructuring, and evaluates the body forms in the 
context of those bindings. In place of a variable to be assigned, you can provide a 
tree of variables. The value to be assigned must be a tree of the same shape. The 
trees are destructured into their component parts, and each variable is assigned to 
the corresponding part of the value tree. 

First the variable-pattern is evaluated. If variable-pattern is a symbol, it is bound to 
the result of evaluating the corresponding value-pattern. If variable-pattern is a 
tree, the result of evaluating value-pattern should be a tree of the same shape. The 
trees are destructured, and each variable that is a component of variable-pattern is 
bound to the value that is the corresponding element of the tree that results from 
evaluating value-pattern. The bindings happen in parallel; all the value-patterns are 
evaluated before any variables are bound. Finally, the body forms are evaluated 
sequentially, the old values of the variables are restored, and the result of the last 
body form is returned. Example: 

(zl:dlet (((a b) '((x y) z)) 
(c 'd)) 
(values a b c)) 

=> (x y) z d 



zhdlet* ((variable-pattern value-pattern)...) body... Special Form 



Page 1056 



Binds variables to values, using destructuring, and evaluates the body forms in the 
context of those bindings. In place of a variable to be assigned, you can provide a 
tree of variables. The value to be assigned must be a tree of the same shape. The 
trees are destructured into their component parts, and each variable is assigned to 
the corresponding part of the value tree. 

The first value-pattern is evaluated. If variable-pattern is a symbol, it is bound to 
the result of evaluating value-pattern. If variable-pattern is a tree, the result of 
evaluating value-pattern should be a tree of the same shape. The trees are de- 
structured, and each variable that is a component of variable-pattern is bound to 
the value that is the corresponding element of the tree that results from evaluat- 
ing value-pattern. The process is repeated for each pair of variable-pattern and val- 
ue-pattern. The bindings happen sequentially; the variables in each variable-pattern 
are bound before the next value-pattern is evaluated. Finally, the body forms are 
evaluated sequentially, the old values of the variables are restored, and the result 
of the last body form is returned. Example: 

(zl:dlet* (((a b) '((x y) z)) (c b)) (values a b c)) 
=> (x y) z z 



do vars endtest &body body 

Special Form 

Provides a simple generalized iteration facility, with an arbitrary number of "index 
variables" whose values are saved when the do is entered and restored when it is 
left, that is, they are bound by the do. The index variables are used in the itera- 
tion performed by do. At the beginning, they are initialized to specified values, 
and then at the end of each trip around the loop the values of the index variables 
are changed according to specified rules, do allows you to specify a predicate that 
determines when the iteration terminates. The value to be returned as the result 
of the form can, optionally, be specified. 

do looks like this: 

(do ( (var init repeat) . . . ) 
(end-test exit-form . . . ) 
body . . . ) 

The first item in the form is a list of zero or more index variable specifiers. Each 
index variable specifier is a list of the name of a variable var, an initial value 
form init, which defaults to nil if it is omitted, and a repeat value form repeat. If 
repeat is omitted, the var is not changed between repetitions. If init is omitted, the 
var is initialized to nil. 

An index variable specifier can also be just the name of a variable, rather than a 
list. In this case, the variable has an initial value of nil, and is not changed be- 
tween repetitions. 

All assignment to the index variables is done in parallel. At the beginning of the 
first iteration, all the init forms are evaluated, then the vars are bound to the val- 



Page 1057 



ues of the init forms, their old values being saved in the usual way. The init forms 
are evaluated before the vars are bound, that is, lexically outside of the do. At the 
beginning of each succeeding iteration those vars that have repeat forms get set to 
the values of their respective repeat forms. All the repeat forms are evaluated be- 
fore any of the vars is set. 

The second element of the do-form is a list of an end-testing predicate form end- 
test, and zero or more forms, called the exit-forms. This resembles a cond clause. 
At the beginning of each iteration, after processing of the variable specifiers, the 
end-test is evaluated. If the result is nil, execution proceeds with the body of the 
do. If the result is not nil, the exit-forms are evaluated from left to right and then 
do returns. The value of the do is the value of the last exit-form, or nil if there 
were no exit-forms (not the value of the end-test as you might expect by analogy 
with cond). 

Note that the end-test gets evaluated before the first time the body is evaluated. 
do first initializes the variables from the init forms, then it checks the end-test, 
then it processes the body, then it deals with the repeat forms, then it tests the 
end-test again, and so on. If the end-test returns a non-nil value the first time, 
then the body is never processed. 

If the second element of the form is (nil), the end-test is never true and there are 
no exit-forms. The body of the do is executed over and over. The infinite loop can 
be terminated by use of return or throw. 

Example: 

(do ((count 1 (+ count 1))) 

(nil) ; Do forever, 

(let ((item (read) )) 

(if (null item) (return) (princ item)))) => ABCDEFGNIL 

; typed - abcdefg() 

If a return special form is evaluated inside the body of a do, the do immediately 
stops, unbinds its variables, and returns the values given to return. See the spe- 
cial form return. 

return and its variants are explained in more detail in that section, go special 
forms and prog-tags can also be used inside the body of a do and they mean the 
same thing that they do inside prog forms, but we discourage their use since they 
make your program complicated and hard to understand. 

Examples: 



Page 1058 



(setq foo-array (make-array '(2 2) : initial -element 'a)) 
=> #2A((A A) (A A)) 

(do ((x (+ x 1)) ; prints out array 

(n (array-dimension foo-array 0) )) 
((= x n)) 
(do ((y (+ y 1)) 

(n (array-dimension foo-array 1) )) 
((= Y n)) 
(princ (aref foo-array x y)))) => AAAA 
NIL 

(arglist 'cl :array-dimensions) => (ARRAY) and NIL and NIL 
(setq a-vector #(1 2 3)) => #(1 2 3) 

(do ((i (+ i 1)) ; changes every 2 in vector into a 

(n (length a-vector))) 
((= i n)) 
(if (=2 (aref a-vector i)) 

(setf (aref a-vector i) 0))) => NIL 
A-VECTOR => #(1 3) 

(do ((z list (cdr z)) ;z starts as list and is cdr'ed each time. 

(y other-list) ;y starts as other-list, and is unchanged by the do. 

(x) ;x starts as nil and is not changed by the do. 

w) ;w starts as nil and is not changed by the do. 

(nil) ;The end-test is nil, so this is an infinite loop. 

body) ; Presumably the body uses return somewhere. 

The following construction exploits parallel assignment to index variables: 

(do ((x e (cdr x)) 
(oldx x x)) 
((null x)) 
body) 

On the first iteration, the value of oldx is whatever value x had before the do was 
entered. On succeeding iterations, oldx contains the value that x had on the previ- 
ous iteration. 

body can contain no forms at all. Very often an iterative algorithm can be most 
clearly expressed entirely in the repeats and exit-forms of a new-style do, and the 
body is empty. 

The following example is like (maplist 'f x y). (See the section "Mapping".) 

(do ((x x (cdr x)) 

(y y (cdr y)) 

(z nil (cons (f x y) z))) ;exploits parallel assignment, 
((or (null x) (null y)) 

(nreverse z)) ;typical use of nreverse. 

)) ;no do-body required. 

For information about a general iteration facility based on a keyword syntax rather 
than a list-structure syntax: 



Page 1059 



See the section "The loop Iteration Macro". See the section "The CLOE Loop Iter- 
ation Macro". 

Zetalisp Note: Zetalisp supports another, "old-style" version of do. This form is in- 
compatible with the language specification presented in Guy Steele's Common 
Lisp: the Language. 

The older do looks like this: 

(do var init repeat end-test body. . .) 

The first time through the loop var gets the value of the init form; the remaining 
times through the loop it gets the value of the repeat form, which is reevaluated 
each time. Note that the init form is evaluated before var is bound, that is, lexical- 
ly outside of the do. Each time around the loop, after var is set, end-test is evalu- 
ated. If it is non-nil, the do finishes and returns nil. If the end-test evaluated to 
nil, the body of the loop is executed. 

If the second element of the form is nil, there is no end-test nor exit-forms, and the 
body of the do is executed only once. In this type of do it is an error to have re- 
peats. This type of do is no more powerful than let; it is obsolete and provided on- 
ly for Maclisp compatibility. 

return and go can be used in the body. It is possible for body to contain no forms 
at all. 

Examples: 

(do ( (i (+ 1 i)) ; searches list for Dan. 

(names '(Adam Brian Carla Dan Eric Fred) (cdr names))) 
((null names)) 
(if (equal 'Dan (car names)) 

(princ "Hey Danny Boooooy "))) => Hey Danny Boooooy NIL 

(do ((zz x (cdr zz))) 
((or (null zz) 

(zerop (f (car zz)))))) 

;this applies f to each element of x 
;continuously until f returns zero. 
;Note that the do has no body. 

(defun list-splice (a b) 
(do ((x a (cdr x)) 
(y b (cdr y)) 

(xy '() (append xy (list (car x) (car y)))) ) 
((endp x) (endp y) (append xy x y) ))) => LIST-SPLICE 
(list-splice '(1 2 3) '(a b c)) => (1 A 2 B 3 C) 
(list-splice '(12 3) ' (a b c d e)) => (1 A 2 B 3 C D E) 

return forms are often useful to do simple searches: 



Page 1060 



(setq a-vector #(1 2 3)) => #(1 2 3) 



(do ((i (+ i 1))) 

((and (= 3 (aref a-vector i)) 
(return i)))) 



Iterate over the length of vector 
If we find a element that = 3 
then return its index. 



=> 2 ;note (aref a-vector 2) => 3 

Example: 

(do ((i 5 (+ i 1)) 

(list (cdr xdata-listx) (cdr list)) 
(item (car *data-l ist*) (car list))) 
((>= i (length xdata-vectorx)) t) 
(unless (= (aref xdata-vectorx i) item) 
(return nil))) 

For a table of related items: See the section "Iteration Functions". 

do keyword for loop 

do expression 

expression is evaluated each time through the loop, as shown in the follow- 
ing example: 

(defun print-elements-of-1 ist (1 ist-of-elements) 
(loop for element in 1 ist-of-elements 
do (print element))) 
=> PRINT-ELEMENTS-OF-LIST 

print-elements-of-list prints each element in its argument, which should be 
a list. It returns nil. 

The forms do and doing are synonymous. Examples 

(defun print-list (small-list) 
(loop for element in small-list 
do 
(princ element) 
(princ " A "))) => PRINT-LIST 
(print-list ' (1 2 3)) => 1 A 2 A 3 A NIL 

This is equivalent to 

(defun print-list (small-list) 
(loop for element in small-list 
doing 
(princ element) 
(princ " A "))) => PRINT-LIST 
(print-list ' (1 2 3)) => 1 A 2 A 3 A NIL 

See the macro loop. 



Page 1061 



do* vars endtest &body body Special Form 

Just like do, except that the variable clauses are evaluated sequentially rather 
than in parallel. When a do starts, all the initialization forms are evaluated before 
any of the variables are set to the results; when a do* starts, the first initializa- 
tion form is evaluated, then the first variable is set to the result, then the second 
initialization form is evaluated, and so on. The stepping forms work analogously. 

Examples: 

(do ( (i (+ 1 i)) 
(i (+ 1 i))) 

((= i 10)) 
(princ i)) => 0123456789NIL 

(do* ( (i (+ 1 i)) 
(i (+ 1 i))) 

((= i 10)) 
(princ i)) => 02468NIL 

Provides a comprehensive iteration control construct, and is a powerful analog to 
iteration control loops as found in Algol derivative languages, composed of zero or 
more variable specifiers, an end test and zero or more result forms, zero or more 
declarations, and a body. 

The variable specifier is a list of variable bindings, including optional initialization 
values and an optional step form. All the variable binding initializations are execut- 
ed sequentially, as are evaluation of the step forms. During initialization, later 
variable specifiers and evaluation of step forms have the ability to refer to the 
most current value of pre-specified variables. If init is omitted, then the variable is 
bound to nil; if step is omitted, the variable value is not automatically changed 
during do* iterations. Declarations may apply to any of the other three major parts 
of the do* form. 

The body of the do* form is an implicit tagbody that contains both statement 
forms and tags that are targets of go statements in the body. The Go statements 
that refer to tags in the body of the do* are not allowed in the variable specifiers, 
end-test, or result forms. 

After the variable specifiers are initialized, and after each variable specifier step 
form evaluation (but before the body forms are evaluated) end-test is evaluated. If 
the result is nil, the body of the do is evaluated. If the result is not nil, the result 
forms of the do* are evaluated, and the value of the last one is returned as the 
value of the do* form. No returns is nil. 

The do* form is wrapped in an implict block whose name is nil, so that values 
can be explicitly returned from do*, using return. 



Page 1062 



(do* ((i 5 (+ i 1)) 

(list xdata-listx (cdr list)) 

(item (car list) (car list))) 
((or (endp list)(>= i (length xdata-vectorx))) t) 
(unless (= (aref xdata-vectorx i) item) 

(return nil))) 

For a table of related items: See the section "Iteration Functions". 

do-all-symbols (var &optional result-form) &body body Special Form 

Evaluates the body forms repeatedly with var bound to each symbol present in any 
package (excluding invisible packages). 

When the iteration terminates, result-form is evaluated and its values are returned. 
The value of var is nil during the evaluation of result-form. If result-form is not 
specified, the value returned is nil. 

The return special form can be used to cause a premature exit from the iteration. 

The following code uninterns all the symbols accessible in my-package, and re- 
turns the list of symbols: 

(let ((symbol-list nil)) 

(do-symbols (symbol my package symbol -list) 
(unintern symbol) 
(setq symbol -list (cons symbol symbol-list)))) 



do-external-symbols (var &optional pkg result-form) &body body Special Form 

Evaluates the body forms repeatedly with var bound to each external symbol ex- 
ported by pkg. pkg can be a package object or a string or symbol that is the name 
of a package, or it can be omitted, in which case the value of *package* is used 
by default. 

When the iteration terminates, result-form is evaluated and its values are returned. 
The value of var is nil during the evaluation of result-form. If result-form is not 
specified, the value returned is nil. 

The return special form can be used to cause a premature exit from the iteration. 

The following code makes all the external symbols of the turbine-package accessi- 
ble in the generator-package. 

(do-external -symbols (symbol 'turbine-package) 
(import symbol 'generator-package)) 

do-external-symbols has an implicit tagbody. 

CLOE Note: This is a macro in CLOE. 



do-local-symbols (var &optional pkg result-form) &body body Special Form 



Page 1063 



Evaluates the body forms repeatedly with var bound to each symbol present in 
package, pkg can be a package object or a string or symbol that is the name of a 
package, or it can be omitted, in which case the value of *package* is used by 
default. 

When the iteration terminates, result-form is evaluated and its values are returned. 
The value of var is nil during the evaluation of result. If result-form is not speci- 
fied, the value returned is nil. 

The return special form can be used to cause a premature exit from the iteration. 



zl:do-named block-name vars endtest &body body Special Form 

Sometimes one do is contained inside the body of an outer do. The return func- 
tion always returns from the innermost surrounding do, but sometimes you want 
to return from an outer do while within an inner do. You can do this by giving 
the outer do a name. You use zl:do-named instead of do for the outer do, and use 
return-from, specifying that name, to return from the zl:do-named. 

The syntax of zl:do-named is like do except that the symbol do is immediately fol- 
lowed by the name, which should be a symbol. Example: 

(zl :do-named out 

((x 1 (+ x D)) 
((= x 4)) 
(do ((y 1 (+ 1 y))) 
((= Y 4)) 
(if (= y 2) (zl : return-from out (values x y))) )) => 1 and 2 

(zl : do-named george ((a 1 (1+ a)) 
(d 'foo)) 
((> a 4) 7) 
(do ((c b (cdr c))) 
((null c)) 

(return-from george (cons b d)) 

If the symbol t is used as the name, it is made "invisible" to returns; that is, 
returns inside that zl:do-named return to the next outermost level whose name is 
not t. (return-from t ...) returns from a zl:do-named named t. You can also make 
a zl:do-named invisible to returns by including immediately inside it the form 
(declare (si:invisible-block t)). This feature is not intended to be used by user- 
written code; it is for macros to expand into. 

If the symbol nil is used as the name, it is as if this were a regular do. Not hav- 
ing a name is the same as being named nil. 

progs and zhloops can have names just as dos can. Since the same functions are 
used to return from all of these forms, all of these names are in the same name- 
space; a return returns from the innermost enclosing iteration form, no matter 



Page 1064 



which of these it is, and so you need to use names if you nest any of them within 
any other and want to return to an outer one from inside an inner one. 

For a table of related items: See the section "Iteration Functions". 



zl:do*-named block-name vars endtest &body body Special Form 

Just like zl:do-named, except that the variable clauses are evaluated sequentially, 
rather than in parallel. See the special form do*. 

Examples: 

(zl : do-named who-do 

( (i (+ 1 i)) 
(i (+ 1 i))) 

((= i 10)) 
(princ i)) => 0123456789NIL 

(zl :dox-named who-do 

( (i (+ 1 i)) 
(i (+ 1 i))) 

((= i 10)) 
(princ i)) => 0123456789NIL 

For a table of related items: See the section "Iteration Functions". 



do-symbols (var &optional pkg result-form) &body body Special Form 

Evaluates the body forms repeatedly with var bound to each symbol accessible in 
pkg. pkg can be a package object or a string or symbol that is the name of a 
package, or it can be omitted, in which case the value of *package* is used by 
default. 

When the iteration terminates, result-form is evaluated and its values are returned. 
The value of var is nil during the evaluation of result. If result-form is not speci- 
fied, the value returned is nil. 

The return special form can be used to cause a premature exit from the iteration. 



dbg: document-proceed- type condition proceed-type stream Generic Function 

Prints out a description of what it means to proceed, using the given proceed-type, 
from this condition, on stream. This is used mainly by the Debugger to create its 
prompt messages. Phrase such a message as an imperative sentence, without any 
leading or trailing #\ return characters. This sentence is for the human users of 
the machine who read this when they have just been dumped unexpectedly into the 
Debugger. It should be composed so that it makes sense to a person to issue that 
sentence as a command to the system. 

The compatible message for dbg: document-proceed- type is: 



Page 1065 



: document-proceed- type 

For a table of related items, see the section "Basic Condition Methods and Init Op- 
tions". 



dbgrdocument-special-command condition special-command 

Generic Function 

Prints the documentation of special-command onto stream. If you don't provide 
your own method explicitly, the default handler uses the documentation string 
from the dbg: special-command method. You can, however, provide this method in 
order to print a prompt string that has to be computed at run-time. This is analo- 
gous to dbg:document-proceed-type. The syntax is: 

(def method (dbg: document-special -command my-flavor :my-command-keyword) 
(stream) 
body...) 

The compatible message for dbgrdocument-special-command is: 
rdocument-special-command 

For a table of related items: See the section "Debugger Special Command Func- 
tions". 

documentation name &optional (type 'defun) Function 

Finds the documentation string of the symbol, name, which is stored in various 
different places depending on the symbol type. If there is no documentation, nil is 
returned. 

Symbolics Common Lisp provides the optional argument type, type can be variable, 
function, structure, type, or setf, according to the construct represented by name. 
Type is a required argument in other implementations of Common Lisp, including 
CLOE Runtime. 

If you are using CLOE, consider the following example: 

(defstruct person "The physical parts of a person" 
(head *defaul t-head*) 
(right-arm *defaul t-right-arm*) 
(left-arm *default-l eft-arm*) 
(right-leg *defaul t-right-leg*) 
(left-leg *default-l eft-leg*) 
(other ' () :type list)) 

(documentation 'person 'structure) 
=> "The physical parts of a person" 



dolist (var listform &optional resultform) &body forms 



Page 1066 



Special Form 

A convenient abbreviation for the most common list iteration. 

dolist performs forms once for each element in the list that is the value of list- 
form, with var bound to the successive elements. 

You can use return and go and prog-tags inside the body, as with do. 

dolist returns nil, or the value of resultform, if the latter is specified. 

Examples: 

(dolist (people ' (mary ann claire cindy) 4) (print people )) => 

MARY 

ANN 

CLAIRE 

CINDY 4 

(dolist (z '(1 2 3 4) "hi") (princ (+ z 2))) => 3456"hi" 

(dolist (j '(1 2 3 4) t) (princ (- 1 j)) (if (= j 3) (return))) 
=> 0-1-2NIL 

For a table of related items: See the section "Iteration Functions". 

zhdolist (var form) &body body 

Special Form 

A convenient abbreviation for the most common list iteration, zhdolist performs 
body once for each element in the list that is the value of form, with var bound to 
the successive elements. 

Examples: 

(zl: doli st (people '(mary ann claire cindy)) (print people )) => 

MARY 

ANN 

CLAIRE 

CINDY NIL 

(zl: doli st (z '(1 2 3 4)) (princ (+ z 2))) => 3456NIL 

(zl:dolist (j '(1 2 3 4)) (princ (- 1 j)) (if (= j 3)(return))) 
=> 0-1-2NIL 



Where 



(zl:dolist (item (frobs foo)) 
(mung item)) 



Page 1067 



is equivalent to: 

(do ((1st (frobs foo) (cdr 1st)) 
(item)) 
((null 1st)) 
(setq item (car 1st)) 
(mung item)) 

except that the name 1st is not used. You can use return and go and prog-tags in- 
side the body, as with do. zkdolist forms return nil unless returned from explicitly 
with return. 

See the special form dolist. 

For a table of related items: See the section "Iteration Functions". 



Provides a control device for iteration over the elements of a list, and is com- 
posed of a single variable specifier, zero or more declarations, and an implicit 

tagbody. 

The variable specifier binds a variable to a form that must evaluate to a list. A 
single, optional result form is permitted and is the value returned by the dolist. 
If result is omitted, dolist returns nil (unless an explicit return is executed). 
Declarations may apply to either of the other major parts of the dolist form. 

The body of the dolist form is an implicit tagbody that contains both statement 
forms and tags that are targets of go statements in the body. The go statements 
referring to tags in the body of the dolist are not allowed in the variable speci- 
fier. The body of the dolist is evaluated once for each element of the list. When 
the end of the list is reached, the value of the specified variable is nil, and re- 
sult form is evaluated. 

The dolist form is wrapped in an implict block whose name is nil, so that val- 
ues can be explicitly returned from dolist, using return. 

(let ((i 5)) 

(dolist (item xdata-listx t) 

(unless (= (aref xdata-vectorx i) item) 

(return nil)) 
(setq i (+ i 1)))) 

See Also: CLtL 126, do, do*, loop, tagbody, dotimes 



dotimes (var countform &optional resultform) &body forms Special Form 

A convenient abbreviation for the most common integer iteration. 

dotimes performs forms the number of times given by the value of countform, with 
var bound to 0, 1, and so forth on successive iterations. 

You can use return and go and prog-tags inside the body, as with do. 

The function returns nil, or the value of resultform if the latter is specified. 

Examples: 



Page 1068 



(dotimes (i 5 10) 

(princ i)(princ " ")) => 1 2 3 4 10 

(dotimes (j 5 t) 

(princ j)(if (= j 3) (return))) => 0123NIL 

Note that in CLOE, the iteration control variable var is required to take on only 
fixnum values. 

For a table of related items: See the section "Iteration Functions". 



zhdotimes (var form) &body body Special Form 

A convenient abbreviation for the most common integer iteration, zhdotimes per- 
forms body the number of times given by the value of count, with index bound to 
0, 1, and so forth on successive iterations. 

Example: 

(zl :dotimes (i 5) 

(princ i) (princ " ")) => 1 2 3 4 NIL 

(zl :dotimes (j 5) 

(princ j)(if (= j 3) (return))) => 0123NIL 

Where 

(zl :dotimes (i (// m n)) 
(frob i)) 

is equivalent to: 

(do ((i (1+ i)) 

(count (// m n))) 
((> i count)) 
(frob i)) 

except that the name count is not used. Note that i takes on values starting at 
rather than 1, and that it stops before taking the value (/ m n) rather than after. 
You can use return and go and prog-tags inside the body, as with do. zhdotimes 
forms return nil unless returned from explicitly with return. For example: 

(zl :dotimes (i 5) 

(if (eq (aref a i) 'foo) 
(return i))) 

This form searches the array that is the value of a, looking for the symbol foo. It 
returns the fixnum index of the first element of a that is foo, or else nil if none 
of the elements are foo. 

See the special form dotimes. 

For a table of related items: See the section "Iteration Functions". 



Page 1069 



provides an control device for iteration over a sequence of natural numbers. It is 
composed of a single variable specifier, zero or more declarations, and an implicit 

tagbody. 

The variable specifier is composed a binding of a variable to zero, and specifica- 
tion of a form, countform which must evaluate to an integer. If countform is neg- 
ative or zero, result is evaluated and dotimes exits. After each iteration, the value 
of the control variable is incremented by one. A single, optional result form is 
permitted, and is the value returned by dotimes. If result is omitted, dotimes re- 
turns nil (unless an explicit return is done). 

Declarations may apply to either of the other major parts of the dotimes form. 

The body of the dotimes form is an implicit tagbody, containing both statement 
forms, and tags which are targets of go statements in the body. Go statements re- 
ferring to tags in the body of the dotimes are not allowed in the variable specifi- 
er. The body of the dotimes is evaluated once for each integer value of the con- 
trol variable, up to but not including the number returned by countform. After 
the last iteration, and during the evaluation of result, the control variable count- 
form has a value, which is the number of times the body was evaluated. 

The dotimes form is wrapped in an implict block whose name is nil, so that val- 
ues can be explicitly returned from dotimes, using return. 

(dotimes (i 20 t) 

(unless (= (aref xdata-vector-ax i) (aref xdata-vector-bx i)) 
(return nil))) 

See Also: CLtL 126, do, do*, loop, tagbody, dolist 



double-float Type Specifier 

double-float is the type specifier symbol for the predefined Lisp double-precision 
floating-point number type. 

The type double-float is a subtype of the type float. In Symbolics Common Lisp, 
the type double-float is equivalent to the type long-float. 

The type double-float is disjoint with the types short-float, and single-float. 

Examples: 

(typep -13D2 'double-float) => T 

(zl:typep -12D4) => :D0UBLE-FL0AT 

(subtypep 'double-float 'float) => T and T ;subtype and certain 

(commonp 0d0) => T 

(sys:double-float-p 6.03e23) => NIL 

(sys:double-float-p 1.5d9) => T 

(equal -typep 'double-float 'long-float) => T 

(sys: type-argl ist 'double-float) => NIL and T 
See the section "Data Types and Type Specifiers". 



Page 1070 



See the section "Numbers". 



double-float-epsilon Constant 

The value of this constant is the smallest positive floating-point number e of a for- 
mat such that it satisfies the expression: 

(not (= (float 1 e) (+ (float 1 e) e))) 

The current value of double-float-epsilon is: 1.1102230246251568d-16. 



double-float-negative-epsilon Constant 

The value of this constant is the smallest positive floating-point number e of a for- 
mat such that it satisfies the expression: 

(not (= (float 1 e) (- (float 1 e) e))) 

The current value of double-float-negative-epsilon is: 5.551115123125784d-17 



sys:double-float-p object Function 

Returns t if object is a double-precision floating-point number, otherwise nil. 
For a table of related items, see the section "Numeric Type-checking Predicates". 

dpb newbyte bytespec integer Function 

The name of this function stands for "Deposit byte". 

Returns a number that is the same as integer except in the bits specified by byte- 
spec. 

bytespec is built using function byte with bit size and position arguments. Here 
size indicates the number of low bits of newbyte to be placed in the result. 

newbyte is interpreted as being right-justified, as if it were the result of ldb ("load 
byte"). 

integer must be an integer. 

Examples: 

(dpb 1 (byte 1 2) 1) => 5 

(dpb (byte 1 31.) -1_31.) => -4294967296. ;; a bignum (-1_32) 

(dpb -1 (byte 40. 0) -1_32.) => -1 . 

(dpb #0230 (byte 6 3) #o4567) => #o4307 

(dpb 320 (byte 7 0) 1024) = (dbp (logior 256 64) (byte 7 0) 1024) 

= (dpb #b101000000 (byte 7 0) #b1000000000) = (logior 1024 64) => 1088 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



Page 1071 



dribble &optional pathname editor-p Function 

Opens pathname as a "dribble file". It rebinds *standard-input*, *standard- 
output*, *tr ace-output*, *error-output*, and *query-io* so that all of the termi- 
nal interaction is directed to the file as well as to the terminal. If editor-p is 
non-nil, it does not open pathname on the file computer, instead it directs the ter- 
minal interaction into a Zmacs buffer whose name is pathname, creating it if it 
does not exist. 

To terminate the recording, reset the I/O streams, and close the file (if any), call 
dribble again with no arguments: 

(dribble) 

Compatibility Note: The optional argument editor-p is a Symbolics extension to 
Common Lisp which might not work in other implementations of Common Lisp, 
and does not work in CLOE Runtime. 



zl:dribble-end Function 

Closes the file opened by zhdribble-start and resets the I/O streams. 



zhdribble-start pathname &optional editor-p (concatenate-p t) (debugger-p nil) 

Function 

Opens pathname as a "dribble file". It rebinds *standard-input*, *standard- 
output*, *tr ace-output*, *error-output*, and *query-io* so that all of the termi- 
nal interaction is directed to the file as well as to the terminal. If editor-p is 
non-nil, it does not open pathname on the file computer, instead it directs the ter- 
minal interaction into a Zmacs buffer whose name is pathname, creating it if it 
does not exist. 



sysrdynamic-closure Type Specifier 

sysrdynamic-closure is the type specifier symbol for the predefined Lisp object of 
that name. 

See the section "Data Types and Type Specifiers". See the section "Scoping". 

Examples: 

(setq four 

(let ((x 4)) 

(closure ' (x) 'zerop))) => #<DTP-CLOSURE 1510647> 

(typep four 'sys: dynamic-closure) => T 

(subtypep 'sys: dynamic-closure 'common) => NIL and NIL 



dynamic-closure-alist closure Function 



Page 1072 



Returns an alist of (symbol . value) pairs describing the bindings which the dy- 
namic closure performs when it is called. This list is not the same one that is ac- 
tually stored in the closure; that one contains pointers to value cells rather than 
symbols, and dynamic-closure-alist translates them back to symbols so you can 
understand them. As a result, clobbering part of this list does not change the clo- 
sure. 

If any variable in the closure is unbound, this function signals an error. See the 
section "Dynamic Closure-Manipulating Functions". 



dynamic-closure-variables closure Function 

Creates and returns a list of all of the variables in the dynamic closure closure. It 
returns a copy of the list that was passed as the first argument to make-dynamic- 
closure when closure was created. See the section "Dynamic Closure-Manipulating 
Functions". 



ecase object &body body Special Form 

The name of this function stands for "exhaustive case" or "error-checking case". 

Structurally ecase is much like case, and it behaves like case in selecting one 
clause and then executing all consequents of that clause. However, ecase does not 
permit an explicit otherwise or t clause. The form of ecase is as follows: 

(ecase key-form 

(test consequent consequent ...) 

(test consequent consequent ...) 

(test consequent consequent ...) 

The first thing ecase does is to evaluate object, to produce an object called the key 
object. 

Then ecase considers each of the clauses in turn. If key is eql to any item in the 
clause, ecase evaluates the consequents of that clause as an implicit progn. 

ecase returns the value of the last consequent of the clause evaluated, or nil if 
there are no consequents to that clause. 

The keys in the clauses are not evaluated; literal key values must appear in the 
clauses. It is an error for the same key to appear in more than one clause. The or- 
der of the clauses does not affect the behavior of the ecase construct. 

If there is only one key for a clause, that key can be written in place of a list of 
that key, provided that no ambiguity results. Such a "singleton key" can not be nil 
(which is confusable with nil, a list of no keys), t, otherwise, or a cons. 

If no clause is satisfied, ecase uses an implicit otherwise clause to signal an error 
with a message constructed from the clauses. It is not permissible to continue 
from this error. To supply your own error message, use case with an otherwise 
clause containing a call to error. 



Page 1073 



Examples: 

(let ((num 24)) 
(ecase num 

((1 2 3) "integer") 

((4 5 6) "integer"))) => non-proceedable error is signalled 

(let ((num 3)) 
(ecase num 

((1 2) "one two") 

((3 4 5 6) (princ "numbers") (princ " three") (terpri) ) 

(t "not today"))) => numbers three 
T 

For a table of related items: See the section "Conditional Functions". 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



eighth list Function 

Returns the eighth element of the list list, eighth is equivalent to 

(nth 7 list) 
For example: 

(setq letters '(abcdefghij))=> 
(ABCDEFGHIJ) 

(eighth letters) => H 

This function is provided because it makes more sense than using nth when you 
are thinking of the argument as a list rather than just as a cons. 

For a table of related items: See the section "Functions for Extracting from Lists". 

elt sequence index 

Function 

Extracts an element from sequence at position index. Returns a new sequence. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

index must be a non-negative integer less than the length of sequence as returned 
by length. The first element of a sequence has index 0. 

For example: 

(setq bird-list '(heron stork pelican turkey)) => 
(HERON STORK PELICAN TURKEY) 



Page 1074 



(elt bird-list 2) => PELICAN 

(equalp (elt bird-list 2) (third bird-list)) => T 

Note that elt observes the fill pointer in those vectors that have fill pointers. The 
array-specific function aref can be used to access vector elements that are beyond 
the vector's fill pointer. 

setf can be used with elt to destructively replace a sequence element with a new 
value. For example: 

(setf (elt bird-list 2) 'hawk) => HAWK 

bird-list => (HERON STORK HAWK TURKEY) 

The following example demonstrats the use of elt to reference array components 
of either type list or type vector. 

(setq seqarr 

(make-array 5 : element-type 'sequence 
: initial-contents 
'((a b c) 

, (vector 'd 'e 'f) 

(x y) 
(y z) 

(z)))) 

(elt (aref seqarr 0) 1) => B 

(elt (aref seqarr 1) 1) => E 

(setf (elt (aref seqarr 0) 1) 'g) => G 

(aref seqarr 1) => #(D G F) 
For a table of related items: See the section "Sequence Construction and Access". 

(flavorrmethod :empty-p sirheap) Method 

Returns t if the heap is empty, otherwise returns nil. 

For a table of related items: See the section "Heap Functions and Methods". 

si:enable-who-calls &optional mode Function 

mode describes how the who-calls database should record the callers of any func- 
tion. For more information about the who-calls database, see the section "Enabling 
the Who-Calls Database". 

rail If you want to include callers of the Symbolics-supplied soft- 

ware (that is, software contained in the distribution world) in 



Page 1075 



: all-remake 



:new 



: all-no-make 



rexplicit 



the database, use rail. This enables you to create the database 
once and then save it when you save the world. (When used 
with this argument, sirfull-gc would discard the existing 
database and then remake it). 

Includes callers of the Symbolics-supplied and site-specific soft- 
ware in the database. Use this if you do not want to perform a 
sirfull-gc. (When used with this argument, sirfull-gc would dis- 
card the existing database and then remake it). 

Enables the who-calls database to record the callers in any 
layered products, special software, or programs loaded into the 
world (after the site has been set). The Set Site command uses 
this argument by default, mew does not cause the callers of 
software in the distribution world to be recorded. 

Enables the who-calls database to record the callers in any 
layered products, special software, or programs loaded into the 
world (after the site has been set), and does not cause the 
callers of software in the distribution world to be recorded un- 
til sirfull-gc is performed. Once sirfull-gc is performed, those 
callers (for software in the distribution world) are recorded. 

If you want only explicitly-named files to be in the database, 
use the function sirenable-who-calls with the argument 
rexplicit. 



Noter Creating a full database takes a long time and about 2000 pages of storage. 



sirencapsulate function outer-function type body &optional extra-debugging-info 

Macro 

A call to sirencapsulate looks like: 

(si : encapsulate function-spec outer-function type 
body-form 
extra-debugging-info ) 

All the subforms of this macro are evaluated. In fact, the macro could almost be 
replaced with an ordinary function, except for the way body-form is handled. 

function-spec evaluates to the function spec whose definition the new encapsulation 
should become, outer-function is another function spec, which should often be the 
same one. Its only purpose is to be used in any error messages from 
sirencapsulate. 

type evaluates to a symbol that identifies the purpose of the encapsulation; it says 
what the application is. For example, it could be advise or trace. The list of possi- 
ble types is defined by the system because encapsulations are supposed to be kept 
in an order according to their type. See the variable sirencapsulation-standard- 
order. type should have an sirencapsulation-grind-function property that tells 
grindef what to do with an encapsulation of this type. 



Page 1076 



body-form is a form that evaluates to the body of the encapsulation-definition, the 
code to be executed when it is called. Backquote is typically used for this expres- 
sion. See the section "Backquote-Comma Syntax", sirencapsulate is a macro be- 
cause, while body is being evaluated, the variable sirencapsulated-function is 
bound to a list of the form (function uninterned-symbol) , referring to the unin- 
terned symbol used to hold the prior definition of function-spec. If sirencapsulate 
were a function, body-form would just get evaluated normally by the evaluator be- 
fore sirencapsulate ever got invoked, and so there would be no opportunity to bind 
sirencapsulated-function. The form body-form should contain 

(apply sirencapsulated-function arglist) somewhere if the encapsulation is to live 
up to its name and truly serve to encapsulate the original definition. (The variable 
arglist is bound by some of the code that the sirencapsulate macro produces auto- 
matically. When the body of the encapsulation is run, arglisfs value is the list of 
the arguments that the encapsulation received.) 

extra-debugging-info evaluates to a list of extra items to put into the debugging in- 
fo alist of the encapsulation function (besides the one starting with 
sirencapsulated-definition that every encapsulation must have). Some applications 
find this useful for recording information about the encapsulation for their own 
later use. 

When a special function is encapsulated, the encapsulation is itself a special func- 
tion with the same argument quoting pattern. (Not all quoting patterns can be 
handled; if a particular special form's quoting pattern cannot be handled, 
sirencapsulate signals an error.) Therefore, when the outermost encapsulation is 
started, each argument has been evaluated or not as appropriate. Because each en- 
capsulation calls the prior definition with apply, no further evaluation takes place, 
and the basic definition of the special form also finds the arguments evaluated or 
not as appropriate. The basic definition can call eval on some of these arguments 
or parts of them; the encapsulations should not. 

Macros cannot be encapsulated, but their expander functions can be; if the defini- 
tion of function-spec is a macro, then sirencapsulate automatically encapsulates the 
expander function instead. In this case, the definition of the uninterned symbol is 
the original macro definition, not just the original expander function. It would not 
work for the encapsulation to apply the macro definition. So during the evaluation 
of body-form, sirencapsulated-function is bound to the form (cdr (function unin- 
terned-symbol)), which extracts the expander function from the prior definition of 
the macro. 

Because only the expander function is actually encapsulated, the encapsulation 
does not see the evaluation or compilation of the expansion itself. The value re- 
turned by the encapsulation is the expansion of the macro call, not the value com- 
puted by the expansion. 



sirencapsulation-standard-order Variable 

The value of this variable is a list of the allowed encapsulation types, in the order 
that the encapsulations are supposed to be kept in (innermost encapsulations first). 
If you want to add new kinds of encapsulations, you should add another symbol to 



Page 1077 



this list. Initially its value is: 

(advise breakon trace si : rename-within) 

advise encapsulations are used to hold advice, breakon and trace encapsulations 
are used for implementing tracing, sirrename-within encapsulations are used to 
record the fact that function specs of the form (rwithin within-function altered- 
function) have been defined. The encapsulation goes on within-function. See the 
section "Rename-Within Encapsulations". 

endp object Function 

Tests for the end of a list. Returns nil when applied to a cons, and t when it is 
applied to nil. endp signals an error when object is not a cons or nil. 

Example: 

(endp '(heron loon sandpiper)) 
returns nil, since endp here is applied to a list. But: 

(endp ()) 
returns t, since endp is applied to an empty list. 

Under Cloe on the 386, endp signals an error, when the safety level is three, for 
an atomic argument other than nil. If the safety level is less than three, endp, de- 
pending upon the values of other optimization parameters, might signal an error 
when given inappropriate arguements. 

(setq a ' (a1 a2 a3 a4)) => (A1 A2 A3 A4) 

(endp a) => NIL 

(endp (cdddr a)) => NIL 

(endp (cddddr a)) => T 

Because of its type checking properties, endp is the preferred predicate when test- 
ing for the end of a list. 

(proclaim '(optimize (safety 3))) 
(defun my-reverse-1 ist( list ) 
"reverses a true list, endp signals error" 
" if arg is not true list." 
(let ((curcon nil) 
(ptr list)) 
(tagbody loop 

(unless (endp ptr) 

(setq curcon (cons (car ptr) curcon)) 
(setq ptr (cdr ptr)) 
(go loop))) 
curcon)) 

(my-reverse-1 ist ' (a b c d)) => (D C B A) 

=> (my-reverse-1 ist 'abed) 
ERROR: ARGUMENT NOT A LIST 



Page 1078 



For a table of related items: See the section "Predicates that Operate on Lists". 



closrensure-generic-function function-specifier &key : lambda-list -.argument- 
precedence-order .-declare .-documentation : generic- function-class .-method-combination 
.-method-class .-environment Function 

Defines a new generic function, or modifies an existing one. This function is part 
of the underlying implementation of closrdefgeneric and closrdefmethod. 
closrensure-generic-function returns the generic function object. 

function-specifier Either a symbol or a list of the form (future-common-lisp rsetf 
symbol); this names the generic function. 

keywords The keywords have the same semantics as the options docu- 

mented in closrdefgeneric. 

The rmethod-class and rgeneric-function-class keywords can 
be either class objects or names (in closrdefgeneric, they must 
be names). Symbolics CLOS supports only the value 
closrstandard-method for rmethod-class and the value 
closrstandard-generic-function for rgeneric-function-class. 

There is an additional keyword, renvironment, which is the 
same as the &environment argument to macro expansion 
functions. It is typically used to distinguish between compile- 
time and run-time environments. 

If function-specifier does not name a generic function (or any other kind of func- 
tion), then a new generic function is created. If function-specifier names an ordi- 
nary Lisp function, a macro, or a special form, an error is signaled. 

If function-specifier names an existing generic function, then that generic function 
is modified, according to the keyword arguments rargument-precedence-order, 
rdeclare, r documentation, rgeneric-function-class, rmethod-combination, and 
rmethod-class. If any of those keyword values differ from the corresponding op- 
tions in the generic function, then the keyword value replaces the existing option. 

If the rlambda-list keyword is unsupplied and the generic function already exists, 
then the existing lambda-list is left alone. If the rlambda-list keyword is unsup- 
plied and the generic function does not already exist, then the generic function is 
created with no lambda-list; the lambda-list will be created from the first method 
defined for the generic function. If the rlambda-list keyword is supplied with a 
value of nil, then the generic function accepts no arguments. 

An error is signaled if the value of rlambda-list is not congruent with the lambda- 
lists of all existing methods. 



&environment Lambda List Keyword 

This keyword is used with macros only. It should be followed by a single variable 
that is bound to an environment representing the lexical environment in which the 



Page 1079 



macro call is to be interpreted. This environment is not required to be the com- 
plete lexical environment; it should be used only with the function macroexpand 
for the sake of any local macro definitions that the macrolet construct may have 
established within that lexical environment. &environment is useful primarily in 
the rare cases where a macro definition must explicitly expand any macros in a 
subform of the macro call before computing its own expansion. 



:eof Message 

Indicates the end of data on an output stream. This is different from rclose be- 
cause some devices allow multiple data files to be transmitted without closing. 
rclose implies :eof when the stream is an output stream and the close mode is not 
rabort. 



eqxj Function 

Returns t if and only if x and y are the same object. Note that things that print 
the same are not necessarily eq to each other. In particular, numbers with the 
same value need not be eq, and two similar lists are usually not eq. Examples: 

(eq 'a 'b) => nil 

(eq 'a 'a) => t 

(eq (cons 'a 'b) (cons 'a 'b)) => nil 

(setq x (cons 'a 'b)) (eq x x) => t 

Note that in Symbolics Common Lisp and CLOE equal fixnums are eq; this is not 
true in Maclisp. Equality does not imply eqness for other types of numbers. To 
compare numbers, use =. 

eq is implemented by comparing pointers. Certain datatypes, such as small inte- 
gers and characters, can be stored locally in a pointer space. For these data ob- 
jects, the same number or character object will yield true when compared by eq. 
However, numbers with the same value are usually not the same object. Exercise 
caution in these cases. Consider this function when comparing numbers and char- 
acters. 

See the section "Numeric Comparisons". 



si:eq-hash-table Flavor 

Creates an old style Zetalisp hash table using the eq function for comparison of 
the hash keys. This flavor is superseded by table:basic-table. It accepts the follow- 
ing init options: 

:size Sets the initial size of the hash table in entries, as an integer. 

The default is 100 (decimal). The actual size is rounded up 
from the size you specify to the next size that is good for the 
hashing algorithm. An automatic rehash of the hash table 
might occur before this many entries are stored in the table 
depending upon the keys being stored. 



Page 1080 



:area Specifies the area in which the hash table should be created. 

This is just like the :area option to zhmake-array. See the 
function zhmake-array. The default is sysrworking-storage- 
area. 

rgrowth-factor Specifies how much to increase the size of the hash table when 

it becomes full. If it is an integer, the hash table is increased 
by that number. If it is a floating-point number greater than 
one, the new size of the hash table is the old size multiplied 
by that number. 

rrehash-before-coldCauses zl:disk-save to rehash this hash table if its hashing 
has been invalidated. (This is part of the before-cold initial- 
izations.) Thus every user of the saved world does not have to 
waste the overhead of rehashing the first time they use the 
hash table after cold booting. 

For eq hash tables, the hashing is invalidated whenever 
garbage collection or world compression occurs because the 
hash function is sensitive to addresses of objects, and those op- 
erations move objects to different addresses. For equal hash 
tables, the hash function is not sensitive to addresses of ob- 
jects that sxhash knows how to hash but it is sensitive to ad- 
dresses of other objects. The hash table remembers whether it 
contains any such objects. 

Normally a hash table is automatically rehashed "on demand" 
the first time it is used after the hashing has become invali- 
dated. This first :get-hash operation is therefore much slower 
than normal. 

The :rehash-before-cold option should be used on hash tables 
that are a permanent part of your world, likely to be saved in 
a world saved by zl:disk-save, and to be touched by users of 
that world. This applies both to hash tables in Genera and to 
hash tables in user-written subsystems saved in a world. 



eql x y Function 

Returns t if its arguments are eq, if they are numbers of the same type with the 
same value, or if they are character objects that represent the same character. 
The predicate = compares the values of two numbers even if the numbers are of 
different types. 

Examples: 



Page 1081 



(eql 'a 'a) => t 

(eql 3 3) => t 

(eql 3 3.0) => nil 

(eql 3.0 3.0) => t 

(eql #/a #/a) => t 

(eql (cons 'a 'b) (cons 'a 'b)) => nil 

(eql "foo" "F00") => nil 

The following expressions might return either t or nil: 



(eql '(a . b) '(a 
(eql "foo" "foo") 



b)) 



In Symbolics Common Lisp: 

(eql 1 .0s0 1 .0d0) => nil 
(eql 0.0 -0.0) => nil 



equal x y 



Function 



Returns t if its arguments are structurally similar (isomorphic) objects. If the two 
objects are eql, then they are also equal. If the objects are of different data types, 
then they are not equal. 

Objects of each data type are compared differently for equal, equal returns t in 
the following cases: 



Conses 
Strings 

Bit-vectors 

Numbers 

Characters 

Symbols 

Arrays 

Pathnames 



The two cars are equal and the two cdrs are equal. 

The strings are of the same length, and corresponding charac- 
ters of each string are char=. 

The vectors are of the same length, and corresponding ele- 
ments of each vector are =. 

The numbers are eql; that is, they must have the same type 
and the same value. 

The characters are eql; that is, they must be character objects 
representing the same character. The code and bits information 
are taken into account for equal, but font information is not. 

The symbols are eq; that is, they must be addressing the same 
memory location. 

The arrays are eq; that is, they must be addressing the same 
array in memory. 

The pathname objects are equivalent; that is, all of the corre- 
sponding components (host, device, directory name, and so on) 
are the same. The sensitivity of the case of the pathname ob- 
ject is dependent on the file naming conventions of the file 
system the pathname object resides in. 



Page 1082 



For example: 

(equal 'a 'a) => T 

(equal 'a 'b) => NIL 

(equal 3.0 3.0) => T 

(equal 3 3.0) => NIL 

(equal #c(3 -4.0) #c(3 -4)) => NIL 

(equal ' (a . b) ' (a . b)) => T 

(equal (cons 'a 'b) (cons 'a 'c)) => NIL 

(progn (setq x '(a . b)) (equal x x )) => T 

(equal #\A #\a) => NIL 

(equal #\A #\A) => T 

(equal #\c-A #\A) => NIL 

(equal "Foo" "Foo") => T 

(equal "FOO" "foo") => NIL 

An intuitive definition, which is not quite correct, is that two objects are equal if 
their printed representation is the same. For example: 

(setq a '(1 2 3)) 
(setq b '(1 2 3)) 
(eq a b) => NIL 
(equal a b) => T 

(setq a 'a) => A 
(setq b a) => A 
(equal a b) => T 



zhequal x y Function 

Returns t if its arguments are similar (isomorphic) objects. See the function eq. 
Two numbers are zhequal if they have the same value and type (for example, a 
flonum is never zhequal to an integer, even if = is true of them). For conses, 
zhequal is defined recursively as the two cars being zhequal and the two cdrs be- 
ing equal. Two strings are zhequal if they have the same length, and the charac- 
ters composing them are the same. See the function string-equal. Alphabetic case 
is ignored. All other objects are zhequal if and only if they are eq. Thus zhequal 
could have been defined by: 

(defun zl : equal (x y) 
(cond ((eq x y) t) 

((neq (typep x) (typep y)) nil) 
((numberp x) (= x y)) 
((stringp x) (string-equal x y)) 
((listp x) (and (equal (car x) (car y)) 

(equal (cdr x) (cdr y)))))) 

As a consequence of the above definition, it can be seen that zhequal may com- 
pute forever when applied to looped list structure. In addition, eq always implies 
zhequal; that is, if (eq a b) then (zhequal a b). An intuitive definition of 



Page 1083 



zlrequal (which is not quite correct) is that two objects are zlrequal if they look 
the same when printed out. For example: 

(setq a '(1 2 3)) 

(setq b '(1 2 3)) 

(eq a b) => nil 

(zl : equal a b) => t 

(zl : equal "Foo" "foo") => t 



si:equal-hash x Function 

Computes a hash code of an object, and returns it as an integer. A property of 
si:equal-hash is that (equal x y) always implies (= (si:equal-hash x) (sirequal- 
hash y)). The number returned by si:equal-hash is always a nonnegative integer, 
possibly a large one. si:equal-hash tries to compute its hash code in such a way 
that common permutations of an object, such as interchanging two elements of a 
list or changing one character in a string, always changes the hash code. 

si:equal-hash uses %pointer to define the hash key for data types such as arrays, 
stack groups, or closures. This means that some of the hash keys in equal hash 
tables are based on a virtual memory address. Hash tables that are at all depen- 
dent on memory addresses are rehashed when the garbage collector flips. 

si:equal-hash returns a second value (t, rdynamic or nil), if it has used %pointer 
to define the hash key. 

Value meaning 

nil Returned if the hash does not depend on the virtual address of 

the object being hashed. 

rdynamic Returned if the hash depends on the virtual address, but none 

of the dependent addresses are ephemeral. That is, if rdynamic 
is returned, future calls to sirequal-hash for the same object 
might not return the same number if an intervening dynamic 
GC occurs. 

t Returned if the hash depends on the virtual address and at 

least one of the virtual addresses is ephemeral. That is, if t is 
returned, future calls to sirequal-hash for the same object 
might not return the same number if an intervening ephemeral 
GC occurs. The value t is the strongest and must be preserved 
when merging more than one result. 

For example, if running-flag is the merged flag that will eventually be returned, 
the following form will efficiently do a hash/merge step: 

(multiple-value-bind (hash flag) (si : equal -hash object) 
;; t is strongest, rdynamic next, do it fast 
(setq running-flag (or (eq flag 't) running-flag flag)) 
hash) 



Page 1084 



Here is an example of how to use si:equal-hash in maintaining hash tables of ob- 
jects: 

(defun knownp (x &aux i bkt) ;look up x in the table 
(setq i (remainder (si : equal -hash x) 176)) 

;The remainder should be reasonably randomized, 
(setq bkt (aref table i)) 

;bkt is thus a list of all those expressions that 

;hash into the same number as does x. 
(memq x bkt)) 

To write an "intern" for objects, one could: 

(defun sintern (x &aux bkt i tern) 

(setq i (remainder (si : equal -hash x) 2n-1)) 
;2n-1 stands for a power of 2 minus one. 
;This is a good choice to randomize the 
; result of the remainder operation, 
(setq bkt (aref table i)) 
(cond ((setq tern (memq x bkt)) 
(car tern)) 
(t (aset (cons x bkt) table i) 
x))) 

For a table of related items: See the section "Table Functions". 



si:equal-hash-table Flavor 

Creates an old style Zetalisp hash table using the zhequal function for comparison 
of the hash keys. This flavor is superseeded by table:basic-table. It accepts the 
following init option as well as those described for eq hash tables. See the flavor 
si:eq-hash-table. 

rrehash-threshold Specifies how full the table can be before it must grow. This is 
typically a flonum. The default is 0.8, which represents 80 
percent. 



equal-typep typel type2 Function 

Returns t if typel and type2 are equivalent and denote the same data type. For the 
standard type specifiers in Symbolics Common Lisp, see the section "Type Specifier 
Symbols". 

Examples: 



Page 1085 



(equal -typep 'bit '(unsigned-byte 1)) => T 

(equal -typep 'double-float 'long-float) => T 

(equal-typep 'bit '(integer 1)) => T 

(equal-typep 'short-float 'single-float) => T 

(equal-typep 'pathname 'complex) => NIL 



equalp x y Function 

Two objects are equalp if they are equal. Objects that have components are 
equalp if they are of the same type and corresponding components are equalp. 

equalp differs from equal when it compares characters, strings and arrays, equalp 
returns t for character objects when they satisfy char-equal, char-equal ignores 
case, as well as font information. For example: 

(equalp #\A #\a) => T 
(equalp #\A #\A) => T 
(equalp #\c-A #\A) => NIL 

equalp returns t for arrays when they have the same dimensions, the dimensions 
match, and the corresponding elements are equalp. A string and a general array 
that happens to contain some characters will be equalp even though it is not 
equal. If either argument has a fill pointer, the fill pointer limits the number of 
elements examined by equalp. Because equalp performs element-by-element com- 
parisons of strings and ignores the alphabetic case of characters, case distinctions 
are also ignored when equalp compares strings. For example: 

(setq string "Any Random String") => "Any Random String" 

(setq array (make-array 17 : initial-contents "any random string")) 

=> #<ART-Q-17 40102625> 
(equalp string array) => T 

(equalp 3 3.0) => t 
(equalp "Abe" "abc") => t 



error format-string &rest format-args Function 

Signals conditions that are not proceedable. 

error takes three possible argument lists, as follows: 

error {format-string &rest format-args} 

or 

error {condition &rest init-options} 

or 

error {condition-object} 

Case 1: 



Page 1086 



When error is called with format-string and format-args, under Genera it signals a 
zhferror condition. Under CLOE Runtime system, it signals simple-error created 
by the following code: 

(MAKE-CONDITION 'SIMPLE-ERROR 
: FORMAT-STRING datum 
: FORMAT-ARGUMENTS arguments) 

format-string is given as a control string to format along with format-args to con- 
struct an error message string. 

Case 2: 

When called with the arguments condition and init-options, a condition of type con- 
dition with init options as specified by init-options is created and is signalled. 

condition is the name of a condition flavor. 

init-options are the init options specified when the error object is created; they are 
passed in the :init message. 

Used this way, error is similar to signal but restricted as follows: 

• error sets the proceed types of the error object to nil so that it cannot be pro- 
ceeded. 

• If no handler exists, the Debugger assumes control, whether or not the object is 
an error object. 

• error never returns to its caller. 

Compatibility Note: The arguments condition and init-options are Symbolics exten- 
sions to Common Lisp. 

Case 3: 

In the third and more advanced form of error, condition-object can be a condition 
object that has been created with make-condition but not yet signalled. In this 
case, init-options is ignored. 

Note: The argument condition-object is a Symbolics extension to Common Lisp. 

For compatibility with the old Maclisp error function, error tries to determine 
that it has been called with Maclisp-style arguments and turns into an zhfsignal 
or zhferror as appropriate. If condition is a string or a symbol that is not the 
name of a flavor, and error has no more than three arguments, error assumes it 
was called with Maclisp-style arguments. 

Note that in CLOE, if typep condition cloe::*break-on-signals* is true, then the 
debugger will be entered prior to beginning the signalling process. The signalling 
process can be continued using the continue restart. This is true also for all other 
functions and macros which signal errors, such as cerror, assert, and check-type. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



Page 1087 



*error-message-hook* Variable 

This variable lets you customize the error message printed by the Debugger. 

You can bind *error-message-hook* to a one-argument function. Before printing 
an error message the Debugger checks the value of *error-message-hook*; if this 
variable is bound to a non-nil value, the Debugger evaluates it and displays the re- 
sult at the end of the Debugger message. 

Examples: 

(defun my-error-hook () 

(format t "This is the error hook")) 
(setq dbg:*error-message-hookx 'dbg:my-error-hook) 



(defun get-plists (1 ist-of-objects) 
(let ((dbg:*error-message-hookx 
(lambda () 

(format t "While getting properties of ~S" 1 ist-of-objects)))) 
(symbol-pl ist 1 ist-of-objects))) => GET-PLISTS 

(get-pl ists ' (a b c)) 



Trap: The argument given to the SYS:PROPERTY-CELL-LOCATION instruction, (ABC), 

was not a symbol . 
While getting properties of (A B C) 

SYMBOL-PLIST: 

Arg (SYMBOL) : (ABC) 
s-A, <RESUME>: Supply replacement argument 



s-B 
s-C 
s-D 



Return a value from the PROPERTY-CELL-LOCATION instruction 
Retry the PROPERTY-CELL-LOCATION instruction 
<AB0RT>: Return to Lisp Top Level in Dynamic Lisp Listener 1 
— > Resume Proceed 
Supply replacement argument 

Form to evaluate and use as replacement argument: 
' integer 

(ZWEI:ZMACS-BUFFERS ((: SAGE-TYPE-SPECIFIER-RECORD #<SECTI0N-N0DE Sage Type 
Specifier Record INTEGER 254116776>)) 



*error-output* Variable 

The value is a stream to which error messages should be sent. Normally, this is 
the same as *standard-output*, but *standard-output* might be bound to a file 
and *error-output* left going to the terminal or a separate file of error messages. 



Page 1088 



(with-open-stream (outstream "myfile" :di recti on :output) 
(let ((xstandard-outputx outstream) 



(xerror-outputx outstream)) 
(fun-1 ikely-to-signal-an-error)) 



redirects xerror-outputx to myfile. lisp 
capture any error messages in file 
end of let restores xerror-outputx, etc. 
more forms 
;end of with-open-f ile closes file 



zherror-output Variable 

In your new programs, we recommend that you use the variable *error-output* 
which is the Common Lisp equivalent of zherror-output. See *error-output*. 



error-restart (flavors description &rest args) &body body Special Form 

This form establishes a restart handler for flavors and then evaluates body. If the 
handler is not invoked, error-restart returns the values produced by the last form 
in body and the restart handler disappears. When the restart handler is invoked, 
control is thrown back to the dynamic environment inside the error-restart form 
and execution of body starts all over again. The format is: 

(error-restart (flavors description) 
form-1 
form-2 

...) 

flavors is either a condition or a list of conditions that can be handled, description 
is a list of arguments to be passed to format to construct a meaningful description 
of what would happen if the user were to invoke the handler, args are evaluated 
when the handler is bound. The Debugger uses these values to create a message 
explaining the intent of the restart handler. 

For a table of related items: See the section "Restart Functions". 



error-restart-loop (flavors description &rest args) &body body 

Special Form 

Establishes a restart handler for flavors and then evaluates the body. If the han- 
dler is not invoked, error-restart-loop evaluates the body again and again, in an 
infinite loop. Use the return function to leave the loop. This mechanism is useful 
for interactive top levels. 

If a condition is signalled during the execution of the body and the restart handler 
is invoked, control is thrown back to the dynamic environment inside the error- 
restart-loop form and execution of the body is started all over again. The format 
is: 



Page 1089 



(error-restart-loop (flavors description) 
form-1 
form-2 

flavors is either a condition or a list of conditions that can be handled, description 
is a list of arguments to be passed to format to construct a meaningful description 
of what would happen if the user were to invoke the handler. The Debugger uses 
these values to create a message explaining the intent of the restart handler. 

For a table of related items: See the section "Restart Functions". 



errorp thing 

Function 

Determines if thing is an error object; returns t if it is, and nil otherwise, 
(errorp x) <=> (typep x 'error) 

For a table of related items, see the section "Condition-Checking and Signalling 
Functions and Variables". 

errorp thing 

Function 

Determines if thing is an error object; returns t if it is, and nil otherwise, 
(errorp x) <=> (typep x 'error) 

For a table of related items, see the section "Condition-Checking and Signalling 
Functions and Variables". 

etypecase object &body body Special Form 

The name of this function stands for "exhaustive type case" or "error-checking type 
case", etypecase is similar to typecase, except that it does not allow an explicit 
otherwise or t clause, and it signals a non-continuable error instead of returning 
nil if no clause is satisfied. 

etypecase is a conditional that chooses one of its clauses by examining the type of 
an object. Its form is as follows: 

(etypecase form 

(types consequent consequent ...) 
(types consequent consequent ...) 

) 

First etypecase evaluates form, producing an object, etypecase then examines 
each clause in sequence, types in each clause is a type specifier in either symbol or 
list form, or a list of type specifiers. The type specifier is not evaluated. If the ob- 



Page 1090 



ject is of that type, or of one of those types, then the consequents are evaluated 
and the result of the last one is returned (or nil if there are no consequents in 
that clause). Otherwise, etypecase moves on to the next clause. 

If no clause is satisfied, etypecase signals an error with a message constructed 
from the clauses. It is not permissible to continue from this error. To supply your 
own error message, use typecase with an otherwise clause containing a call to 
error. 

For an object to be of a given type means that if typep is applied to the object 
and the type, it returns t. That is, a type is something meaningful as a second ar- 
gument to typep. 

See the section "Data Types and Type Specifiers". 

It is permissible for more than one clause to specify a given type, particularly if 
one is a subtype of another; the earliest applicable clause is chosen. Thus, for 
etypecase, the order of the clauses can affect the behavior of the construct. 

Examples: 

(defun tel 1-about-car (x) 
(etypecase (car x) 

(string "string"))) => TELL-ABOUT-CAR 
(tel 1-about-car '("word" "more")) => "string" 
(tel 1-about-car '(a 1)) => non-proceedable error is signalled 

(defun tel 1-about-car (x) 
(etypecase (car x) 

(fixnum "The car is a number.") 

((or string symbol) "symbol or string") 

(otherwise "I don't know."))) => TELL-ABOUT-CAR 
(tel 1-about-car '(1 a)) => "The car is a number." 
(tel 1-about-car '(a 1)) => "symbol or string" 
(tel 1-about-car '("word" "more")) => "symbol or string" 
(tel 1-about-car '(1.0)) => "I don't know." 

For a table of related items: See the section "Conditional Functions". 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



eval form &optional env Function 

Evaluates form, and returns the result. Example: 

(setq x 43 foo 'bar) 
(eval (list 'cons x 'foo)) 
=> (43 . bar) 

It is unusual to explicitly call eval, since usually evaluation is done implicitly. If 
you are writing a simple Lisp program and explicitly calling eval, you are probably 
doing something wrong, eval is primarily useful in programs that deal with Lisp 
itself. 



Page 1091 



Also, if you are only interested in getting at the value of a symbol (that is, the 
contents of the symbol's value cell), then you should use the primitive function 
symbol-value. 

The actual name of the compiled code for eval is "si:*eval" because use of the 
evalhook feature binds the function cell of eval. 

Compatibility Note: The optional argument env, which defaults to the null lexical 
environment, is a Symbolics extension to Common Lisp. You cannot use Env in 
most other implementations of Common Lisp including CLOE Runtime. See the 
section "Some Functions and Special Forms". 



sys:eval-in-instance instance form Function 

Evaluates form in the lexical environment of instance. The following form returns 
the sum of the instance variables x and y of the instance this-box-with-cell: 

(sys:eval-in-instance this-box-with-cell ' (+ x y)) 
=> 6 

You can use setq to modify an instance variable; this is often useful in debugging. 
If you need to evaluate more than one form in the lexical environment of the in- 
stance, you can use sysrdebug-instance: See the function sysrdebug-instance. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



eval-when times-list &body forms Function 

Allows you to tell the compiler exactly when the body forms should be evaluated. 
times-list can contain one or more of the symbols load, compile, or eval, or can be 
nil. 

The interpreter evaluates the body forms only if the times-list contains the symbol 
eval; otherwise eval-when has no effect in the interpreter. 

If symbol is present Then forms are 

load Written into the compiled code file to be evaluated when 

the compiled code file is loaded, with the exception that 
defun forms put the compiled definition into the compiled 
code file. 

compile Evaluated in the compiler. 

eval Ignored by the compiler, but evaluated when read into the 

interpreter (because eval-when is defined as a special 
form there). 

Example 1: Normally, top-level special forms such as defprop are evaluated at load 
time. If some macro expansion depends on the existence of some property, for ex- 
ample, constant-value, the definition of that property must be wrapped inside an 



Page 1092 



(eval-when (compile) ...) so that the property is available at compile (macro ex- 
pansion) time. 

(eval-when (compile load eval) 
(defprop three 3 constant-value)) 

Example 2: eval-when should be used around defconstants of complex expressions. 
This is because the compiler does not maintain an environment acceptable to eval 
containing defconstants 

(eval-when (compile load eval) 
(def constant name expr)) 

In other words, if you are sure that (1) evaluating the expr in the global environ- 
ment gives the correct results, and (2) that no harm is done by changing the cur- 
rent environment to have the (possibly new) value of name, then you can use the 
global environment as a substitute for the compilation environment. 



evenp integer Function 

Returns t if integer is even, otherwise nil. If integer is not an integer, evenp sig- 
nals an error. 

(evenp 1) => nil 

(evenp 0) => t 

(evenp (* 2 (random n))) => t 

See the section "Numeric Property-checking Predicates". 

For a table of related items, see the section "Numeric Property-checking Predi- 
cates". 



every predicate sequence &rest more-sequences Function 

Returns nil as soon as any invocation of predicate returns nil. predicate must take 
as many arguments as there are sequences provided, predicate is first applied to 
the elements of the sequences with an index of 0, then with an index of 1, and so 
on, until a termination criterion is reached or the end of the shortest of the se- 
quences is reached. If the end of a sequence is reached, every returns a non-nil 
value. Thus considered as a predicate, it is true if every invocation of predicate is 
true. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(every tf'oddp '(1 3 5)) => T 

(every tf'equal '(1 2 3) '(3 2 1)) => NIL 

(setq limit-value 1024 sequence (vector 16 64 512 128 32)) 



Page 1093 



(every #' (lambda (x) (<= x limit-value)) sequence) => t 

If predicate has side effects, it can count on being called first on all those ele- 
ments with an index of 0, then all those with an index of 1, and so on. 

For a table of related items: See the section "Predicates that Operate on Lists". 

For a table of related items: See the section "Predicates that Operate on Se- 
quences". 



zhevery list pred &optional (step #'cdr) Function 

Returns t if pred returns non-nil when applied to every element of list, or nil if 
pred returns nil for some element. If step-function is specified, it replaces # 'cdr as 
the function used to get to the next element of the list; # 'cddr is a typical func- 
tion to use here. For example: 

(zl :every '(1 3 5) tf'oddp) => T 

(zl: every '(1 2 3 4 5) tf'oddp) => NIL 

(zl: every '(1 2 3 4 5) tf'oddp tf'cddr) => T 

For a table of related items: See the section "Predicates that Operate on Lists". 

For a table of related items: See the section "Predicates that Operate on Se- 
quences". 

exp number Function 

Returns e raised to the numberth power, where e is the base of natural logarithms. 
If number is an integer or a single-float, the result is converted to a single-float; if 
it is a double-float, the result is double-float. 

Examples: 

(exp 1) => 2.7182817 

(exp #c(0 -3)) => #C(-0. 9899925 -0.14112002) 

(exp 0.08) => 1 .083 

(exp 2) => 7.389 

For a table of related items: See the section "Powers of e and Log Functions". 

zhexplode x Function 

Returns a list of characters represented by symbols that are the characters that 
would be typed out by (prinl x) (that is, the slashified printed representation of x). 
Example: 

(zl: explode ' (+ /12 3)) => (|(| + I I /| |1| |2| /| | | |3| |)|) 

(Note that there are slashified spaces in the above list.) 



Page 1094 



zhexplodec x Function 

Returns a list of characters represented by symbols that are the characters that 
would be typed out by (princ x) (that is, the unslashified printed representation of 
x). Example: 

(zl:explodec ' (+ /12 3)) => (|(| + I I Ml |2| | | |3| |)|) 



zhexploden x Function 

Returns a list of characters (as integers) that are the characters that would be 
typed out by (princ x) (that is, the unslashified printed representation of x). Ex- 
ample: 

(zl :exploden ' (+ /12 3)) => (#/( #/+ tf/Space #/1 #/2 tf/Space #/3 ft/)) 



export symbols &optional package Function 

The symbols argument should be a list of symbols or a single symbol. If symbols is 
nil, it is treated like an empty list. These symbols become available as external 
symbols in package, package can be a package object or the name of a package (a 
symbol or a string). If unspecified, package defaults to the value of *package*. Re- 
turns t. The rexport option to defpackage and make-package is equivalent. 

The following bit of code uses intern with multiple-value-bind to create a new 
symbol or determine the status of an old one. If the status of the interned symbol 
is rinternal, then the symbols is exported. 

=> (multiple-value-bind (symbol status) (intern "new-symbol") 
(when (or (null status) (eq status ':internal)) 
(export symbol))) 
=> T 

If "new-symbol" is truly a new symbol, then intern would have made it an internal 
symbol. If we now execute the following code on "new-symbol", we will see that it 
is now an external symbol, since it has been exported. 

=> (multiple-value-bind (symbol status) (find-symbol "new-symbol") 

status) 
=> : EXTERNAL 



expt base-number power-number Function 

Computes and returns base-number raised to the power power-number. If the base- 
number is of type rational and the power-number is an integer, the calculation is 
exact (using the rule of rational canonicalization where applicable), and the result 
is of type rational; otherwise, a floating-point approximation may result. 

If power-number is zero of type integer, the result is the value one in the type of 
base-number. This is true even if base-number is zero of any type. If power-number 
is a zero of any other data type, the result is the value one, in the type of the ar- 



Page 1095 



guments after the application of the coercion rules, except as follows. An error re- 
sults if the base-number is zero and the power-number is a zero not of type integer. 

If base-number is negative and power-number is not an integer, the result of expt 
can be complex, even though neither argument is complex, expt always returns the 
principal complex value. 

Complex canonicalization is applied to complex results. 

Examples: 

(expt 2 3) => 8 

(expt .5 3) => 0.125 

(expt -49 1/2) => #c(0 7) ;the principal value 

(expt 1/2 -2) => 4 

(expt 2. 0) => 1 

(expt 56) => 

(expt 3/2) => 

(expt 0.0 5) => 0.0 

(expt 0.0 #c(3 4)) => 0.0 

(expt #c(0 7) 2) => -49 

For a table of related items, see the section "Arithmetic Functions". 



zhexpt num expt Function 

Returns num raised to the exptth power. The result is an integer if both argu- 
ments are integers (even if expt is negative!) and floating-point if either num or 
expt or both is floating-point. If the exponent is an integer a repeated-squaring al- 
gorithm is used, while if the exponent is floating the result is (zhexp (* expt (log 
num))). 

(expt 3/5 2) -> 9/25 

(expt 4 3) -> 64 

(expt (exp 1) 2) -> 7.389 
The following functions are synonyms of zhexpt: 

zl:- 
zl:"$ 

For a table of related items: See the section "Arithmetic Functions" and see CLtL 
203. 



sys:external-symbol-not-found Flavor 

A ":" qualified name referenced a name that had not been exported from the speci- 
fied package. 



Page 1096 



The rstring message returns the name being referenced (no symbol by this name 
exists yet). The rpackage message returns the package. 

The rexport proceed type exports a symbol by that name and uses it. 



false &rest ignore Function 

Takes no arguments and returns nil. See the section "Functions and Special Forms 
for Constant Values". 



fboundp symbol Function 

Returns t if symbol's function cell contains a function definition, or if symbol 
names a special form or a macro. Otherwise it returns nil. Since fboundp returns 
t for special forms and macros, if you want to check for these cases use special- 
form-p or macro-function. 

(fboundp alarm-handler) => nil 

(defun alarm-handler () 
(setq xalarmsx 0)) 

(fboundp 'alarm-handler) => t 
See the section "Functions Relating to the Function Cell of a Symbol". 



fceiling number &optional (divisor 1) Function 

Like ceiling, except that the first returned value is always a floating-point number 
instead of an integer. The second returned value is the remainder. If number is a 
floating-point number and divisor is not a floating-point number of longer format, 
then the first returned value is a floating-point number of the same type as num- 
ber. 

Returns the floating point equivalent of the least integer greater than or equal to 
number; or, in the case of a supplied second argument, returns the floating point 
equivalent of the least integer greater than or equal to number divided by divisor. 
A second value, the remainder, is also returned. The remainder returned is the 
same as that returned by ceiling applied to the same arguments. 

Examples: 

(fceiling 5) => 5.0 and 
(fceiling -5) => -5.0 and 
(fceiling 5.2) => 6.0 and -0.8000002 
(fceiling -5.2) => -5.0 and -0.19999981 
(fceiling 5 3) => 2.0 and -1 
(fceiling -5 3) => -1.0 and -2 
(fceiling 5.2 4) => 2.0 and -2.8000002 



Page 1097 



(fceiling -5.2 4) => -1.0 and -1.1999998 

(f ceiling 4.2d0) => 5.0d0 and -0. 7999999999999998d0 

(fceiling -4.2d0) => -4.0d0 and -0.20000000000000018d0 

For a table of related items: See the section "Functions that Divide and Return 
Quotient as Floating-point Number". 

fdefine function-spec definition &optional carefully-flag no-query-flag Function 

The primitive that defun and everything else in the system use to change the def- 
inition of a function spec. If carefully is non-nil, which it usually should be, only 
the basic definition is changed, the previous basic definition is saved if possible 
(see undefun), and any encapsulations of the function such as tracing and advice 
are carried over from the old definition to the new definition, carefully also causes 
the user to be queried if the function spec is being redefined by a file different 
from the one that defined it originally. However, this warning is suppressed if ei- 
ther the argument no-query is non-nil, or if the global variable sysrinhibit-fdefine- 
warnings is t. 

If fdefine is called while a file is being loaded, it records what file the function 
definition came from so that the editor can find the source code. 

If function-spec was already defined as a function, and carefully is non-nil, the 
function-spec's rprevious-definition property is used to save the previous defini- 
tion. If the previous definition is an interpreted function, it is also saved on the 
:previous-expr-definition property. These properties are used by the undefun 
function, which restores the previous definition, and the uncompile function, 
which restores the previous interpreted definition. The properties for different 
kinds of function specs are stored in different places; when a function spec is a 
symbol its properties are stored on the symbol's property list. 

defun and the other function-defining special forms all supply t for carefully and 
nil or nothing for no-query. Operations that construct encapsulations, such as 
trace, are the only ones that use nil for carefully. 



sys:fdefine-file-pathname Variable 

While loading a file, this is the generic pathname for the file. The rest of the time 
it is nil. fdefine uses this to remember what file defines each function. 



fdefinedp function-spec Function 

This returns t if function-spec has a definition, or nil if it does not. 

fdefinition function-spec Function 

Returns function-spec's definition. If it has none, an error occurs. You can use setf 
with fdefinition. 



Page 1098 



sysrfdefinition-location function-spec &optional for-compiler Function 

Returns a locative pointing at the cell that contains function-spec's definition. For 
some kinds of function specs, though not for symbols, this can cause data struc- 
ture to be created to hold a definition. For example, if function-spec is of the 
rproperty kind, then an entry might have to be added to the property list if it 
isn't already there. In practice, you should write (locf (fdefinition function-spec)) 
instead of calling this function explicitly. 



*features* Variable 

Returns a list of symbols indicating features of the Lisp environment. The default 
list for Genera is: 

(:DEFSTORAGE : DEBUG-SCHEDULER-QUEUES : NEW-SCHEDULER :L00P 
DEFSTRUCT :LISPM : SYMBOLICS : GENERA : ROW-MAJOR machine-type 
CHAOS : IEEE-FLOATING-POINT :S0RT :FASL0AD :STRING :NEWI0 
ROMAN :TRACE :GRINDEF :GRIND) 

The value of this list is kept up to date as features are added or removed from the 
Genera system. Most important is the symbol machine-type; this is either 3600 or 
rimach and indicates on which type of Symbolics machine the program is running. 
The order of this list should not be depended on, and might not be the same as 
shown above. 

Features SYMBOLICS and CLOE are present in both the CLOE Developer and the 
CLOE Application Generator. Feature CLOE-DEVELOPER is present only in the CLOE 
Developer, and feature CLOE-RUNTIME is present only in the Application Generator. 

xfeaturesx => 

(:CLOE-RUNTIME :L00P :INTEL-386 :UNIX-V3 :CL0E : IEEE-FLOATING-POINT 

:SYMBOLICS) 



zhferror format-string &rest format-args Function 

Signals when you do not care what the condition is. zhferror signals the condition 
zhferror. (See the flavor zhferror.) The arguments are passed as the rformat- 
string and :format-args init keywords to the error object. 

The old (zhferror nil ...) syntax continues to be accepted for compatibility reasons 
indefinitely; the nil is ignored. An error is signalled if the first argument is a 
symbol other than nil; the first argument must be nil or a string. 

Note: zhferror is an obsolete function. Use error instead in your new programs. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 



ffloor number &optional (divisor 1) Function 



Page 1099 



Like floor, except that the first returned value is always a floating-point number 
instead of an integer. The second returned value is the remainder. If number is a 
floating-point number and divisor is not a floating-point number of longer format, 
then the first returned value is a floating-point number of the same type as num- 
ber. 

Examples: 

(f floor 5) => 5.0 and 

(f floor -5) => -5.0 and 

(ffloor 5.2) => 5.0 and 0.19999981 

(f floor -5.2) => -6.0 and 0.8000002 

(ffloor 5 3) => 1 .0 and 2 

(ffloor -5 3) => -2.0 and 1 

(ffloor 5.2 4) => 1.0 and 1.1999998 

(ffloor -5.2 4) => -2.0 and 2.8000002 

(ffloor 4.2d0) => 4.0d0 and 0.20000000000000018d0 

(ffloor -4.2d0) => -5.0d0 and 0. 7999999999999998d0 

For a table of related items: See the section "Functions that Divide and Return 
Quotient as Floating-point Number". 

fifth list Function 

Returns the fifth element of the list list, fifth is equivalent to: 

(nth 4 list) 

For example: 

(setq letters '(abcdefgij))=> 
(A B C D E F G I J) 

(fifth letters) => E 
For a table of related items: See the section "Functions for Extracting from Lists". 



file-position stream &optional position Function 

Returns or sets the current position in a random-access file. When only stream is 
specified, returns a non-negative integer that indicates the current position within 
stream, or nil if this cannot be determined. (The file position at the start of a file 
is zero.) Ordinarily, the value returned by file-position increases by one each time 
an input or output operation is performed; however, performing a single read-char 
or write-char operation on a character file might increment the file position by 
more than one because of character-set translations. For a binary file, each read- 
byte or write-byte operation increases the file position by one. 

position sets the position in stream to position, position can be an integer, rstart 
for the beginning of the stream, or rend for the end of the stream. An error is 
signalled if the integer is too large for the file. (An integer returned by (file- 
position stream) should be usable as a value of position.) When position is speci- 
fied, file-position returns t if the repositioning was successful, nil if it was not. 



Page 1100 



(with-open-f ile (myfile "myfile.l isp" :di recti on :io) 
(file-position myfile :end) 

(format myfile "This string is appended at the end of: 
(namestring myfile))) 



fill sequence item &key (.start 0) send 

Function 

Destructively modifies sequence by replacing each element of the subsequence spec- 
ified by the rstart (which defaults to zero) and rend (which defaults to the length 
of the sequence) arguments with item. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

item can be any be any Lisp object, but must be a suitable element for sequence. 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, up to but 
not including the one specified by the rend index (defaults to length of sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(setq a-vector (vector 'a 'b 'c 'd 'e)) => #(A B C D E) 

(fill a-vector 'z : start 1 :end 3) => #(A Z Z D E) 

a-vector => #(A Z Z D E) 

(fill a-vector 'rah) => #(RAH RAH RAH RAH RAH) 

a-vector => #(RAH RAH RAH RAH RAH) 
For a table of related items: See the section "Sequence Modification". 

mathrfill-2d-array array list Function 

The opposite of mathrlist-2d-array. list should be a list of lists, with each element 
being a list corresponding to a row. array's elements are stored from the list. Un- 
like zlrfillarray, if list is not long enough, mathrfill-2d-array "wraps around", 
starting over at the beginning. The lists that are elements of list also work this 
way. 



Page 1101 



fill-pointer array Function 

Returns the value of the fill pointer, array must have a fill pointer, setf can be 
used on a fill-pointer form to set the value of the fill pointer. 

Under CLOE, if the new value of fill pointer in a setf command is greater thatn 
the array-total-size, a continuable error signals. 

Some other functions, notably vector-push and vector-pop, alter the value of the 
fill pointer. The value of the fill pointer can be set at the time the array is creat- 
ed by specifying a non-negative integer as the value of the keyword argument :fill- 
pointer. 

(setq astring (make-array 12 : element-type 'string-char : f il 1-pointer 0)) 

(fill-pointer astring) => 
(vector-push #\a astring) => 
astring => "a" 
(fill-pointer astring) => 1 

(setf (fill-pointer astring) 0) 

astring => "" 

(aref astring 0) => #\a 

(vector-push #\b astring) => 
astring => "b" 
aref astring 0) => #\b 
(fill-pointer astring) => 1 



zhfillarray array source Function 

Fills up array with the elements of source, array can be any type of array or a 
symbol whose function cell contains an array. Two forms of this function exist, de- 
pending on whether the type of source is a list or an array. 

If source is a list, then zhfillarray fills up array with the elements of list. If 
source is too short to fill up all of array, then the last element of source is used to 
fill the remaining elements of array. If source is too long, the extra elements are 
ignored. If source is nil (the empty list), array is filled with the default initial val- 
ue for its array type (nil or 0). 

If source is an array (or a symbol whose function cell contains an array), the ele- 
ments of array are filled up from the elements of source. If source is too small, 
then the extra elements of array are not affected, zhfillarray returns array. 

If array is multidimensional, the elements are accessed in row-major order: the 
last subscript varies the most quickly. The same is true of source if it is an array. 



rfilled-elements Message 



Page 1102 



Returns the number of entries in the hash table that have an associated value. 
This message is obsolete; use hash-table-count instead. 



finally keyword for loop 

finally expression 

Puts expression into the epilogue of the loop, which is evaluated when the 
iteration terminates (other than by an explicit return). For stylistic rea- 
sons, then, this clause should appear last in the loop body. Note that cer- 
tain clauses can generate code that terminates the iteration without run- 
ning the epilogue code; this behavior is noted with those clauses. See the 
section "Aggregated Boolean Tests for loop". This clause can be used to 
cause the loop to return values in a nonstandard way: 

(loop for n in 1 ; 1 is a list 

sum n into the-sum 
count t into the-count 
finally (return (quotient the-sum the-count))) 

(defun sum-series (limit) 

(loop for num from to limit 

with sum-of-series = 

initially (print "The sum of this series is :") 

do 
(setq sum-of-series (+ sum-of-series num)) 

finally (prinl sum-of-series))) => SUM-SERIES 
(sum-series 9) => 
"The sum of this series is :" 45 
NIL 

(defun over-the-top (num) 
(loop for i from 1 to 10 

when (= i num) return i 

finally (print "Finally triggered"))) => OVER-THE-TOP 
(over-the-top 5) => 5 
(over-the-top 20) => 
"Finally triggered" NIL 

See the macro loop. 



find item sequence &key (:test #'eql) :test-not (:key #'identity) :from-end (.start 0) 
send 

Function 

If sequence contains an element satisfying the predicate specified by the :test key- 
word argument, returns the leftmost, otherwise returns nil. 



Page 1103 



item is matched against the elements specified by the test keyword. The item can 
be any Symbolics Common Lisp object. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

:test specifies the test to be performed. An element of sequence satisfies the test if 
(funcall testfun item (keyfn x)) is true. Where testfun is the test function specified 
by :test, keyfn is the function specified by :key and x is an element of the se- 
quence. The default test is eql. 

:test-not is similar to :test, except that the sense of the test is inverted. An ele- 
ment of sequence satisfies the test if (funcall testfun item {keyfn x)) is false. 

For example: 

(find 'a '(abed) : test-not tf'eql) => B 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(find 'a '((a b) (a d) (b c)) :key tf'car) => (A B) 
(find 'a #((a b) (a d) (b a)) :key tf'cadr) => (B A) 

If the value of the :from-end keyword is non-nil, the result is the rightmost ele- 
ment satisfying the test. 

For example: 

(find 3 '((right 3) (west 2) (south 3)) :key tf'cadr :from-end t) => (SOUTH 3) 

You can delimit the portion of the sequence to be operated on by the keyword ar- 
guments rstart and rend. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(find 'A '(be a)) => A 

(find 'a ' (a b b) : start 1 :end 3) => NIL 

(find 'a '(abb) : start :end 3) => A 

(find 1 #(2 3 4 1) :end 4) => 1 

(find 1 #(2 3 4 1) :end 3) => NIL 

For a table of related items: See the section "Searching for Sequence Items". 



Page 1104 



find-all-symbols string Function 

Searches all packages for symbols named string and returns a list of them. Dupli- 
cates are removed from the list; if a symbol is present in more than one package, 
it only appears once in the list. The global package is searched first, and so global 
symbols appear earlier in the list than symbols that shadow them. In general pack- 
ages are searched in the order that they were created. 

string can be a symbol, in which case its name is used. This is primarily for user 
convenience when calling find-all-symbols directly from the read-eval-print loop. 

Under Genera, invisible packages are not searched. 

The where-is function under Genera is a more user-oriented version of find-all- 
symbols; it returns information about string, rather than just a list. For example: 



=> (make-symbol 'foo) 

tf:F00 

=> (make-symbol 'foo) 

tf:F00 

=> (setq x (make-symbol 'foo)) 

tf:F00 

=> (setq foo-list (f ind-al 1 -symbols x) 

(#:F00 #:F00 #:F00) 

=> (list-length foo-list) 

3 

Note that find-all-symbols is not in CLOE Runtime. 

For more information: See the section "Mapping Names to Symbols". 



(flavorrmethod :find-by-item sirheap) item &optional (equal-predicate #'=) Method 

Finds the first item that satisfies equal-predicate and returns the item and key if it 
was found; otherwise it signals si:heap-item-not-found. equal-predicate should be a 
function that takes two arguments. The first argument to equal-predicate is the 
current item from the heap and the second argument is item. 

For a table of related items: See the section "Heap Functions and Methods". 



(flavorrmethod :find-by-key sirheap) key &optional (equal-predicate #'=) Method 

Finds the first item whose key satisfies equal-predicate and returns the item and 
key if it was found; otherwise it signals si:heap-item-not-found. equal-predicate 
should be a function that takes two arguments. The first argument to equal- 
predicate is the current key from the heap and the second argument is key. 

For a table of related items: See the section "Heap Functions and Methods". 
closrfind-class class-name &optional errorp environment Function 



Page 1105 



Returns the class object named by class-name in the given environment. You can 
use setf with clos:find-class to change the class associated with the symbol class- 



name. 



class-name 



errorp 



environment 



A symbol to be the name of the class, or nil to remove the as- 
sociation between a class name and a symbol. 

A boolean value indicating what to do if there is no class ob- 
ject named class-name. A value of t causes an error to be sig- 
naled; this is the default. A value of nil causes nil to be re- 
turned. 

The same as the &environment argument to macro expansion 
functions. It is typically used to distinguish between compile- 
time and run-time environments. 



flavorrfind-flavor flavor-name &optional (error-p t) 



Function 



Determines whether a flavor is defined in the world. Returns non-nil if the flavor 
is defined. 

If the flavor is not defined and error-p is non-nil (or not supplied), flavorrfind- 
flavor returns nil. However, if the flavor is not defined and error-p is nil, 
flavorrfind-flavor signals an error. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



closrfind-method generic-function method-qualifiers specializers &optional errorp 

Generic Function 

Returns the method object that is identified by generic- function, method-qualifiers, 
and specializers. 

generic-function A generic function object. 



method-qualifiers 



specializers 



A list of the method's qualifiers. The order of method-qualifiers 
is significant. 

A list of the method's parameter specializers. This list must 
contain an element for each required argument to the generic 
function or else an error is signaled. The parameter specializer 
for any unspecialized parameter is the class named t. 

Note that CLOS distinguishes between a parameter specializer 
name (these appear in the closrdefmethod lambda-list) and the 
corresponding parameter specializer object. The specializers ar- 
gument consists of parameter specializer objects. There are two 
cases: the parameter specializer name is either a class name or 
a list such as (eql form). When the parameter specializer name 
is a class name, the corresponding object is the class object of 



Page 1106 



that name. When the parameter specializer name is a list such 
as (eql form), the corresponding object is the list (eql object), 
where object is the result of evaluating form. 

errorp A boolean value indicating what to do if there is no method. A 

value of t causes an error to be signaled; this is the default. A 
value of nil causes nil to be returned. 



find-if predicate sequence &key :key :from-end (.start 0) :end 

Function 

If sequence contains an element satisfying predicate, the leftmost such element is 
returned; otherwise nil is returned. 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(find-if #' atom '((a (b)) ((a) b) (nil nil)) : key #' second) 
=> ((A) B) 

If the value of the :from-end keyword is non-nil, the result is the rightmost ele- 
ment satisfying the test. 

For example: 

(find-if tf'numberp '(1 1 2 2) :from-end t) => 2 
(find-if tf'numberp '(1 1 2 2) :from-end nil) => 1 

You can delimit the portion of the sequence to be operated on by the keyword ar- 
guments rstart and rend. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(find-if tf'oddp '(121 2)) => 1 

(find-if tf'oddp '(111222) :start 3 :end 4) => NIL 

For a table of related items: See the section "Searching for Sequence Items". 



Page 1107 



find-if-not predicate sequence &key :key :from-end (.start 0) send Function 

If sequence contains an element that does not satisfy predicate, the leftmost such 
element is returned; otherwise nil is returned. 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(find-if-not #' atom '((a (b)) ((a) b) (nil nil)) : key #' second) 
=> (A (B)) 

If the value of the :from-end keyword is non-nil, the result is the rightmost ele- 
ment satisfying the test. 

For example: 

(find-if-not tf'evenp '(3 2 1) :from-end t) => 1 
(find-if-not tf'evenp '(3 2 1) :from-end nil) => 3 

For the sake of efficiency, you can delimit the portion of the sequence to be oper- 
ated on by the keyword arguments rstart and rend. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(find-if-not tf'oddp '(35435)) => 4 

(find-if-not tf'oddp '(35435) :start 3 :end 4) => NIL 

(find-if-not tf'evenp '(35435) :start 3 :end 4) => 3 

(find-if-not tf'oddp a :start 1 :key tf'car) => (4 3) 

(setq text "It was the height, of folly; Was it not?") 

(find-if-not ft' (lambda(x) (or (alpha-char-p x) (char= x #\Space))) text) 

=> tt\, 
For a table of related items: See the section "Searching for Sequence Items". 



Page 1108 



find-package name Function 

Returns the package whose string name is name or the print name of name, if 
name is a symbol. Case is considered, and if no matching package exits, nil is re- 
turned. This allows you to locate the actual package object for use with those 
functions that take a package (not the name of the package) as an argument, such 
as package-name and package-nicknames. 

(find-package 'common-lisp-user) => 

#<Package USER (really COMMON-LISP-USER) 71733245> 
(package-nicknames *) => ("CL-USER") 

In the following example, the current package is set to the package named 
turbine-controller if there is such a package. If no such package exists, a file 
which presumably contains its definition is loaded, and then the current package is 
set to that package. 

(setq xpackagex 

(or (find-package 'turbine-controller) 
(progn (load "turbcont. lsp") 

(find-package 'turbine-control ler)) 
(error "Couldn't find package TURBINE-CONTROLLER."))) 

For more information, see the section "Mapping Between Names and Packages". 

zl:find-position-in-list item list Function 

Looks down list for an element that is eq to item, like zhmemq. However, it re- 
turns the position (numeric index) in the list at which it found the first occur- 
rence of item, or nil if it did not find it at all. This function is sort of the comple- 
ment of nth; like nth, it is zero-based. See the function nth. Examples: 

(zl : f ind-position-in-1 ist 'a ' (a b c)) => 
(zl : f ind-position-in-1 ist 'c ' (a b c)) => 2 
(zl : f ind-position-in-1 ist 'e '(a b c)) => nil 

For a table of related items: See the section "Functions for Finding Information 
About Lists and Conses". 



zl:find-position-in-list-equal item list Function 

Looks down list for an element that is eql to item. However, it returns the position 
(numeric index) in the list at which it found the first occurrence of item, or nil if 
it did not find it at all. This function is sort of the complement of nth; like nth, it 
is zero-based. 

For a table of related items: See the section "Functions for Finding Information 
About Lists and Conses". 



find-symbol string &optional (pkg *package*J 

Function 



Page 1109 



Searches pkg for the symbol string. It behaves like intern except that it never cre- 
ates a new symbol. If it finds a symbol named string, it returns that symbol as its 
first value. The second value is one of the following: 

rinternal The symbol is present in pkg as an internal symbol. 

rexternal The symbol is present in pkg as an external symbol. 

rinherited The symbol is an internal symbol in pkg inherited by way of 

use-package. 

If it is unable to find a symbol named string in the specified packages, it returns 
nil nil. 

In the following example, find-symbol is used to determine the status of a 
prospective internal symbol. If a symbol with the specified print name already ex- 
ists, it is uninterned unless it is inherited from another package. A new symbol 
with the specified print name is then interned. 

(multiple-value-bind (symbol status) (find-symbol new-symbol) 
(if symbol 

(unless (eq status ': inherited) 
(unintern symbol) 
(intern new-symbol)) 
(intern new-symbol))) 



rfinish Message 

Does a rforce-output to a buffered asynchronous device, such as the Chaosnet, 
then waits until the currently pending I/O operation has been completed. If the 
stream does not handle this, the default handler ignores it. 

For file output streams, rfinish finalizes file content. It ensures that all data have 
actually been written to the file, and sets the byte count. It converts non-direct 
output openings into append openings. It allows other users to access the data that 
have been written before the rfinish message was sent. 



finish-output &optional output-stream Function 

Some streams are implemented in an asynchronous, or buffered, manner, finish- 
output attempts to ensure that all output sent to output-stream has reached its 
destination, and only then returns nil. Output-stream if unspecified or nil, defaults 
to *standard-output*, and if t, is *terminal-io*. 



first list Function 

Returns the first element of the list list, first is equivalent to car. This function is 
provided because it makes more sense when you are thinking of the argument as a 
list rather than just as a cons. For example: 



Page 1110 



(setq letters '(abed)) => (A B C D) 

(first letters) => A 
For a table of related items: See the section "Functions for Extracting from Lists". 

zhfirstn n list Function 

Returns the list of length n, whose elements are the first n elements of list. If list 
is fewer than n elements long, zhfirstn fills out the list with elements of the val- 
ue nil. Example: 

(zl :firstn 2 '(abed)) => (a b) 

(zl :firstn '(abed)) => nil 

(zl:firstn 6 '(a b c d)) => (abed nil nil) 

For a table of related items: See the section "Functions for Extracting from Lists". 

zhfix number Function 

Converts number from a floating-point or rational number to an integer, truncating 
towards negative infinity. If number is already an integer, it is returned un- 
changed. 

zhfix is similar to floor, except that it returns only the first value of floor. 

See the section "Functions that Divide and Convert Quotient to Integer". 

For a table of related items: See the section "Functions that Divide and Convert 
Quotient to Integer". 

fixnum Type Specifier 

fixnum is the type specifier symbol for the predefined primitive Lisp object of that 
name. 

The types fixnum and bignum are an exhaustive partition of the type integer, 
since integer = (or bignum fixnum). These are internal representations of integers 
used by the system for efficiency depending on integer size; in general, fixnums 
and bignums are transparent to the programmer. 

Examples: 

(typep 4 'fixnum) => T 

(zl :typep '1 ) => :FIXNUM 

(subtypep 'fixnum 'number) => T and T ; subtype and certain 

(commonp most-positive-f ixnum) => T 

(zl : f ixnump 90) => T 

(type-of 8654) => FIXNUM 
See the section "Data Types and Type Specifiers". See the section "Numbers". 



Page 1111 



sysrfixnump object Function 

Returns t if its argument is a fixnum, otherwise nil. 

For a table of related items, see the section "Numeric Type-checking Predicates". 

zlrfixp object Function 

In your new programs, we recommend that you use the function integerp which is 
the Common Lisp equivalent of the function zlrfixp. 

zlrfixp returns t if its argument is an integer, otherwise nil. 

For a table of related items, see the section "Numeric Type-checking Predicates". 

zlrfixr x Function 

Converts x from a floating-point number to an integer, rounding to the nearest in- 
teger, zlrfixr is similar to round, except when x is exactly halfway between two 
integers. In this case, zlrfixr rounds up (towards positive infinity), while round 
rounds to an even integer. 

zlrfixr could have been defined by: 

(defun zl : f ixr (x) 

(if (zl:fixp x) x (zl:fix (+ x 0.5)))) 

For a table of related items: See the section "Functions that Divide and Convert 
Quotient to Integer". 

sysrflatc x Function 

Returns the number of characters in the unslashified printed representation of x. 
Example: 

(flatsize ' (+ /12 3)) => 10 



sysrflatsize x Function 

Returns the number of characters in the slashified printed representation of x. 
Example: 

(flatsize ' (+ /12 3)) => 12 



flavorrflavor-allowed-init-keywords flavor-name Function 

Returns an alphabetically sorted list of all symbols that are valid init options for 
the flavor named flavor-name. Valid init options are allowed keyword arguments to 
make-instance. 



Page 1112 



This function is primarily useful for people, rather than programs, to call to get 
information. You can use this to help remember the name of an init option or to 
help write documentation about a particular flavor. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



flavor-allows-init-keyword-p flavor-name keyword Function 

Returns non-nil if the keyword is a valid init option for the flavor named flavor- 
name, or nil if it does not. Valid init options are allowed keyword arguments to 
make-instance. The non-nil value is the name of the component flavor that con- 
tributes the support of that keyword. 

This function is primarily useful for people, rather than programs, to call to get 
information. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



flavor:*flavor-compile-trace-list* Variable 

Value is a list of structures, each of which describes the compilation of a combined 
method into the run-time (not the compile-time) environment, in newest-first order. 
The function flavorrprint-flavor-compile-trace lets you selectively access the in- 
formation saved in this variable. See the function flavorrprint-flavor-compile- 
trace. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



flavor:flavor-default-init-get flavor property Function 

Similar to get, except that its first argument is either a flavor structure or the 
name of a flavor. It retrieves the property from the default init-plist of the speci- 
fied flavor. You can use setf with it: 

(setf (flavor: flavor-default-i nit-get f p) x) 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



flavor:flavor-default-init-putprop flavor value property Function 

Like zhputprop, except that its first argument is either a flavor structure or the 
name of a flavor. It puts the property on the default-init-plist of the specified fla- 
vor. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



Page 1113 



flavor:flavor-default-init-remprop flavor property Function 

Similar to remprop, except that its first argument is either a flavor structure or 
the name of a flavor. It removes the property from the default init-plist of the 
specified flavor. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



flet functions &body body Special Form 

Defines named internal functions, flet (function let) defines a lexical scope, body, 
in which these names can be used to refer to these functions, functions is a list of 
clauses, each of which defines one function. Each clause of the flet is identical to 
the cdr of a defun special form; it is a function name to be defined, followed by 
an argument list, possibly declarations, and function body forms, flet is a mecha- 
nism for defining internal subroutines whose names are known only within some 
local scope. 

Functions defined by the clauses of a single flet are defined "in parallel", similar 
to let. The names of the functions being defined are not defined and not accessible 
from the bodies of the functions being defined. The labels special form is used to 
meet those requirements. See the special form labels. 

Here is an example of the use of flet: 

(defun triangle-perimeter (p1 p2 p3) 
(flet ((squared (x) (* x x))) 
(flet ((distance (pointl point2) 

(sqrt (+ (squared (- (point-x pointl) 

(point-x point2))) 
(squared (- (point-y pointl) 

(point-y point2))))))) 
(+ (distance p1 p2) 
(distance p2 p3) 
(distance p1 p3))))) 

flet is used twice here, first to define a subroutine squared of triangle-perimeter, 
and then to define another subroutine, distance. Note that since distance is de- 
fined within the scope of the first flet, it can use squared, distance is then called 
three times in the body of the second flet. The names squared and distance are 
not meaningful as function names except within the bodies of these flets. 

Note that functions defined by flet are internal, lexical functions of their contain- 
ing environment. They have the same properties with respect to lexical scoping 
and references as internal lambdas. They can make free lexical references to vari- 
ables of that environment and they can be passed as funargs to other procedures. 
Functions defined by flet, when passed as funargs, generate closures. The alloca- 
tion of these closures, that is, whether they appear on the stack or in the heap, is 
controlled in the same way as for internal lambdas. See the section "Funargs and 
Lexical Closure Allocation". 



Page 1 1 14 



Here is an example of the use, as a funarg, of a closure of a function defined by 
flet. 

(defun sort-by-closeness-to-goal (list goal) 
(flet ((closer-to-goal (x y) 

(< (abs (- x goal)) (abs (- y goal))))) 
(sort list tf'closer-to-goal ))) 

This function sorts a list, where the sort predicate of the (numeric) elements of 
the list is their absolute distance from the value of the parameter goal. That pred- 
icate is defined locally by flet, and passed to sort as a funarg. 

Note that flet (as well as labels) defines the use of a name as a function, not as a 
variable. Function values are accessed by using a name as the car of a form or by 
use of the function special form (usually expressed by the reader macro #'). 

Within its lexical scope, flet can be used to redefine names that refer to globally 
defined functions, such as sort or cdar, though this is not recommended for stylis- 
tic reasons. This feature does, however, allow you to bind names with flet in an 
unrestricted fashion, without binding the name of some other function that you 
might not know about (such as number-into-array), and thereby causing other 
functions to malfunction. This occurs because flet always creates a lexical binding, 
not a dynamic binding. Contrast this with let, which usually creates a lexical 
binding, unless the variable being bound is declared special, in which case it cre- 
ates a dynamic binding. 

flet can also be used to redefine function names defined by enclosing uses of flet 
or labels. 

In the following example, eql is redefined to a more liberal treatment for charac- 
ters. Note that the global definition of eql is used in the local definition (this 
would not be possible with labels). Note also that member uses the global defini- 
tion of eql. 

(flet ((eql (x y) 

(if (characterp x) 
(equal p x y) 
(eql x y)))) 
(if (member foo bar-list) ;uses global eql 

(adjoin 'baz bar-list :test #'eql) ;uses flet'd eql 
(eql foo (car bar-list)))) 



float &optional ( low '*) ( high '*) Type Specifier 

float is the type specifier symbol for the predefined Lisp floating-point number 
type. 

The types float, rational, and complex are pairwise disjoint subtypes of number. 

The float data type is a supertype of the types: 



Page 1115 



short-float 
single-float 
long-float 
double-float 

This type specifier can be used in either symbol or list form. Used in list form, 
float allows the declaration and creation of specialized floating-point numbers, 
whose range is restricted to low and high. 

low and high must each be a floating-point number, a list of floating-point number, 
or unspecified; in floating-point number form the limits are inclusive; in list form 
they are exclusive, and * means that a limit does not exist and so effectively de- 
notes minus or plus infinity, respectively. 

Examples: 

(typep 20.4e-2 'float) => T 

(typep (/ (float 14) (float 4)) 'float) => T 

;note the use of float the function and float the type 
(subtypep 'float 'number) => T and T ; subtype and certain 
(subtypep 'single-float 'float) => T and T 
(commonp (float 3)) => T 
(floatp 989. e-3) => T 

See the section "Data Types and Type Specifiers". 

See the section "Numbers". 



float number &optional other Function 

Converts any noncomplex number to a floating-point number. With no second ar- 
gument, if number is already a floating-point, number is returned. If number is not 
of floating-point type, a single-float is produced and returned. 

If the second argument other is provided, it must be of floating-point type, and 
number is converted to the same format as other. 

Examples: 

(float 3) => 3.0 

(float 3 1 .0d0) => 3.0d0 

For a table of related items, see the section "Functions that Convert Numbers to 
Floating-point Numbers". 



zhfloat x Function 

Converts any noncomplex number to a single-precision floating-point number. Note 
that zhfloat reduces a double-precision argument to single precision. 

Examples: 

(zl : float 3) => 3.0 

(zl: float 6.02d23) => 6.02e23 



Page 1116 



See the section "Functions that Convert Numbers to Floating-point Numbers". 

For a table of related items: See the section "Functions that Convert Numbers to 
Floating-point Numbers". 

float-digits float Function 

Returns, as a non-negative integer, the number of binary digits used in the binary 
representation of its floating-point argument (including the implicit "hidden bit" 
used in IEEE standard floating-point representation). 

Genera examples: 

(float-digits 0.0) => 24 

(float-digits 3.0s5) => 24 

(float-digits pi) => 53 ;pi is a long float when using Genera 

(float-digits 1.0S-40) => 24 

In CLOE, returns a non-negative integer that provides the number of digits in the 
radix of float (two in CLOE implementations) used to represent float. For normal- 
ized floats, this function will produce the same result as float-precision. 

(float-digits 5.06s2) => 22 

For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 

float-precision float Function 

Returns, as a non-negative integer, the number of significant binary digits present 
in the binary representation of the floating-point argument. Note that if the argu- 
ment is (a floating-point) zero, the result is an (integer) zero. For normalized float- 
ing-point numbers, float-digits and float-precision return identical results. For a 
denormalized or zero number, the precision is smaller than the number of repre- 
sentation digits (that is, float-precision returns a smaller number). 

Examples: 

(float-precision 0.0) => 

(float-precision 1.6s-19) => 24 

(float-precision 1.61-19) => 53 

(float-precision 1.0S-40) => 17 

Under CLOE, returns a non-negative integer that provides the number of signifi- 
cant digits in the radix of float used in the representation of float. For floating 
point zeroes, this function returns zero. For normalized floats, this function pro- 
duces the same result as float-digits. 

(float-precision 4.5) => 22 

For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 



Page 1117 



float-radix float Function 

Returns the integer 2 denoting the radix of the internal IEEE floating-point repre- 
sentation in Symbolics Common Lisp under Genera. 

In CLOE implementations, float-radix returns the constant 2, but Common Lisp 
permits implementations to have an alternate float radix, or even different radices 
for different floats. 



Examples: 












(float- 


■ radix 


P" 


i) => 


2 




(float- 


■radix 


5 


.010) 


=> 


2 



For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 



float-sign floatl &optional float2 Function 

Returns a floating-point number, z, which has the same sign as floatl and the 
same absolute value and format as float2. The second argument defaults to the val- 
ue of (float 1 floatl), that is, it is a floating-point 1 of the same type as floatl. 
Both arguments must be floating-point numbers. 

Examples: 

(float-sign 3.0) => 1 .0 

(float-sign -7.9) => -1 .0 

(float-sign -2.0 pi) => -3. 141592653589793d0 

For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 



floatp object Function 

Returns t if its argument is a (single- or double-precision) floating-point number. 
Otherwise it returns nil. The following code tests whether a and b are numbers. If 
numbers, they are added. Otherwise, we attempt to extract floats that are then 
tested by floatp. 

(if (and (numberp a) (numberp b)) 
(+ a b) 
(if (and (consp a) 

(floatp (car a)) 
(consp b) 
(floatp (car b))) 
(+ (car a) (car b)) 
(error "couldn't extract floats from ~a and ~a" a b))) 

For a table of related items, see the section "Numeric Type-checking Predicates". 
floatp object Function 



Page 1118 



Returns t if its argument is a (single- or double-precision) floating-point number. 
Otherwise it returns nil. The following code tests whether a and b are numbers. If 
numbers, they are added. Otherwise, we attempt to extract floats that are then 
tested by floatp. 

(if (and (numberp a) (numberp b)) 
(+ a b) 
(if (and (consp a) 

(floatp (car a)) 
(consp b) 
(floatp (car b))) 
(+ (car a) (car b)) 
(error "couldn't extract floats from ~a and ~a" a b))) 

For a table of related items, see the section "Numeric Type-checking Predicates". 



zhflonump object Function 

Returns t if object is a single-precision floating-point number, otherwise it returns 
nil. 

The following function is a synonym of zhflonump: 
sys:single-float-p 

For a table of related items, see the section "Numeric Type-checking Predicates". 

floor number &optional (divisor 1) Function 

Divides number by divisor, and truncates the result toward negative infinity. The 
truncated result and the remainder are the returned values. 

number and divisor must each be a noncomplex number. Not specifying a divisor is 
exactly the same as specifying a divisor of 1. 

If the two returned values are Q and R, then (+ (* Q divisor) R) equals number. If 
divisor is 1, then Q and R add up to number. If divisor is 1 and number is an inte- 
ger, then the returned values are number and 0. 

The first returned value is always an integer. The second returned value is inte- 
gral if both arguments are integers, is rational if both arguments are rational, and 
is floating-point if either argument is floating-point. If only one argument is speci- 
fied, then the second returned value is always a number of the same type as the 
argument. 

Examples: 

(floor 5) => 5 and 

(floor -5) => -5 and 

(floor 5.2) => 5 and 0.19999981 

(floor -5.2) => -6 and 0.8000002 

(floor 5.8) => 5 and 0.8000002 



Page 1119 



(floor -5.8) => -6 and 0.19999981 
(floor 5 3) => 1 and 2 
(floor -5 3) => -2 and 1 
(floor 5 4) => 1 and 1 
(floor -5 4) => -2 and 3 
(floor 5.2 3) => 1 and 2.1999998 
(floor -5.2 3) => -2 and 0.8000002 
(floor 5.2 4) => 1 and 1.1999998 
(floor -5.2 4) => -2 and 2.8000002 
(floor 5.8 3) => 1 and 2.8000002 
(floor -5.8 3) => -2 and 0.19999981 
(floor 5.8 4) => 1 and 1.8000002 
(floor -5.8 4) => -2 and 2.1999998 

Using floor with one argument is the same as the zlrfix function, except that 
zlrfix returns only the first value of floor. 

See the section "Comparison of floor, ceiling, truncate and round". 

For a table of related items: See the section "Functions that Divide and Convert 
Quotient to Integer". 



fmakunbound symbol Function 

Causes symbol to be undefined, that is, its function cell to be empty. It returns 
symbol. 

Because symbol no longer has a function definition, function invocation results in 
an error after applying fmakunbound, unless later redefined. 

(fboundp 'alarm-handler) => nil 

(defun alarm-handler () 
(setq xalarmsx 0)) 

(fboundp 'alarm-handler) => t 

(fmakunbound 'alarm-handler) 

(fboundp 'alarm-handler) => nil 
See the section "Functions Relating to the Function Cell of a Symbol". 



future-common-lisp rfmakunbound function-name Function 

Removes the definition of function-name and returns function-name. 

Note that future-common-lisp rfmakunbound is just like fundefine. 

If the function is encapsulated, future-common-lisp rfmakunbound removes both 
the basic definition and the encapsulations. Some types of function specs (rlocation 
for example) do not implement future-common-lisp rfmakunbound. Using future- 



Page 1 120 



common-lisp rfmakunbound on a rwithin function spec removes the replacement 
of function-to-affect, putting the definition of within-function back to its normal 
state. Using future-common-lisp rfmakunbound on a method's function spec re- 
moves the method completely, so that future messages or generic functions will be 
handled by some other method. 



for keyword for loop 

for is one of the iteration driving clauses for loop. As described below, there are 
numerous variants for this keyword. 

The optional argument, data-type is reserved for data type declarations. It is cur- 
rently ignored. 

for var {data-type} from exprl {to expr2} {by expr3} 

To iterate upward. Performs numeric iteration. 

var is initialized to exprl, and on each succeeding iteration is incremented 
by expr3 (default 1). If the to phrase is given, the iteration terminates when 
var becomes greater than expr2. Each of the expressions is evaluated only 
once, and the to and by phrases can be written in either order. 

Note that the to variant appropriate for the direction of stepping must be 
used for the endtest to be formed correctly; that is, the code does not work 
if expr3 is negative or 0. 

data-type defaults to fixnum. The keyword as is equivalent to the keyword 
for. 

Examples: 

(defun loopl () 

(loop for i from 1 to 10 
collect i)) => L00P1 
(loopl) => (1 2 3 4 5 6 7 8 9 10) 

(defun loop2 () 

(loop for i from to 5 by 1 
do 
(princ i))) => L00P2 
(loop2) => 012345NIL 

(defun loop3(inc) 

(loop as x from by inc to (+ inc 4) 
do 
(princ x) 

(setq x (+ x 1)))) => L00P3 
(loop3 1) => 024NIL 

for var {data-type} from exprl downto expr2 {by expr3} 



Page 1 121 



To iterate downward. Performs numeric iteration, var is initialized to exprl, 
and on each succeeding iteration is decremented by expr3, and the endtest 
is adjusted accordingly. 

Examples: 

(defun loop3 () 

(loop for my-number from 7 by 2 downto -2 
do 
(princ my-number) (princ " "))) => L00P3 
(loop3) => 7 5 3 1 -1 NIL 

for var {data-type} from exprl {below expr2} {by expr3} 

Loop will terminate when the variable of iteration, exprl, is greater than or 
equal to some terminal value, expr2. 

Examples: 

(defun loopl () 

(loop for i from below 10 
do 
(princ i))) => L00P1 
(loopl) => 0123456789NIL 

(defun loop2 () 

(loop for my-number from 7.5 by .5 below 12 
do 
(princ my-number) (princ " "))) => L00P2 
(loop2) => 7.5 8.0 8.5 9.0 9.5 10.0 10.5 11.0 11.5 NIL 

for var {data-type} from exprl {above expr2] {by expr3\ 

Loop will terminate when the variable of iteration is less than or equal to 
some terminal value. 

Examples: 



Page 1 122 



(defun loopl () 

(loop for my-number from 12 by .5 above 7.5 
do 
(print my-number))) => L00P1 
(loopl) => 
12 

11 .5 
11 .0 
10.5 
10.0 
9.5 
9.0 
8.5 
8.0 NIL 

for var {data-type} downfrom exprl {by expr2} 

Used to iterate downward with no limit. 

Examples: 

(defun loop-downf rom (num) 
(loop for x downfrom 8 by num 
do 
(print x))) => L00P-D0WNFR0M 
(loop-downf rom 1) 
8 
7 
6 
5. . . ; infinite 

for var {data-type} upfrom exprl {by expr2} 

Used to iterate upward with no limit. 

Examples: 

(defun loop-upfrom () 

(loop for x upfrom -2 by 2 
do 
(print x))) => LOOP-UPFROM 
(loop-upfrom) 
-2 

2 
4. . . ; infinite 

for var {data-type} in exprl {by expr2} 



Page 1 123 



Iterates over each of the elements in the list exprl. If the by subclause is 
present, expr2 is evaluated once on entry to the loop to supply the function 
to be used to fetch successive sublists, instead of cdr. 

Examples: 

(defun loopl (input-list) 
(loop for x in input-list 
for i from 
do 
(princ (list i x)))) => L00P1 
(loopl '(a b (c d) e)) => (0 A) (1 B) (2 (C D))(3 E)NIL 

for var {data-type} on exprl {by expr2} 

Like the previous for format, except that var is set to successive sublists of 
the list instead of successive elements. Note that since var is always a list, 
it is not meaningful to specify a data-type unless var is a destructuring pat- 
tern, as described in the section on destructuring. Note also that loop uses 
a null rather than an atom test to implement both this and the preceding 
clause. 

Example: 

(defun loopl (input-list) 
(loop for subl on input-list 
do 
(print subl))) => L00P1 
(loopl '(a b c (k c) d)) => 
(A B C (K C) D) 
(B C (K C) D) 
(C (K C) D) 
((K C) D) 
(D) NIL 

In contrast to what in would do 

(defun loopl (input-list) 
(loop for subl in input-list 
do 
(print subl))) => L00P1 
(loopl '(a b c (k c) d)) => 
A 
B 
C 

(K C) 
D NIL 

for var {data-type} = expr 

On each iteration, expr is evaluated and var is set to the result. 

for var {data-type} - exprl then expr2 



Page 1 124 



var is bound to exprl when the loop is entered, and set to expr2 (reevaluat- 
ed) at all but the first iteration. Since exprl is evaluated during the binding 
phase, it cannot reference other iteration variables set before it; for that, 
use the following: 

Examples: 

(defun loopl (x) 

(loop for stepper = x then (* stepper x) 
do 
(print stepper))) => L00P1 
(loopl 3) 
3 
9 

27 
81 . . . ; infinite loop 

for var {data-type} first exprl then expr2 

Sets var to exprl on the first iteration, and to expr2 (reevaluated) on each 
succeeding iteration. The evaluation of both expressions is performed inside 
of the loop binding environment, before the loop body. This allows the first 
value of var to come from the first value of some other iteration variable, 
allowing such constructs as: 

(loop for term in poly 

for ans first (car term) then (gcd ans (car term)) 
finally (return ans)) 

for var {data-type} being expr and its path ... 

for var {data-type} being {each | the} path ... 

This provides a user-definable iteration facility, path names the manner in 
which the iteration is to be performed. The ellipsis indicates where various 
path-dependent preposition/expression pairs can appear. 

See the section "Iteration Paths for loop". 

Examples: 

(define- loop-sequence-path asci i-char 

(lambda (string i) 

(ascii-code (aref string i))) 
length) => NIL 

(loop for x being the ascii-char of "ABC" 
doing 
(print x)) => 
65 
66 
67 NIL ; 65 is the ascii equivalent of "A" 



Page 1 125 



(loop for a being the array-elements of q using (index ai) 
collecting (lambda (x) 

when (> x a) 
(aset x q ai)))) 

See the section "Iteration-Driving Clauses". 



force-output &optional output-stream Function 

Some streams are implemented in an asynchronous, or buffered, manner, force- 
output initiates the emptying of any internal buffers, but returns nil without wait- 
ing for completion or acknowledgment. Output-stream if unspecified or nil, defaults 
to *standard-output*, and if t, is *terminal-io*. 



rforce-output Message 

Causes any buffered output to be sent to a buffered asynchronous device, such as 
the Chaosnet. It does not wait for it to complete; use rfinish for that. If a stream 
supports rforce-output, then :tyo, :string-out, and :line-out might have no visible 
effect until a rforce-output is done. If the stream does not handle this, the default 
handler ignores it. 



fourth list Function 

Returns the fourth element of the list, fourth is equivalent to: 
(nth 3 list) 

(setq letters '(a b c d e f)) => (A B C D E F) 

(fourth letters) => D 
For a table of related items: See the section "Functions for Extracting from Lists". 

dbg:frame-active-p frame Function 

Indicates whether frame is an active frame. 



Value 


Meaning 


nil 


Frame is not active 


not nil 


Frame is active 



Caution: Use this function only within the context of the dbgrwith-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



Page 1 126 



dbg:frame-arg-value frame arg-name-or-number &optional callee-context no-error-p 

Function 

Returns the value of the nth argument to frame. Returns a second value, which is 
a locative pointer to the word in the stack that holds the argument. If n is out of 
range, it takes action based on no-error-p: if no-error-p is nil, it signals an error, 
otherwise it returns nil. n can also be the name of the argument (a symbol, but it 
need not be in the right package). Each argument passed for an &rest parameter 
counts as a separate argument when n is a number. dbg:frame-arg-value controls 
whether you get the caller or callee copy of the argument (original or possibly 
modified.) 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-local-value frame local-name-or-number &optional no-error-p 

Function 

Returns the value of the nth local variable in frame, n can also be the name of the 
local variable (a symbol, but it need not be in the right package). It returns a sec- 
ond value, which is a locative pointer to the word in the stack that holds the local 
variable. If n is out of range, then the action is based on no-error-p: if no-error-p is 
nil, it signals an error, otherwise it returns nil. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-next-active-frame frame Function 

Returns a frame pointer to the next active frame following frame. If frame is the 
last active frame on the stack, it returns nil. 

"Next" means the frame of a procedure that was invoked more recently (the frame 
called by this one; toward the top of the stack). 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-next-interesting-active-frame frame Function 



Page 1 127 



Returns a frame pointer to the next interesting active frame following frame. If 
frame is the last interesting active frame on the stack, it returns nil. 

"Next" means the frame of a procedure that was invoked more recently (the frame 
called by this one; toward the top of the stack). 

"Interesting active frames" include all of the active frames except those that are 
parts of the internals of the Lisp interpreter, such as the frames for eval, 
zhapply, funcall, let, and other basic Lisp special forms. The list of such func- 
tions is the value of the system constant, dbg: *uninteresting-f unctions*. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-next-nth-active-frame frame &optional (count I) skip-invisible 

Function 

Goes up the stack by count active frames from frame and returns a frame pointer 
to that frame. It returns a second value that is not nil. When count is positive, 
this is like calling dbg:frame-next-active-frame count times; count can also be 
negative or zero. If either end of the stack is reached, it returns a frame pointer 
to the first or last active frame and nil. 

"Next" means the frame of a procedure that was invoked more recently (the frame 
called by this one; toward the top of the stack). 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-next-nth-interesting-active-frame frame &optional (count I) skip- 
invisible 

Function 

Goes up the stack by count interesting active frames from frame and returns a 
frame pointer to that frame. It returns a second value that is not nil. When count 
is positive, this is like calling dbg:frame-next-interesting-active-frame count 
times; count can also be negative or zero. If either end of the stack is reached, it 
returns a frame pointer to the first or last active frame and nil. 

"Next" means the frame of a procedure that was invoked more recently (the frame 
called by this one; toward the top of the stack). 

"Interesting active frames" include all of the active frames except those that are 
parts of the internals of the Lisp interpreter, such as the frames for eval, 
zhapply, funcall, let, and other basic Lisp special forms. The list of such func- 
tions is the value of the system constant, dbg: *uninteresting-f unctions*. 



Page 1 128 



Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-next-nth-open-frame frame &optional (count 1) skip-invisible 

Function 

Goes up the stack by count open frames from frame and returns a frame pointer to 
that frame. It returns a second value that is not nil. When count is positive, this 
is like calling dbg:frame-next-open-frame count times; count can also be negative 
or zero. If either end of the stack is reached, it returns a frame pointer to the 
first or last active frame and nil. 

"Next" means the frame of a procedure that was invoked more recently (the frame 
called by this one; toward the top of the stack). 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-next-open-frame frame Function 

Returns a frame pointer to the next open frame following frame-pointer. If frame is 
the last open frame on the stack, it returns nil. 

"Next" means the frame of a procedure that was invoked more recently (the frame 
called by this one; toward the top of the stack). 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-number-of-locals frame Function 

Returns the number of local variables allocated for frame. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 

dbg:frame-number-of-spread-args frame &optional (type :suppliedj 

Function 



Page 1 129 



Returns the number of "spread" arguments that were passed in frame. (These are 
the arguments that are not part of a &rest parameter.) Sending a message to an 
instance results in two implicit arguments being passed internally along with the 
other arguments. These implicit arguments are included in the count. 

type requests more specific definition of the number: 

Value Meaning 

rsupplied Returns the number of arguments that were actually passed by 

the caller, except for arguments that were bound to a &rest 
parameter. This is the default. 

rexpected Returns the number of arguments that were expected by the 

function being called. 

rallocated Returns the number of arguments for which stack locations 

have been allocated. In the absence of a &rest parameter, this 
is the same as rexpected for compiled functions, and the same 
as rsupplied for interpreted functions. If stack locations were 
allocated for arguments that were bound to a &rest parameter, 
they are included in the returned count. 

These values would all be the same except in cases where a wrong-number-of- 
arguments error occurred, or where there are optional arguments (expected but 
not supplied). 

Cautionr Use this function only within the context of the dbgrwith-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbgrframe-out-to-interesting-active-frame frame Function 

Returns either frame (if it points to an interesting active frame) or the previous 
interesting active frame before frame-pointer. (This is what the :Previous Frame 
command c-n-U in the Debugger does.) 

"Interesting active frames" include all of the active frames except those that are 
parts of the internals of the Lisp interpreter, such as the frames for eval, 
zlrapply, funcall, let, and other basic Lisp special forms. The list of such func- 
tions is the value of the system constant, dbgr*uninteresting-f unctions*. 

Cautionr Use this function only within the context of the dbgrwith-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbgrframe-previous-active-frame frame Function 

Returns a frame pointer to the previous active frame before frame. If frame is the 
first active frame on the stack, it returns nil. 



Page 1 130 



"Previous" means the frame of a procedure that was invoked less recently (the 
caller of this frame; towards the base of the stack). 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-previous-interesting-active-frame frame Function 

Returns a frame pointer to the previous interesting active frame before frame. If 
frame is the first interesting active frame on the stack, it returns nil. 

"Previous" means the frame of a procedure that was invoked less recently (the 
caller of this frame; towards the base of the stack). 

"Interesting active frames" include all of the active frames except those that are 
parts of the internals of the Lisp interpreter, such as the frames for eval, 
zhapply, funcall, let, and other basic Lisp special forms. The list of such func- 
tions is the value of the system constant, dbg: *uninteresting-f unctions*. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-previous-open-frame frame Function 

Returns a frame pointer to the previous open frame before frame. If frame is the 
first open frame on the stack, it returns nil. 

"Previous" means the frame of a procedure that was invoked less recently (the 
caller of this frame; towards the base of the stack). 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-real-function frame Function 

Returns either the function object associated with frame or the value of self when 
the frame was the result of sending a message to an instance. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



Page 1131 



dbg:frame-real-value-disposition frame Function 

Returns a symbol indicating how the calling function is going to handle the values 

to be returned by this frame. If the calling function just returns the values to its 

caller, then the symbol indicates how the final recipient of the values is going to 

handle them. 

Value Meaning 

rignore The values would be ignored; the function was called for ef- 

fect. 

rsingle The first value would be received and the rest would not; the 

function was called for value. 

rmultiple All the values would be received; the function was called for 

multiple values. It returns a second value indicating the num- 
ber of values expected, nil indicates an indeterminate number 
and is always returned. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



dbg:frame-self-value frame &optional instance-frame-only 

Function 

Returns the value of self in frame, or nil if self does not have a value. If instance- 
frame-only is not nil then it returns nil unless this frame is actually a message- 
sending frame created by send. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



fresh-line &optional output-stream Function 

Outputs a newline only if the stream is not already at the start of a line. If for 
any reason this cannot be determined, then a newline is output anyway. This guar- 
antees that the stream will be on a fresh line while consuming as little vertical 
space as possible, fresh-line returns t if it output a newline, otherwise it returns 
nil. output-stream, which, if unspecified or nil, defaults to *standard-output*, and 
if t, is *terminal-io*. 

(progn (princ 'foo) (terpri) (princ 'bar) (fresh-line) (princ 'baz) nil) 

F00 

BAR 

BAZ 

=> NIL 



Page 1 132 



(progn (princ 'foo) (terpri) (fresh-line) 
(princ 'bar) (fresh-line) (terpri) 
(princ 'baz) nil) 

FOO 

BAR 

BAZ 
=> NIL 



:fresh-line Message 

Tells the stream to position itself at the beginning of a new line. If the stream is 
already at the beginning of a fresh line it does nothing; otherwise it outputs a car- 
riage return. For streams that do not support this, the default handler always out- 
puts a carriage return. 



fround number &optional (divisor 1) Function 

Like round, except that the first returned value is always a floating-point number 
instead of an integer. The second returned value is the remainder. If number is a 
floating-point number and divisor is not a floating-point number of longer format, 
then the first returned value is a floating-point number of the same type as num- 
ber. 

Round returns the floating point equivalent of the integer nearest to number, or 
nearest to the quotient of number divided by divisor. If number is exactly 0.5 
greater than an integer, the even floating point equivalent of the two integers 
closest to number, or closest to the quotient of number divided by divisor is re- 
turned. A second value, the remainder, is also returned. The remainder returned is 
the same as that returned by round applied to the same arguments. 

Examples: 

(fround 5) => 5.0 and 

(fround -5) => -5.0 and 

(fround 5.2) => 5.0 and 0.19999981 

(fround -5.2) => -5.0 and -0.19999981 

(fround 5 3) => 2.0 and -1 

(fround -5 3) => -2.0 and 1 

(fround 5.2 4) => 1.0 and 1.1999998 

(fround -5.2 4) => -1.0 and -1.1999998 

(fround 4.2d0) => 4.0d0 and 0.20000000000000018d0 

(fround -4.2d0) => -4.0d0 and -0.20000000000000018d0 

For a table of related items: See the section "Functions that Divide and Return 
Quotient as Floating-point Number". 



Page 1 133 



zhfset sym definition Function 

Stores definition, which can be any Lisp object, into sym's function cell. It returns 
definition. 

See the section "Functions Relating to the Function Cell of a Symbol". 



zhfset-carefully function-spec definition &optional no-query-flag Function 

This function is obsolete. It is equivalent to: 
(f define symbol definition t force- flag) 

zhfsignal format-string &rest format-args Function 

This is a simple function for signalling when you do not care to use a particular 
condition. zhfsignal signals dbgrproceedable-ferror. (See the flavor 
dbg:proceedable-f error.) The arguments are passed as the rformat-string and 
:format-args init keywords to the error object. 

Note: zhfsignal is now obsolete. Use cerror in your new programs instead. 

For a table of related items: See the section "Condition-Checking and Signalling 
Functions and Variables". 

zhfsymeval symbol Function 

In your new programs, we recommend that you use the function symbol-function, 
which is the Common Lisp equivalent of the function zhfsymeval. 

Returns symbol's definition, the contents of its function cell. If the function cell is 
empty, zhfsymeval signals an error. 

See the section "Functions Relating to the Function Cell of a Symbol". 

ftruncate number &optional (divisor 1) Function 

Like truncate, except that the first returned value is always a floating-point num- 
ber instead of an integer. The second returned value is the remainder. If number 
is a floating-point number and divisor is not a floating-point number of longer for- 
mat, then the first returned value is a floating-point number of the same type as 
number. 

Returns the floating point equivalent of the integer nearer to zero of the two inte- 
gers closest to number, or closest to the quotient of number divided by divisor. A 
second value, the remainder, is also returned. The remainder returned is the same 
as that returned by truncate applied to the same arguments. 

Examples: 

(ftruncate 5) => 5.0 and 



Page 1 134 



(f truncate -5) => -5.0 and 

(f truncate 5.2) => 5.0 and 0.19999981 

(ftruncate -5.2) => -5.0 and -0.19999981 

(f truncate 5 3) => 1.0 and 2 

(ftruncate -5 3) => -1.0 and -2 

(ftruncate 5.2 4) => 1.0 and 1.1999998 

(ftruncate -5.2 4) => -1.0 and -1.1999998 

(ftruncate 4.2d0) => 4.0d0 and 0.20000000000000018d0 

(ftruncate -4.2d0) => -4.0d0 and -0.20000000000000018d0 

For a table of related items: See the section "Functions that Divide and Return 
Quotient as Floating-point Number". 



funcall fn &rest args Function 

(funcall fn al a2 ... an) applies the function fn to the arguments al, a2, ..., an. fn 
cannot be a special form nor a macro; this would not be meaningful. Example: 

(cons 1 2) => (1 . 2) 
(setq cons '+) => + 
(funcall cons 1 2) => 3 
(cons 1 2) => (1 . 2) 

This shows that the use of the symbol cons as the name of a variable and the use 
of that symbol as the name of a function do not interact. The funcall form evalu- 
ates the variable and gets the symbol +, which is the name of a different function. 
The cons form invokes the function named cons. 

Note: The Maclisp functions subrcall, lsubrcall, and zharraycall are not needed 
in Symbolics Common Lisp; funcall is just as efficient, zharraycall is provided for 
compatibility; it ignores its first subform (the Maclisp array type) and is otherwise 
identical to aref. subrcall and lsubrcall are not provided. 

(setq + subfn (symbol -function '-)) 

(defun subfn(x y) (+ x y)) 

(subfn 2 1) => 3 

(funcall subfn 2 1) => 1 

(defun size-of-form (form print-function) 

"print-function should be princ-to-string or prin1-to-string" 
(length (funcall print-function form))) 

In the previous example, the print length of a form is determined by using funcall 
on one of two print functions. 

See the section "Functions for Function Invocation". 

function name arglist result-typel result-type2 ... Declaration 



Page 1 135 



Equivalent to ftype type function-name- 1 function-name-2 , but might be more con- 
venient. 



function function Special Form 

Means different things, depending on whether function is a function or the name 
of a function. (Note that in neither case is function evaluated.) The name of a 
function is a symbol or a function-spec list. See the section "Function Specs". A 
function is typically a list whose car is the symbol lambda; however, there are 
several other kinds of functions available. See the section "Kinds of Functions". 

If you want to pass an anonymous function as an argument to a function, you 
could just use quote. For example: 

(mapc (quote (lambda (x) (car x))) some-list) 

The compiler and interpreter cannot tell that the first argument is going to be 
used as a function; for all they know, mapc treats its first argument as a piece of 
list structure, asking for its car and cdr and so forth. The compiler cannot com- 
pile the function; it must pass the lambda-expression unmodified. This means that 
the function does not get compiled, which makes it execute more slowly than it 
might otherwise. The interpreter cannot make references to free lexical variables 
work by making a lexical closure; it must pass the lambda-expression unmodified. 

The function special form is the way to say that a lambda-expression represents a 
function rather than a piece of list structure. You just use the symbol function in- 
stead of quote: 

(mapc (function (lambda (x) (car x))) some-list) 

To ease typing, the reader converts #' 'thing into (function thing). So #' is similar 
to ' except that it produces a function form instead of a quote form. So the above 
form could be written as: 

(mapc ft' (lambda (x) (car x)) some-list) 

If function is not a function but the name of a function (typically a symbol, but in 
general any kind of function spec), function returns the definition of function; it is 
like fdefinition except that it is a special form instead of a function, and so 

(function fred) 
is like 

(fdefinition 'fred) 
which is like 

(fsymeval 'fred) 

since fred is a symbol. Note that you cannot use fsymeval in CLOE. 

If function is the name of a local function defined with flet or labels, then 
(function function) produces a lexical closure of function, just like (function 
(lambda...)). 

Another way of explaining function is that it causes function to be treated the 
same way as it would as the car of a form. Evaluating the form (function argl 



Page 1 136 



arg2...) uses the function definition of function if it is a symbol, and otherwise ex- 
pects function to be a list that is a lambda-expression. Note that the car of a form 
cannot be a nonsymbol function spec, to avoid difficult-to-read code. This can be 
written as: 

(funcall (function spec) args . . .) 

You should be careful about whether you use #' or '. Suppose you have a program 
with a variable x whose value is assumed to contain a function that gets called on 
some arguments. If you want that variable to be the car function, there are two 
things you could say: 

(setq x 'car) 

or 

(setq x #'car) 

The former causes the value of x to be the symbol car, whereas the latter causes 
the value of x to be the function object found in the function cell of car. When 
the time comes to call the function (the program does (funcall x ...)), either of 
these two work because if you use a symbol as a function, the contents of the 
symbol's function cell are used as the function. The former case is a bit slower, 
because the function call has to indirect through the symbol, but it allows the 
function to be redefined, traced, or advised. (See the special form trace. See the 
special form advise.) The latter case, while faster, picks up the function definition 
out of the symbol car and does not see any later changes to it. 



function (( argl-type arg2-type ... ) value-type ) Type Specifier 

function is the type specifier for the predefined Lisp object of that name. 

The list syntax is for declaration. Every element of this type is a function that ac- 
cepts arguments at least of the types specified by the argj-type forms, and returns 
a value that is a member of the types specified by the value-type form. 

Examples: 

(defun fun-example (num) (+ num num)) => FUN-EXAMPLE 
(typep 'fun-example 'function) => T 
(sys: type-argl ist 'function) => NIL and T 
(functionp 'fun-example) => T 

See the section "Data Types and Type Specifiers". 

See the section "Functions". 

sys:function-cell-location sym Function 

Returns a locative pointer to sym's function cell. See the section "Cells and Loca- 
tives". It is preferable to write: 

(locf (zl : fsymeval sym)) 

rather than calling this function explicitly. See the section "Functions Relating to 
the Function Cell of a Symbol". 



Page 1 137 



si:function-encapsulated-p function-spec 

Function 

Looks at the debugging info alist to check whether function-spec is an encapsula- 
tion. 

closrfunction-keywords method Generic Function 

Returns a list of the keywords for method as its first value, and a boolean indicat- 
ing whether &allow-other-keys was specified as its second value. 

method A method object. 



sysrfunction-parent function-spec &optional definition-type Function 

When a symbol's definition is produced as the result of macro expansion of a 
source definition, so that the symbol's definition does not appear textually in the 
source, the editor cannot find it. The accessor, constructor, and alterant macros 
produced by a defstruct are an example of this. The sysrfunction-parent declara- 
tion can be inserted in the source definition to record the name of the outer defi- 
nition of which it is a part. 

The declaration consists of the following: 
(sysrfunction-parent name type) 

name is the name of the outer definition, type is its type, which defaults to defun. 
See the section "How Programs Manipulate Definitions". Declarations are explained 
in another section. See the section "Declarations". 

sysrfunction-parent is a function related to the declaration. It takes a function 
spec and returns nil or another function spec. The first function spec's definition 
is contained inside the second function spec's definition. The second value is the 
type of definition. 

Two examples: 

(defsubst foo (x y) 

(declare (sys: function-parent bar)) 

(defmacro defxxx (name ...) 

'(zl : local-declare ((sys: function-parent ,name defxxx)) 
(defmacro . . . ) 
(defmacro . . . ) 

)) 

sirfunction-spec-get function-spec indicator Function 



Page 1 138 



Returns the value of the indicator property of function-spec, or nil if it doesn't 
have such a property. 



si:function-spec-putprop function-spec value indicator Function 

Gives function-spec an indicator property whose value is value. 

functionp x &optional allow-special-forms 

Function 

Returns t if its argument x is a function (essentially, something that is acceptable 
as the first argument to apply), otherwise it returns nil. Under Genera, in addi- 
tion to interpreted, compiled, and built-in functions, functionp is true of closures, 
select-methods, and symbols whose function definition is functionp. See the section 
"Other Kinds of Functions", functionp is not true of objects that can be called as 
functions but are not normally thought of as functions: arrays, stack groups, enti- 
ties, and instances. 

Compatibility Note: Symbolics Common Lisp (but not CLOE) provides the optional 
argument allow-special-forms. If allow-special-forms is specified and non-nil, then 
functionp is true of macros and special-form functions (those with quoted argu- 
ments). Normally functionp returns nil for these since they do not behave like 
functions, allow-special-forms might not work in other implementations of Common 
Lisp, functionp returns nil when it is called on a symbol that does not have a 
function definition, although Common Lisp specifies that functionp of a symbol is 
always t. 

As a special case, functionp of a symbol whose function definition is an array re- 
turns t, because in this case the array is being used as a function rather than as 
an object. 

Under CLOE, closures (results of the function special form), lambda expressions, 
and names of functions are all considered functions by functionp. When applied to 
symbols, functionp always returns true, regardless of whether or not they are cur- 
rently fboundp. 

(functionp #'eql) => t 

(functionp 'eql) => t 

(functionp '(lambda (x) (+ 5 x))) => t 



fundefine function-spec Function 

Removes the definition of function-spec and returns function-spec. For symbols this 
is equivalent to fmakunbound. If the function is encapsulated, fundefine removes 
both the basic definition and the encapsulations. Some types of function specs 
(rlocation for example) do not implement fundefine. Using fundefine on a rwithin 
function spec removes the replacement of function-to-affect, putting the definition 
of within-function back to its normal state. Using fundefine on a method's func- 



Page 1 139 



tion spec removes the method completely, so that future messages or generic func- 
tions will be handled by some other method. 



g-l-p array Function 

If array has a fill pointer, g-l-p returns a list that stops at the fill pointer, if you 
never modify the fill-pointer except with zl:array-push, zl:array-pop and so on. 
array must be a general (sys:art-q-list) array. Example: 

(setq a (zl : make-array 4 :type 'art-q-1 ist)) 

(aref a 0) => nil 

(setq b (g-l-p a)) => (nil nil nil nil) 

(setf (car b) t) 

b => (t nil nil nil ) 

(aref a 0) => t 

(setf (aref a 2) 30) 

b => (t nil 30 nil) 



gcd &rest integers Function 

If one argument is given, the absolute value is returned. If there are no argu- 
ments, the returned value is 0. 

Examples: 

(gcd) => 
(gcd -9) => 9 
(gcd 36 48) => 12 
(gcd 16 72 40 24) => 8 

For a table of related items, see the section "Arithmetic Functions". 



zhgcd integerl integer2 &rest more-integers Function 

Returns the greatest common divisor of all its arguments. The arguments must be 
integers. With oneargument integer, it returns the absolute value of integer, and 
with no arguments, it returns 0. The result returned is always returns a non- 
negative integer. 

(gcd -15 105) -> 15 

(gcd 15 12 9) -» 3 

(gcd 5 7 11 18) -» 1 

(gcd) -> 
The following function is a synonym of zhgcd: 
zl:\\ 



Page 1 140 



For a table of related items: See the section "Arithmetic Functions". 



flavorrgeneric generic-function-name Special Form 

Evaluates to the generic function object for generic-function-name (which is not 
evaluated). This is used when there is a prologue function so that the function def- 
inition of generic-function-name is not itself the generic function. This is used in 
conjunction with the rfunction option to def generic. For example: 

(apply (flavor : generic make-instance) new-instance init-options) 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



clos:generic-flet Special Form 

Symbolics CLOS does not support clos:generic-flet. 

closrgeneric-function Macro 

Symbolics CLOS does not support closrgeneric-function. 

sysrgeneric-function Type Specifier 

closrgeneric-labels Special Form 

Symbolics CLOS does not support closrgeneric-labels. 

gensym &optional arg Function 

Invents a print-name, and creates a new symbol with that print-name. It returns 
the new, uninterned symbol. 

The invented print-name is a character prefix (the value of *gensym-prefix*) fol- 
lowed by the decimal representation of a number (the value of *gensym-counter*), 
for example, "G0001". The number is increased by 1 every time gensym is called. 

If the argument arg is present and is a fixnum, then *gensym-counter* is set to 
arg. If arg is a string or a symbol, then *gensym-prefix* is set to the string or 
the symbol's print-name. After handling the argument, gensym creates a symbol 
as it would with no argument. Examples: 

if (gensym) =>#:G3310 

then (gensym "foo") => #:|foo3311| 

(gensym 32) => #:|foo32| 

(gensym) => #:|foo33| 

gensym is usually used to create a symbol that should not normally be seen by the 
user, and whose print-name is unimportant, except to allow easy distinction by eye 



Page 1141 



between two such symbols. The optional argument is rarely supplied because it 
changes the default prefix for future calls to gensym. To create a symbol with a 
particular prefix when using Genera, use sysrgensymbol. See the function 
sysrgensymbol. 

The name gensym comes from "generate symbol", and the symbols produced by it 
are often called "gensyms". This function is also useful for obtaining anonymous, 
locally bound variables created by macros at compile time. In the following exam- 
ple, macro do-vector is created by using gensym. This form is similar to dolist 
because var is successively bound to vector elements. 

(defmacro do-vector ((var vector &optional result) &body forms) 
(let ((genvarl (gensym)) 
(genvar2 (gensym))) 
1 (do ((, genvarl (length , vector)) 
(,genvar2 (+ 1 , genvar2))) 
((>= , genvar2 , genvarl) , result) 
(let ((,var (elt , vector ,genvar2))) 
,@forms)))) 

(do-vector (element '#(foo bar baz)) (print element)) 

F00 

BAR 

BAZ 

For a list of related functions: See the section "Functions for Creating Symbols". 



zlrgensym &optional x Function 

Invents a print-name, and creates a new symbol with that print-name. It returns 
the new, uninterned symbol. 

If the argument x is present and is a fixnum, then future-common-lisp r*gensym- 

counter* is set to x and incremented. If x is a string or a symbol, then 
clirr*gensym-prefix* is set to the first character of the string or of the symbol's 
print-name. After handling the argument, gensym creates a symbol as it would 
with no argument. Examples: 

if (zl :gensym) =>#:G3310 

then (zl:gensym "foo") => #:F3311 

(zl : gensym 32) => #:F0033 

(zl : gensym) => #:F0034 

Note that the number is in decimal and always has four digits, and the prefix is 
always one character. 

See the function gensym. 

See the section "Functions for Creating Symbols". 



sysrgensymbol &optional (prefix "G") count Function 



Page 1 142 



Like gensym, invents a print-name and creates a new symbol with that print- 
name. It returns the new, uninterned symbol. Unlike gensym, however, if a prefix 
is given, it does not become the default for future calls to sysrgensymbol. For ex- 
ample: 

if (sys:gensymbol ) => #:G0035 

then (sys:gensymbol "foo") => #:|foo36| 
(sys:gensymbol ) => #:G0037 

Contrasted with: 

if (gensym) => #:G0038 

then (gensym "foo") => #:|foo39| 
(gensym) => #:|foo40| 

sysrgensymbol is the recommended way to get symbols with a specific prefix. 
For a list of related functions: See the section "Functions for Creating Symbols". 

gentemp &optional (prefix "T") package Function 

Creates and returns a new symbol as gensym does, but gentemp interns the sym- 
bol in package. Package defaults to the current package, that is, the value of 
*package*. gentemp guarantees that the generated symbol is a new one not al- 
ready existing in package. There is no provision for resetting the gentemp counter 
and the prefix is not remembered from one call to the next. If prefix is omitted, 
"T" is used. 

(gentemp) => T1 

(defparameter T2 42) 

(gentemp) => T3 

(gentemp "FOO") => F004 
See the section "Functions for Creating Symbols". 

get symbol indicator &optional default Function 

Searches the property list of symbol for an indicator that is eq to indicator. (See 
the section "Property Lists".) The first argument must be a symbol. If a matching 
indicator is found, the corresponding value is returned; otherwise default is re- 
turned. If default is not specified, nil is used. Note that there is no way to distin- 
guish an absent property from one whose value is default. 

To give a symbol a property, use: 

(setf (get symbol indicator) value) 
Suppose that the property list of eagle is 

(color (brown white) food snakes seed-eater nil) 
Then, for example: 



Page 1 143 



(get 'eagle 'color) => (BROWN WHITE) 

(get 'eagle 'food) => SNAKES 

(get 'eagle 'seed-eater) => NIL 

(get 'eagle 'beak "No such indicator") => "No such indicator" 

setf can be used with get to create a new property-value pair, possibly replacing 
an old pair with the same name. For example: 

(setf (get 'eagle 'food) '(mice snakes)) => (MICE SNAKES) 

For a table of related items: See the section "Functions That Operate on Property 
Lists". 



zhget symbol indicator Function 

Looks up symbol's indicator property. (See the section "Property Lists".) If it finds 
such a property, it returns the value; otherwise, it returns nil. zhget uses the 
symbol's associated property list. For example, if the property list of foo is (baz 
3), then: 

(zl:get 'foo 'baz) => 3 
(zl:get 'foo 'zoo) => nil 

For a table of related items: See the section "Functions That Operate on Property 
Lists". 



flavor:get-all-flavor-components flavor-name &optional env Function 

Returns a list of the components of the flavor flavor-name, in the sorted ordering 
of flavor components. Any duplicate flavors are eliminated from this list by the fla- 
vor ordering mechanism. See the section "Ordering Flavor Components". 

For example: 

(f 1 avor : get-al 1 -f 1 avor-components ' tv : mi ni mum-wi ndow) 
=>(T\/:MINIMUM-WINDOW TV : ESSENTIAL-EXPOSE TV : ESSENTIAL-ACTIVATE 

TV:ESSENTIAL-SET-EDGES TV : ESSENTIAL-MOUSE TV : ESSENTIAL-WINDOW 

TV:SHEET SI : OUTPUT-STREAM SI:STREAM FLAVOR : VANILLA) 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 

get-dispatch-macro-character disp-char sub-char &optional (a-readtable 
*readtable*) Function 

Returns the macro-character function for sub-char under disp-char, or nil if there 
is no function associated with sub-char. If sub-char is one of the ten decimal dig- 
its, get-dispatch-macro-character always returns nil. If sub-char is a lowercase 
character, its uppercase equivalent is always used instead. 

An error is signalled if the specified disp-char is not a dispatch character in the 
specified readtable. 



Page 1 144 



(get-dispatch-macro-character #\# #V) => 

#<LEXICAL-CLOSURE (: INTERNAL GET-DISPATCH-MACRO-CHARACTER 0) 
36057616> 

(get-dispatch-macro-character #\# #\1) => NIL 

Note that because get-dispatch-macro-character returns a lexical closure, subse- 
quent calls will not necessarily return the same object. This may be changed in a 
future release. 

(let ((xreadtablex (copy-readtable nil))) 
(get-dispatch-macro-character #\# #\\) 
(get-dispatch-macro-character #\# #\Q)) 
=> NIL 



zl:get-flavor-handler-for flavor-name operation Function 

Given a flavor-name and an operation (a function spec that names a generic func- 
tion or a message), zl:get-flavor-handler-for returns the flavor's method for the 
operation or nil if it has none. 

For example: 

(zl :get-flavor-handler-for 'box-with-cel 1 'find-neighbors) 
=>#<DTP-COMPILED-FUNCTION 

(FLAVOR: METHOD FIND-NEIGHBORS CELL) 20740320> 

(zl :get-flavor-handler-for 'cell ' :print-sel f) 
=>#<DTP-COMPILED-FUNCTION 

(FLAVOR: METHOD SYS : PRINT-SELF FLAVOR: VANILLA DEFAULT) 42456350> 

Although operation is usually a symbol (naming a generic function) or a keyword 
(naming a message), it is occasionally a list. For example, names of some generic 
functions are lists, such as (setf function). 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



si:get-font device character-set style &optional (error-p t) inquiry-only Function 

Given a device, character-set and style, returns a font object that would be used to 
display characters from that character set in that style on the device. This is use- 
ful for determining whether there is such font mapping for a given device/set/style 
combination. 

A font object may be various things, depending on the device. 

If error-p is non-nil, this function signals an error if no mapping to a font is 
found. If error-p is nil and no font mapping is found, si:get-font returns nil. 



Page 1 145 



If inquiry-only is provided, the returned value is not a font object, but some other 
representation of a font, such as a symbol in the fonts package (for screen fonts) 
or a string (for printer fonts). 

(si: get-font si :*b&w-screenx si :xstandard-character-setx 
'(:jess : roman :normal)) 

=> #<F0NT JESS13 154102066> 

(si :get-font lgp:*lgp2-printerx si :xstandard-character-setx 
'(:swiss : roman : normal) nil t) 

=> "Hel vetica10" 
For related information: See the section "Mapping a Character Style to a Font". 

dbg:get-frame-function-and-args frame Function 

Returns a list containing the name of the function for frame-pointer and the values 
of the arguments. 

Caution: Use this function only within the context of the dbg:with-erring-frame 
macro. 

For a table of related items: See the section "Functions for Examining Stack 
Frames". 



get-handler-for object operation Function 

Given an object and an operation (a function spec that names a generic function or 
a message), returns that object's method for the operation, or nil if it has none. 
When object is an instance of a flavor, this function can be useful to find which of 
that flavor's components supplies the method. If a combined method is returned, 
you can use the Zmacs command List Combined Methods (m-K) to find out what it 
does. 

For example: 

(get-handler-for this-box-with-cel 1 'count-live-neighbors) 
=>#<DTP-COMPILED-FUNCTION 

(FLAVOR: METHOD 'COUNT-LIVE-NEIGHBORS CELL) 42456350> 

(get-handler-for this-box-with-cel 1 ' :print-sel f) 
=>#<DTP-COMPILED-FUNCTION 

(FLAVOR: METHOD SYS : PRINT-SELF FLAVOR: VANILLA DEFAULT) 42456350> 

Because it is a generic function, you can define methods for get-handler-for. The 
syntax of this is: 

(def method (get-handler-for flavor) (operation) 
body) 



Page 1 146 



In most cases you should use :or method combination (by supplying the rmethod- 
combination option for defflavor) so your method need not know what the 
flavorrvanilla method does. 

Although operation is usually a symbol (naming a generic function) or a keyword 
(naming a message), it is occasionally a list. For example, names of some generic 
functions are lists, such as (setf function). 

Note that get-handler-for does not work on named-structures or non-instance 
streams. You might consider using :operation-handled-p instead. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



:get-hash key Message 

Find the entry in the hash table whose key is key, and return three values. The 
first returned value is the associated value of key, or nil if there is no such entry. 
The second value is t if an entry was found or nil if there is no entry for key in 
this table. The third value is key, or nil if there was no such key. 

This message is obsolete; use zhgethash instead. 



get-macro-character char &optional (a-readtable *readtable*) Function 

Returns two values: the function associated with char, and the value of the non- 
terminating-p flag. It returns just the symbol nil if char does not have macro- 
character syntax. For example: 

(get-macro-character #V) => 

#<LEXICAL-CLOSURE (INTERNAL GET-MACRO-CHARACTER 0) 16433170> 

NIL 

(get-macro-character #\-) => NIL 

Note that because get-macro-character returns a lexical closure, subsequent calls 
will not necessarily return the same object. This may be changed in a future re- 
lease. 

(let ((xreadtablex (copy-readtable nil))) 

(get-macro-character #\_)) 
=> NIL 



:get-output-buffer Message 

Returns an array and starting and ending indices. 

get-output-stream-string stream Function 



Page 1 147 



Returns a string containing all of the characters output to stream so far. Works in 
conjunction with make-string-output-stream, stream is reset after each call, thus 
each call to get-output-stream-string gets only the characters that have been out- 
put to the stream since the last such call (or the creation of stream, if no such 
previous call has been made). 

(setq s (make-string-output-stream)) 

=> #<LEXICAL-CLOSURE CLI :: STRING-OUTPUT-STREAM 10602460> 

(write-string "Hello" s) => "Hello" 

(get-output-stream-string s) => "Hello" 

(write-string "Goodbye" s) => "Goodbye" 

(get-output-stream-string s) => "Goodbye" 

(defvar xheadingx '("Name " "Rank " "Serial-number ")) 
(defvar xnumber-of-namesx 3) 

(let ((my-stream (make-string-output-stream)) 
(1 ist-of-strings xheadingx)) 
(dolist (str 1 ist-of-strings) 

(princ str my-stream)) 
(get-output-stream-stri ng my-stream) ) 
(dotimes (i xnumber-of-namesx) 

(print (+ i 1) my-stream)) 
(get-output-stream-stri ng my-stream) ) 



zhget-pname symbol Function 

Returns the print-name of the symbol symbol. Example: 

(zl :get-pname 'xyz) => "xyz" 

In your new programs, we recommend that you use the function symbol-name 
which is the Common Lisp equivalent of the function zhget-pname. See the sec- 
tion "Functions Relating to the Print Name of a Symbol". 

get-properties plist indicator-list Function 

Searches the property list stored in plist for any of the indicators in indicator-list. 



Page 1 148 



get-properties returns three values. If none of the indicators is found, all three 
values are nil. If the search is successful, the first two values are the property 
found and its value and the third value is the tail of the property list whose car is 
the property found. Thus the third value serves to indicate success or failure and 
also allows you to restart the search after the property found, if you so desire. 

In the following example, note that although COLOR does not precede SPEED in 
the indicator-list, it does precede SPEED in the property list. Therefore, COLOR 
is located before SPEED. 

(defvar 'xsome-symbolx 

(list 'COLOR 'RED 'SPEED 'MYSTICAL 'HIT-POINTS '60)) 

(get-properties xsome-symbolx '(magic speed color)) => 

COLOR 

RED 

(COLOR RED SPEED MYSTICAL HIT-POINTS 60) 

See the section "Functions Relating to the Property List of a Symbol". 



get-setf-method reference &optional for-effect Function 

In this context, the word "method" has nothing to do with flavors. 

Returns five values constituting the setf method for reference, which is a general- 
ized-variable reference. (The five values are described in detail at the end of this 
discussion.) get-setf-method takes care of error-checking and macro expansion and 
guarantees to return exactly one store-variable. 

Compatibility Note: The optional argument for-effect is a Symbolics extension to 
Common Lisp. If for-effect is t, you are indicating that you don't care about the 
evaluation of store-forms (one of the five values), which allows the possibility of 
more efficient code. In other words, for-effect is an optimization, for-effect might 
not work in other implementations of Common Lisp, in particular, it is not imple- 
mented for CLOE. 

As an example, an extremely simplified version of setf, allowing no more and no 
fewer than two subforms, containing no optimization to remove uncessary vari- 
ables, and not allowing storing of multiple values, could be defined by: 

(defmacro setf (reference value) 

(multiple-value-bind (vars vals stores store-form access-form) 
(get-setf-method reference) 
(declare (ignore access-form)) 
'(letx , (mapcar tf'list 

(append vars stores) 
(append vals (list value))) 
, store form))) 

For more information, see the macro define-setf-method. 



Page 1 149 



get-setf-method-multiple-value reference &optional for-effect Function 

Returns five values constituting the setf method for reference, which is a general- 
ized-variable reference. (The five values are described in detail at the end of this 
discussion.) This is the same as get-setf-method, except that it does not check the 
number of store-variables (one of the five values). Use get-setf-method-multiple- 
value in cases that allow storing multiple values into a generalized variable. This 
is not a common need. 

Compatibility Note: The optional argument for-effect is a Symbolics extension to 
Common Lisp, which might not work in other implementations of Common Lisp. 

Here are the five values that express a setf method for a given access form. 

• A list of temporary variables. 

• A list of value forms (subforms of the given form) to whose values the tempo- 
rary variables are to be bound. 

• A second list of temporary variable, called store variables. 

• A storing form. 

• An accessing form. 

The temporary variables are bound to the value forms as if by let*; that is, the 
value forms are evaluated in the order given and may refer to the values of earlier 
value forms by using the corresponding variable. 

The store variables are to be bound to the values of the newvalue form, that is, 
the values to be stored into the generalized variable. In almost all cases, only a 
single value is stored, and there is only one store variable. 

The storing form and the accessing form may contain references to the temporary 
variables (and also, in the case of the storing form, to the store variables). The ac- 
cessing form returns the value of the generalized variable. The storing form modi- 
fies the value of the generalized variable and guarantees to return the values of 
the store variables as its values. These are the correct values for setf to return. 
(Again, in most cases there is a single store variable and thus a single value to be 
returned.) The value returned by the accessing form is, of course, affected by exe- 
cution of the storing form, but either of these forms may be evaluated any number 
of times, and therefore should be free of side effects (other than the storing action 
of the storing form). 

The temporary variables and the store variables are generated names, as if by 
gensym or gentemp, so that there is never any problem of name clashes among 
them, or between them and other variables in the program. This is necessary to 
make the special forms that do more than one setf in parallel work properly. 
These are psetf, shiftf and rotatef. 

Here are some examples of setf methods for particular forms: 



Page 1 150 



• For a variable x: 





(g0001) 

(setq x g0001) 

x 

• For (car exp): 

(g0002) 

(exp) 

(g0003) 

(progn (rplaca g0002 g0003) g0003) 

(car g0002) 

• For (supseq seq s e): 

(g0004 g0005 g0006) 

(seq s e) 

(g0007) 

(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) 

g0007) 
(subseq g0004 g0005 g0006) 



zhgetchar s i Function 

Returns the i (indexth) character of s {string) as a symbol. Note that 1-origin in- 
dexing is used. This function is mainly for Maclisp compatibility; aref should be 
used to index into strings (however, aref does not coerce symbols into strings). 

Examples: 

(zl :getchar "string" 1) => |s| 

(zl :getchar 'symbol 2) => Y 

(zl :getchar "STRING" 1) => S 

(zl :getchar "ORANGE" 0) => NIL ;1-origin indexing is used 



zhgetcharn s i Function 

Returns the i (indexth) character of s (string) as a character. Note that 1-origin in- 
dexing is used. This function is mainly for Maclisp compatibility; aref should be 
used to index into strings (however, aref does not coerce symbols or numbers into 
strings). 

Examples: 



Page 1 151 



(zl :getcharn "string" 1) => #\s 

(zl :getcharn 'symbol 2) => #\Y 

(zl:getcharn "STRING" 1) => #\S 

(zl:getcharn "ORANGE" 0) => ;1-origin indexing is used 



getf plist indicator &optional default Function 

Searches for the property indicator on plist. If indicator is found, the corresponding 
value is returned. If getf cannot find indicator, default is returned. If default is not 
specified, nil is used. Note that there is no way to distinguish between a property 
whose value is default and a missing property. 

This function differs from function get in that it takes a place rather than a sym- 
bol as its first argument. 

(getf (symbol -pi ist 'some-symbol) 'color) => RED 

(getf (symbol-pl ist 'some-symbol) 'size 'moderate) => MODERATE 

(defvar xmy-plistx '()) 

(setf (getf xmy-plistx 'mode) 'auto-fill) 

xmy-plistx => (MODE AUTO-FILL) 

(getf xmy-plistx 'mode) => AUTO-FILL 
See the section "Functions Relating to the Property List of a Symbol". 

gethash key table &optional default Function 

Finds the entry in table whose key is key and returns the associated value. If there 
is no such entry, gethash returns default, which is nil if not specified. It returns 
three values; the value associated with key, whether or not the key was found (t or 
nil), and the found key if one exists, or nil if not. 

setf is used with gethash to make new entries in the table. If an entry with the 
specified key exists, it is removed before the new entry is added. 

Compatibility Note: Under Genera, gethash is extended to return an extra value: 
it returns the value of the found key. The reason for this extension is that the 
:test function, in general, matches non-eq keys with the key stored in the table. In 
some situations, you might want to know the actual stored key. CLOE returns two 
values, as specified in CLtL. 

(setf (gethash a-key my-table) a-value) 

The default argument to gethash can be specified in a very useful way with relat- 
ed functions like incf. 

(incf (gethash b-key my-table 0) b-value) 

is a shorthand for 

(setf (gethash b-key my-table) (+ (gethash b-key my-table) b-value)) 



Page 1 152 



For a table of related items: See the section "Table Functions". 



zhgethash key hash-table Function 

Finds the entry in table whose key is key and returns the associated value. This 
function is obsolete; use gethash instead. 



zhgethash-equal key hash-table Function 

Finds the entry in table whose key is key and returns the associated value. This 
function is obsolete; use gethash instead. 



zhgetl symbol indicator-list Function 

Searches down symbol for any of the indicators in indicator-list until it finds a 
property whose indicator is one of the elements of indicator-list, zhgetl uses the 
symbol's associated property list. (See the section "Property Lists".) zhgetl returns 
the portion of the list inside symbol that begin with the first such property it 
finds. So the car of the returned list is an indicator, and the cdr is the property 
value. If none of the indicators on indicator-list are on the property list, zhgetl re- 
turns nil. For example, if the property list of foo were: 

(bar (1 2 3) baz (3 2 1) color blue height six-two) 

then: 

(zl :getl 'foo ' (baz height)) 
=> (baz (3 2 1) color blue height six-two) 

When more than one of the indicators in indicator-list is present in indicator-list, 
which one zhgetl returns depends on the order of the properties. This is the only 
thing that depends on that order. 

For a table of related items: See the section "Functions That Operate on Property 
Lists". 



globalize name &optional package Function 

Establishes a symbol named name in package and exports it. If this causes any 
name conflicts with symbols with the same name in packages that use package, in- 
stead of signalling an error globalize makes an attempt to resolve the name con- 
flict automatically and prints an explanation of what is being done on zherror- 
output. 

globalize is useful for patching up an existing package structure. For example, if 
a new function is added to the Lisp language globalize can be used to add its 
name to the global package and hence make it accessible to all packages. Symbols 
with the desired name might already exist, either by coincidence or because the 
function was already defined or already called, globalize makes all such symbols 
have the new function as their definition. 



Page 1 153 



package can be a package object or the name of a package, as a symbol or a 
string. It defaults to the global package, globalize is the only function that does 
not care whether package is locked. 

name can be a symbol or a string. If package already contains a symbol by that 
name, that symbol is chosen. Otherwise, if name is a symbol, it is chosen. If name 
is a string and any of the packages that use package contains a nonshadowing 
symbol by that name, one such symbol is chosen. Otherwise, a new symbol named 
name is created. Whichever symbol is chosen this way is made present in package 
and exported from it. If the home package of the chosen symbol is a package that 
uses package, then the home package is set to package; in other words, the symbol 
is "promoted" to a "higher" package. If the home package of the chosen symbol is 
some other package, it is not changed. This case typically occurs when the chosen 
symbol is inherited by package from some package it uses. 

The above rules for choosing a symbol to export ensure that no name conflict oc- 
curs if at all possible. If any nonshadowing symbols exist named name but that are 
distinct from the chosen symbol present in the packages that use package, then a 
name conflict occurs, globalize does its best to resolve the name conflict by merg- 
ing together the values, function definitions, and properties of all the symbols in- 
volved. After merging, all the symbols have the same value, the same function 
definition, and the same properties. The value cells, function cells, and property 
list cells of all the symbols are forwarded to the corresponding cells of the chosen 
symbol, using sys:dtp-one-q-forward. This ensures that any future change to one 
of the symbols is reflected by all of the symbols. 

The merging operation consists simply of making sure that there are no conflicts. 
If more than one of the symbols has a value (is boundp), all the values must be 
eql or an error is signalled. Similarly, all the function definitions of symbols that 
are fboundp must be eql and all the properties with any particular indicator must 
be eql. If an error occurs, you must manually resolve it by removing the unwanted 
value, definition, or property (using makunbound, fmakunbound, or zhremprop) 
then try again. 

Note that if name is a symbol, globalize attempts to use that symbol, but there is 
no guarantee that it will not use some other symbol. If name is in a package that 
does not use package, and globalize does not use name as the symbol (because an- 
other symbol by that name already exists in package or in some package that uses 
package), name is not merged with the chosen symbol. It is generally more pre- 
dictable to use a string, rather than a symbol, for name. 

Of course, globalize cannot cause two distinct symbols to become eq. Its conflict 
resolution techniques are useful only for symbols that are used as names for 
things like functions and variables, not for symbols that are used for their own 
sake. You can sometimes get the desired effect by using one of the conflicting 
symbols as the first argument to globalize, rather than using a string. 

For example, suppose a program in the color package deals with colors by symbol- 
ic names, perhaps using zhselectq to test for such symbols as red, green, and 
yellow. Suppose there is also a function named red in the math package and 
someone decides that this function is generally useful and should be made global. 



Page 1 154 



Doing (globalize 'colorrred) ensures that the exported symbol is the one that the 
color program is looking for; this means that every package except the math pack- 
age sees the right symbol to use if it wants to call the color program. Programs 
that call the red function do not care which of the two symbols they use as the 
name of the function, since both symbols have the same definition. Usually the sit- 
uation described in this example would not arise, because standard programming 
style dictates that the color program should have been using keywords for this ap- 
plication. 

globalize returns two values. The first is the chosen symbol and the second is a 
(possibly empty) list of all the symbols whose value, function, and property cells 
were forwarded to the cells of the chosen symbol. 

To disable the messages printed by globalize, bind zherror-output to a null 
stream (one that throws away all output). For example: 

(let ((zl : error-output 'si :nul 1 -stream)) 
(globalize ' rumpelstil tskin)) 



go tag Special Form 

Transfers control within a tagbody form or a construct like do or prog that uses 
an implicit tagbody. 

The tag can be a symbol or an integer. It is not evaluated, go transfers control to 
the tag in the body of the tagbody that is eql to the tag in the go form. If the 
body has no such tag, the bodies of any lexically containing tagbody forms are ex- 
amined as well. If no tag is found, an error is signalled. 

The scope of tag is lexical. That is, the go form must be inside the tagbody con- 
struct itself (or inside a tagbody form that that tagbody lexically contains), not 
inside a function called from the tagbody, but defined outside the tagbody. 

Examples: 

(tagbody 

(let ((z 5)) 
(unwind-protect 

(if (= 5 z) (go out)) 
(print z))) 
out 
(princ "4 3 and then there were none") (terpri)) => 
5 4 3 and then there were none 
NIL 



Page 1 155 



(prog (x y z) 

(setq x some frob) 
loop 

do something 

(if some predicate (go endtag)) 

do something more 

(if (minusp x) (go loop)) 
endtag 

(return z)) 

(let ((i 0) 

(result t)) 
(tagbody loop 

(when (and (< i 20) result) 

(unless (= (aref xdata-vectorx i) i) 

(setq result nil)) 
(go loop)))) 

For a table of related items: See the section "Transfer of Control Functions". 



graphic-char-p char Function 

Returns t if char does not have any control bits set and is not a format effector. 

(graphic-char-p #\A) => T 
(graphic-char-p #\c-A) => NIL 
(graphic-char-p #\Space) => T 

For a table of related items, see the section "Character Predicates". 

zhgreaterp number &rest more-numbers Function 

In your new programs, we recommend that you use the function >, which is the 
Common Lisp equivalent of zhgreaterp. 

zhgreaterp compares its arguments from left to right. If any argument is not 
greater than the next, zhgreaterp returns nil. But if the arguments are monotoni- 
cally strictly decreasing, the result is t. Examples: 

(zl:greaterp 4 3) => t 

(zl :greaterp 4 3 2 1 0) => t 

(zl:greaterp 4 3 1 2 0) => nil 



zhgrind-top-level exp &optional si:grind-width (si:grind-real-io zhstandard-output) 

si:grind-untyo-p (si: grind-displaced 'shdisplaced) (terpri-p t) si: grind-notify- fun (hoc 
(neons exp)) Function 

Pretty-prints exp on stream, inserting up to si: grind-width characters per line. This 
is the primitive interface to the pretty-printer. Note that it does not support vari- 



Page 1 156 



able-width fonts. If the si: grind-width argument is supplied, it is how many charac- 
ters wide the output is to be. If si:grind-width is unsupplied or nil, zl:grind-top- 
level tries to determine the "natural width" of the stream by sending a :size-in- 
characters message to the stream and using the first returned value. If the 
stream does not handle that message, a width of 95 characters is used instead. 

The remaining optional arguments activate various features and usually should not 
be supplied. These options are for internal use by the system, and are documented 
here only for completeness. If untyo-p is t, the runtyo and :untyo-mark operations 
are used on stream, speeding up the algorithm somewhat, displaced controls the 
checking for displacing macros; it is the symbol that flags a place that has been 
displaced, or nil to disable the feature. If terpri-p is nil, zl:grind-top-level does not 
advance to a fresh line before printing. 

If si: grind-notify- fun is non-nil, it is a function of three arguments and is called 
for each "token" in the pretty-printed output. Tokens can be atoms, open and close 
parentheses, and reader macro characters such as '. The arguments to si:grind- 
notify-fun are the token, its "location" (see next paragraph), and t if it is an atom 
or nil if it is a character. 

loc is the "location" (typically a cons) whose car is exp. As the grinder recursively 
descends through the structure being printed, it keeps track of the location where 
each thing came from, for the benefit of the si: grind-notify- fun, if any. This makes 
it possible for a program to correlate the printed output with the list structure. 
The "location" of a close parenthesis is t, because close parentheses have no asso- 
ciated location. 



grindef &rest fens Special Form 

Prints the definitions of one or more functions, with indentation to make the code 
readable. Certain other "pretty-printing" transformations are performed: 

• The quote special form is represented with the ' character. 

• Displacing macros are printed as the original code rather than the result of 
macro expansion. 

• The code resulting from the backquote (') reader macro is represented in terms 
of. 

The subforms to grindef are the function specs whose definitions are to be print- 
ed; ordinarily, grindef is used with a form such as (grindef foo) to print the defi- 
nition of foo. When one of these subforms is a symbol, if the symbol has a value 
its value is prettily printed also. Definitions are printed as defun special forms, 
and values are printed as setq special forms. 

If a function is compiled, grindef says so and tries to find its previous interpreted 
definition by looking on an associated property list. See the function uncompile. 
This works only if the function's interpreted definition was once in force; if the 
definition of the function was simply loaded from a binary file, grindef does not 
find the interpreted definition and cannot do anything useful. 



Page 1 157 



With no subforms, grindef assumes the same arguments as when it was last 
called. 



zhhaipart x n Function 

Returns the high n bits of the binary representation of |x|, or the low -n bits if n 
is negative, x must be an integer; its sign is ignored, zhhaipart could have been 
defined by: 

(defun zl:haipart (x n) 
(setq x (abs x)) 
(if (minusp n) 

(logand x (1- (ash 1 (- n)))) 

(ash x (min (- n (zl:haulong x)) 0)))) 

For a table of related items: See the section "Functions Returning Components or 
Characteristics of Argument". 

rhandle-condition cond ignore Message 

An interactive handler message to instances of dbgrbasic-handler. 

cond is a condition object. You should handle this condition, ignoring the second 
argument, rhandle-condition can return values or throw in the same way that 
condition-bind handlers can. See the message :handle-condition-p. 

:handle-condition-p cond Message 

An interactive handler message to Restart Handlers instances of dbgrbasic- 
handler. This message examines cond which is a condition object. It returns nil it 
if declines to handle the condition and something other than nil when it is pre- 
pared to handle the condition. See the message rhandle-condition. 

hash-table Type Specifier 

hash-table is the type specifier symbol for the predefined Lisp data structure of 
that name. 

The types hash-table, readtable, package, pathname, stream and random-state 

are pairwise disjoint. 

Examples: 



Page 1 158 



(setq a-hash-table (make-hash-table)) 

=> #<EQL-BLOCK-ARRAY-PROCESS-LOCKING-DUMMY 

-GC-LOCKING-ASSOCIATION-MUTATING-TABLE 16126776> 
(setf (gethash 'color a-hash-table) 'red) => RED 
(setf (gethash 'name a-hash-table) 'Ron) => RON 
(typep 'hash-table 'common) => T 
(subtypep 'hash-table 't) => T and T 
(sys: type-argl ist 'hash-table) => NIL and T 
(hash-table-p a-hash-table) => T 

See the section "Data Types and Type Specifiers". See the section "Table Manage- 
ment". 



hash-table-count table Function 

Returns the number of entries in table. When a table is first created or has been 
cleared, the number of entries is zero. 

(hash-table-count (setq new-hash-table (make-hash-table :size 5000))) 
=> 

For a table of related items: See the section "Table Functions". 



hash-table-p object Function 

Returns true if and only if object is a hash table. Under Genera, hash-table-p re- 
turns t for old Zetalisp hash tables also. 

(hash-table-p (make-hash-table)) => T 
For a table of related items: See the section "Table Functions". 

zhhaulong x Function 

Returns the number of significant bits in \x\. x must be an integer. Its sign is ig- 
nored. The result is the least integer strictly greater than the base-2 logarithm of 

I x|. 

zhhaulong is similar to integer-length. 

Examples: 

(zl :haulong 0) => 
(zl :haulong 3) => 2 
(zl :haulong -7) => 3 

For a table of related items: See the section "Functions Returning Components or 
Characteristics of Argument". 

:home-cursorpos Message 



Page 1 159 



This operation is supported by the same streams that support :read-cursorpos. It 
sets the position of the cursor. It puts the cursor back at the begining of the 
stream. For window streams, it puts the cursor at the upper left edge of the win- 
dow. 



zhhostat &rest hosts Function 

Asks each of the hosts for its status, and prints the results. If no hosts are speci- 
fied, asks all hosts on the Chaosnet. Hosts can be specified by either name or octal 
number. 

For each host, a line is displayed that either says that the host is not responding 
or gives metering information for the host's network attachments. If a host is not 
responding, probably it is down or there is no such host at that address. A Symbol- 
ics host can fail to respond if it is looping inside without-interrupts or paging ex- 
tremely heavily, such that it is simply unable to respond within a reasonable 
amount of time. 

See the section "Show Hosts Command". 

To abort the host status report produced by zhhostat or FUNCTION H, press 
c-RBORT. 



zhibase Variable 

In your new programs, we recommend that you use the variable *read-base*, 
which is the Common Lisp equivalent of zhibase. 

The value of zhibase is a number that is the radix in which integers and ratios 
are read. The initial value of zhibase is 10. zhibase should not be greater than 
36. 

When zhibase is set to a value greater than ten, the reader interprets the token 
as a symbol, unless control variable si:*read-extended-ibase-signed-number* or 
si:*read-extended-ibase-unsigned-number* is set to t. 



identity object Function 

Always returns object as its value. Sometimes functions require a second function 
as an argument, and identity is useful in those situations. 



if condition true &rest false 

Special Form 

The simplest conditional form. The "if-then" form looks like: 

(if predicate-form then-form) 

predicate-form is evaluated, and if the result is non-nil, the then-form is evaluated 
and its result is returned. Otherwise, nil is returned. 



Page 1 160 



Examples: 

(if (numberp 'a) "never reaches this point") => NIL 

(if (not nil) "A Word") => "A Word" 

(if 'not-nil "reaches this point") => "reaches this point" 

In the "if- then-else" form, it looks like: 

(if predicate-form then-form else-form) 

predicate-form is evaluated, and if the result is non-nil, the then-form is evaluated 
and its result is returned. Otherwise, the else-form is evaluated and its result is 
returned. 

Examples: 

(if (equal 'boy 'girl) "same" "different") => "different" 

(if (not nil) 'A 'B) => A 

(if 'word "reaches this point" "never reaches this point") 
=> "reaches this point" 

(defun make-even (integer) 

(if (oddp integer) (+ integer 1) integer)) 

(make-even 5) => 6 
(make-even 2) => 2 

Common Lisp Compatibility Note: The Symbolics Common Lisp version of if is 
extended to allow you to supply more than three arguments; the CLtL version re- 
quires two or three arguments, and signals an error if additional arguments are 
supplied. 

Zetalisp Note: Zetalisp supports multiple else clauses: if there are more than three 
subforms, if assumes you want more than one else-form; these are evaluated se- 
quentially and the result of the last one is returned, if the predicate returns nil. 

CLOE Note: In CLOE, if signals a warning if you use multiple else forms. Multi- 
ple else clauses are incompatible with the language specification presented in Guy 
Steele's Common Lisp: the Language. 

For a table of related items: See the section "Conditional Functions". 



if keyword for loop 

if expr 

If expr evaluates to nil, the following clause is skipped, otherwise not. 
Examples 



Page 1 161 



(defun print-odd (1 ist-of-nums) 
(loop for num in 1 ist-of-nums 
if (oddp num) 

collect num and do (print num))) => PRINT-ODD 
(print-odd ' (2 3 49 2 3 4)) => 
3 

49 
3 (3 49 3) 

if-then-else conditionals can be written using the else keyword, as in: 

(defun print-odd-else (1 ist-of-nums) 
(loop for num in 1 ist-of-nums 
if (oddp num) 

collect num and do (print num) 
else 

do (print "An even number !"))) => PRINT-ODD-ELSE 
(print-odd-else '(43297)) => 
"An even number !" 
3 

"An even number !" 
9 
7 (3 9 7) 

Multiple clauses can appear in an else-phrase using and to join them. 

In the typical format of a conditionalized clause such as 

when exprl keyword expr2 

expr2 can be the keyword it. If that is the case, a variable is generated to hold the 
value of exprl, and that variable gets substituted for expr2. Thus, the composition: 

when expr return it 
is equivalent to the clause: 

thereis expr 
and you can collect all non-null values in an iteration by saying: 

when expression collect it 

If multiple clauses are joined with and, the it keyword can only be used in the 
first. If multiple whens, unlesses, and/or ifs occur in sequence, the value substi- 
tuted for it is that of the last test performed. The it keyword is not recognized in 
an else-phrase. 

Conditionals can be nested. 

See the section "loop Conditionalization". 



ignore varl var2 ... Declaration 



Page 1 162 



Specifies that bindings of the vars are never used. 
See the section "Declaration Specifiers". 

ignore &rest ignore Function 

Takes any number of arguments and returns nil. This is often useful as a "dum- 
my" function; if you are calling a function that takes a function as an argument, 
and you want to pass one that does not do anything and does not mind being 
called with any argument pattern, use this. 

ignore is also used to suppress compiler warnings for ignored arguments. For ex- 
ample: 

(defun foo (x y) 
(ignore y) 
(sin x)) 

See the section "Functions and Special Forms for Constant Values". 

ignore-errors &body body Special Form 

Sets up a very simple handler on the bound handlers list that handles all error 
conditions. Normally, it executes body and returns the first value of the last form 
in body as its first value and nil as its second value. If an error signal occurs 
while body is executing, ignore-errors immediately returns with nil as its first 
value and something not nil as its second value. 

ignore-errors replaces zherrset and catch-error. 

For a table of related items, see the section "Basic Forms for Bound Handlers". 

imagpart number Function 

If number is a complex number, imagpart returns the imaginary part of number. 
If number is a noncomplex number, imagpart returns a zero of the same type as 
number. 
Examples: 

(imagpart #c(3 4)) => 4 
(imagpart 4) => 

Related Functions: 

complex 
realpart 

For a table of related items: See the section "Functions that Decompose and Con- 
struct Complex Numbers". 

zhimplode x Function 



Page 1 163 



Similar to zhmaknam, except that the returned symbol is interned in the current 
package. This function is provided mainly for Maclisp compatibility. 

Example: 

(zl : implode '(a #\b "C" #\4 5)) => |AbC4-i| 



import symbols &optional package Function 

symbols should be a list of symbols or a single symbol. If symbols is nil, it is treat- 
ed like an empty list. These symbols become internal symbols in package, and can 
therefore be referred to without a colon qualifier, import signals a correctable er- 
ror if any of the imported symbols has the same name as some distinct symbol al- 
ready available in the package. 

=> xpackagex 

TURBINE-PACKAGE 

=> (export valve-pressure) 

T 

=> (import generator : valve-pressure) 

ERROR: GENERATOR : VALVE-PRESSURE WILL SHADOW VALVE-PRESSURE 

package can be a package object or the name of a package (a symbol or a string). 
If unspecified, package defaults to the value of *package*. Returns t. 

The following code makes all the external symbols of the turbine-package accessi- 
ble in the generator-package. 

(do-external -symbols (symbol 'turbine-package) 
(import symbol 'generator-package)) 

Of course, the following call to use-package inside of generator-package would 
accomplish the same thing: 

(use-package 'turbine-package) 



in-package package-name &rest make-package-keywords Function 

Intended to be placed at the start of a file containing a subsystem that is to be 
loaded into some package other than user. If there is not already a package named 
package-name, this function acts like make-package, except that after the new 
package is created, *package* is set to it. This binding remains until changed by 
the user, or until the *package* variable reverts to its old value at the completion 
of a load operation. 

If there is a package named package-name, the assumption is that the user is 
reloading a file after making some changes. The existing package is augmented to 
reflect any new nicknames or new packages in the ruse list, and *package* is 
then set to this package. 



incf access-form &optional amount Macro 



Page 1 164 



Increments the value of a generalized variable, (incf ref) increments the value of 
ref by 1. (incf ref amount) adds amount to ref and stores the sum back into ref. It 
returns the new value of ref. 

access-form can be any form acceptable to setf. 

(incf (car (mumble))) 
is almost equivalent to 

(setf (car (mumble)) (1+ (car (mumble)))) 

except that while the latter would evaluate mumble twice, incf actually expands 
into a let and mumble is evaluated only once. 

(setq arr (make-array (4) : element-type 'integer 

: initial-element 5)) 

(incf (aref arr 3) 4) => #(5 5 5 9) 
See the section "Generalized Variables". 

rincrement-cursorpos x y &optional (units 'rpixelj Message 

This operation is supported by the same streams that support :read-cursorpos. It 
sets the position of the cursor, x and y are the amounts to increment the current x 
and y coordinates, units is the same as the units argument to :read-cursorpos. 

:info Message 

Returns a cons of the truename and creation date of the file. The creation date is 
a number that is a universal time. This can be used to tell if the file has been 
modified between two opens. For an output stream the info is not meaningful un- 
til after the stream has been closed, at least on an ITS file server. 

sysrinhibit-fdefine-warnings Variable 

Controls printing of warnings when functions are redefined. This variable is nor- 
mally nil. Setting it to t prevents fdefine from warning you and asking about 
questionable function definitions such as a function being redefined by a different 
file than defined it originally, or a symbol that belongs to one package being de- 
fined by a file that belongs to a different package. Setting it to :just-warn allows 
the warnings to be printed out, but prevents the queries from happening; it as- 
sumes that your answer is "yes", that is, that it is all right to redefine the func- 
tion. 

Note: The preferred way of associating the definition of a function with its source 
file is by using record-source-file-name: See the function record-source-file-name. 

closrinitialize-instance instance &rest initargs Generic Function 



Page 1 165 



Calls closrshared-initialize to initialize the instance, and returns the initialized 
instance. This generic function is intended to be specialized by programmers, but 
not to be called directly. It is called by closrmake-instance. 

instance The instance to initialize. 

initargs Alternating initialization argument names and values. 

The default primary method for closrinitialize-instance calls the closrshared- 
initialize generic function with the instance, t, and the initialization arguments 
provided to closrinitialize-instance. 

Note that the usual way for users to customize the initialization behavior is to 
specialize closrinitialize-instance by writing after-methods. Any applicable after- 
methods for closrinitialize-instance are called after the primary method for 
closrinitialize-instance. A user-defined primary method would override the default 
method, and thus could prevent the usual slot-filling behavior. 



sirinitial-readtable Variable 

The value of sirinitial-readtable is the initial standard readtable. You should never 
change the contents of either this readtable or sirinitial-readtable; only examine 
it, by using it as the from-readtable argument to zlrcopy-readtable or zlrset- 
syntax-from-char. Change zlrreadtable instead. 



dbgrinitialize-special-commands condition Generic Function 

The Debugger calls dbgrinitialize-special-commands after it prints the error mes- 
sage. The methods are combined with rprogn combination, so that each one can do 
some initialization. In particular, the methods for this generic function can remove 
items from the list dbgr special-commands in order to decide not to offer these 
special commands. 

The compatible message for dbgrinitialize-special-commands is: 
rinitialize-special-commands 

For a table of related items: See the section "Debugger Special Command Func- 
tions". 



initially keyword for loop 

initially expression 

Puts expression into the prologue of the iteration. It is evaluated before any 
other initialization code other than the initial bindings. For the sake of 
good style, the initially clause should therefore be placed after any with 
clauses but before the main body of the loop. 

Examples 



Page 1 166 



(defun sum-it (limit) 

(loop with sum-of-series = 

initially (print "The sum of this series is 

for num from to limit 

do 
(setq sum-of-series (+ sum-of-series num)) 

finally (prinl sum-of-series))) => SUM-IT 
(sum-it 9) => 

"The sum of this series is :" 45 
NIL 



See the macro loop. 



inline Declaration 

(inline functionl function2 ... ) specifies that it is desirable for the compiler to 
open-code calls to the specified functions; that is, the code for a specified function 
should be integrated into the calling routine, appearing "in line" in place of a pro- 
cedure call. This may achieve extra speed at the expense of debuggability (calls to 
functions compiled in-line cannot be traced, for example). This declaration is per- 
vasive, that is it affects all code in the body of the form. The compiler is free to 
ignore this declaration. 

Note that rules of lexical scoping are observed; if one of the functions mentioned 
has a lexically apparent local definition (as made by flet or labels), the declaration 
applies to that local definition and not to the global function definition. 

See the section "Declaration Specifiers". 



rinput-editor function &rest arguments Message 

This is supported by interactive streams such as windows. It is described in its 
own section (see the section "The Input Editor Program Interface"). 

Most programs should not send this message directly. See the function with-input- 
editing. 



input-stream-p stream Function 

Returns t if stream can handle input operations, otherwise returns nil. 

(streamp xstandard-inputx) => T 
(setq file-stream 

(open "foo" : direction : output : element-type 'character)) 

(input-stream-p file-stream) => NIL 



:input-wait &optional whostate function &rest arguments Message 



Page 1 167 



This message to an input stream causes the stream to process-wait with whostate 
until either of the following conditions is met: 

• Applying function to arguments returns non-nil. 

• The stream enters a state in which sending it a :tyi message would immediately 
return a value or signal an error. 

When either of these conditions is met, :input-wait returns. If the stream enters a 
state in which sending it a :tyi message would signal an error, :input-wait returns 
instead of signalling the error. The returned value is not defined. 

whostate is what to display in the status line while process-waiting. It can be a 
string or nil. A value of nil means to use the normal whostate for this stream, 
such as "Tyi", "Net In", or "Serial In". For interactive streams, the default 
whostate is "Tyi". 

function can be a function or nil. A value of nil means that the stream just waits 
until sending it a :tyi message would immediately return a value or signal an er- 
ror. 

This message is intended for programs that need to wait until either input is 
available from some interactive stream or some other condition, such as the arrival 
of a notification, occurs. Any stream that can become the value of zl:terminal-io 
must support :input-wait. 

Following is a simple example of the use of :input-wait to wait for input or a noti- 
fication to an interactive stream. The function just displays notifications and prints 
representations of characters or blips received as input. 

(defun my-top-level (stream) 

(error-restart-loop ((error sys:abort) "My top level") 
(send stream : input-wait nil 
#' (lambda (note-cell) 

(not (null (location-contents note-cell)))) 
(send stream :notif ication-cel 1 )) 
(let ((note (send stream : receive-notif ication))) 
(if note 

(sys: display-notification stream note : stream) 
(let ((char (send stream :any-tyi -no-hang))) 
(cond ((null char)) 

((characterp char) 

(format stream "~&Character : ~C" char)) 
((1 istp char) 

(format stream "~&Blip: ~S" char)) 
(t (format stream "~&Unknown object: ~S" char)))))))) 



(flavorrmethod rinsert sirheap) item key Method 

Inserts item into the heap based on key, and returns item and key. 



Page 1 168 



For a table of related items: See the section "Heap Functions and Methods". 

inspect &optional object Function 

A window-oriented version of describe. 

Note: While the Symbolics Common Lisp version of this function does not require 
the argument object, the function as specified in Common LISP: The Language 
does. See the section "How the Inspector Works". 

instance &optional (flavor '*) Type Specifier 

Denotes flavor instances. When a new flavor is defined with defflavor, the name 
of the flavor becomes a valid type symbol, and individual instances of that flavor 
become valid types of instance that can be tested with typep. 

instance is a subtype of t. 

Examples: 

(defflavor ship 

(name x-velocity y-velocity z-velocity mass) 

() ; no component flavors 

: readabl e-i nstance-vari abl es 
: wri tabl e-i nstance-vari abl es 
: initable-instance-variables) => SHIP 

(setq my-ship 

(make-instance 'ship :name "Enterprise" 

:mass 4534 
:x-velocity 24 
:y-velocity 2 
:z-velocity 45)) => #<SHIP 43100701> 

(ship-name my-ship) => "Enterprise" 

(typep my-ship 'instance) => T 

(typep my-ship '(instance ship)) => T 

(zl:typep my-ship) => SHIP 

(type-of my-ship) => SHIP 

(type-of 'ship) => SYMBOL 

(sys:type-arglist 'instance) => (&0PTI0NAL (FLAVOR '*)) and T 
See the section "Data Types and Type Specifiers". 



Page 1 169 



For a discussion of flavors: See the section "Flavors". 

instancep object Function 

Returns t if the object is a flavor instance, otherwise nil. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 

int-char integer Function 

Accepts a non-negative integer argument and returns a character if integer is in 
the range of char-int. Especially useful for converting an integer returned by a 
call to char-int back into a character. 

(int-char 65) => #\A 

(defvar char-arr (make-array 512)) 

(setf (elt char-arr (char-int #\a)) 'first) 

(dotimes (i 512) 

(if (eq (elt char-arr i) 'first) 
(return (int-char i)))) 

In the current Unix implementation of CLOE, integer arguments in the range of 1 
to 4096 return unique character objects. A larger integer argument returns one of 
the characters returned by an argument less than 4096. Arguments above 4096 re- 
turn #\undefined-lozenge as defined under Genera. 

For information on characters, see the section "The Character Set". 

For a table of related items, see the section "Character Conversions". 

integer &optional ( low '*) ( high '*) Type Specifier 

integer is the type specifier symbol for the predefined Lisp integer number type. 

The types integer and ratio are an exhaustive partition of the type rational, since 

rational = (or integer ratio). 

This type specifier can be used in either symbol or list form. Used in list form, 
integer allows the declaration and creation of specialized integer numbers, whose 
range is restricted to low and high. 

low and high must each be an integer, a list of an integer, or unspecified. If these 
limits are expressed as integers, they are inclusive; if they are expressed as a list 
of an integer, they are exclusive; * means that a limit does not exist, and so effec- 
tively denotes minus or plus infinity, respectively. 

The type fixnum is simply a name for (integer smallest largest) for the values of 
most-negative-fixnum and most-positive-fixnum. The type (integer 1) is so use- 
ful that it has the special name bit. 



Page 1170 



Examples: 

(typep 4 'integer) => T 

(subtypep 'integer 'rational) => T and T ; subtype and certain 

(subtypep '(integer *) 'rational) => T and T 

(subtypep 'signed-byte 'integer) => T and T 

(subtypep 'fixnum 'integer) => T and T 

(subtypep 'bignum 'integer) => T and T 

(commonp 23.) => T 

(integerp 23.) => T 

(integerp -3_78) => T 

(integerp most-positive-f ixnum) => T 

(integerp most-negative-f ixnum) => T 

(integerp -2147483648) => T 

(equal-typep 'bit '(integer 1)) => T 

(equal-typep '(integer -2147483648 2147483647) 'fixnum) => T 

(sys:type-arglist 'integer) => (&0PTI0NAL (LOW '*) (HIGH '*)) and T 

See the section "Data Types and Type Specifiers". 
See the section "Numbers". 



integer-decode-float float Function 

Returns three values, representing: the significand (scaled so as to be an integer), 
the exponent, and the sign of the floating-point argument, float, as described be- 
low. Scaling the significand essentially means interpreting the bit field of the man- 
tissa as an integer. 

For an argument f, the first result is an integer which is strictly less than (expt 2 
(float-precision /)), but no less than (expt 2 (-(float-precision f) 1)) except that if 
f is zero, the returned integer value is zero. 

The second value returned is an integer e such that the first result (the signifi- 
cand) times 2 raised to the power e is equal to the absolute value of the argument 
float. 

The final value of integer-decode-float represents the sign of float and is 1 or -1. 

Examples: 

(integer-decode-float 2.0) => 8388608 and -22 and 1 
(integer-decode-float -2.0) => 8388608 and -22 and -1 
(integer-decode-float 4.0) => 8388608 and -21 and 1 
(integer-decode-float 8.0) => 8388608 and -20 and 1 
(integer-decode-float 3.0) => 12582912 and -22 and 1 

The exact values produced by the following functions serve illustrative purposes, 
and might vary between CLOE implementations or within an implementation over 
time. 



Page 1171 



signif icand 


exponent si 


9437184 


-21 1 


0.5625 


3 1 


8388608 


-21 1 


0.5 


3 1 


8388608 


-23 1 


0.5 


1 1 



gn 

(integer-decode-float 4.5) 
(decode-float 4.5) 
(integer-decode-float 4.0) 
(decode-float 4.0) 
(integer-decode-float 1.0) 
(decode-float 1 .0) 
(* 0.5625 (expt 2 3)) ^4.5 

For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 



integer-length integer Function 

Returns the result of the following computation: 

(values (ceiling (log (if (minusp integer)(- integer)(l+ integer)) 2)))) 

If integer is non-negative, the result represents the number of significant bits in 
the unsigned binary representation of integer. More generally, regardless of the 
sign of integer, the result denotes the number of significant bits needed to repre- 
sent integer in unsigned binary two's-complement form. (To get the number of bits 
needed for a signed binary two's complement representation, add 1 bit to the result 
of integer-length). 



Examples: 

(integer-length 0) => 

(integer-length 1) => 1 

(integer-length 2) => 2 

(integer-length 8) => 4 

(integer-length 15) => 4 



(integer-length -0) => 

(integer-length -1) => 

(integer-length -2) => 1 

(integer-length -8) => 3 

(integer-length -15) => 4 



A possible use of integer-length 
The function trail ing-zeros returns the number of 
consecutive zeros starting at the least significant 
bit of the binary representation of an integer 



(defun trail ing-zeros (integer) 

(1- (integer-length (logand integer (- integer))))) 



(trail ing-zeros 0) => -1 

; ; ; An adequate result since there are an undefined amount 

;;; of trailing zeros in 

(trail ing-zeros 1) => 

(trail ing-zeros 4) => 2 ; 4 is #b100 

(trail ing-zeros 9) => ; 9 is #b1001 

For a table of related items, see the section "Functions Returning Components or 
Characteristics of Argument". 



Page 1172 



integerp object Function 

This predicate returns t if its argument is an integer; otherwise it returns nil. 

Examples: 

(integerp 7) => T 

(integerp 4.0) => NIL 

(integerp #c(2 0)) => T ;#c(2 0) is coerced to an integer 

(integerp "not a number") => NIL 

The following code tests whether a and b are numbers. If they are numbers, they 
are added. Otherwise, we attempt to extract integers that are then tested by 
integerp: 

(if (and (numberp a) (numberp b)) 
(+ a b) 
(if (and (consp a) 

(integerp (car a)) 
(consp b) 

(integerp (car b))) 
(+ (car a) (car b)) 
(error "couldn't extract integers from ~a and ~a" a b))) 

For a table of related items, see the section "Numeric Type-checking Predicates". 

rinteractive Message 

Returns t if the stream is interactive and nil if it is not. Interactive streams, built 
on sirinteractive-stream, are streams designed for interaction with human users. 
They support input editing. Use the rinteractive message to find out whether a 
stream supports the rinput-editor message. 

intern string &optional (pkg *package*J Function 

Finds or creates a symbol named string in pkg. Inherited symbols in pkg are in- 
cluded in the search for a symbol named string. If a symbol named string is found, 
it is returned. If no such symbol is found, one is created and installed in pkg as 
an internal symbol (if pkg is the keyword package, the symbol is installed as an 
external symbol). 

intern returns two values. The first is the symbol that was found or created. The 
second value is nil for newly created symbols. If the symbol returned is a pre- 
existing symbol, this second value is one of the following: 

rinternal The symbol is present in pkg as an internal symbol. 

rexternal The symbol is present in pkg as an external symbol. 

rinherited The symbol is an internal symbol in pkg inherited by way of 

use-package. 

intern is sensitive to case and under Genera, style. If a string contains character 



Page 1173 



styles, use the function string-thin on its arguments. See the function string-thin. 
The following code uses intern with multiple-value-bind to capture both returned 
values. If the status of the interned symbol is rinternal, then the symbols is ex- 
ported. 

(multiple-value-bind (symbol status) (intern new-symbol) 
(when (eq status ': internal) 
(export symbol))) 

For more information: See the section "Mapping Names to Symbols". 



zhintern sym &optional pkg Function 

Finds or creates a symbol named sym accessible to the package pkg, either directly 
present in pkg or inherited from a package it uses. 

See the function intern. 



intern-local string &optional pkg Function 

Finds or creates a symbol named string directly present in pkg. Symbols inherited 
by pkg from packages it uses are not considered, thus intern-local can cause a 
name conflict, intern-local is considered to be a low-level primitive, and indiscrim- 
inate use of it can cause undetected name conflicts. Use import, shadow, or 
shadowing-import for normal purposes. 

If string is not a string but a symbol, and no symbol with that print name is al- 
ready interned in pkg, intern-local interns string — rather than a newly created 
symbol — in pkg (even if it is also interned in some other package) and returns it. 

For more information: See the section "Mapping Names to Symbols". 



intern-local-soft string &optional pkg Function 

Find a symbol named string directly present in pkg. Symbols inherited by pkg from 
packages it uses are not considered. If no symbol is found, the two values nil nil 
are returned. 

intern-local-soft is a good low-level primitive for when you want complete control 
of what packages to search and when to add new symbols. 

For more information: See the section "Mapping Names to Symbols". 



intern-soft string &optional pkg Function 

Finds a symbol named string accessible to pkg, either directly present in pkg or in- 
herited from a package it uses. If no symbol is found, the two values nil nil are 
returned. 

intersection listl Ust2 &key {test #'eql) test-not (key #'identity) Function 



Page 1174 



Returns a new list containing everything that is an element of both listl and Ust2, 
as checked by the :test and :test-not keywords. If either list has duplicate entries, 
the redundant entries may or may not appear in the result. For example: 

(intersection ' (a b c) '(fa d)) => (A) 
(intersection ' (a b c a d) '(fad)) => (A A D) 

(intersection ' (a b c) ' (a f a d)) => (A) 

There is no guarantee that the order of elements in the result will reflect the or- 
dering of the arguments in any particular way. 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

For all possible ordered pairs consisting of one element from listl and one element 
from Ust2, the test is used to determine whether they match. For every matching 
pair, the element from listl is put in the result. 

In the following example, intersection finds the new tenured professor: 

(setq professors-with-tenure 

'(("Jones" CS101 CS242) ("smith" CS202 CS231) 
("parks" CS221) ("hunter" CS216 CS232))) 
(setq new-professors 

'(("Able" CS101 CS244)("Cain" CS101 CS331) 
("Parks" CS221)("adams" CS215 CS222))) 

(intersection professors-with-tenure new-professors 

:test tt'string-equal :key #'car) 
=> 
(("parks" CS221)) 

For a table of related items: See the section "Functions for Comparing Lists". 



zhintersection &rest lists Function 

Takes any number of lists that represent sets and returns a new list that repre- 
sents the intersection of all the sets it is given, zhintersection uses eq for its 
comparisons. You cannot change the function used for the comparison. If no argu- 
ments are supplied, (zhintersection) returns nil. 

For a table of related items: See the section "Functions for Comparing Lists". 



Page 1175 



clos:invalid-method-error method format-string &rest args Function 

Within method combination, signals an error when the method qualifiers of an ap- 
plicable method are not valid for the method-combination type; it should be called 
only within the dynamic extent of a method-combination function. 

clos:invalid-method-error is called automatically when a method fails to satisfy 
any qualifier pattern or predicate in a clos:define-method-combination-type form. 
A method-combination function that imposes additional restrictions should call 
clos:invalid-method-error explicitly if it encounters an invalid method. 

method The method object that is invalid. 

format-string A control string that can be given to format. 

args Arguments required by the format-string. 



mathrinvert-matrix matrix &optional into-matrix Function 

Computes the inverse of matrix. If into-matrix is supplied, stores the result into it 
and returns it; otherwise it creates an array to hold the result, and returns that. 
matrix must be two-dimensional and square. The Gauss-Jordan algorithm with par- 
tial pivoting is used. Note: If you want to solve a set of simultaneous equations, 
you should not use this function; use mathrdecompose and mathrsolve. 

mathrinvert-matrix does not work on conformally displaced arrays. 



dbgrinvoke-restart-handlers condition &key (flavors nil flavors-specified) Function 

Searches the list of restart handlers to find a restart handler for condition. The 
flavors argument controls which restart handlers are examined, flavors is a list of 
condition names. When flavors is omitted, the function examines every restart 
handler. When flavors is provided, the function examines only those restart han- 
dlers that handle at least one of the conditions on the list. 

The first restart handler that it finds to handle the condition is invoked and given 
condition. It returns nil if no appropriate restart handler is found. 



isqrt integer Function 

Integer square root, integer must be a non-negative integer; the result is the great- 
est integer less than or equal to the exact square root of integer. 
Examples: 

(isqrt 4) => 2 
(isqrt 5) => 2 
(isqrt 8) => 2 
(isqrt 9) => 3 
(isqrt 81) => 9 
(isqrt 42) => 6 



Page 1176 



For a table of related items: See the section "Arithmetic Functions". 



&key Lambda List Keyword 

If the lambda-list keyword &key is present, all specifiers up to the next lambda- 
list keyword, or the end of the list, are keyword parameter specifiers. The keyword 
parameter specifiers can be followed by the lambda-list keyword 
&allow-other-keys, if desired. 



keyword Type Specifier 

keyword is the type specifier symbol for the predefined Lisp object of that name. 

Examples: 

(typep ':list 'keyword) => T 
(subtypep 'keyword 't) => T and T 
(subtypep 'keyword 'common) => NIL and NIL 
(sys: type-argl ist 'keyword) => NIL and T 
(keywordp ':fixnum) => T 

See the section "Data Types and Type Specifiers". 
See the section "Symbols, Keywords, and Variables". 



zhkeyword-extract keylist keyvar keywords &optional flags &body otherwise 

Special Form 

Aids in writing functions that take keyword arguments in the standard fashion. 
You can also use the &key lambda-list keyword to create functions that take key- 
word arguments. &key is preferred and is substantially more efficient; 
zhkeyword-extract is obsolete. See the section "Evaluating a Function Form". 

The form: 

(zl : keyword-extract key-list iteration-var 
keywords flags other-clauses . . .) 

parses the keywords out into local variables of the function, key-list is a form that 
evaluates to the list of keyword arguments; it is generally the function's &rest ar- 
gument, iteration-var is a variable used to iterate over the list; sometimes other- 
clauses uses the form: 

(car (setq iteration-var (cdr iteration-var))) 

to extract the next element of the list. (Note that this is not the same as pop, be- 
cause it does the car after the cdr, not before.) 

keywords defines the symbols that are keywords to be followed by an argument. 
Each element of keywords is either the name of a local variable that receives the 
argument and is also the keyword, or a list of the keyword and the variable, for 
use when they are different or the keyword is not to go in the keyword package. 



Page 1177 



Thus, if keywords is (a (b c) d) the keywords recognized are :a, b, and :d. If :a is 
specified, its argument is stored into a. If :d is specified, its argument is stored 
into d. If b is specified, its argument is stored into c. 

Note that zhkeyword-extract does not bind these local variables; it assumes you 
have done that somewhere else in the code that contains the zhkeyword-extract 
form. 

flags defines the symbols that are keywords not followed by an argument. If a flag 
is seen its corresponding variable is set to t. (You are assumed to have initialized 
it to nil when you bound it with let or &aux.) As in keywords, an element of flags 
can be either a variable from which the keyword is deduced, or a list of the key- 
word and the variable. 

If there are any other-clauses, they are zhselectq clauses selecting on the keyword 
being processed. These clauses are for handling any keywords that are not handled 
by the keywords and flags elements. These can be used to do special processing of 
certain keywords for which simply storing the argument into a variable is not good 
enough. Unless the other-clauses include an otherwise (or t) clause after them, 
there is an otherwise clause to complain about any unhandled keywords found in 
key-list. If you write your own otherwise clause, it is up to you to take care of any 
unhandled keywords. 

For a table of related items, see the section "Iteration Functions". 



keywordp object Function 

A predicate that is true if object is a symbol and its home package is the keyword 
package, and false otherwise. 

(keywordp 'key) => NIL 

(keywordp ':key) => T 
See the section "The Package Cell of a Symbol". 

labels functions &body body Special Form 

Identical to flet in structure and purpose, but has slightly different scoping rules. 
It, too, defines one or more functions whose names are made available within its 
body. In labels, unlike flet, however, the functions being defined can refer to each 
other mutually, and to themselves, recursively. Any of the functions defined by a 
single use of labels can call itself or any other; there is no order dependence. Al- 
though flet is analogous to let in its parallel binding, labels is not analogous to 
let*. 

labels is in all other ways identical to flet. It defines internal functions that can 
be called, redefined, passed as funargs, and so on. 

Functions defined by labels, when passed as funargs, generate closures. The allo- 
cation of these closures, that is, whether they appear on the stack or in the heap, 
is controlled in the same way as for internal lambdas. See the section "Funargs 
and Lexical Closure Allocation". 



Page 1178 



Here is an example of the use of labels: 

(defun combinations (total-things at-a-time) 

;; This function computes the number of combinations of 
;; total-things things taken at-a-time at a time. 
;; There are more efficient ways, but this is illustrative, 
(labels ((factorial (x) 

(permutations x x)) 
(permutations (x n) ;x things n at a time 
(if (= n 1) 
x 

(* x (permutations (1- x) (1- n)))))) 
(/ (permutations total-things at-a-time) 
(factorial at-a-time)))) 

In the following example, we use labels to locally define a function that calls it- 
self. If we instead use flet, an error will result because the call to my-adder in 
the body would refer to an outer (presumably non-existent) my-adder instead of 
the local one. 

(defun example-labels (operand-a operand-b) 
(labels ((my-adder (accumulator counter) 
(if (= counter 0) 
accumulator 

(my-adder (incf accumulator) (decf counter))))) 
(my-adder operand-a operand-b))) 

(example-labels 6 4) => 10 



lambda lambda-list &rest body Special Form 

Provided as a convenience, to obviate the need for using the function special form 
when the latter is used to name an anonymous (lambda) function. When lambda is 
used as a special form, it is treated by the evaluator and compiler identically to 
the way it would have been treated if it appeared as the operand of a function 
special form. For example, the following two forms are equivalent: 

(my-mapping-function (lambda (x) (+ x 2)) list) 

(my-mapping-function (function (lambda (x) (+ x 2))) list) 

Note that the form immediately above is usually written as: 

(my-mapping-function #' (lambda (x) (+ x 2)) list) 

The first form uses lambda as a special form; the latter two do not use the 
lambda special form, but rather, use lambda to name an anonymous function. 

See the section "Functions and Special Forms for Constant Values". 

Using lambda as a special form is incompatible with Common Lisp. 



Page 1179 



lambda-list-keywords Constant 

A list of all of the allowed "&" keywords. Some of these are obsolete and should 
not be used in new code. 

For more information on lambda-list keywords: See the section "Lambda-List Key- 
words". See the section "Evaluating a Function Form". 

&optional 

Declares the following arguments to be optional. See the section "Evaluat- 
ing a Function Form". 

&rest Declares the following argument to be a rest argument. There can be only 
one &rest argument. 

Under Genera, it is important to realize that the list of arguments to which 
a rest-parameter is bound is set up in whatever way is most efficiently im- 
plemented, rather than in the way that is most convenient for the function 
receiving the arguments. It is not guaranteed to be a "real" list. Sometimes 
the rest-args list is stored in the function-calling stack, and loses its validi- 
ty when the function returns. If a rest-argument is to be returned or made 
part of permanent list-structure, it must first be copied, as you must always 
assume that it is one of these special lists. See the function sys:copy-if- 
necessary. 

The system does not detect the error of omitting to copy a rest-argument; 
you simply find that you have a value that seems to change behind your 
back. At other times the rest-args list is an argument that was given to 
apply; therefore it is not safe to rplaca this list, because you might modify 
permanent data structure. An attempt to rplacd a rest-args list is unsafe in 
this case, while in the first case it causes an error, since lists in the stack 
are impossible to rplacd. 

Under CLOE, rest arguments are not typically stack-consed. You can move 
a rest-arg consed on the stack using the declaration (sys:downward-rest- 
argument). 

&key Separates the positional parameters and rest parameter from the keyword 
parameters. See the section "Evaluating a Function Form". 

&allow-other-keys 

In a lambda-list that accepts keyword arguments, says that keywords that 
are not specifically listed after &key are allowed. They and the correspond- 
ing values are ignored, as far as keyword arguments are concerned, but 
they do become part of the rest argument, if there is one. 

&aux Separates the arguments of a function from the auxiliary variables. Follow- 
ing &aux you can put entries of the form: 

(variable initial-value-form) 

or just variable if you want it initialized to nil or do not care what the ini- 
tial value is. 



Page 1 180 



&bodyFor macros defined by defmacro or macrolet only. &body is similar to 
&rest, but declares to grindef and the code-formatting module of the editor 
that the body forms of a special form follow and should be indented accord- 
ingly. See the macro defmacro. 

&whole 

For macros defined by defmacro or macrolet only. &whole is followed by 
variable, which is bound to the entire macro-call form or subform. variable 
is the value that the macro-expander function receives as its first argu- 
ment. &whole is allowed only in the top-level pattern, not in inside pat- 
terns. See the macro defmacro. 

&environment 

For macros defined by defmacro or macrolet only. &environment is fol- 
lowed by variable, which is bound to an object representing the lexical envi- 
ronment where the macro call is to be interpreted. This environment might 
not be the complete lexical environment. It should be used only with the 
macroexpand function for any local macro definitions that the macrolet 
construct might have established within that lexical environment. 
&environment is allowed only in the top-level pattern, not in inside pat- 
terns. See the section "Lexical Environment Objects and Arguments". See 
the macro defmacro. 

zl:&special 

Declares the following arguments and/or auxiliary variables to be special 
within the scope of this function. zl:&special can appear anywhere in the 
lambda-list any number of times. Note that you cannot use this keyword if 
you are using CLOE. 

zl:&local 

Turns off a preceding zl:&special for the variables that follow. zl:&local 
can appear anywhere in the lambda-list any number of times. Note that you 
cannot use this keyword if you are using CLOE. 

zl:&quote 

Using zl:&quote is an obsolete way to define special functions. zl:&quote 
declares that the following arguments are not to be evaluated. You should 
implement language extensions as macros rather than through special 
functions, because macros directly define a Lisp-to-Lisp translation and 
therefore can be understood by both the interpreter and the compiler. 

Special functions, on the other hand, only extend the interpreter. The com- 
piler has to be modified to understand each new special function so that 
code using it can be compiled. Since all real programs are eventually com- 
piled, writing your own special functions is strongly discouraged. Note that 
you cannot use this keyword in CLOE. 

zl:&eval 

This is obsolete. Use macros instead to define special functions. zl:&eval 



Page 1181 



turns off a preceding zl:&quote for the arguments which follow. Note that 
if you are using CLOE, you cannot use this keyword. 

zl:&list-of 

This is not supported. Use loop or mapcar instead of zl:&list-of. 



lambda-macro function lambda-list &body body Function 

Like macro, defines a lambda macro to be called name, lambda-list should be a list 
of one variable, which is bound to the function being expanded. The lambda macro 
must return a function. Example: 

(lambda-macro ilisp (x) 

'(lambda (&optional ,@(second x) &rest ignore) . , (cddr x))) 

This defines a lambda macro called ilisp. After it has been defined, the following 
list is a valid Lisp function: 

(ilisp (x y z) (list x y z)) 

The above function takes three arguments and returns a list of them, but all of 
the arguments are optional and any extra arguments are ignored. (This shows how 
to make functions that imitate Interlisp functions, in which all arguments are al- 
ways optional and extra arguments are always ignored.) So, for example: 

(funcall #'(ilisp (x y z) (list x y z)) 1 2) => (1 2 nil) 



lambda-parameters-limit Constant 

A positive integer that is the upper exclusive bound on the number of distinct pa- 
rameter names that can appear in a single lambda-list. The value is currently 128 
for 3600-series machines and 50 for Ivory-based machines, and CLOE. If you are 
using CLOE, consider this example: 

(if (> (length keyword-pair-list) lambda-parameter-limit) 
(handl e-too-many-keywords keyword-pai r-1 i st) ) 



last x 1, x 0, x n Function 

Using last with the arguments x 1 returns the last cons of list x. If x 1 is nil, it 
returns nil. Note that last is not analogous to first (first returns the first element 
of a list, but last does not return the last element of a list); this is a historical 
artifact. Example: 

(setq x '(abed)) 
(last x) => (d) 
(rplacd (last x) ' (e f)) 
x => ' (a b c d e f ) 

Using last with the arguments x returns the cdr of the last cons of the list. Us- 
ing last with the arguments x n returns the list of the last n conses of the list. 



Page 1 182 



last could have been defined by: 

(defun last (x) 

(cond ((atom x) x) 

((atom (cdr x)) x) 

((last (cdr x))) )) 

(setq b '(q r s t)) => (QRST) 

(Q R S T) 

(last b) => (T) 

(setq a (cons (cons 'first 'cons) (cons 'second 'cons)) => 

((FIRST . CONS) SECOND . CONS)) 

(last a) => (second. cons) 

(SECOND . CONS) 

In the following example, last is used in the body of the do* to locate the cons for 
operation on by rplacd: 

(defun my-nconc( &rest lists ) 

(setq lists (remove nil lists :test #'eq)) 
(do* ((segmentl (first lists) segment2) 

(segment2 (second lists) (first list)) 
(result segmentl) 

(list (rest (rest lists)) (rest list))) 
((null segment2) result) 
(rplacd (last segmentl) segment2))) 

For a table of related items: See the section "Functions for Extracting from Lists". 

lcm &rest integers Function 

Computes and returns the least common multiple of the absolute values of its ar- 
guments. All the arguments must be integers, and the result is always a non- 
negative integer. 

For one argument, lcm returns the absolute value of that argument. If one or 
more of the arguments is zero, lcm returns zero. If there are no arguments, the 
returned value is 1. 

Examples: 

(lcm) => 1 

(lcm -6) => 6 ;absolute value of only one argument 

(lcm 6 15) => 30 

(lcm 6) => 

(lcm 2 3 4 5) => 60 

(lcm -15 105) => 105 

(lcm 15 12 9) => 180 

(lcm 5 7 11 18) => 6930 

For a table of related items, see the section "Arithmetic Functions". 



Page 1 183 



ldb bytespec integer Function 

"Load byte." 

Returns a byte extracted from integer as specified by bytespec. 

bytespec is built using function byte with bit size and position arguments. 

ldb extracts from integer size contiguous bits starting at position and returns this 
value, integer must be an integer. 

The result is right-justified: the size bits are the lowest bits in the returned value 
and the rest of the returned bits are zero, ldb always returns a nonnegative inte- 
ger. This function has a setf method. However, in order to use zhsetf on an ldb 
form, the integer argument must suit the zhsetf operation. Examples: 

(ldb (byte 1 2) 5) => 1 

(ldb (byte 32. 0) -1) => (1- 1_32.) ;;a positive bignum 

(ldb (byte 16. 24.) -1_31.) => #0177600 

(ldb (byte 6 3) #o4567) => #o56 

(setq eight-x-seven 56) 

(setf (ldb (byte 3 3) eight-x-seven) 4) => 4 

eight-x-seven => 32 

(ldb (byte 7 0) 257) => 1 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



ldb-test bytespec integer Function 

Returns t if any of the bits designated by the byte specifier bytespec are l's in inte- 
ger. That is, it returns t if the designated field is nonzero, ldb-test could have 
been defined as follows: 

(ldb-test bytespec integer) ==> (not (zerop (ldb bytespec integer))) 

Examples: 

(ldb-test (byte 2 1) 6) => T 
(ldb-test (byte 2 3) #o542) => NIL 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



ldiff list sublist Function 

Returns a new list, whose elements are those elements of list that appear before 
sublist. list should be a list, and sublist should be eq one of the conses that make 
up list. 

Examples: 



Page 1 184 



(setq x ' (a b c d e)) 

(setq y (cdddr x)) => (d e) 

(ldiff x y) => (a b c) 

(ldiff '(abed) ' (c d)) => (a b c d) 

For a table of related items: See the section "Functions for Comparing Lists" 

least-negative-double-float Constant 

The negative floating-point number in double-float format which is closest in value 
(but not equal to) zero. 

least-negative-long-float Constant 

The negative floating-point number in long-float format closest in value (but not 
equal to) zero. In Symbolics Common Lisp this constant has the same value as 
least-negative-double-float. 

least-negative-normalized-double-float Constant 

The normalized negative floating-point number in double-float format which is 
closest in value (but not equal to) zero. Its value is -2.2250738585072014d-308. 

least-negative-normalized-long-float Constant 

The normalized negative floating-point number in long-float format which is clos- 
est in value (but not equal to) zero. Its value is the same as least-negative- 
normalized-double-float, -2.2250738585072014d-308. 

least-negative-normalized-short-float Constant 

The normalized negative floating-point number in short-float format which is clos- 
est in value (but not equal to) zero. Its value is the same as least-negative- 
normalized-single-float, -1.1754944e-38. 

least-negative-normalized-single-float Constant 

The normalized negative floating-point number in single-float format which is clos- 
est in value (but not equal to) zero. Its value is -1.1754944e-38. 

least-negative-short-float Constant 

The negative floating-point number in short-float format closest in value (but not 
equal to) zero. In Symbolics Common Lisp this constant has the same value as 
least-negative-single-float. 



Page 1 185 



least-negative-single-float Constant 

The negative floating-point number in single-float format that is closest in value 
(but not equal to) zero. 



least-positive-double-float Constant 

The positive floating-point number in double-float format closest in value (but not 
equal to) zero. 



least-positive-long-float Constant 

The positive floating-point number in single-float format closest in value (but not 
equal to) zero. In Symbolics Common Lisp this constant has the same value as 
least-positive-double-float. 



least-positive-normalized-double-float Constant 

The normalized positive floating-point number in double-float format closest in val- 
ue (but not equal to) zero. Its value is 2.2250738585072014d-308. 



least-positive-normalized-long-float Constant 

The normalized positive floating-point number in long-float format closest in value 
(but not equal to) zero. Its value is the same as least-positive-normalized-double- 
float, 2.2250738585072014d-308. 



least-positive-normalized-short-float Constant 

The normalized positive floating-point number in short-float format closest in value 
(but not equal to) zero. Its value is the same as least-positive-normalized-single- 
float, 1.1754944e-38. 



least-positive-normalized-single-float Constant 

The normalized positive floating-point number in single-float format closest in val- 
ue (but not equal to) zero. Its value is 1.1754944e-38. 



least-positive-short-float Constant 

The positive floating-point number in short-float format closest in value (but not 
equal to) zero. In Symbolics Common Lisp this constant has the same value as 
least-positive-single-float. 



least-positive-single-float Constant 



Page 1 186 



The positive floating-point number in single-float format closest in value (but not 
equal to) zero. 



length sequence Function 

Returns the number of elements in sequence as a non-negative integer. If the se- 
quence is a vector with a fill pointer, the "active length" as specified by the fill 
pointer, is returned. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(length '()) => 

(length ' (a b c)) => 3 
(length '(a (b c) d e)) => 4 

(length (vector 'a 'b 'c 'd 'e)) => 5 

The following example defines a simplified replacement function. This function us- 
es length to ensure that the end values default to the length of the sequences. 

(defun my-replace (sequencel sequence2 &key startl endl start2 end2) 
"real replace must do some extra work" 
(unless endl (setq endl (length sequencel))) 
(unless end2 (setq end2 (length sequence2))) 
(setf (subseq sequencel startl endl) 

(subseq sequence2 start2 end2)) 
sequencel) 

See the section "Array Leaders". 

For a table of related items: See the section "Functions for Finding Information 
About Lists and Conses". 

For a table of related items: See the section "Sequence Construction and Access". 
Also: See the section "Getting Information About an Array". 



rlength Message 

Returns the length of the file, in bytes or characters. For text files on PDP-10 file 
servers, this is the number of PDP-10 characters, not Symbolics characters. The 
numbers are different because of character-set translation. (See the section "The 
Character Set".) For an output stream the length is not meaningful until after the 
stream has been closed, at least on an ITS file server. 



zhlength x Function 



Page 1 187 



Returns the length of x. The length of a list is the number of elements in it. Ex- 
amples: 

(zl : length nil) => 

(zl : length '(abed)) => 4 

(zl :length '(a (b c) d)) => 3 

zhlength could have been defined by: 

(defun zl : length (x) 
(cond ((atom x) 0) 

((1+ (zl: length (cdr x)))) )) 

or by: 

(defun zl : length (x) 
(do ((n (1+ n)) 
(y x (cdr y))) 
((atom y) n) )) 

except that it is an error to take zhlength of a non-nil atom. 

For a table of related items: See the section "Functions for Finding Information 
About Lists and Conses". 

For a table of related items: See the section "Sequence Construction and Access". 

zhlessp number &rest more-numbers Function 

In your new programs, we recommend that you use function <, which is the Com- 
mon Lisp equivalent of zhlessp. 

zhlessp compares its arguments from left to right. If any argument is not less 
than the next, zhlessp returns nil. But if the arguments are monotonically strictly 
increasing, the result is t. 

Arguments must be noncomplex numbers, but they need not be of the same type. 

Examples: 

(zl :lessp 3 4) => t 

(zl :lessp 1 1) => nil 

(zl :lessp 1 2 3 4) => t 

(zl :lessp 1 .0 5/2 3 2 4) => nil 



let bindings &body body Special Form 

Binds some variables to some objects and evaluates some forms (the "body") in the 
context of those bindings. A let form looks like this: 



Page 1 188 



(let {{varl vforml) 
(var2 vform2) 

bforml 
bform2 

When this form is evaluated, first the vforms (the values) are evaluated. Then the 
variables are bound to the values returned by the corresponding vforms. Thus the 
bindings happen in parallel; all the vforms are evaluated before any of the vari- 
ables are bound. Finally, the bforms (the body) are evaluated sequentially, the old 
values of the variables are restored, and the result of the last bform is returned. 
The body of the let form is an implicit progn. 

You can omit the vform from a let clause, in which case it is as if the vform were 
nil: the variable is bound to nil. Furthermore, you can replace the entire clause 
(the list of the variable and form) with just the variable, which also means that 
the variable gets bound to nil. It is customary to write just a variable, rather than 
a clause, to indicate that the value to which the variable is bound does not matter, 
because the variable is setq'ed before its first use. Example: 

(let ((a (+ 3 3)) 
(b 'foo) 
(c) 
d) 
...) 

Within the body, a is bound to 6, b is bound to foo, c is bound to nil, and d is 
bound to nil. 

The values of any special variables bound by let are restored upon returned value 
of let. 

(setq a '(1 2 3) b '(3 4 5)) 
(let ((one a) 

(two (cdr b))) 
(append one two)) 
=> (1 2 3 4 5) 

The special form let and its companion let* are most useful for providing a con- 
text with local variables for temporary storage during a computation. For example: 

(let ((list argl) 

(ptr (car argl)) 
(rest (cdr argl))) 
(1 isp: loop 
(process ptr) 
(unless rest (return)) 
(setq list rest) 
(setq ptr (car list)) 
(setq rest (cdr rest)))) 

Nesting of let forms is also possible, for example, to avoid use of let*: 



Page 1 189 



(let ((xprint-escapex nil) 

(array (get-my-array))) 
(let ((message (format nil "~A" array))) 
(my-process message))) 

See the section "Special Forms for Binding Variables". 



let* bindings &body body Special Form 

Binds some variables to some objects, sequentially, and evaluates some forms (the 
"body") in the context of those bindings, let* is the same as let, except that the 
binding is sequential. Each variable is bound to the value if its vform before the 
next vform is evaluated. This is useful when the computaton of a vform depends 
on the value of a variable bound in an earlier vform. Example: 

(let* ((a (+ 1 2)) 
(b (+ a a))) 
...) 

Within the body, a is bound to 3 and b is bound to 6. 

The body of the let* form is an implicit progn. Therefore, the forms are evaluated 
sequentially, and let* returns the value of the last form evaluated. The values of 
any special variables bound by let* are restored upon the returned value of the 
let*. 

(setq a '(1 2 3) b '(3 4 5)) 
(let* ((one (append a b)) 

(two (remove-duplicates one))) 
two) 
=> (1 2 3 4 5) 

Special forms let* and let provide a local variable context for temporary storage 
during a computation. For example: 

(let* ((1 ist argl) 

(ptr (car list)) 
(rest (cdr list))) 
(tagbody loop 
(process ptr) 
(when rest 

(setq list rest) 
(setq ptr (car list)) 
(setq rest (cdr rest)) 
(go loop)))) 

See the section "Special Forms for Binding Variables". 

let-and-make-dynamic-closure vars &body body Function 

When using dynamic closures, it is very common to bind a set of variables with 
initial values, and then make a closure over those variables. Furthermore, the vari- 



Page 1 190 



ables must be declared as "special", let-and-make-dynamic-closure is a special 
form that does all of this. It is best described by example: 

(let-and-make-dynamic-closure ((a 5) b (c 'x)) 
(function (lambda () ...))) 

macro-expands into 

(let ((a 5) b (c 'x)) 

(declare (special a b c )) 
(make-dynamic-closure ' (a b c) 

(function (lambda () ...))))) 

See the section "Dynamic Closure-Manipulating Functions". 

zhlet-closed vars &body body Special Form 

When using dynamic closures, it is very common to bind a set of variables with 
initial values, and then make a closure over those variables. Furthermore, the vari- 
ables must be declared as "special", zhlet-closed is a special form that does all of 
this. It is best described by example: 

(zl : let-closed ((a 5) b (c 'x)) 
(function (lambda () ...))) 

macro-expands into 

(zl :let ((a 5) b (c 'x)) 
(declare (special a b c )) 
(closure ' (a b c) 

(function (lambda () ...))))) 

The Symbolics Common Lisp equivalent of this function is let-and-make-dynamic- 
closure. See the section "Dynamic Closure-Manipulating Functions". 

let-globally varlist &body body 

Special Form 

Similar in form to letf. The difference is that let-globally does not bind the vari- 
ables; instead, it saves the old values and sets the variables, and sets up an 
unwind-protect to set them back. The important difference between let-globally 
and letf is that when the current stack group calls some other stack group, the old 
values of the variables are not restored. Thus, let-globally makes the new values 
visible in all stack groups and processes that do not bind the variables themselves, 
not just the current stack group. 

See the section "Special Forms for Binding Variables". 



Page 1191 



let-globally-if cond varlist &body body 

Special Form 

Similiar to let-globally. It takes a cond form as its first argument. It binds the 
variables only if cond evaluates to something other than nil. body is evaluated in 
either case. 

let-if cond bindings &body body 

Special Form 

A variant of let in which the binding of variables is conditional. The variables 
must all be special variables. The let-if special form, typically written as: 

(let-if cond 

( {var-1 val-2) {var-1 val-2) . . .) 
body-forml body-form2 . . .) 

first evaluates the predicate form cond. If the result is non-nil, bindings (in the 
example above, val-1, val-2, and so on, are evaluated and then the variables var-1, 
var-2, and so on, are bound to them). If the result is nil, bindings are ignored. Fi- 
nally the body forms are evaluated. 

See the section "Special Forms for Binding Variables". 

letf places-and-values &body body 

Special Form 

Just like let, except that it can bind any storage cells rather than just variables. 
The cell to be bound is specified by an access form that must be acceptable to 
locf. For example, letf can be used to bind slots in a structure, letf does parallel 
binding. 

Given the following structure, letf calls do-something-to with ship's x position 
bound to zero. 

(defstruct ship position-x position-y) => SHIP 

(setq QE2 (make-ship)) => #S(SHIP :P0SITI0N-X NIL :P0SITI0N-Y NIL) 

(letf (((ship-position-x QE2) 0)) 
(do-something-to QE2)) 

It is preferable to use letf instead of the sys:%bind-location and sys:%with- 
binding-stack-level subprimitives. 

See the section "Special Forms for Binding Variables". 

letf* places-and-values &body body 

Special Form 



Page 1 192 



Just like let*, except that it can bind any storage cells rather than just variables. 
The cell to be bound is specified by an access form that must be acceptable to 
locf. For example, letf* can be used to bind slots in a structure, letf* does sequen- 
tial binding. 

Given the following structure, letf* calls do-something-to with ship's x position 
bound to and y position bound to 5. 

(defstruct ship position-x position-y) => SHIP 

(setq QE2 (make-ship)) => #S(SHIP :P0SITI0N-X NIL :P0SITI0N-Y NIL) 

(letf* (((ship-position-x QE2) 0) 

((ship-position-y QE2) (+ (ship-position-x QE2) 5))) 
(do-something-to QE2)) 

It is preferable to use letf* instead of the zhbind subprimitive. 
See the section "Special Forms for Binding Variables". 



sysrlexical-closure Type Specifier 

sysrlexical-closure is the type specifier symbol for the predefined Lisp object of 
that name. 

Examples: 

(typep xstandard-outputx 'sys: lexical -closure) => T 
(zl:typep *standard-output*) => : LEXICAL-CLOSURE 
(sys: type-argl ist 'sys: lexical-closure) => NIL and T 

See the section "Data Types and Type Specifiers". 

See the section "Scoping". 



lexpr-continue- whopper &rest args Special Form 

Calls the methods for the generic function that was intercepted by the whopper in 
the same way that continue-whopper does, but the last element of args is a list of 
arguments to be passed. This is useful when the arguments to the intercepted 
generic function include an &rest argument. Returns the values returned by the 
combined method. 

For more information on whoppers, including examples: See the section "Wrappers 
and Whoppers". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



lexpr-send object message-name &rest arguments Function 

Sends the message named message-name to the object, arguments are the argu- 
ments passed, except that the last element of arguments should be a list, and all 
the elements of that list are passed as arguments. For example: 



Page 1 193 



(send some-window : set-edges 10 10 40 40) 
does the same thing as these forms do: 



(lexpr-send some-window 
(lexpr-send some-window 
(lexpr-send some-window 



set-edges 10 ' (10 40 40)) 
set-edges 10 10 ' (40 40)) 
set-edges 10 10 40 ' (40)) 



lexpr-send is to send as zhlexpr-funcall is to funcall. 

lexpr-send is supported for compatibility with previous versions of the flavor sys- 
tem. When writing new programs, it is good practice to use generic functions in- 
stead of message-passing. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



lexpr-send-if-handles object message &rest arguments Function 

object performs the operation indicated by message with the given arguments, if it 
has a method for the operation. If no method for the operation is available, nil is 
returned. 

object is a Lisp object, usually a flavor instance, message is a message name or a 
generic function object, such as the result of evaluating the form (flavorrgeneric 
generic- function-name), arguments are the arguments for the operation. 

The difference between lexpr-send-if-handles and send-if-handles is that for 
lexpr-send-if-handles, the last element of arguments is a list of arguments, all of 
which are used as arguments to the operation. 

lexpr-send-if-handles is to send-if-handles as lexpr-send is to send. 

For information on restrictions in using lexpr-send-if-handles with generic func- 
tions: See the function send-if-handles. 

Note that lexpr-send-if-handles works by sending the : send-if-handles message. 
You can customize the behavior of lexpr-send-if-handles by defining a method for 
the : send-if-handles message. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 



:line-in &optional leader Message 

The stream should input one line from the input source and return it as a string 
with the carriage return character stripped off. Despite its name, this operation is 
not much like the zhreadline function. 

Many streams have a string that is used as a buffer for lines. If this string itself 
were returned, there would be problems if the caller of the stream attempted to 
save the string away somewhere, because the contents of the string would change 
when the next line was read in. To solve this problem, the string must be copied. 
On the other hand, some streams do not reuse the string, and it would be wasteful 



Page 1 194 



to copy it on every :line-in operation. This problem is solved by using the leader 
argument to :line-in. If leader is nil (the default), the stream does not copy the 
string, and the caller should not rely on the contents of that string after the next 
operation on the stream. If leader is t, the stream makes a copy. If leader is an in- 
teger then the stream makes a copy with an array-leader leader elements long. 
(This is used by the editor, which represents lines of buffers as strings with addi- 
tional information in their array-leaders, to eliminate an extra copy operation.) 

If the stream reaches the end-of-file while reading in characters, it returns the 
characters it has read in as a string, and returns a second value of t. The caller 
of the stream should therefore arrange to receive the second value, and check it to 
see whether the string returned was an whole line or only the trailing characters 
after the last carriage return in the input source. 

The :line-in message can be sent to windows. It interacts correctly with the input 
editor, including correct handling of activation characters. 



:line-out string &optional start end Message 

Outputs the characters of string, followed by a carriage return character, to the 
stream, start and end optionally specify a substring, as with :string-out. If the 
stream does not support :line-out itself, the default handler converts it to :tyos. 



lisp-implementation-type Function 

Returns a string that is the name of the Lisp system running on your machine. 

(lisp-implementation-type) => "Symbolics Common Lisp" 
or 

(lisp-implementation-type) => "Symbolics CLOE" 



lisp-implementation-version Function 

Returns a string that identifies the current version of the system running on your 
machine, including the patch level and microcode. 

(1 isp- implementation- vers ion) 
=> "System 424.207 3640-MIC microcode 428" 

For the CLOE Developer, 

(1 isp- implementation- vers ion) 
=>"1.1, Cloe Developer 318.0" 

and for the CLOE Application Generator, 

=>(1 isp- implementation- vers ion) 
"CLOE Application Generator 1.1" 



si:lisp-top-levell &optional (stream zl:terminal-io) Function 



Page 1 195 



This is the actual top-level loop. It reads a form from *standard-input*, evaluates 
it, prints the result (with slashification) to *standard-output*, and repeats indefi- 
nitely. If several values are returned by the form, all of them will be printed. The 
values of *, +, -, /, ++, **, +++, and *** are maintained. 



list Type Specifier 

list is the type specifier symbol for the predefined Lisp data structure of that 
name. 

The types list and vector are an exhaustive partition of the type sequence, since 

sequence = (or list vector). 

Examples: 

(typep ' (a b c) 'list) => T 
(zl:typep '(a b (d c) e)) => :LIST 
(subtypep 'list 'sequence) => T and T 
(sys: type-argl ist 'list) => NIL and T 
(listp ()) => T 

(listp '(2.0S0 (a 1) #\*)) => T 
(listp '(\A|b|)) => T 

See the section "Data Types and Type Specifiers". See the section "Lists". 

list &rest elements 

Function 

Constructs and returns a list of its arguments. Example: 

(list 3 4 'a (car ' (b . c)) (+ 6 -2)) => (3 4 a b 4) 

list could have been defined by: 

(defun list (&rest args) 

(let ((list (make-list (length args)))) 
(do ((1 list (cdr 1)) 
(a args (cdr a))) 
((null a) list) 
(rplaca 1 (car a))))) 

Using list helps avoid clumsy nesting callsto cons by providing a clean construc- 
tor for lists (as opposed to trees). 

(list 'a 'b) = (cons 'a (cons 'b nil)) => (A B) 

(list 'a 'b 'c 'd (cons 'e 'f) 'g)=> 
(A B C D (E . F) G) 

(list 'a 'b 'c 'd) = (list*'a 'b 'c 'd '()) 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



Page 1 196 



list* &rest args Function 

Constructs and returns a list of its arguments, whose last cons is "dotted". It must 
be given at least one argument. Example: 

(list* 'a 'b 'c 'd) => 
(a b c . d) 

This is like 

(cons 'a (cons 'b (cons 'c 'd))) 
More examples: 

(list* 'a 'b) => 

(a . b) 

(1 ist* 'a) => a 

list* is like list, except thatthe last argument is not consed with nil. When applied 
to one argument, list* simply returns the argument. A true list is returned when 
the last argument of list* is a true list, such as nil. Using list* also helps avoid 
clumsy nesting calls to cons. 

(list* 'a 'b 'c) = (cons 'a (cons 'b 'c)) 
=. (A B . C) 

(list* 'temp) => temp 

(list* 'temp nil) = (list 'temp) => (temp) 

When using 1 i st to create a new list from given elements, 1 i st* is the preferred 
function for adding a number of new elements to an already existing list: 

(setq my-friends (list 'jim 'fred)) => (JIM FRED) 

(setq my-friends 

(list* 'jack 'John 'bill my-friends)) 
=> (JACK JOHN BILL JIM FRED) 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



math:list-2d-array array Function 

Returns a list of lists containing the values in array, which must be a two- 
dimensional array. There is one element for each row; each element is a list of the 
values in that row. 



list-all-packages Function 

Returns a list of all the packages that exist in Genera or CLOE. 



Page 1 197 



The following example shows the definition of a macro similar to do-all-symbols, 
but which touches only external symbols. 

(def macro do-al 1 -external -symbols ((variable) &body forms) 
(let ((package-variable (gensym))) 

'(dolist (, package-variable (1 ist-al 1 -packages)) 

(do-external -symbols (, variable , package-variable) 
, forms)))) 



list-array-leader array &optional limit Function 

Creates and returns a list whose elements are those of array's leader, array can be 
any type of array or a symbol whose function cell contains an array. 

If limit is present, it should be an integer, and only the first limit (if there are 
more than that many) elements of array's leader are used, and so the maximum 
length of the returned list is limit. If array has no leader, nil is returned. 

For a table of related items: See the section "Copying an Array". 



list-in-area area &rest elements Function 

Constructs and returns a list of its arguments, and takes an area number argu- 
ment, and creates the list in that area. See the section "Areas". 

list-in-area is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



list*-in-area area &rest args Function 

Constructs and returns a list of its arguments, whose last cons is "dotted", and 
takes an area number argument, and creates the list in that area. 

See the section "Areas". 

list*-in-area is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



list-length list Function 

Returns, as an integer, the length of list, list-length differs from length when list 
is circular. In these cases, length can fail to return, whereas list-length returns 
nil. For example: 

(list-length ' ()) => 



Page 1 198 



(list-length ' (a b c d)) => 4 

(list-length '(a (b c) d)) => 3 

(let ((x (list 'a 'b 'c))) 
(rplacd (last x) x) 
(list-length x)) => NIL 

If the argument is known to be non-circular, list-length is less efficient than 
length because it performs significantly more work to determine the existence of 
circularities. 

(setq xprint-ci rclex t) 
(setq a '(1 2 3 4 5)) 
(1 ist-length a) => 5 
(rplacd (last a) (cddr a)) 
a => (1 2 . #1=(3 4 5 . #1#)) 
(list-length a) => nil 

See the function length. 

For a table of related items: See the section "Functions for Finding Information 
About Lists and Conses". 



zhlistarray array &optional limit Function 

Creates and returns a list whose elements are those of array, array can be any 
type of array or a symbol whose function cell contains an array. 

If limit is present, it should be an integer, and only the first limit (if there are 
more than that many) elements of array are used, and so the maximum length of 
the returned list is limit. 

If array is multidimensional, the elements are accessed in row-major order: the 
last subscript varies the most quickly. 



listen &optional input-stream Function 

The predicate listen returns t if there is a character immediately available from 
input-stream, and otherwise it returns nil. This is particularly useful when the 
stream obtains characters from an interactive device such as a keyboard. A call to 
read-char would simply wait until a character was available, but listen can sense 
whether or not to attempt input. On a non-interactive stream, the general rule is 
that listen returns t except when it's at EOF. 

(1 isten) 
=> NIL 



Page 1 199 



(let ((c (read-char))) 
(1 ist c 

(1 isten) 

(progn (unread-char c) (listen)) 
(progn (peek-char) (listen)) 
(progn (read-char) (listen))))x 

=> (#\x NIL T T NIL) 



rlisten Message 

Tests whether the user has pressed a key, perhaps trying to stop a program in 
progress, rlisten does not err; it returns either non-nil or nil. This makes it useful 
as a wait function. 

On an interactive device, rlisten returns non-nil if any input characters are imme- 
diately available, or nil if not, which implies that rtyi would hang. If rtyi would 
err, that is not considered hanging, and rlisten returns non-nil in this case. 

On a noninteractive device, the operation always returns non-nil except at end-of- 
file, by virtue of the default handler. 



zlrlistify n Function 

Manufactures a list of n of the arguments of a lexpr. With a positive argument n, 
it returns a list of the first n arguments of the lexpr. With a negative argument 
n, it returns a list of the last (abs n) arguments of the lexpr. Basically, it works 
as if defined as follows: 

(defun zl : 1 istify (n) 
(cond ((minusp n) 

(listifyl (arg nil) (+ (arg nil) n 1))) 
(t 
(listifyl n 1)) )) 

(defun listifyl (n m) ; auxiliary function. 

(do ((i n (1- i)) 

(result nil (cons (arg i) result))) 
((< i m) result) )) 

zlrlistify exists only for compatibility with Maclisp lexprs. To write functions that 
can accept variable numbers of arguments, use the &optional and &rest keywords. 
See the section "Evaluating a Function Form". 



listp object Function 

Returns t if its argument is a list, otherwise nil. This means (listp nil) is t. Note 

this distinction between listp and zlrlistp. (zlrlistp nil) is nil, since zlrlistp returns 
t if its argument is a cons. 



Page 1200 



(listp object) = (or (consp object) (null object)) 

Example: 

(listp '(5 9 12 16 8)) 

returns t, since the argument is a list. But: 

(listp '5) 
returns nil, since the argument is not a list. 

(listp (cons 'a 'b)) => t 

(listp 24) => nil 

(if (1 istp object) 

(my-function (car object) (cdr object)) 
(alt-function (test-for-type object))) 

For a table of related items: See the section "Predicates that Operate on Lists". 

listp object Function 

Returns t if its argument is a list, otherwise nil. This means (listp nil) is t. Note 
this distinction between listp and zhlistp. (zhlistp nil) is nil, since zhlistp returns 
t if its argument is a cons. 

(listp object) = (or (consp object) (null object)) 

Example: 

(listp '(5 9 12 16 8)) 

returns t, since the argument is a list. But: 

(listp '5) 
returns nil, since the argument is not a list. 

(listp (cons 'a 'b)) => t 

(listp 24) => nil 

(if (1 istp object) 

(my-function (car object) (cdr object)) 
(alt-function (test-for-type object))) 

For a table of related items: See the section "Predicates that Operate on Lists". 

zhlistp object Function 

In your new programs, we recommend that you use the function consp, which is 
the Common Lisp equivalent of zhlistp. 

Returns t if its argument is anything (for example, a symbol, array, or flavor in- 
stance, etc.) except nil. If its argument is nil, zhlistp returns nil. Note that this 
means (zhlistp nil) is nil even though nil is the empty list. 



Page 1201 



For a table of related items, see the section "Predicates that Operate on Lists". 



load-byte from-value position size Function 

Like ldb, except that instead of using a byte specifier, the bit position and size are 
passed as separate arguments. The argument order is not analogous to that of ldb 
so that load-byte can be compatible with older versions of Lisp. 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



sysrlocal-declarations Variable 

A list of local declarations. Each declaration is itself a list whose car is an atom 
which indicates the type of declaration. The meaning of the rest of the list de- 
pends on the type of declaration. For example, in the case of special and 
zhunspecial the cdr of the list contains the symbols being declared. 

The compiler is interested only in special, zhunspecial, macro, and arglist decla- 
rations. 

Local declarations are added to sysrlocal-declarations in two ways: 

• Inside a zhlocal-declare, the specified declarations are bound onto the front. 

• If sys:undo-declarations-flag is t, some kinds of declarations in a file that is 
being compiled are consed onto the front of the list; they are not popped until 
sysrlocal-declarations is unbound at the end of the file. 

Note: zhlocal-declare and sysrlocal-declarations are available in Genera, but 
should not be used for new code. See the section "Lexical Scoping". 

zhlocal-declare declarations &body body Special Form 

This function, while available in Genera, should not be used for new code. See the 
section "Lexical Scoping". See the section "Operators for Making Declarations". 

A zhlocal-declare form looks like this: 

(zl : local -declare (declaration declaration ...) 
forml 
form2 

Example: 



Page 1202 



(zl : local -declare ((special fool foo2)) 
(defun larry () 

) 
(defun george () 

) 
); end of zl : local -declare 

zhlocal-declare understands the same declarations as declare. 

Each local declaration is consed onto the list sysrlocal-declarations while the 
forms are being evaluated (in the interpreter) or compiled (in the compiler). This 
list has two uses. First, it can be used to pass information from outer macros to 
inner macros. Secondly, the compiler specially interprets certain declarations as lo- 
cal declarations, which apply only to the compilation of the forms. 



sys:localize-list list &optional area Function 

Improves locality of incrementally constructed lists and association lists. 
sys:localize-list returns either list or a copy of list, depending on how sparsely it 
is stored in virtual memory. 

The optional area argument is the number of the area in which to create the new 
list. (Areas are an advanced feature of storage management. See the section 

"Areas".) 

sys:localize-list is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Copying Lists". 



sys:localize-tree tree &optional (n-levels 100) area Function 

Improves locality of incrementally constructed lists and trees. sys:localize-tree re- 
turns either tree or a copy of tree, depending on how sparsely it is stored in virtual 
memory. 

The optional argument n-levels is the number of levels of list structure to localize. 
This is especially useful for association lists, where the value of n-levels is set to 
2. 

The optional area argument is the number of the area in which to create the new 
tree. (Areas are an advanced feature of storage management. See the section 
"Areas".) 

sys:localize-tree is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Copying Lists". 

locally &body body Macro 

Makes local pervasive declarations wherever you need them (wherever you can 
legally place a form). No variables are bound by this form, and no declarations in 
this form alter enclosing bindings. You can use the special declaration to perva- 
sively affect references to, rather than bindings of, variables. For example: 



Page 1203 



(locally (declare (inline floor) (notinline car cdr)) 
(declare (optimize space)) 
(floor (car x) (cdr y))) 

In the following example, we call a value swapping function within the scope of a 
locally call, and use a declaration that calls for optimization with respect to execu- 
tion speed: 

(locally (declare (optimize speed)) 
(swap-values item-a item-b)) 

Special declarations are allowed only to affect references. 
See the section "Operators for Making Declarations". 

zl:locate-in-closure closure symbol Function 

This returns the location of the place in the dynamic closure closure where the 
saved value of symbol is stored. An equivalent form is (locf (zl:symeval-in-closure 
closure symbol)). See the section "Dynamic Closure-Manipulating Functions". 

zl:locate-in-instance instance symbol Function 

Returns a locative pointer to the cell inside instance that holds the value of the in- 
stance variable named symbol, regardless of whether the instance variable was de- 
clared a rlocatable-instance-variable. 

In Symbolics Common Lisp, this operation is performed by: 

(locf (scl : symbol -value-in-instance instance symbol)) 

For a summary of all functions, macros, special forms, and variables related to 
Flavors: See the section "Summary of Flavor Functions and Variables". 

location-boundp location Function 

Takes a locative pointer to designate the cell rather than a symbol. It returns t if 
the cell at location is bound to a value, and otherwise it returns nil. 

location-boundp is a version of boundp that can be used on any cell. 

The following two calls are equivalent: 

(location-boundp (locf a)) 
(variable-boundp a) 

The following two calls are also equivalent. When a is a special variable, they are 
also the same as the two calls in the preceding example. 

(location-boundp (value-cell-location 'a)) 
(boundp 'a) 



Page 1204 



location-contents locative Function 

Returns the contents of the cell at which locative points. For example: 

(location-contents (value-cell-location x)) 
is the same as: 

(symeval x) 

To store objects into the cell at which a locative points, you should use (setf 
(location-contents x) y) as shown in the following example: 

(setf (location-contents (value-cell-location x)) y) 

This is the same as: 

(set x y) 

Note that location-contents is not the right way to read hardware registers, since 
cdr (which is called by location-contents) will in some cases start a block-read 
and the second read could easily read some register you didn't want it to. There- 
fore, you should use car or sys:%p-ldb as appropriate for these operations. 

location-makunbound loc &optional variable-name Function 

Takes a locative pointer to designate the cell rather than a symbol, (makunbound 
is restricted to use with symbols.) 

location-makunbound is a version of makunbound that can be used on any cell 
in the Symbolics Lisp Machine. 

location-makunbound takes a symbol as an optional second argument: variable- 
name of the location that is being made unbound. It uses variable-name to label 
the null pointer it stores so that the Debugger knows the name of the unbound lo- 
cation if it is referenced. This is particularly appropriate when the location being 
made unbound is really a variable value cell of one sort or another, for example, 
closure or instance. 

locative Type Specifier 

locativep x Function 

Returns t if its argument is a locative, otherwise nil. 

locf reference Macro 

Takes a form that accesses some cell and produces a corresponding form to create 
a locative pointer to that cell. Examples: 

(locf (array-leader foo 3)) ==> (ap-leader foo 3) 
(locf a) ==> (variable-location 'a) 
(locf (plist 'a)) ==> (property-cell-location 'a) 
(locf (aref q 2)) ==> (aloe q 2) 



Page 1205 



If access-form invokes a macro or a substitutable function, locf expands the access- 
form and starts over again. This lets you use locf together with zhdefstruct ac- 
cessors. 

If access-form is (cdr list), locf returns the list itself instead of a locative. 

See the section "Generalized Variables". 

For a table of related items: See the section "Basic Array Functions". 

log number &optional base Function 

Computes and returns the logarithm of number in the base base, which defaults to 
e, the base of the natural logarithms. Note that the result can be a complex num- 
ber even when the argument is noncomplex. This occurs if the argument is nega- 
tive. 

The range of the one-argument log function is that strip of the complex plane con- 
taining numbers with imaginary parts between -ji (exclusive) and n (inclusive). 

The range of the two-argument log function is the entire complex plane. It is an 
error if number or base is zero. Both arguments can be numbers of any type. 

The result is always in complex or noncomplex floating-point format. Numeric type 
coercion is applied to the arguments where proper. 

Examples: 

(log 2) => 0.6931472 

(log 16 2) => 4.0 

(log -1.0) => #C(0.0 3.1415927) 

(log -1 #C(0 1)) => #C(2.0 0.0) 

For a table of related items, see the section "Powers of e and Log Functions". 

zhlog n Function 

Returns the natural logarithm of n. n must be positive, and can be of any numeric 
data type. 

Example: 

(zl :log 2) => 0.6931472 

(log 81 3) -> 4.0 

(log (exp 4)) -> 4.0 

(log -1) -> #C(0.0 3.1415927) 

For a table of related items: See the section "Powers of e and Log Functions" and 
see CLtL 204. 



logand &rest integers Function 



Page 1206 



Returns the bit-wise logical and of its arguments. If no argument is given the re- 
sult is -1, which is an identity for this operation. 

Examples: 

(logand) => -1 
(logand 8) => 8 
(logand 9 15) => 9 
(logand 9 15 12) => 8 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 



zhlogand number &rest more-numbers Function 

Returns the bit-wise logical and of its arguments. At least one argument is re- 
quired. Examples: 

(zl: logand #o3456 #o707) => #o406 
(zl: logand #o3456 tfo-100) => #o3400 

For a table of related items: See the section "Functions Returning Result of Bit- 
wise Logical Operations" and see CLtL 221. 

logandcl integerl integer2 Function 

This is a non-associative bit-wise logical operation and takes exactly two argu- 
ments. It returns the bit-wise logical and of the complement of integerl with inte- 
ger2. 

Examples: 

(logandcl 15 8) => 

(logandcl 8 15) => 7 

(logandcl 1 4) => 4 

(logandcl 2 6) => 4 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 

logandc2 integerl integer2 Function 

This is a non-associative bit-wise logical operation and takes exactly two argu- 
ments. It returns the bit-wise logical and of integerl with the complement of inte- 
ger2. 

Examples: 



Page 1207 



(logandc2 15 8) => 7 

(logandc2 8 15) => 

(logandc2 1 4) => 1 

(logandc2 2 6) => 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 



logbitp index integer Function 

If index is a non-negative integer j, the predicate logbitp is true if bit j in integer 
(that bit whose weight is 2 J ) is a one-bit; otherwise it is false. 

Examples: 

(logbitp 1 8) => NIL 

(logbitp 1 10) => T 

(logbitp 6) => nil 

(logbitp 1 6) => T 

(logbitp 2 6) => T 

For a table of related items, see the section "Predicates for Testing Bits in Inte- 
gers". 



logcount integer 



Function 



If integer is positive, determines and returns the number of one-bits in the binary 
representation of integer. If integer is negative, logcount determines and returns 
the number of bits in the two's-complement binary representation of integer. The 
result is always a non-negative integer. 

Examples: 

(logcount 0) => 

(logcount 6) => 2 

(logcount -1) => 

(logcount -5) => 1 ;-5 is #b ...11011 

(logcount 7) => 3 

(logcount -11) => 2 

For a table of related items, see the section "Functions Returning Components or 
Characteristics of Argument". 



sys:%logdpb newbyte bytespec integer 



Function 



Like dpb, except that it only returns fixnums, while dpb would produce a bignum 
result for arithmetic correctness. If the sign-bit (bit-32) changes, the result reflects 
the changed sign. 



Page 1208 



sys:%logdpb is good for manipulating fixnum bit-masks such as are used in some 
internal system tables and data structures. 

The behavior of sys:%logdpb depends on the size of fixnums, so functions using it 
might not work the same way on future implementations of Symbolics Common 
Lisp. Its name starts with "%" because it is more like machine-level subprimitives 
than other byte manipulation functions. 

For a table of related items: See the section "Machine-Dependent Arithmetic Func- 
tions". 



logeqv &rest integers Function 

Returns the bit-wise logical equivalence (also known as exclusive nor) of its argu- 
ments interpreted as bit vectors. If no argument is given, the result is -1, which is 
an identity for this operation. If the integers (bit-vectors) are interpreted as sets, 
this operation represents iterated pairwise equivalence. Thus, an even number of 
small positive integer arguments returns a negative integer, and an odd number of 
small positive arguments returns a positive integer. 

Examples: 

(logeqv) => -1 

(logeqv 5) => 5 

(logeqv -3 4) => 6 ;-3 is #b1 1101 and 4 is #000100 

(logeqv 9 2) => -12 

(logeqv -3 4 9 2) => 13 ; (logeqv 6 -12) => 13 

(logeqv 1) => 1 

(logeqv 1 2) => -4 

(logeqv 1 2 4) => 7 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 



logior &rest integers Function 

Returns the bit-wise logical inclusive or of its arguments. 

If no argument is given, the result is zero. This is an identity for this operation. 

Examples: 

(logior) => 
(logior -5) => -5 
(logior 3 10) => 11 
(logior 4 8 2) => 14 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 



Page 1209 



zhlogior number &rest more-numbers Function 

Returns the bit-wise logical inclusive or of its arguments. At least one argument is 
required. Example: 

(zl:logior #o4002 #o67) => #o4067 

For a table of related items: See the section "Functions Returning Result of Bit- 
wise Logical Operations". 

sys:%logldb bytespec integer Function 

Like ldb, except that it loads out of fixnums, allowing a byte size of 32 bits of the 
fixnum, including the sign bit. sys:%logldb also loads out of bignums, allowing a 
byte size of 32 bits, including the sign bit. The result of sys:%logldb can be nega- 
tive when the size of the byte specified by bytespec is 32. 

The behavior of sys:%logldb depends on the size of fixnums, so functions using it 
might not work the same way on future implementations of Symbolics Common 
Lisp. Its name starts with "%" because it is more like machine-level subprimitives 
than other byte manipulation functions. 

For a table of related items: See the section "Machine-Dependent Arithmetic Func- 
tions". 



lognand integerl integer2 Function 

This is a non-associative bit-wise logical operation and takes exactly two argu- 
ments. It returns the logical not-and of its two arguments interpreted as bit vec- 
tors. 

Examples: 

(lognand 6 12) => -5 ;(lognot 4) => -5 

(lognand 1 4) => -1 

(lognand 1 -4) => -1 

(lognand -1 4) => -5 

(lognand -1 -4) => 3 

(lognand 2 6) => -3 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 



lognor integerl integer2 Function 

This is a non-associative bit-wise logical operation and takes exactly two argu- 
ments. It returns the logical not-or of its two arguments. 

Example: 



Page 1210 



(lognor 3 10) => -12 
(lognor 1 4) => -6 
(lognor 2 6) => -7 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 

lognot integer Function 

Returns the logical complement of integer interpreted as a bit vector. This is the 
same as logxoring integer with -1. If integer is interpreted as a set, this operation 
represents complementation. 
Example: 

(lognot 3456) => -3457 
(lognot 0) => -1 
(lognot 1) => -2 
(lognot -1) => 
(lognot -2) => 1 

For a table of related items: See the section "Functions Returning Result of Bit- 
wise Logical Operations". 

logorcl integerl integer2 Function 

This is a non-associative bit-wise logical operation and takes exactly two argu- 
ments. It returns the logical or of the complement of integerl with integer2. 

Examples: 

(logorcl -1 11) => 11 

(logorcl 11 -1) => -1 

(logorcl 1 4) => -2 

(logorcl 2 6) => -1 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 

logorc2 integerl integer2 Function 

This is a non-associative bit-wise logical operation and takes exactly two argu- 
ments. It returns the logical or of integerl with the complement of integer2. 

Examples: 



Page 1211 



(logorc2 -1 11) => -1 
(logorc2 11 -1) => 11 
(logorc2 1 4) => -5 
(logorc2 2 6) => -5 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 

logtest integerl integer2 Function 

Returns t if any of the bits designated by the l's in integerl are l's in integer2 
(that is, if there exists at least one non-negative integer j, such that bit j in inte- 
gerl and bit j in integer2 are both l's). 

Examples: 

(logtest 10 4) => NIL 
(logtest 9 1) => T 
(logtest 11 3) => T 

For a table of related items, see the section "Predicates for Testing Bits in Inte- 
gers". 

logxor &rest integers Function 

Returns the bit-wise logical exclusive or of its arguments. If no argument is given, 
the result is zero. This is an identity for this operation. 

Examples: 

(logxor) => 

(logxor 5) => 5 

(logxor 3 4) => 7 

(logxor 9 2) => 11 

(logxor 3 4 9 2) => 12 ; (logxor 7 11) => 12 

See the function boole. 

For a table of related items, see the section "Functions Returning Result of Bit- 
wise Logical Operations". 

zhlogxor integer &rest more-integers Function 

Returns the bit-wise logical exclusive or of its arguments. At least one argument is 
required. 

Example: 

(zl: logxor #o2531 #o7777) => #o5246 

For a table of related items: See the section "Functions Returning Result of Bit- 
wise Logical Operations" and see CLtL 221. 



Page 1212 



long-float Type Specifier 

long-float is the type specifier symbol for the predefined Lisp double-precision 
floating-point number type. 

The type long-float is a subtype of the type float. In Symbolics Common Lisp, the 
type long-float is identical to the type double-float. 

The type long-float is disjoint with the types short-float, and single-float. 

Examples: 

(typep 0d0 'long-float) => T 

(subtypep 'long-float 'double-float) 
=> T and T ; subtype and certain 

(commonp 1 .5d9) => T 

(equal -typep 'long-float 'double-float) => T 

(sys:double-float-p 1.5d9) => T 

See the section "Data Types and Type Specifiers". 

See the section "Numbers". 

long-float-epsilon Constant 

The value of this constant is the smallest positive floating-point number e of a for- 
mat such that it satisfies the expression: 

(not (= (float 1 e) (+ (float 1 e) e))) 

In Symbolics Common Lisp long-float-epsilon has the same value as double-float- 
epsilon, namely: 1.1102230246251568d-16. 

long-float-negative-epsilon Constant 

The value of this constant is the smallest positive floating-point number e of a for- 
mat such that it satisfies the expression: 

(not (= (float 1 e) (- (float 1 e) e))) 

In Symbolics Common Lisp the value of long-float-negative-epsilon is the same as 
that of double-float-negative-epsilon, namely: 5.551115123125784d-17. 

long-site-name Function 

Returns a string that is the full name of your site. This is the contents of the 
Pretty-name field in your site's namespace object. 

The CLOE Runtime environment does not provide a uniform way to obtain a "site" 
designation. If the value of the variable cloe::*long-site-name* is nil, you are 
prompted to enter the correct values for your site. Initially, cloe::*long-site-name* 

is set to "CLOE-USER-SITE". 



Page 1213 



loop &rest forms Macro 

loop is a Lisp macro that provides a programmable iteration facility. The Symbol- 
ics Common Lisp implementation of loop is an extension of the Common Lisp spec- 
ification for this macro in Guy L. Steele's Common Lisp: the Language. The Sym- 
bolics Common Lisp version, loop is similar to the Zetalisp version, except that 
loop allows its body to be a sequence of lists, for example: 

(let ((i 0)) 
(loop 
(print i) 
(incf i) 
(when (> i 1) (return (values))))) 

The general approach is that a form introduced by the word loop generates a sin- 
gle program loop, into which a large variety of features can be incorporated. The 
loop consists of some initialization (prologue) code, a body that can be executed 
several times, and some exit (epilogue) code. Variables can be declared local to the 
loop. The features are concerned with loop variables, deciding when to end the it- 
eration, putting user-written code into the loop, returning a value from the con- 
struct, and iterating a variable through various real or virtual sets of values. 

The loop form consists of a series of clauses, each introduced by a keyword sym- 
bol. Forms appearing in or implied by the clauses of a loop form are classed as 
those to be executed as initialization code, body code, and/or exit code; within each 
part of the template that loop fills in, they are executed strictly in the order im- 
plied by the original composition. Thus, just as in ordinary Lisp code, side effects 
can be used, and one piece of code might depend on following another for its prop- 
er operation. 

If entries are added to or deleted from the loop macro while loop is in progress, 
the results are unpredictable, with one exception: if the function calls remhash to 
remove the entry currently being processed by the body, or performs a setf of 
gethash on that entry to change the associated value, then those operations will 
have the intended effect. 

Note that loop forms are intended to look like stylized English rather than Lisp 
code. There is a notably low density of parentheses, and many of the keywords are 
accepted in several synonymous forms to allow writing of more euphonious and 
grammatical English. 

Compatibility Note: The Symbolics Common Lisp version of this function allows 
you to control its iteration by using keywords. The version of loop as specified in 
CltL does not allow atoms in the body of the loop. 



zhloop x &optional ignore Macro 

A Lisp macro that provides a programmable iteration facility, zhloop is obsolete; 
use loop instead. 

The general approach is that a form introduced by the word zhloop generates a 
single program loop, into which a large variety of features can be incorporated. 



Page 1214 



The loop consists of some initialization (prologue) code, a body that can be execut- 
ed several times, and some exit (epilogue) code. Variables can be declared local to 
the loop. The features are concerned with loop variables, deciding when to end the 
iteration, putting user-written code into the loop, returning a value from the con- 
struct, and iterating a variable through various real or virtual sets of values. 

The zhloop form consists of a series of clauses, each introduced by a keyword 
symbol. Forms appearing in or implied by the clauses of a zhloop form are classed 
as those to be executed as initialization code, body code, and/or exit code; within 
each part of the template that zhloop fills in, they are executed strictly in the or- 
der implied by the original composition. Thus, just as in ordinary Lisp code, side 
effects can be used, and one piece of code might depend on following another for 
its proper operation. 

Note that zhloop forms are intended to look like stylized English rather than Lisp 
code. There is a notably low density of parentheses, and many of the keywords are 
accepted in several synonymous forms to allow writing of more euphonious and 
grammatical English. 

Here are some examples to illustrate the use of zhloop. 

print-elements-of-list prints each element in its argument, which should be a list. 
It returns nil. 

(defun print-elements-of-list (1 ist-of-elements) 
(zl:loop for element in 1 ist-of-elements 

do (print element))) => PRINT-ELEMENTS-OF-LIST 

gather-alist-entries takes an association list and returns a list of the "keys"; that 
is, (gather-alist-entries '((foo 1 2) (bar 259) (baz))) returns (foo bar baz). 

(defun gather-alist-entries (1 ist-of-pai rs) 
(zl:loop for pair in 1 ist-of-pai rs 

collect (car pair))) => GATHER-ALIST-ENTRIES 

extract-interesting-numbers takes two arguments, which should be integers, and 
returns a list of all the numbers in that range (inclusive) that satisfy the predicate 
interesting-p. 

(defun extract-interesting-numbers (start-value end-value) 
(zl:loop for number from start-value to end-value 
when (interesting-p number) collect number)) 
=> EXTRACT-INTERESTING-NUMBERS 

find-maximum-element returns the maximum of the elements of its argument, a 
one-dimensional array. For Maclisp, aref could be a macro that turns into either 
funcall or zharraycall depending on what is known about the type of the array. 

(defun find-maximum-element (an-array) 

(zl:loop for i from below (array-dimension-n 1 an-array) 
maximize (aref an-array i))) 
=> FIND-MAXIMUM-ELEMENT 



Page 1215 



my-remove is like the Lisp function zlrdelete, except that it copies the list rather 
than destructively splicing out elements. This is similar, although not identical, to 
the zlrremove function. 

(defun my-remove (object list) 
(zl:loop for element in list 

unless (equal object element) collect element)) 
=> MY-REMOVE 

find-frob returns the first element of its list argument that satisfies the predicate 
frobp. If none is found, an error is generated. 

(defun find-frob (list) 
(loop for element in list 

when (frobp element) return element 

finally (ferror nil "No frob found in the list ~S" list))) 
=> FIND-FROB 

In many of the clause descriptions, an optional data-type is shown. This is a slot 
reserved for data type declarations; it is currently ignored. 



future-common-lisprloop &rest keywords-and-forms Macro 

The macro future-common-lisprloop performs iteration by executing a series of 
forms one or more times. Loop keywords are symbols recognized by future- 
common-lisprloop. The provide such capabilites as control of direction of iteration, 
accumulation of values inside the loop body, and evaluation of expressions that pre- 
cede or follow the loop body. 

For future-common-lisprloop without clauses, each form is evaluated in turn from 
left to right. When the last form has been evaluated, then the first form is evalu- 
ated again, and so on, in a never-ending cycle, future-common-lisprloop establish- 
es an implicit block named nil. The execution of future-common-lisprloop can be 
terminated explicitly, by using return, throw or return-from, for example. 

The syntax and usage of future-common-lisprloop is relatively complex. For com- 
plete information, see the section "Using future-common-lisprloop". 



loop-finish Macro 

(loop-finish) causes the iteration to terminate "normally", the same as implicit ter- 
mination by an iteration-driving clause, or by the use of while or until — the epi- 
logue code (if any) is run, and any implicitly collected result is returned as the 
value of the loop. For example: 

(loop for x in '(1 2 3 4 5 6) 
collect x 

do (cond ((= x 4) (loop-finish)))) 
=> (1 2 3 4) 

This particular example would be better written as until (= x 4) in place of the do 
clause. 



Page 1216 



See the section "End Tests for loop". 



si:loop-named-variable keyword Function 

Used when an iteration path function desires to make an internal variable accessi- 
ble to the user. Call this function only from within an iteration path function. If 
keyword has been specified in a using phrase for this path, the corresponding vari- 
able is returned; otherwise, gensym is called and that new symbol returned. With- 
in a given path function, this routine should only be called once for any given 
keyword. 

If you specify a using preposition containing any keywords for which the path 
function does not call si:loop-named-variable, loop informs you of the error. See 
the section "Iteration Paths for loop". 



sirloop-tassoc token keyword-alist Function 

The assoc variant of sirloop-tequal. 

See the section "Defining Iteration Paths". 

sirloop-tequal token keyword Function 

The loop token comparison function. 

token is any Lisp object, keyword must be an atomic symbol. The function returns 
t if token and keyword represent the same token, comparing them in a manner ap- 
propriate for the implementation. 

See the section "Defining Iteration Paths". 

sirloop-tmember token keyword-list Function 

The member variant of sirloop-tequal. 

See the section "Defining Iteration Paths". 

lower-case-p char Function 

Returns t if char is a lowercase letter. 

(lower-case-p #\a) => T 
(lower-case-p #\A) => NIL 

For a table of related items, see the section "Character Predicates". 

lsh number count Function 

Returns number shifted left count bits if count is positive or zero, or number shift- 
ed right | count | bits if count is negative. Zero bits are shifted in (at either end) to 



Page 1217 



fill unused positions, number and count must be fixnums. Since the result is also a 
fixnum, bits shifted off either end are lost. (In some applications you might find 
ash useful for shifting bignums.) 

Note that like the Zetalisp functions whose name begins with the percent-sign (%), 
lsh is machine-dependent. 

Examples: 

(lsh 4 1) => #o10 

(lsh #o14 -2) => #o3 

(lsh -1 1) => #o-2 

(lsh -100 27) => -536870912 ; (ash -100 27) => -13421772800 

For a table of related items: See the section "Machine-Dependent Arithmetic Func- 
tions". 



machine-instance Function 

Returns a string that is the name of your machine. 
(machine-instance) => "WOMBAT" 

This is the contents of the Host field in your machine's namespace object. See the 
section "Why do you name machines and printers?". 

machine-type Function 

Returns a string that identifies the kind of hardware you are using. 

(machine-type) => "Symbolics 3620" 

For the CLOE Developer, 

(machine-type) 
=>" Symbol ics" 

and for the CLOE Application Generator, 

(machine-type) 
=>" Intel " 



machine-version Function 

Under Genera, returns the board-level hardware information about your machine. 
This is the same as the information displayed by the Show Machine Configuration 
command for your machine. 

Under CLOE, returns a string indicating the current version of the machine for 
current implementation. For example, for the CLOE Developer you might get 
something like the following: 

(machine-version) 
=>"3640" 

and for the CLOE Application Generator 



Page 1218 



(machine-version) 
=>"386" 



macro name lambda-list &body body Special Form 

The primitive special form for defining macros. A macro definition looks like this: 

(macro name (form env) 
body) 

name can be any function spec, form and env must be variables, body is a se- 
quence of Lisp forms that expand the macro; the last form should return the ex- 
pansion, defmacro is usually preferred in practice. 



macroexpand macro-call &optional env dont-expand-special-forms for-declares 

Function 

If macro-call is a macro form, macroexpand expands it repeatedly by making as 
many repeated calls to macroexpand-1 as required until it is not a macro form, 
and returns two values: the final expansion and t. Otherwise, it returns macro-call 
and nil. The optional env environment parameter conveys information about local 
macro definitions that are defined via macrolet. (See the section "Lexical Environ- 
ment Objects and Arguments".) 

Compatibility Note: The optional argument dont-expand-special-forms, is a Symbol- 
ics extension to Common Lisp, which prevents macro expansion of forms that are 
both special forms and macros, dont-expand-special-forms will not work in other im- 
plementations of Common Lisp including CLOE. 

(defmacro nand (&rest args) '(not (and , args))) 
(macroexpand '(nand foo (eq bar baz) (> foo bar))) 

==> (not (and foo (eq bar baz) (> foo bar))) 

The following example shows the probable results of three calls to macroexpand-1 
from within a call to macroexpand: 

(defmacro and-op (op &rest args) l (,op , args)) 

(macroexpand '(and-op or (eq bar baz) (> foo bar))) = 

(macroexpand-1 (and-op or (eq bar baz) (> foo bar))) 
==> (or (eq bar baz) (> foo bar)) t 

(macroexpand-1 (or (eq bar baz) (> foo bar))) 
==> (cond ((eq bar baz)) (t (> foo bar))) t 



Page 1219 



(macroexpand-1 (cond ((eq bar baz)) (t (> foo bar)))) 
==> (if (eq bar baz) (eq bar baz) (> foo bar)) t 

==> (if (eq bar baz) (eq bar baz) (> foo bar)) t 



macroexpand-1 macro-call &optional env dont-expand-special-forms Function 

If macro-call is a macro form, macroexpand-1 expands it (once) and returns the 
expanded form and t. Otherwise, it returns macro-call and nil. The optional env 
environment parameter is conveys information about local macro definitions as de- 
fined via macrolet. 

(defmacro nand (&rest args) '(not (and , args))) 

(macroexpand-1 '(nand foo (eq bar baz) (> foo bar))) 

==> (not (and foo (eq bar baz) (> foo bar))) T 

(defmacro and-op (op &rest args) l (,op , args)) 

(macroexpand-1 '(and-op or (eq bar baz) (> foo bar))) 

==> (or (eq bar baz) (> foo bar)) T 

(See the section "Lexical Environment Objects and Arguments".) 

Compatibility Note: The optional argument dont-expand-special-forms, is a Symbol- 
ics extension to Common Lisp, which prevents macro expansion of forms that are 
both special forms and macros, dont-expand-special-forms will not work in other im- 
plementations of Common Lisp including CLOE. See the variable *macroexpand- 
hook*. 

*macroexpand-hook* Variable 

The value is used as the expansion interface hook by macroexpand-1. When 
macroexpand-1 determines that a symbol names a macro, it obtains the expansion 
function for that macro. The value of *macroexpand-hook* is called as a function 
of three arguments: the expansion function, form, and env. The value returned 
from this call is the expansion of the macro call. 

The initial value of *macroexpand-hook* is funcall, and the net effect is to in- 
voke the expansion function, giving it form and env as its two arguments. 

This special variable allows for more efficient interpretation of code, for example, 
by allowing caching of macro expansions. Such efficiency measures are unneces- 
sary in compiled environments such as the CLOE runtime system. 

macro-function function 



Page 1220 



Function 

Tests whether its argument is the name of a macro, function should be a symbol. 
If function has a global function definition that is a macro definition, the expan- 
sion function (a function of two arguments, the macro-call form and an environ- 
ment) is returned. The function macroexpand is the best way to invoke the expan- 
sion function. 

If function has no global function definition, or has a definition as an ordinary 
function or as a special form but not as a macro, then nil is returned. In the fol- 
lowing example, macro-function (before using funcall) tests an argument intended 
as a function . 

(defun foo (function-arg arg-arg) 
(if (macro-function function-arg) 
(do-something-else arg-arg) 
(funcall function-arg arg-arg (cadr arg-arg)))) 

Usually, macroexpand is used to expand a macro. However, in the following exam- 
ple of a highly simplified definition of macroexpand-1, we see how to expand a 
macro by using macro-function. 

(defun simple-macroexpand-1 (form) 
(let ((name (first form)) 

(expander (macro-function name))) 
(if expander 

(values (funcall expander form) t) 
(values form nil)))) 

It is possible for both macro-function and special-form-p to be true of a symbol. 
This is so because it is permitted to implement any macro also as a special form 
for speed. 

macro-function cannot be used to determine whether a symbol names a locally de- 
fined macro established by macrolet; macro-function can examine only global def- 
initions. 

zhsetf can be used with macro-function to install a macro as a symbol's global 
function definition: 

For example: 

(zhsetf (macro-function symbol) fn) 

The value installed must be a function that accepts two arguments, an entire 
macro call and an environment, and computes the expansion for that call. Perform- 
ing this operation causes the symbol to have only that macro definition as a global 
function definition; any previous definition, whether as a macro or as a function, is 
lost. 



macrolet macros &body body Special Form 

Defines, within its scope, a macro. It establishes a symbol as a name denoting a 
macro, and defines the expander function for that macro, defmacro does this 



Page 1221 



globally; macrolet does it only within the (lexical) scope of its body. A macro so 
defined can be used as the car of a form within this scope. Such forms are expand- 
ed according to the definition supplied when interpreted or compiled. 

The syntax of macrolet is identical to that of flet or labels: it consists of clauses 
defining local, lexical macros, and a body in which the names so defined can be 
used, macros a list of clauses each of which defines one macro. Each clause is 
identical to the cdr of a defmacro form: it has a name being defined (a symbol), a 
macro pseudo-argument list, and an expander function body. 

The pseudo-argument list is identical to that used by defmacro. It is a pattern, 
and can use appropriate lambda-list keywords for macros, including &environment. 
See the section "Lexical Environment Objects and Arguments". 

The following example of macrolet is for demonstration only. If the macro square 
needed to be open-coded, was long and cumbersome, or was used many times, then 
the use of macrolet would be suggested. 

(defun square-coordinates (point) 
(macrolet ((square (x) ' (* ,x ,x))) 

(setf (point-x point) (square (point-x point)) 

(point-y point) (square (point-y point))))) 

(defstruct point x y) => POINT 

(setq p1 (make-point :x 3 :y 4)) => #S(P0INT :X 3 :Y 4) 

(square-coordinates p1) => 16 

(defun foo (x) 

(macrolet ((do-it (var n) 
1 (case , var 

,(do ((i (+ i 1)) 

(1 '())) 
((= i n) (nreverse 1 )) 
(push (list i (format nil "~R" i)) 

1))))) 
(do-it x 100))) 

(foo 12) => "twelve" 

The following example implements a macro to establish a context where items can 
be added to the end of list. This is similar to the way push adds to the beginning 
of a list. We use macrolet to ensure that push-onto-end has access to the pointer 
until the last cons of the list. 



Page 1222 



(def macro with-end-push2 (list &body body) 
(let ((lastptr (gensym))) 

'(let ((, lastptr (last .list))) 
(macrolet ((push-onto-end (val) 
1 (rplacd , ' , lastptr 

(setq , '.lastptr (cons , val nil))))) 
.body)))) 

(defun example-3 () 

(let ((mylist (list 1 2 3)) 

(a-list (list 'a 'b 'c 'd))) 
(with-end-push2 mylist 
(dolist (1 a-list mylist) 
(push-onto-end 1))))) 

(example-3) 

It is important to realize that macros defined by macrolet are run (when the com- 
piler is used) at compile time, not run-time. The expander functions for such 
macros, that is, the actual code in the body of each macrolet clause, cannot at- 
tempt to access or set the values of variables of the function containing the use of 
macrolet. Nor can it invoke run-time functions, including local functions defined 
in the lexical scope of the macrolet by use of flet or labels. The expander func- 
tion can freely generate code that uses those variables and/or functions, as well as 
other macros defined in its scope, including itself. 

There is an extreme subtlety with respect to expansion-time environments of 
macrolet. It should not affect most uses. The macro-expander functions are closed 
in the global environment; that is, no variable or function bindings are inherited 
from any environment. This also means that macros defined by macrolet cannot 
be used in the expander functions of other macros defined by macrolet within the 
scope of the outer macrolet. This does not prohibit either of the following: 

• Generation of code by the inner macro that refers to the outer one. 

• Explicit expansion (by macroexpand or macroexpand-1), by the inner macro, of 
code containing calls to the outer macro. Note that explicit environment man- 
agement must be utilized if this is done. See the section "Lexical Environment 
Objects and Arguments". 



make-array dimensions &key (: element-type t) .-initial-element .-initial-contents .-ad- 
justable .-fill-pointer :displaced-to :displaced-index-offset :displaced-conformally -.area 
-.leader-list -.leader-length mamed-structure-symbol Function 

Creates and returns a new array, dimensions is the only required argument, di- 
mensions is a list of integers that are the dimensions of the array; the length of 
the list is the dimensionality, or rank of the array. 



Page 1223 



; ; Create a two-dimensional array 

(make-array '(3 4) :element-type 'string-char) 

You can use these element types: bit, string-char, (unsigned-byte 8), (unsigned- 
byte 16), (signed-byte 8), and (signed-byte 16). 

For convenience when making a one-dimensional array, the single dimension can 
be provided as an integer rather than a list of one integer. 

;; Create a one-dimensional array of five elements, 
(make-array 5) 

The initialization of the elements of the array depends on the element type. By 
default, the array is a general array, the elements can be any type of Lisp object, 
and each element of the array is initially nil. However, if the :element-type option 
is supplied, and it constrains the array elements to being integers or characters, 
the elements of the array are initially or characters whose character code is 
and style is NIL.NIL.NIL. You can specify initial values for the elements by using 
the rinitial-contents or rinitial-element options. 

Compatibility Note: The optional arguments rdisplaced-conformally, :area, 
:leader-list, rieader-length, and mamed-structure-symbol are Symbolics exten- 
sions to Common Lisp, and are not available in CLOE. 

For a table of related items: See the section "Basic Array Functions". 

See the section "Examples of make-array". 

If you are using CLOE, see the section "Keyword Options for make-array". 



zhmake-array dimensions &key :area :type :displaced-to :displaced-index-offset :dis- 
placed-conformally .-adjustable deader-list deader-length mamed-structure-symbol -.ini- 
tial-value -.fill-pointer Function 

We recommend using make-array instead of zhmake-array. See the function 
make-array. 

Creates and returns a new array, dimensions is the only required argument, di- 
mensions is a list of integers that are the dimensions of the array; the length of 
the list is the dimensionality, or rank of the array. For the one-dimensional case 
you can just give the integer. 

zhmake-array returns two values: the newly created array, and the number of 
words allocated in the process of creating the array. The second value is the 
sys:%structure-total-size of the array. Note that make-array returns only one 
value, the newly created array. 

Most of the keyword options to zhmake-array have the same meaning as the key- 
word options with the same name that can be given to make-array. See the sec- 
tion "Keyword Options for make-array". 

:initial-value The :initial-value keyword for zhmake-array has the same 

meaning as the rinitial-element keyword for make-array. 



Page 1224 



:type The :type option for zhmake-array is used for the same pur- 

pose as is the :element-type option for make-array; that is, to 
specify that the elements of the array should be of a certain 
type. The value of the :type option is the symbolic name of 
one of the Zetalisp array types, which include: 



sys:art-q 

sys:art-q-list 

sys:art-nb 

sysrart-string 

sys:art-fat-string 

sysrart-boolean 

sysrart-fixnum 



The default type of array is sys:art-q, a general array. See the 
section "Zetalisp Array Types". 

The initialization of the elements of the array depends on the type of array. If the 
array is of a type whose elements can only be integers or characters, element of 
the array are initially or character code 0. Otherwise, each element is initially 
nil. 



zl:make-array-into-named-structure array Function 

Turns array into a named structure, and returns it. 

make-char char &optional (bits 0) (font 0) 

Function 

Takes the argument char, which must be a character object, bits and font must be 
non-negative integers, make-char sets the bits field to bits and returns the new 
character. If make-char cannot construct a character given its arguments, it re- 
turns nil. 

To set the bits of the character, supply one of the character bits constants as the 
bits argument. See the section "Character Bit Constants". 

(make-char #\A char-meta-bit) => #\m-A 

Since the value of char-font-limit is 1, the only valid value of font is 0, since Sym- 
bolics does not support font numbers. The only reason to use the font option would 
be when writing a program intended to be portable to other Common Lisp systems. 
Common Lisp supports font attributes for character objects, Symbolics Common 
Lisp does not. 

In Genera, make-char does not change character styles. If you want to construct a 
new character with a specified character style, use make-character. See the func- 
tion make-character. 

For a table of related items, see the section "Making a Character". 



Page 1225 



make-character char &key (bits 0) (style nil) Function 

Takes an argument char, which must be a character object, and returns a new 
character with the same code, but having the specified bits and style. 

To set the bits of the character, supply one of the character bits constants as the 
value of the :bits keyword. See the section "Character Bit Constants". For example: 

(make-character #\1 :bits char-control-bit) => #\c-1 

To set the character style of the character, use the rstyle keyword and supply a 
list of the form (.-family :face :size). Any of the elements of this list can be nil. For 
example: 

(make-character #\A : style '(nil : italic nil)) => #\A 
For a table of related items, see the section "Making a Character". 



make-concatenated-stream &rest streams Function 

Returns a stream that only works in the input direction. Input is taken from the 
first of the streams until it reaches EOF (end-of-file); then that stream is discard- 
ed, and input is taken from the next of the streams, and so on. If no arguments 
are given, the result is a stream with no content; any input attempt will result in 
EOF. 

In the following example, three file input streams are created using open. These 
streams are read from inside a loop by using make-concatenated-stream. 

(with-open-f ile (streaml xstream-namelx :direction :input) 
(with-open-f ile (stream2 xstream-name2x :direction :input) 
(with-open-f ile (stream3 xstream-name3x :direction :input) 
(let ((input '()) 

(cat-stream (make-concatenated-stream streaml 

stream2 
stream3))) 
(loop 

(setq input (read cat-stream nil :eof)) 
(unless (and input (not (eq input :eof))) 

(return t)) 
(process-input input)))))) 



make-condition condition-name &rest init-options 

Function 

Creates a condition object of the specified condition-name with the specified init- 
options. This object can then be signalled by passing it to signal or error. Note 
that you are not supposed to design functions that indicate errors by returning er- 
ror objects; functions should always indicate errors by signalling error objects. 
This function makes it possible to build complex systems that use subroutines to 
generate condition objects so that their callers can signal them. 



Page 1226 



For a table of related items available in Genera: See the section 
Checking and Signalling Functions and Variables". 



"Condition- 



sysrmake-coroutine-bidirectional-stream function &rest arguments 
This function is obsolete. See the function sysropen-coroutine-stream. 



Function 



sys:make-coroutine-input-stream function &rest arguments 

This function is obsolete. See the function sysropen-coroutine-stream. 



Function 



sysrmake-coroutine-output-stream function &rest arguments 

This function is obsolete. See the function sysropen-coroutine-stream. 



Function 



make-dispatch-macro-character char &optional 
*readtable*) 



non-terminating-p 



(a-readtable 
Function 



Causes char to be a dispatching macro character in readtable. If non-terminating-p 
is non-nil (it defaults to nil), it will be a non-terminating macro character, which 
means that it may be embedded within extended tokens, make-dispatch-macro- 
character returns t. 

Initially, every character in the dispatch table has a character-macro function that 
signals an error. Use set-dispatch-macro-character to define entries in the dis- 
patch table. 

(let ((xreadtablex (copy-readtable nil)) 

(macfun (get-dispatch-macro-character #\# #\\))) 
(set-syntax-f rom-char #\[ #\#) 

(make-dispatch-macro-character #\[ t xreadtablex) 
(set-dispatch-macro-character #\[ #\\ macfun) 
(values (read-f rom-string "[\+"))) 
=> ft\+ 



make-dynamic-closure symbol-list function 



Function 



Creates and returns a dynamic closure of function over the variables in symbol-list. 
Note that all variables on symbol-list must be declared special. 

To test whether an object is a dynamic closure, use (typep x rclosure). (typep x 
rclosure) is equivalent to (zlrclosurep x). See the section "Dynamic Closure- 
Manipulating Functions". 



make-echo-stream input-stream output-stream 



Function 



Page 1227 



This function, which is part of the Common Lisp standard, is not currently avail- 
able in the Symbolics implementation of Common Lisp under Genera. 

In CLOE, make-echo-stream creates and returns an input/output stream that 
takes input from input-stream, echoes the input to output-stream, and sends output 
to output-stream. 

(with-open-f ile (instream "foo" :di recti on :input) 

(with-open-f ile (outstream "bar. out" :di recti on :output) 
(let ((my-io-stream (make-echo-stream instream outstream))) 

(my-decide xdeciderx (read my-io-stream)) ; these reads are echoed 
(if (eq xdecisionx 'sell) 

(sell -action (read my-io-stream)) ; to outstream. 

))) 
The function make-echo-stream is thus handy for implementing 'dribble' facilities, 
to record interactions. 



zl:make-equal-hash-table &rest options Function 

Creates a new hash table using the equal function for comparison of the keys. 
This function calls make-instance using the si:equal-hash-table flavor, passing 
options to make-instance as init options. See the flavor si:equal-hash-table. This 
function is obsolete; use make-hash-table with the :test keyword instead. 



make-hash-table &key :name (.-test 'eql) (:size cli:*default-table-size*J Oarea 
sys:default-cons-areaJ .-hash-function :rehash-before-cold :rehash-after-full-gc (:num- 
ber-of-values 1) : store-hash-code (:gc-protect-values t) (.-mutating t) .-initial-contents 
.-optimizations (.-locking rprocessj :ignore-gc (-growth-factor cli::*default-table- 
growth-factor*) (-growth-threshold cli::*default-table-growth-threshold*J rehash- 
size .-rehash-threshold Function 

Creates and returns a new table object. This function calls make-instance using a 
basic table flavor and mixins for the necessary additional flavors as specified by 
the options. 

make-hash-table takes the following keyword arguments: 

:name A symbol that identifies the table in progress notes. 

:test Determines how keys are compared. Its argument can be any 

function; eql is the default. If you supply one of the following 
values or predicates the hash table facility automatically sup- 
plies a :hash-function: eq, eql, equal, char-equal, char=, 
string-equal, #'string-equal, strings, zhequal, zhstring-equal, 
zl:string=. If you supply a value or predicate that is not on 
this list, you must supply a :hash-function explicitly. Note: the 
:test and :hash-function interact closely, and must agree with 
each other. 



Page 1228 



:size An integer representing the initial size of the table. The table 

will be made large enough to hold this many entries without 
growing. 

:area If :area is nil (the default), the *default-cons-area* is used. 

Otherwise, the number of the area that you wish to use. This 
keyword is a Symbolics extension to Common Lisp. 

:hash-function Specifies a replacement hashing function. The default is based 
on the :test predicate. This keyword is a Symbolics extension 
to Common Lisp. 

rrehash-before-coldCauses a rehash whenever the hashing algorithm has been in- 
validated, during a Save World operation. Thus every user of 
the saved world does not have to waste the overhead of rehash- 
ing the first time they use the table after cold booting. 

For eq tables, hashing is invalidated whenever garbage collec- 
tion or world compression occurs because the hash function is 
sensitive to addresses of objects, and those operations move ob- 
jects to different addresses. For equal tables, the hash function 
is sensitive to addresses of some objects, but not to others. The 
table remembers whether it contains any such objects. 

Normally a table is automatically rehashed "on demand" the 
first time it is used after hashing has become invalidated. This 
first gethash operation is therefore much slower than normal. 

The :rehash-before-cold keyword should be used on tables that 
are a permanent part of your world, likely to be saved in a 
world saved by Save World, and to be touched by users of that 
world. This applies both to tables in Genera and to tables in 
user-written subsystems saved in a world. 

This keyword is a Symbolics extension to Common Lisp. 

:rehash-after-full-gc 

Similar to :rehash-before-cold. Causes a rehash whenever the 
garbage collector performs a full gc. This keyword is a Symbol- 
ics extension to Common Lisp. 

:entry-size This keyword is obsolete. :entry-size 2 is equivalent to 

:number-of-values 1. :entry-size 1 is equivalent to :number-of- 

values 0. This keyword is a Symbolics extension to Common 
Lisp. 

:number-of-values Specifies the number of values associated with the key to be 
stored in the table. Currently, the only valid values are and 
1. If is specified, the table functions return t for the value of 
the entry. This keyword is a Symbolics extension to Common 
Lisp. 

: store-hash-code Specifies that the table system store the hash code for each 
key with the key. This keyword makes make-hash-table run 



Page 1229 



rmutating 



rinitial-contents 



faster, since its use avoids the need to run a test function, un- 
less the hash codes are the same. Use of this keyword increas- 
es the size of the table. Since gethash searches for keys equiv- 
alent to the supplied key under the supplied value of the :test 
argument, : store-hash-code t improves performance if the :test 
function pages or is slow. This keyword is a Symbolics exten- 
sion to Common Lisp. 

Turns mutation on and off. The overhead involved with specify- 
ing this keyword is relatively higher for small tables than for 
large ones. The default value is t. This keyword is a Symbolics 
extension to Common Lisp. 

Set the initial contents for the new table. It can be either a ta- 
ble object to be copied, or a sequence of keys and values, for 
example: 

'(KEY1 VALUE1 ... KEYn VALUEn) 

This keyword is a Symbolics extension to Common Lisp. 

One of the following locking strategies: rprocess, rwithout- 
interrupts, nil, or a cons consisting of a lock and an unlock 
function. The default is to lock against other processes. This 
keyword is a Symbolics extension to Common Lisp. 

By default, if the hash function is sensitive to the garbage col- 
lector, the table is protected against GC flip. If you supply this 
keyword, the table is not protected. 

If the hash function utilizes the address of a Lisp object that 
might be changed by the GC, the hash function must recom- 
pute the hash code if that address is changed. :ignore-gc as- 
serts that the hash function never uses such addresses, so that 
it need not recompute the codes. The default depends on the 
hash function: if it's one of a small set of functions that Lisp 
knows do not depend on addresses, this defaults to t (meaning 
yes, it can ignore the GC). Otherwise, it chooses nil, which is 
always safe, t might make your program run faster (avoiding 
rehashes at GC time) but might also break your program (if 
the hash function depends on address values). This keyword is 
a Symbolics extension to Common Lisp. 

:gc-protect-values The default is t. If nil, table entries are automatically deleted 
if a value becomes unreachable other than through the table. 
This keyword is a Symbolics extension to Common Lisp. 



rlocking 



:ignore-gc 



rgrowth-factor 



A synonym for :rehash-size. If the keyword is an integer, it is 
the number of entries to add, and if it is a floating-point num- 
ber, it is the ratio of the new size to the old size. If the value 
is neither an integer or a floating-point number, an error is 
signalled. This keyword is a Symbolics extension to Common 
Lisp. 



Page 1230 



rgrowth-threshold A synonym for rrehash-threshold. If it is an integer greater 
than zero and less than the :size, it is related to the number 
of entries at which growth should occur. The threshold is the 
current size minus the rgrowth-threshold. If it is a floating- 
point number between zero and one, it is the percentage of en- 
tries that can be filled before growth will occur. If the value is 
neither an integer or a floating-point number, an error is sig- 
nalled. This keyword is a Symbolics extension to Common Lisp. 

:rehash-size The growth factor of the table when it becomes full. If the val- 

ue of the keyword is an integer, it is the number of entries to 
add, and if it is a floating-point number, it is the ratio of the 
new size to the old size. If the value is neither an integer or a 
floating-point number, an error is signalled. 

rrehash-threshold How full the table can become before it must grow. If it is an 
integer greater than zero and less than the value of rsize, it is 
related to the number of entries at which growth should occur. 
The threshold is the current size minus the rgrowth-threshold. 
If it is a floating-point number between zero and one, it is the 
percentage of entries that can be filled before growth will oc- 
cur. If the value is neither an integer nor a floating-point 
number, an error is signalled. 

If you are using CLOE, zlrmake-hash-table returns a newly created hash table 
with size entries. Argument test must be eq, eql or equal expressed as either sym- 
bols or as the function-quoted objects. Argument rehash-size can be an integer that 
provides the number of entries to add, or a floating point number that indicates 
the portion of the previous size to grow the hash table. Argument rehash-threshold 
also may be an integer or floating point number, and indicates the maximum ca- 
pacity of the hash table before it should grow. 

(setq hash-table-1 (make-hash-table)) 



(setq hash-table-2 

(make-hash-table :size (* number-of-my-symbols 100) 
rehash-size 2.0 
rehash-threshold 0.8 
test 'eq)) 

Compatibility Note: The following keywords are Symbolics extensions to Common 
Lisp: rarea, rhash-function, rrehash-before-cold, rrehash-after-full-gc, rentry-size, 
mumber-of-valuesr rstore-hash-coder, rmutating, rinitial-contents, roptimizations, 
rlocking, rignore-gc, rgc-protect-values, rgrowth-factor, and rgrowth-threshold. 

For a table of related items: See the section "Table Functions". 



zlrmake-hash-table &key :size :area :rehash-before-cold .-initial-data .-growth-factor 

Function 



Page 1231 



Creates a new hash table using the eq function for comparison of the keys. This 
function calls make-instance using the si:eq-hash-table flavor, passing options to 
make-instance as init options. See the flavor si:eq-hash-table. 

This is obsolete; use make-hash-table with the :test keyword instead. 



make-heap f&key (.size 100) (.-predicate #'<) (: growth- factor 1.5) .-interlocking) 

Function 

Creates a new heap, rpredicate, :size, and rgrowth-factor are passed as init op- 
tions to make-instance when the heap is created. 

make-heap takes the following keyword arguments: 
The default is 100. 



:size 
rpredicate 

rgrowth-factor 



rinterlocking 



An ordering predicate that is applied to each key. The default 
is #'<. 

A number or nil. If it is an integer, the heap is increased by 
that number. If it is a floating-point number greater than one, 
the new size of the heap is the old size multiplied by that 
number. If it is nil, the condition sirheap-overflow is signalled 
instead of growing the heap. 



rwithout-interruptsCauses make-heap to create a kind of heap 
that can be interlocked for use by multiple 
processes, using without-interrupts to per- 
form the interlocking. 

t Causes make-heap to create a kind of heap 

that can be interlocked for use by multiple 
processes, using process-lock to perform 
the interlocking. 



nil 



Causes make-heap to create a heap that 
uses no locking at all. This is the default. 



For a table of related items: See the section "Heap Functions and Methods". 



make-instance flavor-name &rest init-options 



Function 



Creates and returns a new instance of the flavor named flavor-name, initialized ac- 
cording to init-options, which are alternating keywords and arguments. All init- 
options are passed to any methods defined for make-instance. 

If compile-flavor-methods has not been done in advance, make-instance causes 
the combined methods of a program to be compiled, and the data structures to be 
generated. This is sometimes called composing the flavor, make-instance also 
checks that the requirements of the flavor are met. Requirements of the flavor are 



Page 1232 



set up with these defflavor options: rrequired-flavors, 
:required-init-keywords, and rrequired-instance-variables. 

init-options can include: 



rrequired-methods, 



rinitable-instance-variable value 

You can supply keyword arguments to make-instance that 
have the same name as any instance variables specified as 
rinitable-instance-variables in the defflavor form. Each key- 
word must be followed by its initial value. This overrides any 
defaults given in defflavor forms. 

:init-keyword valueYou can supply keyword arguments to make-instance that 
have the same name as any keywords specified as :init- 
keywords in the defflavor form. Each keyword must be fol- 
lowed by a value. This overrides any defaults given in 
defflavor forms. 

: allow-other-key s t Specifies that unrecognized keyword arguments are to be ig- 
nored. 

: allow-other-key s rreturn 

Specifies that a list of unrecognized keyword arguments are to 
be the second return value of make-instance. Otherwise only 
one value is returned, the new instance. 



:area number 



:area nil 



Specifies the area number in which the new instance is to be 
created. Note that you can use the :area-keyword option to 
defflavor to change the :area keyword to make-instance to a 
keyword of your choice, such as :area-for-instances. 

Any ancillary values constructed by make-instance (other than 
the instance itself) are constructed in whatever area you speci- 
fy for them; this is not affected by using the :area keyword. 
For example, if you supply a variable initialization that causes 
consing, that allocation is done in whatever area you specify 
for it, not in this area. For example: 

(defflavor foo ((foo-1 (make-array 100))) 
0) 

In this example the array is consed in sys:default-cons-area. 

Specifies that the new instance is to be created in the 
sys:default-cons-area. This is the default, unless the rdefault- 
init-plist option is used to specify a different default for :area. 



If not supplied in the init-options argument to make-instance, the :default-init- 
plist option to the defflavor form is consulted for any default values for initable 
instance variables, init keywords, and the :area and : allow-other-key s options. 



Page 1233 



An alternative way to make instances is to use constructors. One advantage in us- 
ing constructor functions is that they are much faster than using make-instance. 
You can define constructors by using the rconstructor option; for more informa- 
tion, see the section "Complete Options for defflavor". 

If you want to know what the allowed keyword arguments to make-instance are, 
use the Show Flavor Initializations command. See the section "Show Flavor Com- 
mands". c-sh-R works too, if the flavor name is constant. 

You can define a method to run every time an instance of a certain flavor is cre- 
ated. For information, see the section "Writing Methods for make-instance". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



Page 1234 



Creates and returns a new instance of the flavor named flavor-name, initialized 
according to init-options , which are alternating keywords and arguments. All init- 
options are passed to any methods defined for make-instance. 

If compile-flavor-methods has not been done in advance, make-instance causes 
the combined methods of a program to be compiled, and the data structures to be 
generated. This is sometimes called composing the flavor, make-instance also 
checks that the requirements of the flavor are met. Requirements of the flavor 
are set up with these defflavor options: rrequired-flavors, rrequired-methods, 
:required-init-keywords, and rrequired-instance-variables. 

init-options can include: 

dnitable-instance-variable value 

You can supply keyword arguments to make-instance that 
have the same name as any instance variables specified as 
rinitable-instance-variables in the defflavor form. Each key- 
word must be followed by its initial value. This overrides any 
defaults given in defflavor forms. 

:init-keyword value You can supply keyword arguments to make-instance that 
have the same name as any keywords specified as :init- 
keywords in the defflavor form. Each keyword must be fol- 
lowed by a value. This overrides any defaults given in 
defflavor forms. 

: allow-other-key s t Specifies that unrecognized keyword arguments are to be ig- 
nored. 

: allow-other-key s rreturn 

Specifies that a list of unrecognized keyword arguments are 
to be the second return value of make-instance. Otherwise 
only one value is returned, the new instance. 

If not supplied in the init-options argument to make-instance, the :default-init- 
plist option to the defflavor form is consulted for any default values for initable 
instance variables, init keywords, and the : allow-other-key s options. 

If you want to know what the allowed keyword arguments to make-instance are, 
use the Show Flavor Initializations command. 

You can define a method to run every time an instance of a certain flavor is 
created: 



closrmake-instance class &rest initargs Generic Function 

Creates, initializes, and returns a new instance of the given class. 

class The name of the class, or a class object. 

initargs Alternating initialization argument names and values. The ini- 

targs are used to initialize the new instance. The set of valid 
initialization argument names includes: 



• 



Page 1235 



clos-internals:storage-area, which specifies the area in 
which to create the instance. The value should be an area 
number. The default is sys:default-cons-area. 

Symbols declared by the rinitarg slot option to closrdefclass, 
which are used to initialize the value of a slot. 

Keyword arguments accepted by any applicable methods for 
closrinitialize-instance and closrshared-initialize. 

• The keyword :allow-other-keys. The default value for 
: allow-other-key s is nil. If you provide t as its value, then 
all keyword arguments are valid. 

closrmake-instance does the following: 

1. Checks the validity of the initargs and signals an error if an invalid initializa- 
tion argument name is detected. See the section "Declaring Initargs for a 
Class". 

2. Creates a new instance. 

3. Calls the closrinitialize-instance generic function with the instance, and the 
initialization arguments provided to closrmake-instance followed by the de- 
fault initialization arguments of the class. (This order of initialization argu- 
ments ensures that all initialization arguments provided to closrmake- 
instance are used to fill slots first, and then the default initialization argu- 
ments are used to fill slots that are still unbound.) 

4. Fills any unbound slots with values according to the default initialization ar- 
guments of the class. The default initialization arguments are specified by the 
rdefault-initargs class option to closrdefclass. 

5. When finished, returns the initialized instance. 

The default primary method for closrinitialize-instance calls the closrshared- 
initialize generic function with the instance, t, and the initialization arguments 
provided to closrinitialize-instance. 

Note that the usual way for users to customize the initialization behavior is to 
specialize closrinitialize-instance by writing after-methods. Any applicable after- 
methods for closrinitialize-instance are called after the primary method for 
closrinitialize-instance. A user-defined primary method would override the default 
method, and thus could prevent the usual slot-filling behavior. 

The default primary method for closrshared-initialize does the following: 

1. Fills slots with values according to the initargs. That is, for any initialization 
argument name that is associated with a slot, the value of the slot is initial- 
ized according to the argument given to closrmake-instance. 



Page 1236 



2. Fills any unbound slots indicated by the second argument to closrshared- 
initialize with values according to the initform of the slot. The initform is 
specified by the rinitform slot option to closrdefclass. 

Users can define after-methods for closrshared-initialize, to customize the initial- 
ization behavior that occurs in several cases. Note that a user-defined primary 
method for closrshared-initialize would override the default method, and thus 
could prevent the usual slot-filling behavior. The closrshared-initialize generic 
function is called in these cases: 

• When an instance is first created; that is, when closrmake-instance is called. 

• When an instance is reinitialized; that is, when closrreinitialize-instance is 
called. 

• When the class of an instance is changed; that is, when closrupdate-instance- 
for-different-class is called. 

• When a class is redefined; that is, when closrupdate-instance-for-redefined- 
class is called. 

Any slot that is not filled by closrshared-initialize is left unbound. 

The generic function closrmake-instance itself is not intended to be specialized by 
applications programmers. (Instead, it is intended to be specialized by meta-object 
programmers who wish to customize the behavior of closrmake-instance for a 
metaclass other than closrstandard-class). 



closrmake-instances-obsolete class Generic Function 

Called automatically when a class is redefined to trigger the updating of instances. 
Users can call closrmake-instances-obsolete to trigger the class redefinition pro- 
cess without actually redefining the class; the purpose of this would be to invoke 
the closrupdate-instance-for-redefined-class generic function. 

class The class whose instances should be updated. This can be the 

name of a class or a class object. 

The modified class is returned. 



make-list size &key .-initial-element :area Function 

Creates and returns a list containing size elements, each of which is initialized to 
the value supplied for the rinitial-element keyword. The value of size should be a 
non-negative integer. For example: 

(make-list 5) => (NIL NIL NIL NIL NIL) 

(make-list 3 : initial -element 'rah) => (RAH RAH RAH) 



Page 1237 



rinitial-element The value to be assigned to each element of the created list. 
The default is nil). 

:area optional argument that is the number of the area in which to 

create the new list. (Areas are an advanced feature of storage 
management, and are not available in CLOE. See the section 

"Areas".) 

Compatibility Note: :area is a Symbolics extension to Common Lisp and is not 
available in CLOE. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



zl:make-list length &key :area .-initial-value Function 

Creates and returns a list containing length elements, length should be an integer. 
The keywords can be either of the following: 

:area Either an area number (an integer), or nil to mean the default area. The 
value specifies in which area the list should be created. Note that you can- 
not use this option in Cloe. See the section "Areas". 

:initial-value 

The initial value of all elements of the list. It defaults to nil. 

zl:make-list always creates a cdr-coded list. See the section "Cdr-Coding". Exam- 
ples: 

(zl :make-l ist 3) => (nil nil nil) 

(zl :make-l ist 4 : initial-value 7) => (7 7 7 7) 

When zl:make-list was originally implemented, it took exactly two arguments: area 
and length. This obsolete form is still supported so that old programs will continue 
to work, but the new keyword-argument form is preferred. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses" and see CLtL 267. 



clos:make-load-form object Generic Function 

Provides a way to use an instance of a user-defined CLOS class (that is, an in- 
stance whose metaclass is clos:standard-class or clos:structure-class) as a con- 
stant in a program compiled with compile-file. Users can define a method for 
clos:make-load-form that describes how an equivalent object can be reconstructed 
when the compiled-code file is loaded. 

compile-file calls clos:make-load-form on an object needed at load time, if the 
object's metaclass is clos:standard-class. compile-file will call clos:make-load- 

form only once for any given object (compared with eq) within a single file. If 
clos:make-load-form is called and no user-defined method is applicable, an error 
is signaled. 



Page 1238 



The argument object is an object needed at load-time. 

clos:make-load-form returns two values. The first value, called the "creation 
form", is a form that, when evaluated at load time, should return an object that is 
equivalent to object. 

The second value, called the "initialization form", is a form that, when evaluated 
at load time, should perform further initialization of the object. The value returned 
by the initialization form is ignored. If the clos:make-load-form method returns 
only one value, the initialization form is nil, which has no effect. If the object used 
as the argument to clos:make-load-form appears as a constant in the initialization 
form, at load time it will be replaced by the equivalent object constructed by the 
creation form; this is how the further initialization gains access to the object. 

Both the creation form and the initialization form can contain references to in- 
stances of user-defined CLOS classes. However, there must not be any circular de- 
pendencies in creation forms. An example of a circular dependency is when the 
creation form for the object X contains a reference to the object Y, and the cre- 
ation form for the object Y contains a reference to the object X. A simpler example 
would be when the creation form for the object X contains a reference to X itself. 
Initialization forms are not subject to any restriction against circular dependencies, 
which is the entire reason that initialization forms exist. See the example of circu- 
lar data structures below. 

The creation form for an object is always evaluated before the initialization form 
for that object. When either the creation form or the initialization form references 
other objects of user-defined types that have not been referenced earlier in the 
compile-file, the compiler collects all of the creation and initialization forms. Each 
initialization form is evaluated as soon as possible after its creation form, as deter- 
mined by data flow. If the initialization form for an object does not reference any 
other objects of user-defined types that have not been referenced earlier in the 
compile-file, the initialization form is evaluated immediately after the creation 
form. If a creation or initialization form F references other objects of user-defined 
types that have not been referenced earlier in the compile-file, the creation forms 
for those other objects are evaluated before F, and the initialization forms for 
those other objects are also evaluated before F whenever they do not depend on 
the object created or initialized by F. Where the above rules do not uniquely deter- 
mine an order of evaluation, which of the possible orders of evaluation is chosen is 
unspecified. 

While these creation and initialization forms are being evaluated, the objects are 
possibly in an uninitialized state, analogous to the state of an object between the 
time it has been created and it has been processed fully by 
closrinitialize-instance. Programmers writing methods for clos:make-load-form 
must take care in manipulating objects not to depend on slots that have not yet 
been initialized. 

Examples: 



Page 1239 



; ; Example 1 

(def class my-class () 

((a :initarg :a : reader my-a) 

(b :initarg :b : reader my-b) 

(c : accessor my-c))) 

(defmethod shared-initial ize ((self my-class) ignore &rest ignore) 
(unless (slot-boundp self 'c) 

(setf (my-c self) (some-computation (my-a self) (my-b self))))) 

(defmethod make-load-form ((self my-class)) 
1 (make-instance ', (class-name (class-of self)) 

:a ' , (my-a self) :b ' , (my-b self))) 

In this example, an equivalent instance of my-class is reconstructed by using the 
values of two of its slots. The value of the third slot is derived from those two 
values. 

Another way to write the last form in the above example is to use clos:make-load- 
form-saving-slots: 

(defmethod make-load-form ((self my-class)) 
(make-load-form-saving-slots self '(a b))) 

; ; Example 2 

(def class my-frob () 

((name :initarg :name : reader my-name))) 
(defmethod make-load-form ((self my-frob)) 

1 (f ind-my-f rob ', (my-name self) : if-does-not-exist :create)) 

In this example, instances of my-frob are "interned" in some way. An equivalent 
instance is reconstructed by using the value of the name slot as a key for search- 
ing existing objects. In this case the programmer has chosen to create a new ob- 
ject if no existing object is found; an alternative would be to signal an error in 
that case. 

; ; Example 3 

(defclass tree-with-parent () 

((parent : accessor tree-parent) 
(children :initarg :children))) 
(defmethod make-load-form ((x tree-with-parent)) 
(values 

; ; creation form 

1 (make-instance ', (class-of x) 

:children ', (slot-value x 'children)) 
;; initialization form 
1 (setf (tree-parent ',x) ', (slot-value x 'parent)))) 

In this example, the data structure to be dumped is circular, because each parent 
has a list of its children and each child has a reference back to its parent. Sup- 
pose clos:make-load-form is called on one object in such a structure. The creation 
form creates an equivalent object and fills in the children slot, which forces ere- 



Page 1240 



ation of equivalent objects for all of its children, grandchildren, and so on. At this 
point none of the parent slots have been filled in. The initialization form fills in 
the parent slot, which forces creation of an equivalent object for the parent if it 
was not already created. Thus the entire tree is recreated at load time. At compile 
time, clos:make-load-form is called once for each object in the tree. All the cre- 
ation forms are evaluated, in unspecified order, and then all of the initialization 
forms are evaluated, also in unspecified order. 



clos:make-load-form-saving-slots object &optional save-slots Function 

Used in the bodies of methods for clos:make-load-form. The argument object is an 
object needed at load-time. The argument save-slots is a list of the names of the 
slots to preserve; it defaults to all of the local slots. 

clos:make-load-form-saving-slots returns forms that construct an equivalent ob- 
ject using closrmake-instance and setf of clos:slot-value for slots with values, or 
closrslot-makunbound for slots without values, or other functions of equivalent 
effect. 

clos:make-load-form-saving-slots returns two values, thus it can deal with circu- 
lar structures. clos:make-load-form-saving-slots works for instances of user- 
defined classes; that is, instances whose metaclass is clos:standard-class or 
clos:structure-class. 

See the generic function clos:make-load-form. 



closrmake-method form Macro 

A list such as (#:make-method form) can be used instead of a method object as 
the first subform of closrcall-method or as an element of the second subform of 
closrcall-method. 

form Specifies a method object whose method function has a body 

that is the given form. Note that form is not evaluated. 



make-package name &key .-nicknames .-prefix-name :use .shadow .-export .-import 
-.shadowing-import :import-from -.relative-names :relative-names-for-me .size .-external- 
only :new-symbol-function :hash-inherited-symbols invisible -.colon-mode iprefix- 
intern-function .-include 

Function 

Makes a new package and returns it. make-package is the primitive subroutine 
called by defpackage. An error is signalled if the package name or nickname con- 
flicts with an existing package, make-package takes the same arguments as 
defpackage except that standard &key syntax is used, and there is one additional 
keyword, rinvisible. 



Page 1241 



When an argument is called a name, it can be either a symbol or a string. When 
an argument is called a package, it can be the name of the package as a symbol or 
a string, or the package itself. 

The keyword arguments are: 

ruse '(package package...) 

External symbols and relative name mappings of the specified packages are 
inherited. If only a single package is to be used, the name rather than a 
list of the name can be passed. If no package is to be used, specify nil. The 
default value for ruse is cl. 

(rnicknames name name...) for defpackage 
rnicknames '(name name...) for make-package 

The package is given these nicknames, in addition to its primary name. 

Compatibility Note: Symbolics Common Lisp under Genera provides additional 
functionality with these keywords, which are extensions to Common Lisp: 

(rprefix-name name) for defpackage 
rprefix-name name for make-package 

This name is used when printing a qualified name for a symbol in this 
package. You should make the specified name one of the nicknames of the 
package or its primary name. If you do not specify rprefix-name, it defaults 
to the shortest of the package's names (the primary name plus the nick- 
names). 

rinvisible boolean 

If true, the package is not entered into the system's table of packages, and 
therefore cannot be referenced via a qualified name. This is useful if you 
simply want a package to use as a data structure, rather than as the pack- 
age in which to write a program. 

(rshadow name name...) for defpackage 
rshadow '(name name...) for make-package 

Symbols with the specified names are created in this package and declared 
to be shadowing. 

(rexport name name...) for defpackage 
rexport '(name name...) for make-package 

Symbols with the specified names are created in this package, or inherited 
from the packages it uses, and declared to be external. 

(rimport symbol symbol...) for defpackage 
rimport '(name name...) for make-package 

The specified symbols are imported into the package. Note that unlike 
rexport, rimport requires symbols, not names; it matters in which package 
this argument is read. 

(rshadowing-import symbol symbol...) for defpackage 



Page 1242 



rshadowing-import '(symbol symbol...) for make-package 

The same as rimport but no name conflicts are possible; the symbols are 
declared to be shadowing. 

(:import-from package name name...) for defpackage 
:import-from '(package name name...) for make-package 

The specified symbols are imported into the package. The symbols to be im- 
ported are obtained by looking up each name in package. 
(defpackage only) This option exists primarily for system bootstrapping, 
since the same thing can normally be done by rimport. The difference be- 
tween rimport and rimport-from can be visible if the file containing a 
defpackage is compiled; when rimport is used the symbols are looked up at 
compile time, but when rimport-from is used the symbols are looked up at 
load time. If the package structure has been changed between the time the 
file was compiled and the time it is loaded, there might be a difference. 

(rrelative-names (name package) (name package)...) - defpackage 

rrelative-names '((name package) ...) - make-package 

Declares relative names by which this package can refer to other packages. 
The package being created cannot be one of the packages, since it has not 
been created yet. For example, to be able to refer to symbols in the 
common-lisp package print with the prefix lispr instead of clr when they 
need a package prefix (for instance, when they are shadowed), you would 
use rrelative-names like this: 

(defpackage my-package (:use cl) 

(: shadow error) 

(: relative-names (lisp common-lisp))) 

(let ((xpackagex (find-package 'my-package))) 
(print (list 'my-package: :error 'cl:error))) 

(rrelative-names-for-me (package name) ...) for defpackage 
rrelative-names-for-me '((package name) ...) for make-package 

Declares relative names by which other packages can refer to this package. 
(defpackage only) It is valid to use the name of the package being created 
as a package here; this is useful when a package has a relative name for 
itself. 

(rsize number) for defpackage 
rsize number for make-package 

The number of symbols expected in the package. This controls the initial 
size of the package's hash table. You can make the rsize specification an 
underestimate; the hash table is expanded as necessary. 

(rhash-inherited-symbols boolean) for defpackage 
rhash-inherited-symbols boolean for make-package 

If true, inherited symbols are entered into the package's hash table to 
speed up symbol lookup. If false (the default), looking up a symbol in this 
package searches the hash table of each package it uses. 



Page 1243 



(:external-only boolean) for defpackage 
:external-only boolean for make-package 

If true, all symbols in this package are external and the package is locked. 
This feature is only used to simulate the old package system that was used 
before Release 5.0. See the section "External-only Packages and Locking". 

(rinclude package package...) for defpackage 
rinclude '(package package...) for make-package 

Any package that uses this package also uses the specified packages. Note 
that if the rinclude list is changed, the change is not propagated to users 
of this package. This feature is used only to simulate the old package sys- 
tem that was used before Release 5.0. 

(:new-symbol-function function) for defpackage 
:new-symbol-function function for make-package 

function is called when a new symbol is to be made present in the package. 
The default is si:pkg-new-symbol unless :external-only is specified. Do not 
specify this option unless you understand the internal details of the package 
system. 

(:colon-mode mode) for defpackage 
:colon-mode mode for make-package 

If mode is rexternal, qualified names mentioning this package behave dif- 
ferently depending on whether ":" or "::" is used, as in Common Lisp. ":" 
names access only external symbols. If mode is rinternal, ":" names access 
all symbols, rexternal is the default. See the section "Specifying Internal 
and External Symbols in Packages". 

(:prefix-intern-f unction function) for defpackage 
rprefix-intern-function function for make-package 

The function to call to convert a qualified name referencing this package 
with ":" (rather than "::") to a symbol. The default is intern unless (rcolon- 
mode rexternal) is specified. Do not specify this option unless you under- 
stand the internal details of the package system. 



make-plane rank &key (:type 'sysrart-qj -.default-value (-.extension 32) -.initial- 
dimensions -.initial-origins Function 

Creates and returns a plane, rank is the number of dimensions, options is a list of 
alternating keyword symbols and values. The allowed keywords are: 

rtype The array type symbol (for example, sys:art-lb) specifying the type of the 
array out of which the plane is made. 

: default- value 

The default component value. 



Page 1244 



rextension 

The amount by which to extend the plane. See the section "Planes". 

rinitial-dimensions 

A list of dimensions for the initial creation of the plane. You might want to 
use this option to create a plane whose first dimension is a multiple of 32, 
so you can use bitblt on it. The default is 1 in each dimension. 

rinitial-origins 

A list of origins for the initial creation of the plane. The default is all zero. 

Example: 

(make-plane 2 :type sys:art-4b : default-value 3) 
creates a two-dimensional plane of type sys:art-4b, with default value 3. 
For a table of related items, see the section "Operations on Planes". 

make-random-state &optional state Function 

Returns a new object of type random-state, which the function random can use 
as its state argument. 

If state is nil or omitted, make-random-state returns a copy of the current ran- 
dom-number state object (the value of variable *random-state*). 

If state is a state object, a copy of that state object is returned. 

If state is t, the function returns a new state object that has been "randomly" ini- 
tialized. 

Examples: 

(setq x (make-random-state)) => ft. (RANDOM-STATE 71 1695406379...) 

;;; the value of x is now a random state 

(setq copy-x (make-random-state x)) => ft. (RANDOM-STATE 71...) 

;;; this makes a copy of random state x 

;;; a way to get reproducibly random numbers 

(equal p (make-random-state t) xrandom-statex) => nil 

For a table of related items, see the section "Random Number Functions". 



make-raster-array width height &key (: element-type t) .-initial-element .-initial- 
contents .-adjustable .-fill-pointer :displaced-to :displaced-index-offset idisplaced- 
conformally -.area -.leader-list -.leader-length mamed-structure-symbol Function 

Makes rasters; this should be used instead of make-array when making arrays 
that are rasters, make-raster-array is similar to make-array, but make-raster- 
array takes width and height as separate arguments instead of taking a single di- 
mensions argument. If the raster is to be used with bitblt, the width times the 
number of bits per array element must be a multiple of 32. 



Page 1245 



The make-array-options are the options that can be given to make-array. For in- 
formation on those options: See the section "Keyword Options for make-array". 

When you cannot use make-raster-array, for example from the :make-array op- 
tion to defstruct contructors, you should use raster-width-and-height-to-make- 
array-dimensions instead. 

For a table of related items: See the section "Operations on Rasters". 



zlrmake-raster-array width height &rest make-array-options Function 

This function is provided for compatibility with previous releases. Use the Common 
Lisp function, make-raster-array. 



make-sequence type size &key .-initial-element :area 

Function 

Returns a sequence of type type and of length size, each of whose elements has 
been initialized to the value of the rinitial-element argument (or nil if none is 
specified). If rinitial-element is specified, the value must be an object that can be 
an element of a sequence of type type. For example: 

(make-sequence '(vector double-float) 5 : initial -element 1d0) 
=> #(1.0d0 1.0d0 1.0d0 1.0d0 1.0d0) 

(make-sequence 'list 4 : initial-element 'a) => (a a a a) 

(make-sequence 'string 4 : initial-element #\a) => "aaaa" 

If rinitial-element is a fat character, under Genera, make-sequence makes a fat 
string (a string of element type character). 

The keyword rarea is the number of the area in which to create the new alist. 
(Areas are an advanced feature of storage management.) rarea is a Symbolics ex- 
tension to Common Lisp, and is not supported in CLOE. See the section "Areas". 
See the function vector. See the function make-list. 

For a table of related items: See the section "Sequence Construction and Access" 



make-string size &key .-initial-element .-element-type -.area Function 

Returns a simple string of length size. It constructs a one-dimensional array with- 
out fill pointer or displacement, to hold elements of type character, or any of its 
subtypes, that is, string-char, or standard-char. Depending on their character 
type, Genera strings created with make-string can therefore be either fat or thin. 
When using CLOE, strings made with make-string always have elements of type 
string-char. 

The ability to create fat as well as thin strings represents an extension of the 
make-string function as presented in Guy L. Steele's Common Lisp: the Language. 



Page 1246 



The optional keywords are as follows: 



rinitial-element 



:element-type 



:area 



Each element of the new array is initialized to the character 
specified by this keyword; this character must correspond to 
the type specified by :element-type, if any. If no initial ele- 
ment is specified, array elements are initialized to characters 
with a char-code of 0, whose type corresponds to the type 
specified by :element-type; if :element-type is also unspeci- 
fied, make-string builds a thin string. 

Specifies the type of characters in the string and if you are 
using Genera, must be of type character, or any of its sub- 
types. If this keyword is left unspecified, the string type cor- 
responds to the type of the character specified in rinitial- 
element. If both keywords are omitted, make-string builds a 
thin string. :element-type is a Symbolics extension to Com- 
mon Lisp, and not available when using CLOE. 

Specifies the area in which to create the array, rarea should 
be an integer or nil to mean the default area, rarea is a 
Symbolics extension to Common Lisp, and not available under 
CLOE. 



The examples below show the interaction of the keywords rinitial-element and 
relement-type. 

Since make-string only lets you build simple character arrays, you must use the 
array-specific function make-array to build more complex character arrays. 

Examples: 

; rinitial-element and relement-type are omitted. String is thin, 
(string-char-p (char (make-string 5) 1)) => T 

; rinitial-element and relement-type specify a thin string, 
(string-char-p (char (make-string 5 : initial-element #\C 

:element-type 'string-char) 0)) => T 

; rinitial-element and relement-type specify a fat string, 
(string-fat-p (make-string 5 : initial-element #\hyper-C 

: element-type 'character)) => T 

; relement-type is omitted, and rinitial-element 

; is a standard character. String is thin. 

(string-char-p (char (make-string 5 : initial-element #\a) 2)) => T 



; relement-type is omitted, and rinitial-element 

; is a fat character. String is fat. 

(string-fat-p (make-string 3 : initial-element #\hyper-super-a)) => T 



Page 1247 



; rinitial-element is omitted and 

; :element-type is a subtype of character. String is thin. 

(string-fat-p (make-string 4 :element-type 'string-char)) => NIL 

; rinitial-element is omitted and 

; :element-type is of type character. String is fat. 

(string-fat-p (make-string 4 :element-type 'character)) => T 

(make-array 5 :element-type 'string-char) => "DDDDD" 
;returns a simple, thin string 

(make-array 3 : element-type 'character : initial -element #\hyper-super-q) 
=> "<H-S-QxH-S-Q-xH-S-Q>" ; returns a fat, simple string 

(make-string 4 :area working-storage-area) => "DDDD" 

Under CLOE, make-string always creates a simple string. If an adjustable string 
or a string with a fill-pointer is required, use make-array instead of make-string. 
The following call to make-array creates a non-simple string. 

(setq str (make-array 10 

:element-type 'string-char 
: f il 1-pointer 
: adjustable t)) 



(push #\a str) 
(push #\b str) 
(push #\c str) 

(char str 2) => #\c 
For a table of related items: See the section "String Construction" 

make-string-input-stream string &optional (start 0) end 



Function 



Returns an input stream. The input stream will supply, in order, the characters in 
the substring of string delimited by start and end. After the last character has 
been supplied, the stream will then be at end-of-file. 

(make-string- input-stream "Hel lo") 

=> #<LEXICAL-CLOSURE CLI :: STRING-INPUT-STREAM 10223204> 



(make-string-input-stream "Hello" 1 3) 

=> #<LEXICAL-CLOSURE CLI :: STRING-INPUT-STREAM 10224324> 



Page 1248 



(defvar input-string " foo bar baz") 
(let ((my-stream 

(make-stri ng-i nput-stream 
input-string 

(position-if #'alphanumericp input-string)))) 
(read-char my-stream)) 

=> ft\f 
Often it is preferable to use with-input-from-string. 

make-string-output-stream Function 

Returns an output stream that will accumulate all string output given it for the 
benefit of the function get-output-stream-string. 

(setq stream (make-string-output-stream)) 

=> #<LEXICAL-CLOSURE CLI :: STRING-OUTPUT-STREAM 44310040> 

(setq output-string 'hello) => HELLO 

(write output-string :stream stream) => HELLO 

(get-output-stream-string stream) => "HELLO" 

(defvar xheadingx '("Name " "Rank " "Serial-number ")) 

(let ((my-stream (make-string-output-stream)) 
(1 ist-of-strings xheadingx)) 
(dolist (str 1 ist-of-strings) 

(princ str my-stream)) 
(get-output-stream-stri ng my-stream) ) 

=> "Name Rank Serial-number " 
Often it is more convenient to use with-output-to-string. 

make-symbol print-name &optional permanent-p Function 

Creates a new uninterned symbol whose print-name is the string print-name. The 
value and function bindings are unbound and the property list is empty. 

Symbolics Common Lisp provides the optional argument permanent-p. If 
permanent-p is specified, it is assumed that the symbol is going to be interned and 
probably kept around forever; in this case it and its print-name are put in the 
proper areas. If permanent-p is nil (the default), the symbol goes in the default 
area and print-name is not copied, permanent-p is mostly for the use of intern it- 
self and might not work in other implementations of Common Lisp. 



Examples: 



Page 1249 



(make-symbol "F00") => F00 
(make-symbol "Foo") => I Fool 

Note that the symbol is not interned; it is simply created and returned. 

If a symbol has lowercase characters in its print-name, the printer quotes the 
name using slashes or vertical bars. The vertical bars inhibit the Lisp reader's 
normal action, which is to convert a symbol to uppercase upon reading it. See the 
section "What the Printer Produces". 

Example: 

(setq a (make-symbol "Hello")) ; => |Hello| 

(princ a) ; prints out Hello 

See the section "Functions for Creating Symbols". 



zl:make-syn-stream symbol Function 

Creates and returns a "synonym stream" (syn for short), symbol can be either a 
symbol or a locative. 

If symbol is a symbol, the synonym stream is actually an uninterned symbol named 
#:sj7n6oZ-syn-stream. This generated symbol has a property that declares it to be a 
legitimate stream. This symbol is the value of symbol's sirsyn-stream property, 
and its function definition is forwarded to the value cell of symbol using a sysrdtp- 
external-value-cell-pointer. Any operations sent to this stream are redirected to 
the stream that is the value of symbol. 

If symbol is a locative, the synonym stream is an uninterned symbol named #:syn- 
stream. This generated symbol has a property that declares it to be a legitimate 
stream. The function definition of this symbol is forwarded to the cell designated 
by symbol. Any operations sent to this stream are redirected to the stream that is 
the contents of the cell to which symbol points. 

Synonym streams should not be passed between processes, since the streams to 
which they redirect operations are specific to a process. 



make-synonym-stream stream-symbol Function 

Creates and returns a new stream that reads or writes indirectly to the stream de- 
noted by stream-symbol. If the dynamic variable stream-symbol is rebound to a new 
stream, the operations of the synonym stream are redirected to the newly bound 
stream. 

Under CLOE, the following streams are initially all bound to synonym-streams 
which do input or output via *terminal-io*, *standard-input*, *standard-output*, 
*error-output*, *tr ace-output*, *query-io*, and *debug-io*. 

Under CLOE-Runtime, in the following example, my-output-stream is bound to a 
synonym stream using the variable *file-stream*. This variable is initially bound 
to *standard-output*. As the value of *file-stream* changes, the output of the 
synonym stream is directed to the stream currently the value of *file-stream*. 



Page 1250 



(defvar xf ile-streamx xstandard-outputx) 
(setq my-output-stream 

(make-synonym-stream ' xf i 1 e-streamx) ) 

(with-open-f ile (xf ile-streamx xout-f ile-name1x :di rection :output) 
(process data) 
(format my-output-stream stuff)) 

(setq xf ile-streamx xstandard-outputx) 
(format my-output-stream more-stuff) 

(with-open-f ile (xf ile-streamx xout-f ile-name2x :direction :output) 
(process data) 
(format my-output-stream other-stuff)) 



make-two-way-stream input-stream output-stream Function 

Returns a bidirectional stream that gets its input from input-stream and sends its 
output to output-stream. 

(with-open-stream (streaml xstream-namelx 
:direction :input 
: element-type 'character) 
(with-open-stream (stream2 xstream-name2x 
:direction :output 
: element-type 'character) 
(let ((input '()) 

(two-way (make-two-way-stream streaml stream2))) 
(loop 

(setq input (read-char two-way nil :eof)) 
(unless (and input (not (eq input :eof))) 

(return t)) 
(write-char input two-way))))) 



zhmaknam charl Function 

Returns an uninterned symbol whose print-name is a string made up of the char- 
acters in charl. This function is provided mainly for Maclisp compatibility. 

Examples: 

(zl:maknam '(a b #\0 d)) => #:AB0D 
(zl:maknam '(1 2 #\h "b")) => #:|iahb| 



makunbound symbol Function 

Causes symbol to become unbound, and returns its argument. Example: 



Page 1251 



(setq a 1) 

a => 1 

(makunbound 'a) 

a => causes an error. 

Other examples: 

(defvar xalarmsx) 
(boundp 'xalarmsx) => nil 
(setq xalarmsx 20) 
(boundp 'xalarmsx) => t 
(makunbound 'xalarmsx) 
(boundp 'xalarmsx) => nil 

See the section "Functions Relating to the Value of a Symbol". 

makunbound-globally var Function 

Works like makunbound but sets the global value regardless of any bindings cur- 
rently in effect. 

makunbound-globally operates on the global value of a special variable; it bypass- 
es any bindings of the variable in the current stack group. It resides in the global 
package. 

makunbound-globally does not work on local variables. See the section "Functions 
Relating to the Value of a Symbol". 

makunbound-in-closure closure symbol Function 

Makes symbol be unbound in the environment of closure; that is, it does what 
makunbound would do if you restored the value cells known about by closure. If 
symbol is not closed over by closure, this is just like makunbound. See the section 
"Dynamic Closure-Manipulating Functions". 



map 



result-type function sequence &rest more-sequences Function 

Applies function to sequences, and returns a new sequence such that element j of 
the new sequence is the result of applying function to element j of each of the ar- 
gument sequences. The returned sequence is as long as the shortest of the input 
sequences, function must take at least as many arguments as there are sequences 
provided, and at least one sequence must be provided. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(map 'list #'- '(4 3 2 1) '(321 0)) => (1 1 1 1) 

(map 'string ft' (lambda (x) (if (oddp x) #\1 #\0)) '(123 4)) => 
"1010" 



Page 1252 



If function has side effects, it can count on being called first on all of the ele- 
ments with index 0, then on all of those numbered 1, and so on. 

The type of the result sequence is specified by the argument result-type (which 
must be a subtype of the type sequence), as for the function coerce. In addition, 
you can specify nil for the result type, meaning that no result sequence is to be 
produced. In this case function is invoked only for effect, and map returns nil. 
This gives an effect similar to mapc. 

In the following example, map is used to define a function which works like 
pairlis, but takes vectors as input. 

(defun make-al ist-f rom-vectors (vectorl vector2) 
(map 'list #'cons vectorl vector2)) 

(make-al ist-f rom-vectors '#(first second third) '#(1 2 3)) 

=> ((FIRST . 1) (SECOND . 2) (THIRD . 3)) 
For a table of related items: See the section "Mapping Functions". 
For a table of related items: See the section "Mapping Sequences". 

zhmap fen list &rest more-lists Function 

The Common Lisp function, mapl, is preferred. 

Applies fen to list and to successive sublists of that list. If all the lists are not of 
the same length, the iteration terminates when the shortest list runs out, and ex- 
cess sublists of it are ignored. 

zhmap works like maplist, except that it does not construct a list to return. Use 
zhmap when the fen is being called merely for its side effects, rather than its re- 
turned values. 

Examples: 

(zl:map tf'equal '(2 3 4) '(2 3 4)) => (2 3 4) 

(zl :map ft' (lambda (x y) (if (equal x y)(princ "equal "))) 

'(2 3 4) '(2 3 4)) 
=> equal equal equal 
(2 3 4) 

(zl :map ft' (lambda (x) (if (member (car x) (cdr x)) nil 

(princ (car x)) (princ " "))) 
'(a b a c b)) => A C B (A B A C B) 

For a table of related items: See the section "Mapping Functions". 

For a table of related items: See the section "Mapping Sequences". 



:map-hash function &rest args Message 



Page 1253 



For each entry in the hash table, calls function on the key of the entry and the 
value of the entry. If args are supplied, they are passed along to function following 
the value of the entry argument. This message is obsolete; use maphash instead. 



map-into result-sequence function sequence &rest more-sequences Function 

Destructively modifies the result-sequence to contain the results of applying func- 
tion to each element in the argument sequences in turn. The modified result- 
sequence is returned. 

map-into differs from map in that it modifies an existing sequence rather than 
creating a new one. 

The arguments result-sequence and sequences can be either a list or a vector (one- 
dimensional array). Note that nil is considered to be a sequence, of length zero. 

function must take at least as many arguments as there are sequences provided, 
and at least one sequence must be provided. 

For example: 

(setf n-list (list "12345")) 
=> ("12345") 

(map-into n-list #'parse-integer n-list) 
=> (12345) 

If function has side effects, it can count on being called first on all of the ele- 
ments with index 0, then on all of those numbered 1, and so on. 

The function is applied to the minimum of the length of result-sequence and the 
shortest sequence, and if the result is longer than the shortest sequence, the re- 
maining elements are not changed. 

For tables of related items: 

See the section "Mapping Functions". 
See the section "Mapping Sequences". 



zhmapatoms function &optional (pkg *package*J (inherited-p t) 

Function 

Applies function to each of the symbols in package, function should be a function of 
one argument. If inherited-p is t, this is all symbols accessible to package, includ- 
ing symbols it inherits from other packages. If inherited-p is nil, function only sees 
the symbols that are directly present in package. 

Note that when inherited-p is t symbols that are shadowed but otherwise would 
have been inherited are seen; this slight blemish is for the sake of efficiency. If 
this is a problem, function can try zhintern in package on each symbol it gets, and 
ignore the symbol if it is not eq to the result of zhintern; this measure is rarely 
needed. 



Page 1254 



zl:mapatoms-all function Function 

Applies function to all of the symbols in all of the packages in existence, except for 
invisible packages, function should be a function of one argument. Note that sym- 
bols that are present in more than one package are seen more than once. 

Example: 

(zl :mapatoms-al 1 
(function 
(lambda (x) 

(and (alphalessp 'z x) 
(print x))))) 



mapc fen list &rest more-lists Function 

Like mapcar, except that it does not return any useful value. 

mapc applies fen to successive elements of the argument lists. If the lists are not 
of the same length, the iteration terminates when the shortest list runs out. 

fen must take take as many arguments as there are lists. 

mapc is used when fen is being called merely for its side effects, rather than its 
returned values. 

Examples: 

(mapc tf'set '(ABC) '(11 22 33)) 
=> (A B C) 

(mapc ft' (lambda (x y) (if (= (+ x y) 3) (princ "three "))) 

'(1 2 3) '(2 1 3)) 
=> three three (1 2 3) 

(mapc ft' (lambda (x) (setf (get x 'color) t)) '(red blue green yellow)) 

(get 'red 'color) => T 
For a table of related items: See the section "Mapping Functions". 



mapcan fen list &rest more-lists Function 

Applies fen to list and to successive elements of that list. This function is like 
mapcar, except that it combines the results of the function using nconc instead of 
list. 

fen must take as many arguments as there are lists. 

Examples: 



Page 1255 



(mapcan ft' (lambda (x) (if (equal x 3) nil (princ x))) '(123 4)) 
=> 124NIL 

(mapcan #' (lambda (x) (and (integerp x) (list x))) 

'(1 2.3 3. 4 'd 0)) 
=> (1 3 4 0) 

If mapcar were used for the above example, the result would be as follows: 

(mapcar ft' (lambda (x) (if (equal x 3) nil (princ x))) '(123 4)) 
=> 124(1 2 NIL 4) 

(mapcar ft' (lambda (x) (and (integerp x) (list x))) 

'(1 2.3 3. 4 'd 0)) => ((1) NIL (3) (4) NIL (0)) 

(mapcan ft' (lambda (x) (if (integerp x) (cons x nil)) (list 'a 3 'b 4 2)) 

=> (3 4 2) 
For a table of related items: See the section "Mapping Functions". 

mapcar fen list &rest more-lists Function 

fen is a function that takes as many arguments as there are lists in the call to 
mapcar. For example, since expt takes two arguments the following use of 
mapcar is incorrect: 

Wrong: 

(mapcar tf'expt '(12345) ' (43 2 1 4 2) '(23232)) 
Right: 

(mapcar tf'expt '(12345) '(43 2 1 4 2)) 

In the correct example, mapcar calls expt repeatedly, each time using successive 
elements of the first list as its first argument and successive elements of the sec- 
ond list as its second argument. Thus, mapcar calls expt with the arguments 1 
and 43, 2 and 2, 3 and 1, 4 and 4, and 5 and 2 and returns a list of the five re- 
sults. 

Examples: 

(mapcar ft'- ' (3 4 2 5) ' (1 1 2 3)) => (2 3 2) 

(mapcar #'='(12 3 4) '(123 8)) => (T T T NIL) 

(mapcar ft' (lambda (x) (if (numberp x) 1)) '(123 'k "hi" 'fly)) 
=> (0 1 1 1) 

(mapcar tf'list '('hot 'cat 'sam 'new) '('dog 'hat 'man 'york)) 
=> (('HOT 'DOG) ('CAT 'HAT) ('SAM 'MAN) ('NEW 'YORK)) 



Page 1256 



(mapcar #' + '(1 2 3 4) (circular-list 1)) => (2 3 4 5) 

(mapcar #'='(1233 45) '(2 2)) => (NIL T) 

(mapcar #'1+ '(5 25 33)) => (6 26 34) 
For a table of related items: See the section "Mapping Functions". 

mapcon fen list &rest more-lists 

Function 

Applies fen to list and to successive sublists of that list rather than to successive 
elements. 

This function is like maplist, except that it combines the results of the function 
using nconc instead of list. 

fen must take as many arguments as there are lists. 

mapcon could have been defined by: 

(defun mapcon (f x y) 

(apply 'nconc (maplist f x y))) 

Of course, this definition is less general than the real one. 

Examples: 

(mapcon ft' (lambda (x y) (and (equal y x)(list x)) ) 

'('yo 'ho 'woo 'wa) '('hi 'ho 'woo 'wa)) 
=> (('HO 'WOO 'WA) ('WOO 'WA) ('WA)) 

If maplist were used for the above example the result would look as follows: 

(maplist ft' (lambda (x y) (and (equal y x)(list x)) ) 

'('yo 'ho 'woo 'wa) '('hi 'ho 'woo 'wa)) 
=> (NIL (('HO 'WOO 'WA)) (('WOO 'WA)) (('WA))) 

(mapcon ft' (lambda (x) (list (length x) x) (list 'a 'b 'c)) 
=> (3 (A B C) 2 (B C) 1 (C)) 

For a table of related items: See the section "Mapping Functions". 

maphash function table Function 

For each entry in table, calls function on the key of the entry and the value of the 
entry. If entries are added to or deleted from the hash table while a maphash is 
in progress, the results are unpredictable, with one exception: if the function calls 
remhash to remove the entry currently being processed by the function, or per- 
forms a setf of gethash on that entry to change the associated value, then those 
operations will have the intended effect. In the following example, maphash re- 
turns nil. 



Page 1257 



;; alter every entry in MY-HASH-TABLE, replacing the value with 
;; its square root. Entries with negative values are removed, 
(maphash #' (lambda (key val ) 
(if (minusp val) 

(remhash key my-hash-table) 

(setf (gethash key my-hash-table) 
(sqrt val)))) 

my-hash-table) 

The following example illustrates a maphash call that removes all entries whose 
keys equal their corresponding values. 

(maphash #' (lambda (key val) 

(if (eq key val) (remhash key 'my-hash-table))) 
'my-hash-table) 

For a table of related items: See the section "Table Functions". 



zhmaphash-equal function hash-table &rest args Function 

For each entry in hash-table, calls function on the key of the entry and the value 
of the entry. If args are supplied, they are passed along to function following the 
value of the entry. This message is obsolete; use maphash instead. 



mapl fen list &rest more-lists Function 

Applies fen to list and to successive sublists of that list. If all the lists are not of 
the same length the iteration terminates when the shortest list runs out and ex- 
cess sublists of it are ignored. 

mapl works like maplist, except that it does not accumulate the results of calling 
fen. Use mapl when fen is being called merely for its side effects, rather than its 
returned value. 

(mapl tf'print ' (a b c)) 
=> 

(A B C) 
(B C) 

(C) 

(A B C) 

For a table of related items: See the section "Mapping Functions". 



maplist fen list &rest more-lists Function 

Applies fen to list and to successive sublists of that list rather than to successive 
elements as does mapcar. It returns a list that accumulates the results of the suc- 
cessive calls to fen. 

fen must take as many arguments as there are lists. 



Page 1258 



Examples: 

(maplist tf'append '(abed) '(1 234)) 

=> ((A B C D 1 2 3 4) (B C D 2 3 4) (C D 3 4) (D 4)) 

(maplist ft' (lambda (a-list) (cons 'twiddle a-list)) 
' (blank dee dumb)) 
=> ((TWIDDLE BLANK DEE DUMB) (TWIDDLE DEE DUMB) (TWIDDLE DUMB)) 

(maplist tf'equal '("car" "house" "door" "barn") 

'('cat 'hat "door" "barn")) 
=> (NIL NIL T T) 

(maplist tf'length ' (a b c d)) => (4 3 2 1) 

(maplist ^'identity '(a b c)) => ((a b c) (b c) (c)) 
For a table of related items: See the section "Mapping Functions". 

mask-field bytespec integer Function 

Similar to ldb ("load byte"), but the specified byte of integer is returned as a num- 
ber in the position specified by bytespec in the returned word, instead of in position 
as with ldb. integer must be an integer. 

bytespec is built using function byte with bit size and position arguments. This 
function can be used with setf and a suitable integer to update the place. The re- 
sult of a deposit-field operation on the value is stored in the updated place. Ex- 
ample: 

(mask-field (byte 8 1) 257) => 256 

(mask-field (byte 6 3) #o4567) => #o560 

(setq place-numb #b100 new-byte #b1 00111) => 39 

(setf (mask-field (byte 8 3) place-numb) new-byte) => 39 

(format nil "~D #b~B" place-numb place-numb) => 36 #b100100 

For a table of related items: See the section "Summary of Byte Manipulation Func- 
tions". 



max number &rest numbers Function 

Returns the largest of its arguments. At least one argument is required. The argu- 
ments can be of any noncomplex numeric type. The result type is the type of the 
largest argument. An error is returned if any of the arguments are complex or not 
numbers. 

Example: 

(max 1 3 2) => 3 

(max 5.0 42 6.7 8 3.2 12) => 42 



Page 1259 



For a table of related items, see the section "Numeric Comparison Functions" 

maximize keyword for loop 
maximize expr {data-type} {into var} 



Computes the maximum of expr over all iterations, data-type defaults to number. 
Note that if the loop iterates zero times, or if conditionalization prevents the code 
of this clause from being executed, the result is meaningless. If loop can deter- 
mine that the arithmetic being performed is not contagious (by virtue of data-type 
being fixnum or flonum), it can choose to code this by doing an arithmetic com- 
parison rather than calling max. As with the sum clause, specifying data-type im- 
plies that both the result of the max operation and the value being maximized is 
of that type. When the epilogue of the loop is reached, var has been set to the ac- 
cumulated result and can be used by the epilogue code. 

It is safe to reference the values in var during the loop, but they should not be 
modified until the epilogue code for the loop is reached. 

Examples: 

(defun maxi (my-list) 
(loop for x from 

for item in my-1 ist 

maximize item into resultl 

finally (return resultl))) => MAXI 
(maxi '(1 2 4 5 8 7 6)) => 8 

Not only can there be multiple accumulations in a loop, but a single accumulation 
can come from multiple places within the same loop form, if the types of the col- 
lections are compatible, maximize and minimize are compatible. 

See the section "Accumulating Return Values for loop". 



zlrmem pred item list Function 

Returns nil if item is not one of the elements of list. Otherwise, it returns the 
sublist of list beginning with the first occurrence of item; that is, it returns the 
first cons of the list whose car is item. The comparison is made by pred. Because 
zlrmem returns nil if it does not find anything, and something non-nil if it finds 
something, it is often used as a predicate. 

zlrmem is the same as zlrmemq except that it takes a predicate of two arguments, 
which is used for the comparison instead of eq. (zlrmem 'eq a b) is the same as 
(zlrmemq a b). (zlrmem 'equal a b) is the same as (member a b). 

zlrmem is usually used with equality predicates other than eq and equal, such as 
=, char-equal or string-equal. It can also be used with noncommutative predi- 
cates. The predicate is called with item as its first argument and the element of 



Page 1260 



list as its second argument, so: 

(zl :mem #'< 4 list) 

finds the first element in list for which (< 4 x) is true; that is, it finds the first el- 
ement greater than 4. 

For a table of related items: See the section "Functions for Searching Lists". 

zkmemass pred item list Function 

Looks up item in the association list list. The value returned is the portion of the 
list beginning with the first pair whose car matches item, according to pred. Re- 
turns nil if none matches. 

(car (zkmemass x y z)) = (zkass x y z). 

See the function zlrmem. As with zlrmem, you can use noncommutative predicates; 
the first argument to the predicate is item and the second is the indicator of the 
element of list. 

For a table of related items: See the section "Functions that Operate on Associa- 
tion Lists". 



member &rest list Type Specifier 

Allows the definition of a data type consisting of objects that are elements of list. 
An object is of this type if it is eql to one of the objects specified in list. As a type 
specifier, member can only be used in list form. 

Examples: 

(typep 3 '(member 1 2 3)) => T 
(typep 'a '(member a b c)) => T 

(subtypep '(member one two three) '(member one two three four)) 
=> T and T 
(sys: type-argl ist 'member) => (&REST LIST) and T 

See the section "Data Types and Type Specifiers". See the section "Lists". 



member item list &key (:test #'eql) :test-not (:key #'identityj Function 

Searches list for an element that matches item according to the predicate supplied 
for :test. In no element matches item, nil is returned; otherwise the tail of list, be- 
ginning with the first element that satisfied the predicate, is returned. The key- 
words are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 



Page 1261 



:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

The list is searched on the top level only. For example: 

(member 'item '(a b c)) => NIL 

(member 'item '(a #\Space item 5/3)) => (ITEM 5/3) 

member can be used as a predicate, since the value it returns is eq to the portion 
of the list it matches. This implies that rplaca or rplacd can be used to alter the 
found list element, as long as a check is made first that member did not return 
nil. For example: 

(setq list '(loon eagle heron)) => (LOON EAGLE HERON) 

(if (member 'eagle list) 

(rplaca (member 'eagle list) 'hawk)) => (HAWK HERON) 

list => (LOON HAWK HERON) 

In the following example, member implements the Common Lisp function union: 

(defun my-union( listl list2 &key (test #'eql) 

(test-not nil) (key ^'identity) ) 
(let ((result list2) 
(element nil)) 
(if list2 

(dolist (element listl) 

(unless (member element list2 :test test 

: test-not test-not :key key) 
(setq result (cons element result)))) 
(setq result listl)) 
result)) 

For a table of related items: See the section "Functions for Searching Lists". 



zhmember item in-list Function 

Returns nil if item is not one of the elements of in-list. Otherwise, it returns the 
sublist of in-list that begins with the first occurrence of item; that is, it returns 
the first cons of the list whose car is item. The comparison is made by zhequal. 

zhmember could have been defined by: 

(defun zl :member (item list) 
(cond ((null list) nil) 

((equal item (car list)) list) 

(t (zl :member item (cdr list))) )) 



Page 1262 



For a table of related items: See the section "Functions for Searching Lists". 



member-if predicate list &key :key Function 

Searches for an element in list that satisfies predicate. If none is found, member-if 
returns nil; otherwise it returns the tail of list beginning with the first element 
that satisfied the predicate. The list is searched on the top level only, member-if 
is similar to member. For example: 

(member-if #'numberp '(a #\Space 5/3 item)) => (5/3 ITEM) 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

The following example defines a retrieval function thatsearches an association list. 
This function returns the tail of the list, beginning with the pair that matches the 
key. Non-public data is not retrieved when stored before the pair with the appro- 
priate key. 

(defun secure-retrieve( alist ) 

(member-if #' (lambda(x) (string= "NAME" x)) 
al ist :key #'car)) 
(setq jones 

'((SALARY . 23000) (NAME . "John Jones") 

(TITLE . "Account rep") (HIRE-DATE . 3-3-76))) 
(secure-retrieve jones) => 

((NAME . "John Jones") (TITLE . "Account rep") 
(HIRE-DATE . 3-3-76)) 

Note that the :key argument of #'car extracts the matching field designator from 
the a-list pair. 

For a table of related items: See the section "Functions for Searching Lists". 



member-if-not predicate list &key key Function 

Searches for the first element in list that does not satisfy predicate. If every ele- 
ment satisfies the predicate, member-if-not returns nil; otherwise it returns the 
tail of list, beginning with the first element that did not satisfy the predicate. The 
list is searched on the top level only, member-if-not is similar to member. For 
example: 

(member-if-not #'numberp '(4.0 #\Space 5/3 item)) => 
(tfXSpace 5/3 ITEM) 

(member-if-not tf'numberp '(5/3 4.0)) => NIL 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

The following example defines a retrieval function thatsearches an association list. 



Page 1263 



This function returns the tail of the list, beginning with the first pair that does 
not match a particular key. Non-public data is not retrieved when stored before 
the pair with the appropriate key. 

(defun secure-retrieve( alist ) 
(member-if-not 

#'(lambda(x)(or (string= "SALARY" x) 

(string= "RELIGION" x))) 
al ist :key #'car)) 
(setq jones 

'((SALARY . 23000) (NAME . "John Jones") 

(TITLE . "Account rep") (HIRE-DATE . 3-3-76))) 
(secure-retrieve jones) => 

((NAME . "John Jones") (TITLE . "Account rep") 
(HIRE-DATE . 3-3-76)) 

For a table of related items: See the section "Functions for Searching Lists". 



zlrmemq item in-list Function 

Returns nil if item is not one of the elements of in-list. Otherwise, it returns the 
sublist of in-list that begins with the first occurrence of item; that is, it returns 
the first cons of the list whose car is item. The comparison is made by eq. Be- 
cause zlrmemq returns nil if it does not find anything, and something non-nil if it 
finds something, it is often used as a predicate. Examples: 

(zl :memq 'a '(1 2 3 4)) => nil 

(zl :memq 'a ' (g (x a y) c a d e a f)) => (a d e a f) 

Note that the value returned by zlrmemq is eq to the portion of the list beginning 
with a. Thus you can use rplaca on the result of zlrmemq, if you first check to 
make sure zlrmemq did not return nil. Example: 

(let ((sublist (zl :memq x z))) ;search for x in the list z. 

(if (not (null sublist)) ;if it is found, 

(rplaca sublist y))) ;replace it with y. 

zlrmemq could have been defined by: 

(defun zl :memq (item list) 
(cond ((null list) nil) 

((eq item (car list)) list) 

(t (zl :memq item (cdr list))) )) 

zlrmemq is hand-coded in microcode and therefore especially fast. 

For a table of related items: See the section "Functions for Searching Lists". 

merge result-type sequencel sequence2 predicate &key key Function 

Destructively merges the sequences according to an order determined by predicate. 
The result is a sequence of type result-type, which must be a subtype of sequence, 
as for the function coerce. 



Page 1264 



Sequencel and sequence2 can be either a list or a vector (one-dimensional array). 
Note that nil is considered to be a sequence, of length zero. 

predicate should take two arguments and return a non-nil value if and only if the 
first argument is strictly less than the second (in some appropriate sense). If the 
first argument is greater than or equal to the second (the the appropriate sense), 
then predicate should return nil. 

The merge function determines the relationship between two elements by giving 
keys extracted from the elements to predicate. The :key function, when applied to 
an element, should return the key for that element. The :key function defaults to 
the identity function, thereby making the element itself be the key. 

The :key function should not have any side effects. A useful example of a :key 
function would be a component selector function for a defstruct structure, used to 
merge a sequence of structures. 

If the :key and predicate functions always return, the merging function will always 
terminate. The result of merging two sequences x and y is a new sequence z, such 
that the length of z is the sum of the lengths of x and y, and z contains all of the 
elements of x and y. If xl and x2 are two elements of x, and xl precedes x2 in x, 
then xl precedes x2 in z, and similarly for the elements of y. In short, z is an in- 
terleaving of x and y. 

Moreover, if x and y were correctly sorted according to predicate, then z will also 
be correctly sorted. For example: 

(merge 'list '(1 3 4 6 7) '(258) #'<) => (1 2 3 4 5 6 7 8) 

If x or y is not so sorted, then z will not be sorted, but will nevertheless be an in- 
terleaving of x and y. For example: 

(merge 'list '(3641 7) '(258) #'<) => (2 3 5 6 4 1 7 8) 

(setq a (vector 1 2 5) b (vector 2 3 4)) 

(merge 'list a b #'<) => (1 2 2 3 4 5) 

Note in the previous example that the input sequences are vectors, but merge pro- 
duces the requested list. In the following example, input sequences are of different 
types. This generally results in reduced efficiency. Also, the result is not complete- 
ly in order because the sequence c is not sorted according to #'<. 

(setq c (3 2 1) d #(1 2 4)) 
(merge c d #'<) =>'(1 2 3 2 1 4) 



items from c / 

In the previous example, the elements from c are the elements in positions 2 
through 4 in the merged list. 

The merging operation is guaranteed to be stable, that is, if two or more elements 
are considered equal by predicate, then the elements from sequencel will precede 



Page 1265 



those from sequence2 in the result. The predicate is assumed to consider two ele- 
ments from x and y to be equal if (funcall predicate x y) and 
(funcall predicate y x) are both false. For example: 

(merge 'string "BOY" "nosy" tf'char-lessp) => "BnOosYy" 

The result can not be "BnoOsYy", "BnOosyY", or "BnoOsyY", because the function 
char-lessp ignores case, and so considers the characters Y and y to be equal. 
Since Y and y are equal, the stability property then guarantees that the character 
from the first argument (Y) must precede the one from the second argument (y). 

For a table of related items: See the section "Sorting and Merging Sequences". 



clos:method-combination-error format-string &rest args Function 

Signals an error within method combination; it should be called only within the dy- 
namic extent of a method-combination function. 

format-string A control string that can be given to format. 

args Arguments required by the format-string. 



flavorrmethod-options function-spec Function 

Returns the (options...) portion of the function-spec, options is the options argument 
that was given in the defmethod form for this method, such as rbefore or rprogn. 
See the section "Function Specs for Flavor Functions". 

The (options... portion is the cdddr of the function-spec. Functions specs for meth- 
ods are in the form: 

(type generic flavor options...) 

type is typically flavorrmethod. 

This is useful in the bodies of define-method-combination forms. The definition 
of the :case method combination type provides a good example of the use of 
flavorrmethod-options. See the section "Examples of define-method-combination". 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



closrmethod-qualifiers method Generic Function 

Returns a list of the qualifiers of the method. 

method A method object. 



Page 1266 



mexp (repeat nil) (compile nil) (do-style-checking nil) (do-macro-expansion t) (do- 
named-constants nil) (do-inline-forms t) (do-optimizers nil) (do-constant-folding nil) 
(do-function-args nil) Function 

This special form goes into a loop in which it reads forms and sequentially ex- 
pands them, printing out the result of each expansion (using the grinder to im- 
prove readability). See the section "Functions for Formatting Lisp Code". It termi- 
nates when you press the END key. If you type in a form that is not a macro form, 
there are no expansions and so it does not type anything out, but just prompts you 
for another form. This allows you to see what your macros are expanding into, 
without actually evaluating the result of the expansion. 

For example: 

(mexp) 

Type End to stop expanding forms 

Macro form — > (loop named t until nil return 5) 
(ZL:L00P NAMED T UNTIL NI RETURN 5) -> 
(PROG T NIL 
SI:NEXT-L00P AND NIL 

(GO SI: END-LOOP)) 

(RETURN 5) 

(GO SI:NEXT-L00P) 
SI:END-L00P) 

Macro form — > (defparameter foo bar) — > 
(PROGN (EVAL-WHEN (COMPILE) 

(C0MPILER:SPECIAL-2 'FOO)) 
(EVAL-WHEN (LOAD EVAL) 

(SI:DEFC0NST-1 FOO BAR NIL))) 

See the section "Expanding Lisp Expressions in Zmacs". That section describes two 
editor commands that allow you to expand macros — c-sh-M and n-sh-M. There is 
also the Command Processor command, Show Expanded Lisp Code. See the docu- 
ment Genera User's Guide. 



min number &rest numbers Function 

Returns the smallest of its arguments. At least one argument is required. The ar- 
guments can be of any noncomplex numeric type. The result type is the type of 
the smallest argument. An error is returned if any of the arguments are complex 
or not numbers. 

Example: 

(min 1 3 2) => 1 

(min 5.0 42 6.7 8 3.2 12) => 3.2 

For a table of related items, see the section "Numeric Comparison Functions". 



Page 1267 



minimize keyword for loop 
minimize expr {data-type} {into var} 



Computes the minimum of expr over all iterations, data-type defaults to number. 
Note that if the loop iterates zero times, or if conditionalization prevents the code 
of this clause from being executed, the result is meaningless. If loop can deter- 
mine that the arithmetic being performed is not contagious (by virtue of data-type 
being fixnum or flonum), it can choose to code this by doing an arithmetic com- 
parison rather than calling min. As with the sum clause, specifying data-type im- 
plies that both the result of the min operation and the value being minimized is of 
that type. When the epilogue of the loop is reached, var has been set to the accu- 
mulated result and can be used by the epilogue code. 

It is safe to reference the values in var during the loop, they should not be modi- 
fied until the epilogue code for the loop is reached. 

Examples: 

(defun mini (my-list) 
(loop for x from 

for item in my-1 ist 

minimize item into resultl 

finally (return resultl))) => MINI 
(mini '(3456087)) => 

Not only can there be multiple accumulations in a loop, but a single accumulation 
can come from multiple places within the same loop form, if the types of the col- 
lections are compatible, minimize and maximize are compatible. 

See the section "Accumulating Return Values for loop". 



zhminus x Function 

Returns the negative of x. zhminus is similar to - used with one argument. 

Examples: 

(zl :minus 1) => -1 

(zl :minus -3.0) => 3.0 

For a table of related items, see the section "Arithmetic Functions". 

minusp number Function 

Returns t if its argument is a negative number, strictly less than zero. Otherwise 
it returns nil. If number is not a noncomplex number, minusp signals an error. 

Examples: 



Page 1268 



(minusp -5) => T 

(minusp 0) => NIL 

(minusp 0.0d0) => NIL 

(minusp -0.0) => NIL 

(minusp -0) => nil 

(minusp least-negative-single-float) => t 

(minusp least-positive-single-float) => nil 

For a table of related items, see the section "Numeric Property-checking Predi- 
cates". 



mismatch sequencel sequence2 &key :from-end (:test #'eql) :test-not :key Ostartl 0) 
(:start2 0) :endl :end2 Function 

Compares the specified subsequences of sequencel and sequence2 element-wise. If 
they are of equal length and match in every element, the result is nil. Otherwise, 
the result is a non-negative integer representing the index within sequencel of the 
leftmost position at which the two subsequences fail to match, or, if one subse- 
quence is shorter than and a matching prefix of the other, the result is the index 
relative to sequencel beyond the last position tested. 

For example: 

(mismatch '(loon heron stork) '(loon heron stork)) => NIL 

(mismatch '(hawk loon owl pelican) '(hawk loon eagle pelican)) => 2 

(mismatch '(12 3) ' (1 2 3 4 5)) => 3 

If the value of the :from-end keyword is non-nil, one plus the index of the right- 
most position in which the sequences differ is returned. In effect, the 
(sub)sequences are aligned at their right-hand ends and the last elements are 
compared, then the ones before, and so on. The index returned is again an index 
relative to sequencel. For example: 

(mismatch '(hawk loon owl pelican) '(hawk loon eagle pelican) 
:from-end t) => 3 

-.test specifies the test to be performed. An element of sequence satisfies the test if 
(funcall testfun item {keyfn x)) is true. Where testfun is the test function specified 
by :test, keyfn is the function specified by :key and x is an element of the sequence. 
The default test is eql. 

For example: 

(mismatch '(2 3 4) '(1 2 3) :test #'>) => NIL 

:test-not is similar to :test, except that the sense of the test is inverted. An ele- 
ment of sequence satisfies the test if (funcall testfun item {keyfn x)) is false. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 



Page 1269 



For example: 

(mismatch '((north 1) (south 2)) '((right 1)(left 2)) :key tf'second) 
=> NIL 

For a table of related items: See the section "Searching for Sequence Items". 

mod number divisor Function 

Divides number by divisor, converting the quotient into an integer and truncating 
the result toward negative infinity. Returns the remainder. This is the same as the 
second value of (floor number divisor). 

When there is no remainder, the returned value is 0. 

The arguments can be integers or floating-point numbers. 

Examples: 

(mod 3 2) => 1 

(mod -3 2) => 1 

(mod 3 -2) => -1 

(mod -3 -2) => -1 

(mod 4 -2) => 

(mod 3.8 2) => 1.8 

(mod -3.8 2) => 0.20000005 

Related Functions: 

floor 
rem 

For a table of related items, see the section "Arithmetic Functions". 

mod n Type Specifier 

Defines the set of non-negative integers less than n. This is equivalent to (integer 
n-1), or to (integer (n)). 

As a type specifier, mod can only be used in list form. 

Examples: 

(typep 3 ' (mod 4)) => T 
(typep 5 ' (mod 4)) => NIL 
(typep 4 ' (mod 4)) => NIL 
(subtypep 'bit '(mod 2)) => T and T 
(sys: type-argl ist 'mod) => (N) and T 

See the section "Data Types and Type Specifiers". For a discussion of the function 
mod: See the section "Numbers". 

:modify-hash key function &rest args Message 



Page 1270 



Combines the actions of :get-hash and :put-hash. It lets you both examine the val- 
ue for a particular key and change it. It is more efficient because it does the hash 
lookup once instead of twice. 

It finds value, the value associated with key, and key-exists-p, which indicates 
whether the key was in the table. It then calls function with key, value, 
key-exists-p, and other-args. If no value was associated with the key, then value is 
nil and key-exists-p is nil. It puts whatever value function returns into the hash 
table, associating it with key. 

(send new-corns ' :modify-hash k foo a b c) => 
(funcall foo k val key-exists-p a b c) 

This function is obsolete; use modify-hash instead. 

modify-hash table key function 

Function 

Combines the action of setf of gethash into one call to modify-hash. It lets you 
both examine the value of key and change it. It is more efficient because it does 
the lookup once instead of twice. 

Finds the value associated with key in table, then calls function with key, this val- 
ue, a flag indicating whether or not the value was found. Puts whatever is re- 
turned by this call to function into table, associating it with key. Returns the new 
value and the key of the entry. Note: The actual key stored in table is the one 
that is used on function, not the one you supply with key. 

For a table of related items: See the section "Table Functions". 



*modules* Variable 

This special variable has as its value a list of names of the modules that have 
been loaded into the lisp system. 

=> xmodulesx 

(TURBINE-PACKAGE GENERATOR-PACKAGE LISP) 



most-negative-double-float Constant 

The floating-point number in double-float format closest in value (but not equal to) 
negative infinity. 



most-negative-fixnum Constant 

The fixnum closest in value to negative infinity. 

most-negative-long-float Constant 



Page 1271 



The floating-point number in long-float format closest in value (but not equal to) 
negative infinity. In Symbolics Common Lisp this constant has the same value as 
most-negative-double-float. 



most-negative-short-float Constant 

The floating-point number in short-float format closest in value (but not equal to) 
negative infinity. In Symbolics Common Lisp this constant has the same value as 
most-negative-single-float. 



most-negative-single-float Constant 

The floating-point number in single-float format closest in value (but not equal to) 
negative infinity. 



most-positive-double-float Constant 

The floating-point number in double-float format which is closest in value (but not 
equal to) positive infinity. 



most-positive-fixnum Constant 

The value of most-positive-fixnum is that fixnum closest in value to positive in- 
finity. 



most-positive-long-float Constant 

The value of most-positive-long-float is that floating-point number in long-float 
format which is closest in value (but not equal to) positive infinity. In Symbolics 
Common Lisp this constant has the same value as most-positive-double-float. 



most-positive-short-float Constant 

The value of most-positive-short-float is that floating-point number in short-float 
format which is closest in value (but not equal to) positive infinity. In Symbolics 
Common Lisp this constant has the same value as most-positive-single-float. 



most-positive-single-float Constant 

The value of most-positive-single-float is that floating-point number in single-float 
format which is closest in value (but not equal to) positive infinity. 



mouse-char-p char Function 

Returns t if char is a mouse character, nil otherwise. 



Page 1272 



zhmultiple-value vars value Special Form 

Used for calling a function that is expected to return more than one value. This is 
the Zetalisp name for multiple-value-setq. See the section "Special Forms for Re- 
ceiving Multiple Values". 



multiple-value-bind vars value &body body &whole form &environment env 

Special Form 

Similar to multiple-value-setq, but locally binds the variables that receive the val- 
ues, rather than setting them, and has a body — a set of forms that are evaluated 
with these local bindings in effect. First form is evaluated. Then the variables are 
bound to the values returned by form. Then the body forms are evaluated sequen- 
tially, the bindings are undone, and the result of the last body form is returned. 

(let ((retl '()) 

(ret2 nil)) 
(multiple-value-setq (retl ret2) (subtypep type-1 type-2)) 
(if ret2 

(values retl ret2) 

(and (multiple-value-setq (retl ret2) 

(my-even-more-expensive-subtype type-1 type-2)) 
(if ret2 

(values retl ret2) 

(error "Could not determine if ~A is a subtype of ~A." type-1 type-2))))) 

See the section "Special Forms for Receiving Multiple Values". 

CLOE Note: This is a macro in CLOE. 



multiple-value-call 

function &rest args Special Form 

First evaluates function to obtain a function. It then evaluates all the forms in 
args, gathering together all the values of the forms (not just one value from each). 
It gives these values as arguments to the function and returns whatever the func- 
tion returns. 

For example, suppose the function frob returns the first two elements of a list of 
numbers: 

(multiple-value-call #'+ (frob '(1 2 3)) (frob '(4 5 6))) 
<=> (+1 2 4 5) => 12. 

(defmacro get-values (form) 

1 (mul tiple-value-cal 1 #' (lambda (&rest args) (format nil "~{~a , }" args)) 

, form)) 

(get-values (get-decoded-time)) => "40, 58, 8, 25, 8, 1984, 1, T, 5" 



Page 1273 



(get-values (floor 9 2)) => "4, 1" 

(get-values (+ 9 2)) => "11" 
See the section "Special Forms for Receiving Multiple Values". 

multiple-value-list form Special Form 

Evaluates form and returns a list of the values it returned. This is useful for 
when you do not know how many values to expect. 

Examples: 

(setq a (multiple-value-list (intern "goo"))) 
a => (goo nil) 

This is similar to the example of multiple-value-setq; a is set to a list of two ele- 
ments, the two values returned by intern. 

In this example, multiple-value-list implements a very simplistic trace function 
(traces functions that return multiple values). 

(defun trace-function (function-name &rest args) 
(let ((fundef (symbol-function function-name)) 
(result '())) 
(format xtrace-outputx 

"~&Entering ~a with arguments ~{ ~a~}" 
function-name args) 
(setq result (multiple-value-list (apply fundef args))) 
(format xtrace-outputx 

"~&Exiting ~a with values ~{ ~a~}" 
function-name result) 
(values-list result))) 

CLOE Note: This is a macro in CLOE. 

multiple-value-progl value &body body Special Form 

Evaluates its first form argument and saves the values produced. Then evaluates 
the remaining forms and discards the returned values. The values saved from eval- 
uating the first form are returned. This special form is like progl except that its 
first form returns multiple values, multiple-value-progl returns those values. In 
certain cases, progl is more efficient than multiple-value-progl, which is why 
both special forms exist. 

See the section "Special Forms for Receiving Multiple Values". 
flavor:multiple-value-prog2 before result &rest after Function 



Page 1274 



Evaluates the forms and returns all the values of the second form. This is similar 
to multiple-value-progl. 

For a summary of all functions, macros, special forms, and variables related to 
Flavors, see the section "Summary of Flavor Functions and Variables". 



multiple-value-setq vars value Function 

Used for calling a function that is expected to return more than one value, value 
is evaluated, and the vars are set (not lambda-bound) to the values returned by 
value. If more values are returned than there are variables, the extra values are 
ignored. If there are more variables than values returned, extra values of nil are 
supplied. If nil appears in the var-list, then the corresponding value is ignored (you 
can't use nil as a variable.) Example: 

(multiple-value-setq (symbol al ready-there-p) 
(intern "goo")) 

In addition to its first value (the symbol), intern returns a second value, which is 
nil if the symbol returned as the first value was created by intern. If the symbol 
was already interned, the value is rinternal, rexternal, rinherited, depending on 
the symbol found. (See the function intern.) 

So if the symbol goo was already known and an internal symbol in the package, 
the variable already-there-p is set to rinternal, if goo is unknown, the value of 
already-there-p is nil. 

multiple-value-setq is usually used for effect rather than for value; however, its 
value is defined to be the first of the values returned by form. 

Evaluates form and sets the variables in the list variables to those values. Excess 
values are discarded, and excess variables are set to nil. Returns the first value 
obtained from evaluating form. If no values are produced, nil is returned. 

(multiple-value-setq (quotient remainder) (truncate 13 5)) 

The function multiple-value-setq can be used to obtain multiple values, each of 
which is used in further computation. 

(let ((retl '()) 
(ret2 nil)) 
(multiple-value-setq (retl ret2) (subtypep type-1 type-2)) 
(if ret2 

(values retl ret2) 

(and (multiple-value-setq (retl ret2) 

(my-even-more-expensive-subtype type-1 type-2)) 
(if ret2 

(values retl ret2) 

(error "Could not determine if ~A is a subtype of ~A." type-1 type-2))))) 

See the section "Special Forms for Receiving Multiple Values". 

CLOE Note: This is a macro in CLOE. 



Page 1275 



multiple-values-limit Constant 

A positive integer that is the upper exclusive bound on the number of values that 
can be returned from a function. The current value is 128 for 3600-series ma- 
chines, 50 for Ivory-based machines, and 128 for CLOE. 

mathrmultiply-matrices matrix-1 matrix-2 &optional matrix-3 Function 

Multiplies matrix-1 by matrix-2. If matrix-3 is supplied, mathrmultiply-matrices 
stores the results into matrix-3 and returns matrix-3; otherwise it creates an array 
to contain the answer and returns that. All matrices must be two-dimensional ar- 
rays, and the first dimension of matrix-2 must equal the second dimension of ma- 
trix-1. 

(flavorrmethod rremove sirheap) Method 

Removes the top item from the heap and returns it and its key as values. The 
third value is nil if the heap was empty; otherwise it is t. 

For a table of related items: See the section "Heap Functions and Methods". 

(flavorrmethod rtop sirheap) Method 

Returns the value and key of the top item on the heap. The third value is nil if 
the heap was empty; otherwise it is t. 

For a table of related items: See the section "Heap Functions and Methods". 

name-char name Function 

Accepts a string, or a string coercible object, as an argument. If name is the same 
as the name of a character object, that object is returned; otherwise nil is re- 
turned, name-char does not recognize names with modifier bit prefixes such as 
"hyper-space". 

(name-char "Tab") => #\Tab 
(name-char "Newline") => #\Newline 

(char-code (name-char "Space")) => 32 
For a table of related items, see the section "Character Names". 

sysmame-conflict Flavor 

Any sort of name conflict occurred (there are specific flavors, built on sysmame- 
conflict, for each possible type of name conflict). The following proceed types 
might be available, depending on the particular error: 

The rskip proceed type skips the operation that would cause a name conflict. 



Page 1276 



The rshadow proceed type prefers the symbols already present in a package to 
conflicting symbols that would be inherited. The preferred symbols are added to 
the package's shadowing-symbols list. 

The rexport proceed type prefers the symbols being exported (or being inherited 
due to a use-package) to other symbols. The conflicting symbols are removed if 
they are directly present, or shadowed if they are inherited. 

The runintern proceed type removes the conflicting symbol. 

The rshadowing-import proceed type imports one of the conflicting symbols and 
makes it shadow the others. The symbol to be imported is an optional argument. 

The rshare proceed type causes the conflicting symbols to share value, function, 
and property cells. It as if globalize were called. 

The rchoose proceed type pops up a window in which the user can choose between 
the above proceed types individually for each conflict. 



named Keyword for loop 

named name 

Gives the prog that loop generates a name of name, so that you can use the 
return-from form to return explicitly out of that particular loop: 

(loop named sue 

do (loop ... do (return-from sue value) .... ) 

The return-from form shown causes value to be immediately returned as the value 
of the outer loop. Only one name can be given to any particular loop construct. 
This feature does not exist in the Maclisp version of loop, since Maclisp does not 
support "named progs". 

See the section "loop Clauses". 



named-structure-invoke operation structure &rest args Function 

Calls the the handler function of the named structure symbol, found as the value 
of the named-structure-invoke property of the symbol, with the appropriate argu- 
ments. Operation should be a keyword symbol, and structure should be a named 
structure. 



named-structure-p structure Function 

This semi-predicate returns nil if structure is not a named structure; otherwise it 
returns structure's named structure symbol. 



named-structure-symbol named-structure Function 



Page 1277 



Returns named-structure's named structure symbol: if named-structure has an array 
leader, element 1 of the leader is returned, otherwise element of the array is re- 
turned. Named-structure should be a named structure. 



nbutlast list &optional (n 1) Function 

Destructive version of butlast; it changes the cdr of the second-to-last cons of the 
list to nil. If there is no second-to-last cons (that is, if the list has fewer than two 
elements) it returns nil. nbutlast returns all the conses in the list except for the 
last one. Examples: 

(setq foo ' (a b c d)) 
(nbutlast foo) => (a b c) 
foo => (a b c) 
(nbutlast ' (a)) => nil 
(setq a '(1 2 3 4 5 6 7)) 
(nbutlast a) => (1 2 3 4 5 6) 
(nbutlast a 4) => (1 2) 
a => (1 2) 

For a table of related items: See the section "Functions for Modifying Lists". 

nconc &rest arg Function 

Concatenates its arguments and returns the resulting list. The arguments are 
changed, rather than copied. Example: 

(setq x ' (a b c)) 

(setq y'(def)) 

(nconc x y) => (a b c d e f) 

x => (a b c d e f) 

Note that the value of x is now different, since its last cons has been changed (by 
rplacd) to the value of y. If 

(nconc x y) 

were evaluated again, it would yield a piece of "circular" list structure, whose 
printed representation would be(abcdefdefdef ...), repeating forever. 

nconc could have been defined by: 

(defun nconc (x y) ;for simplicity, this definition 

(cond ((null x) y) ;only works for 2 arguments, 

(t (rplacd (last x) y) ;hook y onto x 

x))) ;and return the modified x. 

nconc performs destructive operations on lists except if the first argument to the 
function is nil. For example: 



Page 1278 



(defvar xgx nil) 
(defvar xhx ' (a)) 
(defvar xix ' (b c)) 

(nconc xgx xix) => (B C) 
xgx => NIL 

(nconc xhx xix) => (A B C) 
xhx => (A B C) 



But: 



(setq xgx (nconc xgx xix)) => (B C) 
xgx => (B C) 

Do not use nconc for destructive operations with t or nil. For example: 

(nconc nil (neons 'b)) => (B) 

The following does not signal an error: 

(nconc 'a (neons 'b)) => (B) 

In the following example, push and nreverse sort queued entries in order of pri- 
ority, and nconc resets the queue. 

(defun sort-queue-2 (in-queue) 

"Sorts arg first by priorities (car element), then by original order." 
(let ((for-queue1 '()) 
(for-queue2 ' ()) 
(for-queue3 ' ())) 
(dolist (queue-element in-queue) 
(case (car queue-element) 

(1 (push queue-element for-queue1)) 
(2 (push queue-element for-queue2)) 
(3 (push queue-element for-queue3)))) 
;; reverse the temporary lists 
;; that were built by push 
(nconc (nreverse for-queue1) 
(nreverse for-queue2) 
(nreverse for-queue3)))) 

(setq queue-all 

'((1 element-a) (2 element-b) (3 element-c) (2 element-d) (1 element-e))) 
(sort-queue queue-all) => 
((1 ELEMENT-A) (1 ELEMENT-E) (2 ELEMENT-B) (2 ELEMENT-D) (3 ELEMENT-C)) 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



nconc keyword for loop 
nconc expr {into var} 



Page 1279 



Causes the values of expr on each iteration to be nconced together, for example: 

(loop for i from 1 to 3 

nconc (list i (* i i))) 
=> (1 1 2 4 3 9) 

When the epilogue of the loop is reached, var has been set to the accumulated re- 
sult and can be used by the epilogue code. 

It is safe to reference the values in var during the loop, but they should not be 
modified until the epilogue code for the loop is reached. 

The forms nconc and nconcing are synonymous. 

Examples: 

(defun indexing (small-list) 
(loop for x from 

for item in small -list 

nconc (list x item))) => INDEXING 
(indexing ' (a b c d )) => (0 A 1 B 2 C 3 D) 

is equivalent to 

(defun indexing (small-list) 
(loop for x from 

for item in small -list 

nconcing (list x item))) => INDEXING 
(indexing ' (a b c d )) => (0 A 1 B 2 C 3 D) 

Not only can there be multiple accumulations in a loop, but a single accumulation 
can come from multiple places within the same loop form, if the types of the col- 
lections are compatible, nconc, collect, and append are compatible. 

See the section "Accumulating Return Values for loop". 



neons x Function 

Creates a new cons, whose car is x (where x can be anything) and whose cdr is 
nil. (neons x) is the same (cons x nil). The name of the function is from "nil- 
cons". 

Example: 

(neons ' (5)) 
returns a new cons whose cdr is nil: 

((5)) 
To test if a cons has been created, apply the predicate endp to the new cons: 

(endp '(5)) 
This returns nil, since endp returns nil when applied to a cons. 
neons is a Symbolics extension to Common Lisp. 



Page 1280 



For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



ncons-in-area x area Function 

Creates a cons, whose car is x and whose cdr is nil, in the specified area. (Areas 
are an advanced feature of storage management. See the section "Areas".) 

ncons-in-area is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



neq x y Function 

(neq x y) = (not (eq x y)). This is provided simply as an abbreviation for typing 
convenience. 



never keyword for loop 
never expr 



Causes the loop to return t if expr never evaluates non-null. This is equivalent to 
always (not expr). If the loop terminates before expr is ever evaluated, the epi- 
logue code is run and the loop returns t. 

never expr is like (and (not exprl) (not expr2) ...). If the loop terminates before 
expr is ever evaluated, never is like (and). 

If you want a similar test, except that you want the epilogue code to run if expr 
evaluates non-null, use until. 

Examples: 

(defun loop-never (my-1 ist) 
(loop for x in my-list 

finally (print "what you going to do next ?") 
do 
(princ x) (princ " ") 
do 
and never (equal x 'a))) => LOOP-NEVER 

(loop-never ' (b c a e) => (B C A E) 

(loop-never '(a a)) => A NIL 

See the section "Aggregated Boolean Tests for loop". 



Page 1281 



clos:next-method-p Function 

Called within the body of a method to determine whether a next method exists; re- 
turns true if a next method exists, otherwise returns false. 

clos:next-method-p has lexical scope and indefinite extent. 



nintersection listl Ust2 &key (:test #'eql) :test-not (:key #'identityj Function 

The destructive version of intersection. It takes listl and Ust2 and returns a new 
list containing everything that is an element of both lists, using the cells of listl 
to construct the result. The value of Ust2 is not altered. The keywords are: 

:test Any predicate that spedifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

See the function intersection. For example: 

(setq a-list '(a b c)) => (A B C) 

(setq b-list ' (f a d)) => (F A D) 
(nintersection a-list b-list) => (A) 
a-list => (A) 

b-list => (F A D) 

In the following example, we want the list chips-32-data, to include only chips on 
the approved list. We use nintersection to destructively alter chips-32-data. 

(setq chips-approved 

'(68000 68010 68020 80186 80286 80386)) 
(setq chips-32-data '(68020 32032 80386)) 

(setq chips-32-data 

(nintersection chips-32-data chips-approved)) 

chips-32-data => (68020 80386) 

chips-approved => 

(68000 68010 68020 80186 80286 80386) 



Page 1282 



For a table of related items: See the section "Functions for Comparing Lists". 



zhnintersection &rest lists Function 

Takes any number of lists that represent sets and returns a new list that repre- 
sents the intersection of all the sets it is given, by destroying any of the lists 
passed as arguments and reusing the conses. zhnintersection uses eq for its com- 
parisons. You cannot change the function used for the comparison. 
(zhnintersection) returns nil. 

For a table of related items: See the section "Functions for Comparing Lists". 



ninth list Function 

Takes a list as an argument, and returns the ninth element of list, ninth is identi- 
cal to 

(nth 8 list) 

For example: 

(setq letters '(abcdefghijkl))=> 
(ABCDEFGHIJKL) 

(ninth letters) => I 

This function is provided because it makes more sense than using nth when you 
are thinking of the argument as a list rather than just as a cons. 

For a table of related items: See the section "Functions for Extracting from Lists". 



nleft n I &optional tail Function 

Returns a "tail" of I consisting of the last n elements of I, that is, one of the cons- 
es that makes up I, or nil. If n is too large, nleft returns I. Example: 

(nleft 2 '(bass bluefish tuna)) 
returns the last 2 conses: 
(bluefish tuna) 

(nleft n I tail) takes the cdr of the original I and returns a list such that taking n 
more cdrs of it would yield tail. You can see that when tail is nil, this is the same 
as the two-argument case. If tail is not eq to any tail of I, nleft returns nil. Ex- 
ample: 

(setq z ' (a b c d e)) => (A B C D E) 
(setq y (cdddr z)) => (D E) 
(nleft 2 z y) => (B C D E) 

nleft is a Symbolics extension to Common Lisp. 

For a table of related items: See the section "Functions for Extracting from Lists". 



Page 1283 



nlistp x Function 

Returns t if its argument x is not a list, otherwise nil. This means (nlistp nil) is 
nil. nlistp can be thought of as (not-listp). Note this distinction between nlistp 
and zhnlistp. (zhnlistp nil) is t, since zhnlistp returns nil if its argument is a 
cons. 

Example: 

(nlistp '(heron sandpiper bluejay)) 
returns nil, since this argument is a list. 

But: 

(nlistp '"sss") 
returns t since its argument is not a list. 
nlistp is a Symbolics extension to Common Lisp. 
For a table of related items: See the section "Predicates that Operate on Lists". 

zhnlistp x Function 

Equivalent to atom, so it returns t. 

nodeclare keyword for loop 

nodeclare variable-list 

The variables in variable-list are noted by loop as not requiring local type 
declarations. Consider the following: 

(declare (special k) (fixnum k)) 
(defun foo (1) 

(loop for x in 1 as k fixnum = (f x) ...)) 

If k did not have the fixnum data-type keyword given for it, then loop 
would bind it to nil, and some compilers would complain. On the other 
hand, the fixnum keyword also produces a local fixnum declaration for k; 
since k is special, some compilers complain (or error out). The solution is 
to do: 

(defun foo (1) 

(loop nodeclare (k) 

for x in 1 as k fixnum = (f x) ...)) 

which tells loop not to make that local declaration. The nodeclare clause 
must come before any reference to the variables so noted. Positioning it in- 
correctly causes this clause to not take effect, and cannot be diagnosed. See 
the macro loop. 

This exists for compatibility with other implementations of loop. 



not x 



Page 1284 



Function 



Returns t if x is nil, otherwise returns nil. null is the same as not; both functions 
are included for the sake of clarity. Use null to check whether something is nil; 
use not to invert the sense of a logical value. Even though Lisp uses the symbol 
nil to represent falseness, you should not make understanding of your program de- 
pend on this. For example, one often writes: 

(cond ((not (null 1st)) ... ) 

( ■■■ )) 
rather than 
(cond (1st ... ) 

( ■■■ )) 

There is no loss of efficiency, since these compile into exactly the same instruc- 
tions. 

The following example searches a list: 

(defun my-search(l key) 
(if (null 1) 
nil 
(or (equal (car 1) key) 

(search (cdr 1) key)))) 

See the function null. 



not type 



Type Specifier 



Defines the set of objects that are not of the specified type. As a type specifier, 
not can only be used in list form. 

Examples: 

(typep "music" '(not integer)) => T 
(subtypep 'nil '(not t)) => T and T 
(subtypep 'nil '(not integer)) => T and T 
(subtypep 'bit (not nil)) => T and T 
(equal -typep t (not nil)) => T 
(sys: type-argl ist 'not) => (TYPE) and T 

See the section "Data Types and Type Specifiers". See the section "Predicates". 



notany predicate sequence &rest more-sequences 



Function 



Returns nil as soon as any invocation of predicate returns a non-nil value, predi- 
cate must take as many arguments as there are sequences provided, predicate is 
first applied to the elements of the sequences with an index of 0, then with an in- 
dex of 1, and so on, until a termination criterion is reached or the end of the 
shortest of the sequences is reached. If the end of a sequence is reached, notany 
returns a non-nil value. Thus considered as a predicate, it is true if no invocation 
of predicate is true. 



Page 1285 



sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(notany tf'oddp '(1 2 5)) => NIL 

(notany tf'equal '(0123) '(3 2 1 0)) => T 

If predicate has side effects, it can count on being called first on all those ele- 
ments with an index of 0, then all those with an index of 1, and so on. 

The following example demonstrates how notany implements a test to determine if 
an element of a sequence exceeds a critical value. 

(setq limit-value 1024 sequence (vector 16 64 512 128 32)) 

(notany ft' (lambda (x) (> x limit-value)) sequence) => t 

For a table of related items: See the section "Predicates that Operate on Se- 
quences". 

notevery predicate sequence &rest more-sequences Function 

Returns a non-nil value as soon as any invocation of predicate returns nil. predi- 
cate must take as many arguments as there are sequences provided, predicate is 
first applied to the elements of the sequences with an index of 0, then with an in- 
dex of 1, and so on, until a termination criterion is reached or the end of the 
shortest of the sequences is reached. If the end of a sequence is reached, notevery 
returns nil. Thus considered as a predicate, it is true if not every invocation of 
predicate is true. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(notevery tf'oddp '(1 2 5)) => T 

(notevery tf'equal '(1 2 3) '(1 2 3)) => NIL 

(setq limit-value 212 sequence (vector 16 64 512 128 32)) 

(notevery #'(lambda(x) (<= x limit-value)) sequence) => t 

If predicate has side effects, it can count on being called first on all those ele- 
ments with an index of 0, then all those with an index of 1, and so on. 

For a table of related items: See the section "Predicates that Operate on Se- 
quences". 

notinline Declaration 



Page 1286 



(notinline functionl function2 ... ) specifies that it is undesirable to compile the 
specified functions in-line. This declaration is pervasive, that is, it affects all code 
in the body of the form. 

Note that rules of lexical scoping are observed; if one of the functions mentioned 
has a lexically apparent local definition (as made by flet or labels), then the decla- 
ration applies to that local definition and not to the global function definition. 

See the section "Declaration Specifiers". 



clos:no-next-method generic-function calling-method &rest args Generic Function 

Provides a mechanism for users to control what happens when clos:call-next- 
method is called, and no next method exists. The default method for closrcall- 
next-method signals an error. 

The typical way to specialize clos:call-next-method is to define a primary method, 
which would override the default primary method. 

This generic function is called automatically, and is not intended to be called by 
users. 

generic-function The generic function of method. 

calling-method The method whose call to clos:call-next-method resulted in 

this call to clos:no-next-method. 

args A list of arguments to clos:call-next-method. 



nreconc I tail Function 

Reverses the elements of I, concatenates them with the elements of tail, and re- 
turns the resulting list. Modifies both arguments, (nreconc I tail) is exactly the 
same as (nconc (zhnreverse I) tail) except that it is more efficient. Both I and tail 
should be lists. Example: 

(setq x ' (a b c)) 

(setq y'(def)) 

(nreconc x y) => (c b a d e f) 

x => undefined 

nreconc could have been defined by: 

(defun nreconc (1 tail) 
(cond ((null 1) tail) 

((nreversel 1 tail)) )) 

(defun nreversel (1 tail) ; auxiliary function 

(cond ((null (cdr 1)) (rplacd 1 tail)) 

((nreversel (cdr 1) (rplacd 1 tail))))) 

;; this last call depends on order of argument evaluation. 



Page 1287 



Note: nreconc actually works differently, and uses both rplacd and element shuf- 
fling. It therefore rarely causes rplacd-forwarding. 

In the following example, nreconc sorts queued entries in order of priority. 

(defun sort-queue( in-queue ) 

"Sorts arg first by priorities (car element), then by original order." 
(let ((for-queue1 '()) 
(for-queue2 ' ()) 
(for-queue3 ' ())) 
(dolist (queue-element in-queue) 
(case (car queue-element) 

(1 (push queue-element for-queue1)) 
(2 (push queue-element for-queue2)) 
(3 (push queue-element for-queue3)))) 
;; reverse the temporary lists 
;; that were built by push 
(nreconc for-q1 

(nreconc for-q2 (nreverse for-q3))))) 

(setq queue-all 

'((1 element-a) (2 element-b) (3 element-c) (2 element-d) (1 element-e))) 
(sort-queue queue-all) => 
((1 ELEMENT-A) (1 ELEMENT-E) (2 ELEMENT-B) (2 ELEMENT-D) (3 ELEMENT-C)) 

See the section "Cdr-Coding". 

For a table of related items: See the section "Functions for Constructing Lists and 
Conses". 



nreverse sequence Function 

Returns a sequence containing the same elements as sequence, but in reverse or- 
der. The result may or may not be eq to the argument, so it is usually wise to say 
something like (setq x (nreverse x)), because (nreverse x) is not guaranteed to 
leave the reversed value in x. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

For example: 

(setq item-list '(heron stork loon owl)) => (HERON STORK LOON OWL) 

(nreverse item-list) => (OWL LOON STORK HERON) 

item-list => (HERON) 

When used on a list, nreverse reverses the list by shuffling list elements or by 
calling rplacd on conses making up the list, or both, nreverse rarely causes 
rplacd-forwarding. For example, under Genera, this usually returns a cdr-coded 
list: 

(nreverse (list 'a 'b 'c)) 



Page 1288 



Note: The exact list destruction which occurs when using nreverse is undefined. 
It depends on the the cdr-coding of the list and the machine type. See the section 
"Cdr-Coding". 

nreverse is the destructive version of reverse. 

The following example creates a list of primes from 2 to 100, and demonstrates 
how nreverse restores a list of elements, built by push, to source order: 

(do ((i 2 (+ i 1)) 

(return-list '())) 
((= i 100) (nreverse return-list)) 
(if (primep i) 

(push i return-list))) 

Generally, use nreverse only with recently consed lists, or lists that are known to 
be dispensable. In other cases, reverse might be more appropriate. 

For a table of related items: See the section "Functions for Modifying Lists". 

For a table of related items: See the section "Sequence Modification". 

zhnreverse I Function 

Reverses its argument, which should be a list, by shuffling list elements or by call- 
ing rplacd on conses making up the list, or both, zhnreverse rarely causes 
rplacd-forwarding. The following usually returns a cdr-coded list: 

(nreverse (list 1 2 3)) 

Here is an example of zhnreverse: 

(zl: nreverse '(a b c)) => (c b a) 

Note: The exact list destruction which occurs when using zhnreverse is undefined. 
It depends on the the cdr-coding of the list and the machine type. See the section 
"Cdr-Coding". 

For a table of related items: See the section "Functions for Modifying Lists". 

nset-difference listl Ust2 &key {test #'eql) test-not {key #'identity) Function 

Returns a new list of elements of listl that do not appear in Ust2, using the cells 
of listl to construct the result. The value of Ust2 is not altered. Destructive ver- 
sion of set-difference. The keywords are: 

:test Any predicate that spedifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 



Page 1289 



:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

See the function set-difference. For example: 

(setq a-list '(eagle hawk loon pelican)) => 
(EAGLE HAWK LOON PELICAN) 

(setq b-list '(owl hawk stork)) => (OWL HAWK STORK) 

(nset-difference a-list b-list) => (EAGLE LOON PELICAN) 

a-list => (EAGLE LOON PELICAN) 

b-list => (OWL HAWK STORK) 

In the following example, we no longer want the list of approved chips chips- 
approved to include any chips with a 32 bit data path. We use nset-difference to 
destructively alter chips-approved: 

(setq chips-approved 

'(68000 68010 68020 80186 80286 80386)) 
(setq chips-32-data '(68020 32032 80386)) 
(setq chips-approved 

(nset-difference chips-approved chips-32-data)) 

chips-32-data => (68020 32032 80386) 
chips-approved => (68000 68010 80186 80286) 

For a table of related items: See the section "Functions for Comparing Lists". 

nset-exclusive-or listl Ust2 &key (:test #'eql) :test-not (:key #'identity) Function 

Destructive version of set-exclusive-or. It returns a list of elements that appear in 
exactly one of listl and Ust2, and alters values of the list arguments during the 
operation. The keywords are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

See the function set-exclusive-or. For example: 



Page 1290 



(setq a-list '(eagle hawk loon pelican)) => 
(EAGLE HAWK LOON PELICAN) 

(setq b-list '(owl hawk stork)) => (OWL HAWK STORK) 

(nset-exclusive-or a-list b-list) => 
(EAGLE LOON PELICAN OWL STORK) 

a-list => (EAGLE HAWK LOON PELICAN) 

b-list => (OWL STORK) 
For a table of related items: See the section "Functions for Comparing Lists". 

nstring-capitalize string &key (.start 0) send Function 

Returns string modified such that for every word in string, the initial character, if 
case-modifiable, is uppercased. All other case-modifiable characters in the word are 
lowercased. This function is the destructive version of string-capitalize. 

For the purposes of string-capitalize, a word is defined as a consecutive subse- 
quence of alphanumeric characters or digits, delimited at each end either by a 
non-alphanumeric character, or by an end of string. 

The keywords let you select portions of the string argument for uppercasing. 
These keyword arguments must be non-negative integer indices into the string ar- 
ray. The entire argument, string, is returned, however. 

If string is not a string, an error is signalled. 

rstart Specifies the position within string from which to begin uppercasing (count- 
ing from 0). Default is 0, the first character in the string, rstart must be < 
rend. 

rend Specifies the position within string of the first character beyond the end of 
the operation. Default is nil, that is, the operation continues to the end of 
the string. 

Examples: 

(nstring-capitalize " a bUNch of WOrDs" :start :end 3) 
=> " A bUNch of WOrDs" 

(nstring-capitalize " a bUNch of WOrDs" :start 8) 
=> " a bUNch Of Words" 

(nstring-capitalize " 1234567 a bunch of numbers" :start 1 :end 5) 
=> " 1234567 a bunch of numbers" 



Page 1291 



(setq a-string "poppy SEED") 

(nstring-capital ize a-string) 
=> "Poppy Seed" 

a-string => "Poppy Seed" 
For a table of related items: See the section "String Conversion". 

nstring-capitalize-words string &key (start 0) (end nil) Function 

The destructive version of string-capitalize-words. 

nstring-capitalize-words returns string, modified such that hyphens are changed 
to spaces and initial characters of each word are capitalized if they are case- 
modifiable. 

If string is not a string, an error is signalled. See the function string. 

The keywords let you select portions of the string argument for uppercasing. 
These keyword arguments must be non-negative integer indices into the string ar- 
ray. The entire argument, string, is returned, however. 

rstart Specifies the position within string from which to begin uppercasing (count- 
ing from 0). Default is 0, the first character in the string, rstart must be < 
rend. 

rend Specifies the position within string of the first character beyond the end of 
the uppercasing operation. Default is nil, that is, the operation continues to 
the end of the string. 

Examples: 

(nstri ng-capi tal i ze-words " three-hyphenated-words" ) 
=> "Three Hyphenated Words" 

(nstring-capitalize-words "three-hyphenated-words" :end 5) 
=> "Three-hyphenated-words" 

(nstring-capitalize-words "three-hyphenated-words" :start 6) 
=> "three-Hyphenated Words" 

For a table of related items: See the section "String Conversion". 



nstring-downcase string &key (start 0) (end nil) Function 

Returns string, modified to replace its uppercase alphabetic characters by the cor- 
responding lowercase characters. This function is the destructive version of the 
function string-downcase. 

If string is not a string, an error is signalled. 



Page 1292 



See the function string. 

The keywords let you select portions of the string argument for lowercasing. These 
keyword arguments must be non-negative integer indices into the string array. The 
entire argument, string, is returned, however. 

rstart Specifies the position within string from which to begin lowercasing (count- 
ing from 0). Default is 0, the first character in the string, rstart must be < 
rend. 

rend Specifies the position within string of the first character beyond the end of 
the lowercasing operation. Default is nil, that is, the operation continues to 
the end of the string. 

Examples: 

(nstring-downcase "WHAT TIME IS IT MM") => "what time is it MM" 
(nstring-downcase "A BUNCH OF WORDS" : start 2 :end 7) => "A bunch OF WORDS" 
(nstring-downcase "A BUNCH OF WORDS" : start 11) => "A BUNCH OF words" 
(setq string "THREE UPPERCASE WORDS") => "THREE UPPERCASE WORDS" 
(nstring-downcase string : start :end 5 ) => "three UPPERCASE WORDS" 
(nstring-downcase string : start 16 :end nil) => "three UPPERCASE words" 
string => "three UPPERCASE words" 

For a table of related items: See the section "String Conversion". 



nstring-upcase string &key (start 0) (end nil) Function 

Returns string, modified by replacing its lowercase alphabetic characters by the 
corresponding uppercase characters. This function is the destructive version of the 
function string-upcase. 

If string is not a string, an error is signalled. See the function string. 

The keywords let you select portions of the string argument for uppercasing. 
These keyword arguments must be non-negative integer indices into the string ar- 
ray. The entire string argument is returned, however. 

rstart Specifies the position within string from which to begin uppercasing (count- 
ing from 0). Default is 0, the first character in the string, rstart must be < 
rend. 

rend Specifies the position within string of the first character beyond the end of 
the uppercasing operation. Default is nil, that is, the operation continues to 
the end of the string. 

Characters not in the standard character set are unchanged. 
Examples: 



Page 1293 



(nstring-upcase "a four word string" :start 2 :end 6) 

=> "a FOUR word string" 
(nstring-upcase "a four word string" :start 12) 

=> "a four word STRING" 

(setq a-string "poppy SEED") 

(nstring-upcase a-string) 
=> "POPPY SEED" 

a-string => "POPPY SEED" 
For a table of related items: See the section "String Conversion". 

nsublis alist tree &rest args &key (:test #'eql) :test-not (:key #'identityj 

Function 

Destructive version of sublis. It makes substitutions for objects in a tree, altering 
the relevant parts of tree. See the function sublis. 

The keywords are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

Example: 

(setq exp '((* x y) (+ x y))) => ((* X Y) (+ X Y)) 

(nsublis '((x . 100)) exp) => ((* 100 Y) (+ 100 Y)) 

exp => ((* 100 Y) (+ 100 Y)) 

Thus, nsublis is comparable to several nsubst operations in parallel. The following 
example shows that sequential calls to nsubst can not replace every nsublis. 

(setq alist (pairlis '(monkey zebra) '(zebra monkey))) 
(setq newthing '(is-taller monkey zebra)) 

(nsublis alist newthing) => (IS-TALLER ZEBRA MONKEY) 
For a table of related items: See the section "Functions for Modifying Lists". 



Page 1294 



zhnsublis alist form Function 

Destructive version of sublis. Makes substitutions for symbols in a tree, but 
changes the original tree instead of creating a new tree. 

zhnsublis could have been defined by: 

(defun zl:nsublis (alist tree) 
(cond ((atom tree) 

(let ((tern (assq tree alist))) 
(if tern (cdr tern) tree))) 
(t (rplaca tree (zl:nsublis alist (car tree))) 
(rplacd tree (zl:nsublis alist (cdr tree))) 
tree))) 

In your new programs, we recommend that you use the function nsublis, which is 
the Common Lisp equivalent of zhnsublis. 

For a table of related items: See the section "Functions for Modifying Lists". 



nsubst new old tree &rest args &key (:test #'eql) :test-not (:key #'identityj Function 

Destructive version of subst. It changes tree by substituting new for every subtree 
or leaf of tree that matches old according to :test. See the function subst. The 
keywords are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

For example: 

(setq bird-list '(waders (flamingo stork) raptors (eagle hawk))) => 
(WADERS (FLAMINGO STORK) RAPTORS (EAGLE HAWK)) 

(nsubst 'heron 'stork bird-list) => 

(WADERS (FLAMINGO HERON) RAPTORS (EAGLE HAWK)) 

bird-list => (WADERS (FLAMINGO HERON) RAPTORS (EAGLE HAWK)) 

(setq sentence 

'((SUB (PN . Avery)) (PRED (\l . was) (ADJ . cool)) 
(SUB (RPN . he)) (PRED (\l . was) (ADJ . calm)) 
(SUB (RPN . he)) (PRED (\l . was) (ADJ . suave)))) 



Page 1295 



(nsubst ' (PN . Avery) 'RPN sentence :key #' (lambda(x) (and (consp x) (car x)))) 
=> 

((SUB (PN . Avery)) (PRED (V . was) (ADJ . cool)) 

(SUB (PN . Avery)) (PRED (V . was) (ADJ . calm)) 

(SUB (PN . Avery)) (PRED (V . was) (ADJ . suave))) 

For a table of related items: See the section "Functions for Modifying Lists". 



zhnsubst new old s-exp Function 

Destructive version of subst. Changes s-exp by replacing each element occurence of 
old with new . zhnsubst could have been defined as 

(defun nsubst (new old tree) 

(cond ((eq tree old) new) ;if item eq to old, replace. 

((atom tree) tree) ;if no substructure, return arg. 

(t ;otherwise, recurse. 

(rplaca tree (nsubst new old (car tree))) 

(rplacd tree (nsubst new old (cdr tree))) 
tree))) 



nsubst-if new predicate tree &rest args &key :key 

Function 

Destructive version of subst-if. It change tree by substituting new for every sub- 
tree or leaf of tree that satisfies predicate. See the function subst-if. The keyword 
is: 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 



For example: 



(setq item-list '(numbers (1.0 2 5/3) symbols (foo bar))) 
=> (NUMBERS (1.0 2 5/3) SYMBOLS (FOO BAR)) 

(nsubst-if '3.1415 tf'numberp item-list) 

=> (NUMBERS (3.1415 3.1415 3.1415) SYMBOLS (FOO BAR)) 

item-list => (NUMBERS (3.1415 3.1415 3.1415) SYMBOLS (FOO BAR)) 
(setq b '(1 2 (AA BB (3 BB)) CC DD 4)) 

(nsubst-if 'ZZ tf'numberp b) 
=> (ZZ ZZ (AA BB (ZZ BB)) CC DD ZZ) 

b => (ZZ ZZ (AA BB (ZZ BB)) CC DD ZZ) 



Page 1296 



The following call to nsubst-if uses an anonymous function. After the call, a is al- 
tered according to the results returned by nsubst-if. 

(setq a '("In" "our" "prairie" "home" "we" "read" 
"The" "Prairie" "Home" "Companion")) 

(nsubst-if "Gopher" 

#' (lambda (comparator) (string= comparator "Prairie")) 
=> 

("In" "our" "prairie" "home" "we" "read" 
"The" "Gopher" "Home" "Companion") 

For a table of related items: See the section "Functions for Modifying Lists". 

nsubst-if-not new predicate tree &rest args &key :key 

Function 

Destructive version of subst-if-not. It changes tree by substituting new for every 
subtree or leaf of tree that does not satisfy predicate. See the function subst-if-not. 
The keyword is: 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

For example: 

(setq item-list '(numbers 1.0 2 5/3 symbols foo bar)) 
=> (NUMBERS 1.0 2 5/3 SYMBOLS FOO BAR) 

(nsubst-if-not '3.1415 #' '(numbers 1.0 2 5/3 symbols foo bar)) 

item-1 ist 

In the following example, the key function ensures that the test is not applied to 
the entire list. 

(setq prop-results '(integer nil nil float)) 

(nsubst-if-not t tf'null prop-results 

:key ft' (lambda(x) (and (atom x) x))) 
=> (t nil nil t) 

prop-results => (t nil nil t) 
For a table of related items: See the section "Functions for Modifying Lists". 



nsubstitute newitem olditem sequence &key (:test #'eql) :test-not (:key #'identityj 
:from-end (.start 0) send -.count Function 

Returns a sequence of the same type as the argument sequence which has the 
same elements, except that those in the subsequence delimited by rstart and rend 



Page 1297 



and satisfying the predicate specified by the :test keyword have been replaced by 
newitem. The argument sequence is destroyed during construction of the result, but 
the result may or may not be eq to sequence. 

For example: 

(setq letters '(a b c)) => (A B C) 
(nsubstitute 'a 'b ' (a b c)) => (A A C) 
letters => (A B C) 

However, 

letters => (A B C) 

(nsubstitute 'b 'c letters) => (A B B) 

letters => (A B B) 

newitem and olditem can be any Symbolics Common Lisp object but newitem must 
be a suitable element for sequence. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence of length zero. 

:test specifies the test to be performed. An element of sequence satisfies the test if 
(funcall testfun item {keyfn x)) is true. Where testfun is the test function specified 
by :test, keyfn is the function specified by :key and x is an element of the se- 
quence. The default test is eql. 

For example: 

(nsubstitute 3 ' (1 1 4 4 2) :test #'<) => (1 1 2) 

:test-not is similar to :test, except that the sense of the test is inverted. An ele- 
ment of sequence satisfies the test if (funcall testfun item {keyfn x)) is false. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(nsubstitute 1 2 '((1 1) (1 2) (4 3)) :key tf'second) => ((1 1) 1 (4 3)) 
(nsubstitute 'a 'b '((a b) (b c) (b b)) :key tf'second) => (A (B C) A) 

A non-nil :from-end specification matters only when the rcount argument is pro- 
vided; in that case only the rightmost rcount elements satisfying the test are re- 
placed. 

For example: 

(nsubstitute 'hi 'b ' (b a b) :from-end t :count 1 ) 
=> (B A HI) 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 



Page 1298 



rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 



(nsubstitute 'a 'B ' (b a b) 
(nsubstitute 'a 'b ' (b a b) 
(nsubstitute 'a 'b ' (b a b) 



start 1 :end 3) => (B A A) 
end 2) => (A A B) 
end 3) => (A A A) 



A non-nil rcount, if supplied, limits the number of elements altered; if more than 
rcount elements satisfy the test, then of these elements only the leftmost are re- 
placed, as many as specified by rcount. A negative rcount argument is equivalent 
to a rcount of 0. 

For example: 

(nsubstitute 'a 'b ' (b b a b b) :count 3) => (A A A A B) 

To perform destructive substitutions throughout a tree: See the function nsubst. 

nsubstitute is case-insensitive. 

nsubstitute is the destructive version of substitute. 

For a table of related items: See the section "Sequence Modification". 

nsubstitute-if newitem predicate sequence &key :key :from-end (.start 0) send .-count 

Function 

Returns a sequence of the same type as the argument sequence which has the 
same elements, except that those in the subsequence delimited by rstart and rend 
and satisfying predicate have been replaced by newitem. The argument sequence is 
destroyed during construction of the result, but the result may or may not be eq 
to sequence. 

For example: 

(setq numbers '(a b)) => (A B) 
(nsubstitute-if 3 #'numberp numbers) => (A B) 
numbers => (A B) 

However, 

numbers => (1 1 19) 

(nsubstitute-if 2 tf'numberp numbers) => (2 2 2) 

numbers => (2 2 2) 

newitem can be any Symbolics Common Lisp object but must be a suitable element 
for the sequence. 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 



Page 1299 



The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(nsubstitute-if 1 tf'oddp '((1 1) (1 2) (4 3)) :key tf'second) 
=> (1 (1 2) 1) 

A non-nil :from-end specification matters only when the rcount argument is pro- 
vided; in that case only the rightmost rcount elements satisfying the test are re- 
placed. 

For example: 

(nsubstitute-if 'hi #'atom ' (b 'a b) :from-end t :count 1 ) 
=> (B 'A HI) 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 

If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(nsubstitute-if 1 tf'zerop '(0 1 0) : start 1 :end 3) => (0 1 1) 
(nsubstitute-if 1 tf'zerop '(0 1 0) : start :end 2) => (1 1 0) 
(nsubstitute-if 1 tf'zerop '(0 1 0) :end 1) => (1 1 0) 

A non-nil rcount, if supplied, limits the number of elements altered; if more than 
rcount elements satisfy the test, then of these elements only the leftmost are re- 
placed, as many as specified by rcount. A negative rcount argument is equivalent 
to a rcount of 0. 

For example: 

(nsubstitute-if 'see 'atom ' (b b a b b) :count 3) 
=> (SEE SEE SEE B B) 

(setq alist (pairlis '(second third start end) '(11 21 13 43))) 

(nsubstitute-if '(boundary 42) ft' (lambda(x) (member x '(start end middle))) 
al ist :key #'car)) 

alist => ((BOUNDARY 42) (BOUNDARY 42) (THIRD 21) (SECOND 11)) 
nsubstitute-if is the destructive version of substitute-if. 
For a table of related items: See the section "Sequence Modification". 



Page 1300 



nsubstitute-if-not newitem predicate sequence &key :key :from-end (.start 0) send 
.-count 

Function 

Returns a sequence of the same type as the argument sequence which has the 
same elements, except that those in the subsequence delimited by rstart and rend 
which do not satisfy predicate have been replaced by newitem. The argument se- 
quence is destroyed during construction of the result, but the result may or may 
not be eq to sequence. 

For example: 

(setq numbers '(000)) => (00 0) 
(nsubstitute-if-not 1 #'numberp numbers) => (0 0) 
numbers => (0 0) 

However, 

numbers => (1 0) 

(nsubstitute-if-not 2 #'consp numbers) => (2 2 2) 

numbers => (2 2 2) 

newitem can be any Symbolics Common Lisp object but must be a suitable element 
for the sequence. 

predicate is the test to be performed on each element. 

sequence can be either a list or a vector (one-dimensional array). Note that nil is 
considered to be a sequence, of length zero. 

The value of the keyword argument :key, if non-nil, is a function that takes one 
argument. This function extracts from each element the part to be tested in place 
of the whole element. 

For example: 

(nsubstitute-if-not 1 tf'oddp '((1 1) (1 2) (4 3)) :key tf'second) 
=> ((1 1) 1 (4 3)) 

A non-nil :from-end specification matters only when the rcount argument is pro- 
vided; in that case only the rightmost rcount elements satisfying the test are re- 
placed. 

For example: 

(nsubstitute-if-not 'hi tf'atom '('b a 'b) :from-end t :count 1 ) 
=> ('B A HI) 

Use the keyword arguments rstart and rend to delimit the portion of the sequence 
to be operated on. 

rstart and rend must be non-negative integer indices into the sequence, rstart 
must be less than or equal to rend, else an error is signalled. It defaults to zero 
(the start of the sequence). 

rstart indicates the start position for the operation within the sequence, rend indi- 
cates the position of the first element in the sequence beyond the end of the oper- 
ation. It defaults to nil (the length of the sequence). 



Page 1301 



If both rstart and rend are omitted, the entire sequence is processed by default. 

For example: 

(nsubstitute-if-not 1 tf'zerop '(3 2) : start 1 :end 3) => (3 1) 
(nsubstitute-if-not 1 tf'zerop '(3 2) : start :end 2) => (1 2) 
(nsubstitute-if-not 1 tf'zerop '(3 2) :end 1) => (1 2) 

A non-nil rcount, if supplied, limits the number of elements altered; if more than 
rcount elements satisfy the test, then of these elements only the leftmost are re- 
placed, as many as specified by rcount. A negative rcount argument is equivalent 
to a rcount of 0. 

For example: 

(nsubstitute-if-not 'see 'consp ' (b b a b b) :count 3) 
=> (SEE SEE SEE B B) 

(setq alist (pairlis '(second third start end) '(11 21 13 43))) 

(nsubstitute-if-not '(inner 24) ft' (lambda(x) (member x '(start end middle))) 
al ist :key #'car)) 

alist => ((END 43) (START 13) (INNER 24) (INNER 24)) 
nsubstitute-if-not is the destructive version of substitute-if-not. 
For a table of related items: See the section "Sequence Modification". 

nsubstring string from &optional to (area nil) Function 

Destructive form of the function substring. Instead of copying the substring, the 
system creates an indirect array that shares part of the argument string. See the 
section "Indirect Arrays". Modifying one string modifies the other. 

string is a string or an object that can be coerced to a string. Since nsubstring is 
destructive, coercion should be used with care since a string internal to the object 
might be modified. See the function string. 

Note that nsubstring does not necessarily use less storage than substring; an 
nsubstring of any length uses at least as much storage as a substring four char- 
acters long. So you should not use this just "for efficiency"; it is intended for uses 
in which it is important to have a substring that, if modified, causes the original 
string to be modified too. 

Examples: 

(setq a "Aloysius") => "Aloysius" 

a => "Aloysius" 

(setq b (nsubstring a 2 4)) => "oy" 

(nstring-upcase b) => "OY" 

a => "AlOYsius" 

For a table of related items: See the section "String Access and Information". 



Page 1302 



nsymbolp arg Function 

Returns nil if its argument is a symbol, otherwise t. 

nth n list Function 

Returns the nth element of list, where the zeroth element is the car of the list. 
Examples: 

(nth 1 ' (foo bar gack)) => bar 
(nth 3 '(foo bar gack)) => nil 

Returns nil if n is greater than the length of the list. 

Note: this is not the same as the Interlisp function called nth, which is similar to, 
but not exactly the same as, the Symbolics Common Lisp function nthcdr. 

nth could have been defined by: 

(defun nth (n list) 
(do ((i n (1- i)) 

(1 list (cdr 1))) 
((zerop i) (car 1)))) 

The relationship between nth and lists is similar to that of svref and simple vec- 
tors. However, references beyond the end of the vector are not considered errors 
by nth. 

(nth '(a b c)) = (first '(a b c)) => a 
(nth 2 '(a b c)) = (third '(a b c)) => c 
(nth 3 '(a b c)) = (fourth '(a b c)) => nil 

This function allows selection beyond the cadddr, or even the zl-user:tenth ele- 
ment of a list. 

For a table of related items: See the section "Functions for Extracting from Lists". 

nthcdr n list Function 

Performs n cdr operations on list, and returns the result. Examples: 

(nthcdr ' (a b c)) => (a b c) 
(nthcdr 2 ' (a b c)) => (c) 

In other words, it returns the nth cdr of the list. Returns nil if n is greater than 
the length of the list. 

This is similar to Interlisp 's function nth, except that the Interlisp function is one- 
based instead of zero-based; see the Interlisp manual for details, nthcdr could have 
been defined by: 

(defun nthcdr (n list) 
(do ((i (1+ i)) 

(list list (cdr list))) 
((= i n) list))) 

This selector function allows selection beyond the cddddr. Though the numeric ar- 



Page 1303 



gument is evaluated, it allows parameterization of the selected position. Compare 
the following two forms, and their results, in the following example. 

(let ((foo joblist)) 

(dotimes (i xtimesx foo) (setq foo (cdr foo)))) 
(nthcdr xtimesx joblist) 

For a table of related items: See the section "Functions for Extracting from Lists". 

null Type Specifier 

null is the type specifier symbol for the predefined Lisp null data type. 

The type null is a subtype of the type symbol; the only object of type null is nil. 

The types null and cons form an exhaustive partition of the type list. 

Examples: 

(typep nil 'null) => T 

(null ()) => T 

(subtypep 'null 't) => T and T 

(subtypep 'null 'symbol) => T and T 

(equal -typep (null ()) (not ())) => T 

(sys: type-argl ist 'null) => NIL and T 

See the section "Data Types and Type Specifiers". See the section "Predicates". 

null x Function 

Returns t if x is nil, otherwise returns nil. null is the same as not; both functions 
are included for the sake of clarity. Use null to check whether something is nil; 
use not to invert the sense of a logical value. Even though Lisp uses the symbol 
nil to represent falseness, you should not make understanding of your program de- 
pend on this. For example, one often writes: 

(cond ((not (null 1st)) ... ) 

( ■■■ )) 
rather than 
(cond (1st ... ) 

( ■■■ )) 

There is no loss of efficiency, since these compile into exactly the same instruc- 
tions. 

The following example searches a list: 

(defun my-search(l key) 
(if (null 1) 
nil 
(or (equal (car 1) key) 

(search (cdr 1) key)))) 



Page 1304 



sysrnull-stream op &rest args Function 

Can be used as a dummy stream object. As an input stream, it immediately reports 
end-of-file; as an output stream, it absorbs and discards arbitrary amounts of out- 
put. Note: sysrnull-stream is not a variable; it is defined as a function. Use its 
definition (or the symbol itself) as a stream, not its value. Examples: 

(stream-copy-until-eof a 'si :nul 1 -stream) 
(stream-copy-until-eof a #'si :nul 1-stream) 

Either of the above two forms reads characters out of the stream that is the value 
of a and throws them away, until a reaches the end-of-file. 

number &optional (low-limit '*) (high-limit '*) Type Specifier 

number is the type specifier symbol for the predefined Lisp data type, number. 

The type number is a supertype of the following types, which are themselves pair- 
wise disjoint: 

rational 

float 

complex 

The types number, cons, symbol, array, and character are pairwise disjoint. 

In addition to a symbol form, Symbolics Common Lisp provides a list form for 
number. Used in list form, number allows the declaration and creation of special- 
ized numbers whose range is restricted to the limits specified in the arguments 
low-limit and high-limit. The list form might not work in other implementations of 
Common Lisp. 

low-limit and high-limit must each be an integer, a list of an integer, or unspeci- 
fied. If these limits are expressed as integers, they are inclusive; if they are ex- 
pressed as a list of an integer, they are exclusive; * means that a limit does not 
exist, and so effectively denotes minus or plus infinity, respectively. 

Examples: 

(typep '1 'number) => T 

(typep 1 '(number 1 3)) => T 

(typep '(number 1 3)) => NIL 

(typep 4 '(number 5 *)) => NIL 

(typep 5 '(number 5 *)) => T 

(subtypep 'bit '(number 4)) => T and T 

(commonp 3.14) => T 

(numberp '16) => T 

(numberp most-positive-long-float) => T 

(subtypep 'rational 'number) => T and T 

(subtypep 'float 'number) => T and T 



Page 1305 



(subtypep 'complex 'number) => T and T 

(sys: type-argl ist 'number) 

=> (&0PTI0NAL (LOW-LIMIT '*) (HIGH-LIMIT '*)) and T 

See the section "Data Types and Type Specifiers". See the section "Numbers". 



sys:number-into-array array n &optional (radix zhbase) (at-index 0) (min-columns 
0) Function 

Deposits the printed representation of n into array, which must be a string, which 
is an integer. sys:number-into-array is the inverse of zhparse-number. It has 
three optional arguments: 

radix The radix to use when converting the number into its printed 

representation. It defaults *print-base*. 

at-index The character position in the array to start putting the num- 

ber. 

min-columns The minimum number of characters required for the printed 

representation of the number. If the number contains fewer 
characters than min-columns, the number is right-justified 
within the array. If the number contains more characters than 
min-columns, min-columns is ignored. An error is signalled if 
the number contains more characters than the length of the 
array minus at-index. The default is the first position, position 
0. 

The following example puts 23453243 into string starting at character position 5. 
Since min-columns is 10, the number is preceded by two spaces. 

(let ((string (make-array 20. :type 'art-string : initial-value #\X))) 
(zl :number-into-array string 23453243. 10. 5. 10.) 
string) 

=> "XXXXX 23453243XXXXX" 
For a table of related items: See the section "String Access and Information". 



numberp object Function 

Returns t if its argument is any kind of number, otherwise nil. 

The following code first tests whether a and b are numbers. If numbers, they are 
added, if strings, they are concatenated. 

(if (and (numberp a) (numberp b)) 
(+ a b) 
(if (and (stringp a) (stringp b)) 

(concatenate 'string a b) 

(error "couldn't combine ~a and ~a" a b))) 



Page 1306 



For a table of related items, see the section "Numeric Type-checking Predicates". 



numerator Function 

If rational is a ratio, numerator returns the numerator of rational. If rational is 

an integer, numerator returns rational. 

Examples: 

(numerator 4/5) => 4 
(numerator 3) => 3 
(numerator 4/8) => 1 
(numerator (/ 12 -17)) => -12 
(numerator (rational 0.200)) => 13421773 

Related Functions: 
denominator 

For a table of related items: See the section "Functions that Extract Components 
From a Rational Number". 



nunion listl Ust2 &key (test #'eql) test-not (key #'identity) Function 

Destructive version of union. It takes two lists and returns a new list containing 
everything that is an element of either of the lists, and destroys the values of the 
list arguments. See the function union. The keywords are: 

:test Any predicate that specifies a binary operation on a supplied 

argument and an element of a target list. The item matches 
the specification only if the predicate returns t. If :test is not 
supplied, the default operation is eql. 

:test-not Similar to :test, except that item matches the specification only 

if there is an element of the list for which the predicate re- 
turns nil. 

:key If not nil, should be a function of one argument that will ex- 

tract the part to be tested from the whole element. 

For example: 

(setq a-list '(a b c)) => (A B C) 

(setq b-list ' (f a d)) => (F A D) 

(nunion a-list b-list) => (A B C F D) 

a-list => (A B C F D) 

b-list => (F D) 
In the following example, nunion updates the list of tenured professors by combin- 



Page 1307 



ing the list of tenured professors with the list of newly tenured professors. 

(setq professors-with-tenure 

'(("Jones" CS101 CS242) ("smith" CS202 CS231) 
("hunter" CS216 CS232))) 
(setq new-tenured-professors 

'(("parks" CS221))) 

(setq professors-with-tenure 

(nunion professors-with-tenure new-tenured-professors 
:test tt'string-equal :key #'car)) 

professors-with-tenure => 
(("Jones" CS201 CS242) ("smith" CS202 CS231) 
("hunter" CS216 CS232) ("parks" CS221)) 

For a table of related items: See the section "Functions for Comparing Lists". 



zhnunion &rest lists Function 

Takes any number of lists that represent sets and returns a new list that is the 
union of all those sets. Destroys the arguments and reuses their conses. zhnunion 
uses eq for its comparisons. You cannot change the function used for the compari- 
son. Given no arguments, (nunion) returns nil. 

For a table of related items: See the section "Functions for Comparing Lists". 



oddp integer Function 

Returns t if integer is odd, otherwise nil. If integer is not an integer, oddp signals 
an error. 

(oddp 1) => t 

(oddp (x 2 (random n))) => nil 

For a table of related items, see the section "Numeric Property-checking Predi- 
cates". 



once-only (variable-name ... &environment environment) &body body 

Macro 
A once-only form looks like this: 

(once-only (variable-name &environment environment) 
forml 
form2 

variable-name is a list of variables, once-only is usually used in macros where the 
variables are Lisp forms. &environment should be followed by a single variable 
that is bound to an environment representing the lexical environment in which the 



Page 1308 



macro is to be interpreted. Typically this comes from the &environment parame- 
ter of a macro. The forms are a Lisp program that presumably uses the values of 
the variables to construct a new form to be the value of the macro. When a call to 
the macro that includes the once-only form is macroexpanded, the form produced 
by that expansion will be evaluated. 

The macro that includes the once-only form will be macroexpanded. The form pro- 
duced by that expansion is then evaluated. In the process, the values of each of 
the variables in variable-name are first inspected. These variables should be bound 
to subforms, that probably originated as arguments to the defmacro or similar 
form, and will be incorporated in the macro expansion, possibly in more than one 
place. 

Each variable is then rebound either to its current value, if the current value is a 
trivial form, or to a generated symbol. Next, once-only evaluates the forms, in this 
new binding environment, and when they have been evaluated it undoes the bind- 
ings. The result of the evaluation of the last form is presumed to be a Lisp form, 
typically the expansion of a macro. If all of the variables had been bound to trivial 
forms, then once-only just returns that result. Otherwise, once-only returns the 
result wrapped in a lambda-combination that binds the generated symbols to the 
result of evaluating the respective nontrivial forms. 

The effect is that the program produced by evaluating the once-only form is coded 
in such a way that it only evaluates each of the forms that are the values of vari- 
ables in variable-name once, unless evaluation of the form has no side effects. At 
the same time, no unnecessary lambda-binding appears in the program. The body 
of the once-only is not cluttered up with extraneous code to decide whether or not 
to introduce lambda-binding in the program it constructs. 

Note well: once-only can be used only with an &environment keyword argument. 
If this argument is not present, a compiler warning will result. 

For more information about using once-only with &environment: See the lambda 
list keyword &environment. Also, refer to the definitions of the macro defining 
forms: defmacro, macrolet, and defmacro-in-flavor. 

(defmacro double (x &envi ronment env) 
(once-only (x &envi ronment env) 
'(+ ,x ,x))) 
=> DOUBLE 

(double 5) 
==> (+ 5 5) 

(double var) 
==> (+ UAR UAR) 

(double (compute-value var)) 

==> (LET ((#:0NCE-0NLY-X-3553 (COMPUTE-VALUE UAR))) 
(+ #:0NCE-0NLY-X-3553 ft: 0NCE-0NLY-X-3553) ) 

Note that in the first three examples, when the argument is simple, it is duplicat- 



Page 1309 



ed. In the last example, when the argument is complicated and the duplication 
could cause a problem, it is not duplicated. 

For information about avoiding problems with evaluation: See the section "Avoiding 
Multiple and Out-of-Order Evaluation". 

once-only evaluates its subforms in the order they are presented. If it finds any 
form which is non-trivial, it rebinds the earlier variables to temporaries, and eval- 
uates them first. In the following example, the order of evaluation is x, then y, 
even though the y appears before the x in the body of the once-only: 

(defmacro my-progn (x y &envi ronment env) 
(once-only (x y &envi ronment env) 

;; We willfully try to make it evaluate in the wrong order, 
'(progn ,y ,x))) => MY-PROGN 

;; Macro expansion shows code that would be produced by the 
;; once-only form in the macro. 

(my-progn (print x) (setq x 'foo)) => 
(LET ((#:0NCE-0NLY-X-7614 (PRINT X))) 
(PROGN (VALUES (SETQ X 'FOO)) #: 0NCE-0NLY-X-7614) ) 

In the next example, once-only evaluates y, then x, because y appears before x in 
once-only' s variable list. In actuality, this style is an example of poor program- 
ming practice as it is confusing. Always list variables in the order in which the 
forms they are bound to appear in the source that produced them. In a macro, this 
is normally the order they appear in the macro's argument list. 

(defmacro backward-progn (x y &envi ronment env) 
(once-only (y x &envi ronment env) 

;; We willfully try to make it evaluate in the wrong order. 
;; But this time we tell once-only to evaluate y before x. 
1 (progn ,y ,x))) => BACKWARD-PROGN 

(backward-progn (print x) (setq x 'foo)) => FOO 

FOO 

(PROGN (VALUES (SETQ X 'FOO)) (VALUES (PRINT X))) => FOO 

FOO 



sysropen-coroutine-stream function &key (.-direction rinput) Obuffer-size 1000) (ele- 
ment-type 'character) Function 

Creates either input streams, output streams, or bidirectional streams, each with a 
shared buffer, depending on the argument given to .-direction. For examples of 
coroutine streams, see the section "Coroutine Streams". 

Using the functions read-char and write-char on the stream returned by 
sysropen-coroutine-stream cause the new stack group to be resumed and function 



Page 1310 



to be called from that stack group. The argument to function is the second stream 
created by sysropen-coroutine-stream. The first stream is t