# 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+ :

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+\$ :

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".

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) 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.

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"))

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))

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

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

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".

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.

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

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.

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

(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.

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

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

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".

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".

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)

(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.

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

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)
: 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) 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) is the same as (car (car (cdr (car x))))

Function

(caaddr x) is the same as (car (car (cdr (cdr x))))

Function

(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) is the same as (car (cdr (car (car x))))

Function

Function

Page 908

(cadar x) is the same as (car (cdr (car x)))

Function

(caddar x) is the same as (car (cdr (cdr (car x))))

Function

(cadddr x) is the same as (car (cdr (cdr (cdr x))))

Function

(caddr x) is the same as (car (cdr (cdr x)))

Function

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

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

#' (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) 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) is the same as (cdr (car (cdr (car x))))

Function

(cdaddr x) is the same as (cdr (car (cdr (cdr x))))

Function

(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) 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

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

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.

(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.

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.

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".

This function can be defined by:

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

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.

(list (peek-char)

=> (#\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

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-

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-

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
nored by the Lisp reader. Example:

(defun foo (x)

(cond ((null x) 0)

(t (1+ (foo (cdr x)))) ;x has something in it

))

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

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)

(consp 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)

(consp 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"))

=> 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

: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.

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:

returns the following association list, which is equal to the original association
list:

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

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

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".

ue of the global variable *readtable*). If from-readtable is nil, then a copy of a

will restore the input syntax to standard Common Lisp syntax, even if the original

must be a readtable, which is destructively copied into.

Page 971

(let* ((foo "zzzY'zzz")

(set-syntax-f rom-char #\" #\%)
(setq result (cons result (read-f rom-string foo))))

=> (ZZZ . | ZZZ"ZZZ | )

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.

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".

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

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:

(ctypecase (car x)

(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*.

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
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:

Defines a method for a reader generic function named
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.

Defines a method for a reader generic function named
reader-name, and a method for a writer named (future-

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

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.")

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)

: 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

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".

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

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-

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

This says that the form to create a locative pointer to array-leader is the function

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).

Symbols with the specified names are created in this package and declared

(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

The same as rimport but no name conflicts are possible; the symbols are

(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)

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

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
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:

(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.

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.

(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.

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,

(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"
(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))))

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)))

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-
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)

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
— > 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:

(etypecase (car x)

(tel 1-about-car '("word" "more")) => "string"
(tel 1-about-car '(a 1)) => non-proceedable error is signalled

(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.

(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

(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.

(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)

(find-package 'turbine-control ler))
(error "Couldn't find package TURBINE-CONTROLLER.")))

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

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

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

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-

P"

i) =>

2

(float-

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

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".

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-

(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".

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

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.

(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.

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.

(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

(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))
(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)))

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

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-

=> 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

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.

The value of sirinitial-readtable is the initial standard readtable. You should never
it, by using it as the from-readtable argument to zlrcopy-readtable or zlrset-

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)))

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

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.

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.

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)

(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)
(if (= counter 0)
accumulator

(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.

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

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)

For a table of related items: See the section "Functions for Finding Information

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

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.

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-

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".

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))))

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

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

(1 ist c

(1 isten)

(progn (peek-char) (listen))

=> (#\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".

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 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;

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

This is the same as the information displayed by the Show Machine Configuration

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)

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

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,
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-
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

non-terminating-p

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.

(macfun (get-dispatch-macro-character #\# #\\)))
(set-syntax-f rom-char #\[ #\#)

(set-dispatch-macro-character #\[ #\\ macfun)
=> 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)))

(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

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.

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)))))

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:

; ; Example 2

(def class my-frob ()

((name :initarg :name : reader my-name)))

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)))
(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.

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.

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.

Symbols with the specified names are created in this package and declared

(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

Page 1242

The same as rimport but no name conflicts are possible; the symbols are

(: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)

(: 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-

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-

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

(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))))

=> 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))
(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

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".

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))

(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

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:

(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

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 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.

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```